casacore
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 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward declarations
41 class 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 
159 template <class T> class AipsrcValue : public Aipsrc {
160 
161 public:
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 
221 private:
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 
242 template <>
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 
253 template <> class AipsrcValue<Bool> : public Aipsrc {
254 public:
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);
263 private:
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
Specialization of AipsrcValue for Bool.
Definition: AipsrcValue.h:253
static Bool find(Bool &value, const String &keyword)
static void save(uInt keyword)
AipsrcValue< Bool > & operator=(const AipsrcValue< Bool > &other)
static Bool find(Bool &value, const String &keyword, const Bool &deflt)
static AipsrcValue myp_p
Definition: AipsrcValue.h:264
AipsrcValue(const AipsrcValue< Bool > &other)
static uInt registerRC(const String &keyword, const Bool &deflt)
static std::mutex theirMutex
Definition: AipsrcValue.h:265
static const Bool & get(uInt keyword)
static void set(uInt keyword, const Bool &deflt)
AipsrcValue(const AipsrcValue< T > &other)
static uInt registerRC(const String &keyword, const Unit &defun, const Unit &resun, const T &deflt)
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)
The find() functions will, given a keyword, return the value of a matched keyword found in the files.
~AipsrcValue()
See note with constructor.
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.
static uInt registerRC(const String &keyword, const T &deflt)
Functions to register keywords for later use in get() and set().
Block< String > ntlst
Definition: AipsrcValue.h:229
AipsrcValue< T > & operator=(const AipsrcValue< T > &other)
Copy constructor (not implemented)
Block< T > tlst
Register list.
Definition: AipsrcValue.h:228
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.
Definition: AipsrcValue.h:224
static std::mutex theirMutex
Definition: AipsrcValue.h:225
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.