casacore
Loading...
Searching...
No Matches
AipsrcValue.h
Go to the documentation of this file.
1//# AipsrcValue.h: Class to read values from the Aipsrc general resource files
2//# Copyright (C) 1995,1996,1997,1999,2002,2003
3//# Associated Universities, Inc. Washington DC, USA.
4//#
5//# This library is free software; you can redistribute it and/or modify it
6//# under the terms of the GNU Library General Public License as published by
7//# the Free Software Foundation; either version 2 of the License, or (at your
8//# option) any later version.
9//#
10//# This library is distributed in the hope that it will be useful, but WITHOUT
11//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
12//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
13//# License for more details.
14//#
15//# You should have received a copy of the GNU Library General Public License
16//# along with this library; if not, write to the Free Software Foundation,
17//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
18//#
19//# Correspondence concerning AIPS++ should be addressed as follows:
20//# Internet email: aips2-request@nrao.edu.
21//# Postal address: AIPS++ Project Office
22//# National Radio Astronomy Observatory
23//# 520 Edgemont Road
24//# Charlottesville, VA 22903-2475 USA
25//#
26//# $Id$
27
28#ifndef CASA_AIPSRCVALUE_H
29#define CASA_AIPSRCVALUE_H
30
31#include <casacore/casa/aips.h>
32#include <casacore/casa/BasicSL/String.h>
33#include <casacore/casa/Containers/Block.h>
34#include <casacore/casa/System/Aipsrc.h>
35
36#include <mutex>
37
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward declarations
41class Unit;
42
43// <summary> Class to read values from the Aipsrc general resource files
44// </summary>
45
46// <use visibility=export>
47
48// <reviewed reviewer="mhaller" date="1997/10/08" tests="tAipsrcValue" demos="">
49// </reviewed>
50
51// <prerequisite>
52// <li> <linkto class=Aipsrc>Aipsrc</linkto>
53// </prerequisite>
54//
55// <etymology>
56// A class for getting values from the Aipsrc files
57// </etymology>
58//
59// <synopsis>
60// The static AipsrcValue class can get typed values from the Aipsrc
61// resource files.<br>
62// The basic interaction with the class is with the static keyword match
63// functions:
64// <srcblock>
65// Bool AipsrcValue<Type>::find(Type &result, const String &keyword)
66// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
67// const Type &deflt)
68// </srcblock>
69// comparable to the standard (String) <linkto class=Aipsrc>Aipsrc</linkto>
70// find.<br>
71// If the resource file contains a multi-valued keyword, use the
72// <linkto class=AipsrcVector>AipsrcVector</linkto> class instead.
73//
74// The class is templated. For ease of use typedefs are provided for:
75// <srcblock>
76// AipsrcDouble, AipsrcInt, AipsrcBool, AipsrcString
77// AipsrcVDouble, AipsrcVInt, AipsrcVBool, AipsrcVString
78// </srcblock>
79// In addition to the above finds, special finds:
80// <srcblock>
81// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
82// const Unit &defun, const Unit &resun)
83// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
84// const Unit &defun, const Unit &resun,
85// const Type &deflt)
86// </srcblock>
87// are provided. These finds will read the keyword value as a Quantity.
88// If no units are given, the defun are assumed. The result is converted
89// to the resun, before the value is returned. E.g.
90// <srcblock>
91// Double x;
92// find(x, "time.offset", "h", "d");
93// </srcblock>
94// will return:
95// <ul>
96// <li> 2.5/24 for a value specified as 2.5 in resource file
97// <li> 2.5/24 for 2:30:00
98// <li> 0.5/24 for 30min
99// <li> 0.5 for 0.5d
100// </ul>
101//
102// The class has <src>registerRC, get, set</src> functions as described in
103// <linkto class=Aipsrc>Aipsrc</linkto>. Note that registration is on a
104// per Type basis, and hence registration of the same keyword in different
105// types (and possible sets) act on different values, but with the same
106// result if no set has been done.
107//
108// Specialisation exists for <src>Bool</src>, where <src>True</src> is
109// any value string starting with one of 'yYtT123456789', and False in
110// all other cases, and no finds with Units are provided. Strings are
111// supposed to be handled by standard <linkto class=Aipsrc>Aipsrc</linkto>
112// class for single values, and a specialisation exists for the
113// <linkto class=AipsrcVector>AipsrcVector</linkto> case.
114//
115// </synopsis>
116//
117// <example>
118// <srcblock>
119// String tzoff; // result of keyword find
120// if (!AipsrcValue<Double>::find(tzoff, "time.zone.offset")) { // look for key
121// tzoff = -5;
122// };
123// </srcblock>
124// A more convenient way of accomplishing the same result is:
125// <srcblock>
126// AipsrcDouble::find(tzoff, "time.zone.offset", -5);
127// </srcblock>
128// or even:
129// <srcblock>
130// AipsrcDouble::find(tzoff, "time.zone.offset",
131// "h", "h", -5);
132// </srcblock>
133// Here the final argument is the default to use if the keyword is not found
134// at all.
135// </example>
136//
137//
138// <templating>
139// <li> All types with a <src>>></src> defined.
140// <note role=warning>
141// Since interpretation of the keyword value string is done with the standard
142// input right-shift operator, specialisations are necessary for non-standard
143// cases like Bool. They are provided. String is supposed to be handled by
144// standard Aipsrc.
145// </note>
146// </templating>
147//
148// <motivation>
149// Programs need a way to interact with the AipsrcValue files.
150// </motivation>
151//
152// <thrown>
153// <li>AipsError if the environment variables HOME and/or AIPSPATH not set.
154// </thrown>
155//
156// <todo asof="1997/08/07">
157// </todo>
158
159template <class T> class AipsrcValue : public Aipsrc {
160
161public:
162 //# Constructors
163 // Default constructor
164 // <note role=tip>
165 // A constructor (and destructor) have been provided to be able to generate
166 // a (routine-level) static register list. This had to be done since
167 // static data members are not yet implemented in the gcc compiler for
168 // templated classes. Once they are available the <tt>tlist</tt> and
169 // <tt>ntlst</tt> data can become static, constructor and desctructor and
170 // all references to the init() method can disappear.
171 // </note>
173 //# Destructor
174 // See note with constructor
176
177 //# Member functions
178 // The <src>find()</src> functions will, given a keyword, return the value
179 // of a matched keyword found in the files. If no match found the
180 // function will be False, and the default returned if specified.
181 // <group>
182 static Bool find(T &value, const String &keyword);
183 static Bool find(T &value, const String &keyword, const T &deflt);
184 // </group>
185 // These <src>find()</src> functions will, given a keyword, read the value
186 // of a matched keyword as a Quantity. If no unit has been given in the
187 // keyword value, the defun Unit will be assumed. The value returned
188 // will be converted to the resun Unit. If no match found, the default
189 // value is returned (see example above).
190 // <group>
191 static Bool find(T &value, const String &keyword,
192 const Unit &defun, const Unit &resun);
193 static Bool find(T &value, const String &keyword,
194 const Unit &defun, const Unit &resun,
195 const T &deflt);
196 // </group>
197 // Functions to register keywords for later use in get() and set(). The
198 // returned value is the index for get() and set().
199 // <group>
200 static uInt registerRC(const String &keyword,
201 const T &deflt);
202 static uInt registerRC(const String &keyword,
203 const Unit &defun, const Unit &resun,
204 const T &deflt);
205 // </group>
206
207 // Gets are like find, but using registered integers rather than names. The
208 // aipsrc file is read only once, and values can be set as well.
209 // <group>
210 static const T &get(uInt keyword);
211 // </group>
212
213 // Sets allow registered values to be set
214 // <group>
215 static void set(uInt keyword, const T &deflt);
216 // </group>
217
218 // Save registered value to <src>$HOME/.aipsrc</src>
219 static void save(uInt keyword);
220
221private:
222 //# Data
223 // The global AipsrcValue object
225 static std::mutex theirMutex;
226 // Register list
227 // <group>
230 // </group>
231
232 //# Constructors
233 // Copy constructor (not implemented)
235
236 //# Copy assignment (not implemented)
238
239 //# General member functions
240};
241
242template <>
244 const String &keyword,
245 const Unit &defun, const Unit &resun);
246
247
248// <summary> Specialization of AipsrcValue for Bool </summary>
249
250// <synopsis>
251// </synopsis>
252
253template <> class AipsrcValue<Bool> : public Aipsrc {
254public:
257 static Bool find(Bool &value, const String &keyword);
258 static Bool find(Bool &value, const String &keyword, const Bool &deflt);
259 static uInt registerRC(const String &keyword, const Bool &deflt);
260 static const Bool &get(uInt keyword);
261 static void set(uInt keyword, const Bool &deflt);
262 static void save(uInt keyword);
263private:
265 static std::mutex theirMutex;
270};
271
272
273//# Declare extern templates for often used types.
274 extern template class AipsrcValue<Bool>;
275 extern template class AipsrcValue<Int>;
276 extern template class AipsrcValue<Double>;
277 extern template class AipsrcValue<String>;
278
279} //# NAMESPACE CASACORE - END
280
281#ifndef CASACORE_NO_AUTO_TEMPLATES
282#include <casacore/casa/System/AipsrcValue.tcc>
283#endif //# CASACORE_NO_AUTO_TEMPLATES
284#endif
static Bool find(Bool &value, const String &keyword)
AipsrcValue< Bool > & operator=(const AipsrcValue< Bool > &other)
static void save(uInt keyword)
static Bool find(Bool &value, const String &keyword, const Bool &deflt)
AipsrcValue(const AipsrcValue< Bool > &other)
static uInt registerRC(const String &keyword, const Bool &deflt)
static std::mutex theirMutex
static void set(uInt keyword, const Bool &deflt)
static const Bool & get(uInt keyword)
AipsrcValue(const AipsrcValue< T > &other)
static uInt registerRC(const String &keyword, const Unit &defun, const Unit &resun, const T &deflt)
static Bool find(T &value, const String &keyword)
The find() functions will, given a keyword, return the value of a matched keyword found in the files.
~AipsrcValue()
See note with constructor.
static const T & get(uInt keyword)
Gets are like find, but using registered integers rather than names.
static Bool find(T &value, const String &keyword, const Unit &defun, const Unit &resun, const T &deflt)
static void save(uInt keyword)
Save registered value to $HOME/.aipsrc
static Bool find(T &value, const String &keyword, const T &deflt)
static Bool find(T &value, const String &keyword, const Unit &defun, const Unit &resun)
These find() functions will, given a keyword, read the value of a matched keyword as a Quantity.
AipsrcValue< T > & operator=(const AipsrcValue< T > &other)
Copy constructor (not implemented)
static uInt registerRC(const String &keyword, const T &deflt)
Functions to register keywords for later use in get() and set().
Block< String > ntlst
Block< T > tlst
Register list.
AipsrcValue()
Default constructor Tip: A constructor (and destructor) have been provided to be able to generate a ...
static void set(uInt keyword, const T &deflt)
Sets allow registered values to be set.
static AipsrcValue myp_p
The global AipsrcValue object.
static std::mutex theirMutex
simple 1-D array
Definition Block.h:200
String: the storage and methods of handling collections of characters.
Definition String.h:225
this file contains all the compiler specific defines
Definition mainpage.dox:28
unsigned int uInt
Definition aipstype.h:51
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:42
LatticeExprNode value(const LatticeExprNode &expr)
This function returns the value of the expression without a mask.