casacore
Aipsrc.h
Go to the documentation of this file.
1 //# Aipsrc.h: Class to read the casa general resource files
2 //# Copyright (C) 1995,1996,1997,1998,1999,2002,2004,2016
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_AIPSRC_H
29 #define CASA_AIPSRC_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/Arrays/Vector.h>
35 
36 #include <mutex>
37 
38 namespace casacore { //# NAMESPACE CASACORE - BEGIN
39 
40 //# Forward declarations
41 template <class T> class AipsrcValue;
42 template <class T> class AipsrcVector;
43 class Aipsrc;
44 
45 //# Typedefs
54 
55 
56 // <summary> Class to read the casa general resource files </summary>
57 
58 // <use visibility=export>
59 
60 // <reviewed reviewer="wyoung" date="1996/11/25" tests="tAipsrc" demos="">
61 // </reviewed>
62 
63 // <prerequisite>
64 // <li> None
65 // </prerequisite>
66 //
67 // <etymology>
68 // A class for getting values from the casa resource files
69 // </etymology>
70 //
71 // <synopsis>
72 // The static Aipsrc class can get information from the casa resource files.
73 // It has the same functionality as getrc (c program used for Casacore
74 // installation scripts).<br>
75 // In addition it acts as a central clearing house between system and
76 // software by providing functionality to obtain Casacore system parameters
77 // (like AIPSPATH elements), and the possibility of storing system wide
78 // information provided by a class for reference by other classes. <br>
79 // The format of a line in a resource file is:
80 // <srcblock>
81 // # Line starting with an # in column 1 is a comment (as is an empty line)
82 // keyword: value
83 // keyword: value
84 // </srcblock>
85 // The keyword (starting at first non-blank)
86 // consists in general of keyword fields separated by periods:
87 //<srcblock>
88 // printer.ps.page
89 // measures.precession.d_interval
90 // measures.nutation.d_interval
91 // </srcblock>
92 // and, by preference, in lower case (but
93 // search is case sensitive) with an <src>_</src> as word-parts separator. <br>
94 // The keyword and value are separated by a <src>:</src>. The value is the string
95 // from the first non-whitespace character after the separator to the end of
96 // the line. Interpretation of the string is in general the program's
97 // responsibility, but special <src>find()</src> calls (see below) exist to
98 // aid.<br>
99 // Any part of the keyword string can be replaced by a wildcard <src>*</src>
100 // to indicate all values with that structure (e.g.
101 // <src>*.d_interval</src> would indicate in the example above both the
102 // precession and the nutation <src>d_interval</src>.<br>
103 // A match between a keyword to be found and a keyword in the resource files
104 // will be the first match (taking wildcards into account) encountered in the
105 // search through the resource files.
106 // The resource files to be looked at can be defined in the environment
107 // variable CASARCFILES. If undefined, the resource files searched are (in the
108 // given order):
109 // <srcblock>
110 // ~/.casarc
111 // ~/.casa/rc
112 // ~/.aipsrc
113 // $AIPSROOT/.aipsrc
114 // $AIPSHOST/aipsrc
115 // $AIPSSITE/aipsrc
116 // $AIPSARCH/aipsrc
117 // </srcblock>
118 // It is not an error for any of the aipsrc files to be absent or empty.
119 // However, it is an error if <em>HOME</em> has not been set:
120 // an exception will occur. AIPSPATH will in general be
121 // read from the global environment variables, but can, before any other
122 // <src>Aipsrc</src> related call, be set with the
123 // <src>setAipsPath()</src> call.<br>
124 // If AIPSPATH is not set in either way, it is set to the home directory.
125 // <p>
126 // The basic interaction with the class is with the static keyword match function
127 // <srcblock>Bool Aipsrc::find(String &result, const String &keyword)
128 // </srcblock>
129 // A set of
130 // <srcblock>Bool AipsrcValue::find(Type &result, const String &keyword, ...)
131 // </srcblock>
132 // are available to interpret the string value found.
133 // (see <linkto class="AipsrcValue">AipsrcValue</linkto>).<br>
134 // All the <src>find</src>
135 // functions have the ability to set a default if there is no match,
136 // while also unit conversion is possible.<br>
137 // The Bool return indicates if the keyword was found, and, in the case of the
138 // interpretative finds, if an 'important' format error was found (e.g.
139 // '+12a' will be accepted as a Double, with a result of '12', since the
140 // standard double conversion in <src>>></src> will produce this result.)
141 // <note role=caution> The search keyword (unlike the file keyword) has no
142 // wildcards. The real name should, of course, be looked for.</note>
143 // To aid in other places, the following (static) methods are available
144 // to get the requested information (derived from <src>HOME</src> and
145 // <src>AIPSPATH</src>, computer system information and/or aipsrc keywords):
146 // <ul>
147 // <li> const String &Aipsrc::aipsRoot()
148 // <li> const String &Aipsrc::aipsArch()
149 // <li> const String &Aipsrc::aipsSite()
150 // <li> const String &Aipsrc::aipsHost()
151 // <li> const String &Aipsrc::aipsHome()
152 // </ul>
153 // Other, numeric, system information can be found in
154 // <linkto class=AipsrcValue>AipsrcValue</linkto>.<br>
155 //
156 // Given an AIPSPATH of
157 // <srcblock>/epp/aips++ sun4sol_gnu epping norma</srcblock>
158 // aipsSite will return
159 // <srcblock>/epp/aips++/sun4sol_gnu/epping</srcblock>.
160 //
161 // The basic find above reacts with the aipsrc files available. If regular
162 // access is necessary (e.g. a lot of routines have to check independently a
163 // certain integration time limit), keywords can be <em>registered</em> to
164 // enable:
165 // <ul>
166 // <li> fast access with integer code, rather than string
167 // <li> ability to set values from programs if no aipsrc information given
168 // (a dynamic default)
169 // <li> update the <src>$HOME/.aipsrc</src> keyword/value list with save()
170 // </ul>
171 // <note role=tip> The registered value is never equal to zero, hence a zero
172 // value can be used to check if registration is done. Also, registering the
173 // same keyword twice is safe, and will produce the same value.</note>
174 // When saving a keyword/value pair in <src>$HOME/.aipsrc</src>, the old
175 // version is saved in <src>$HOME/.aipsrc.old</src>, before the keyword/value
176 // pair is prepended to the file. A limited number of edits of the same keyword
177 // is preserved only (default 5, changeable with the
178 // <src>user.aipsrc.edit.keep</src> keyword.
179 // </synopsis>
180 //
181 // <example>
182 // <srcblock>
183 // String printerPage; // result of keyword find
184 // if(!Aipsrc::find(printerPage, "printer.ps.page")) { // look for keyword match
185 // printerPage = "notSet";
186 // };
187 // </srcblock>
188 // A more convenient way of accomplishing the same result is:
189 // <srcblock>
190 // Aipsrc::find(printerPage, "printer.ps.page", "notSet");
191 // </srcblock>
192 // Here the final argument is the default to use if the keyword is not found
193 // at all.<br>
194 // If you often want to know, dynamically, the current 'printer.ps.page'
195 // value, you could do something like:
196 // <srcblock>
197 // static uInt pp = Aipsrc::registerRC("printer.ps.page", "noSet");
198 // String printerPage = Aipsrc::get(pp);
199 // // Processing, and maybe somewhere else:
200 // Aipsrc::set(pp, "nowSet");
201 // // ...
202 // printerPage = Aipsrc::get(pp);
203 // // and save it to the <src>$HOME/.aipsrc</src> list
204 // Aipsrc::save(pp);
205 // </srcblock>
206 // </example>
207 //
208 // <motivation>
209 // Programs need a way to interact with the aipsrc files.
210 // </motivation>
211 //
212 // <thrown>
213 // <li>AipsError if the environment variables HOME and/or AIPSPATH not set.
214 // </thrown>
215 //
216 // <todo asof="1997/08/07">
217 // </todo>
218 
219 class Aipsrc {
220 
221 public:
222  //# Constructors
223 
224  //# Destructor
225 
226  //# Copy assignment
227 
228  //# Member functions
229  // <thrown>
230  // <li> AipsError if HOME environment variable not set
231  // </thrown>
232  // The <src>find()</src> functions will, given a keyword, return the value
233  // with a matched keyword found in the files. If no match found the
234  // function will be False. The <src>findNoHome()</src> emulates the <src>-i</src>
235  // switch of getrc by bypassing the <src>~/.aipsrc</src> file.
236  // <group>
237  static Bool find(String &value, const String &keyword);
238  static Bool findNoHome(String &value, const String &keyword);
239  // </group>
240 
241  // These finds check a (possible) value of the keyword against a list
242  // of coded values provided, and return an index into the list (N if not
243  // found). Matching is minimax, case insensitive. Always better to use
244  // the one with default. return is False if no keyword or no match.
245  // <group>
246  static Bool find(uInt &value, const String &keyword,
247  Int Nname, const String tname[]);
248  static Bool find(uInt &value, const String &keyword,
249  const Vector<String> &tname);
250  // </group>
251  // This find usually saves you some lines of code, since you can supply the
252  // default you want to use when no such keyword is defined.
253  // If the return value is False, the keyword was not found and the default
254  // was used.
255  // <group>
256  static Bool find(String &value, const String &keyword,
257  const String &deflt);
258  static Bool findNoHome(String &value, const String &keyword,
259  const String &deflt);
260  static Bool find(uInt &value, const String &keyword,
261  Int Nname, const String tname[], const String &deflt);
262  static Bool find(uInt &value, const String &keyword,
263  const Vector<String> &tname, const String &deflt);
264  // </group>
265 
266  // Sets foundDir to the first /firstPart/lastPart path that it finds
267  // present on the system, where /firstPart comes from, in order,
268  // this list:
269  // contents of prepends
270  // + useStd ? (., aipsHome(), aipsRoot()) : ()
271  // + contents of appends
272  static Bool findDir(String& foundDir, const String& lastPart="",
273  const Vector<String>& prepends=Vector<String>(),
274  const Vector<String>& appends=Vector<String>(),
275  Bool useStds=True);
276 
277  // Functions to register keywords for later use in get() and set(). The
278  // returned value is the index for get() and set().
279  // <group>
280  static uInt registerRC(const String &keyword,
281  const String &deflt);
282  static uInt registerRC(const String &keyword,
283  Int Nname, const String tname[], const String &deflt);
284  static uInt registerRC(const String &keyword,
285  const Vector<String> &tname, const String &deflt);
286  // </group>
287 
288  // Gets are like find, but using registered integers rather than names.
289  // <group>
290  static const String &get(uInt keyword);
291  // get for code
292  static const uInt &get(uInt &code, uInt keyword);
293  // </group>
294 
295  // Sets allow registered values to be set
296  // <group>
297  static void set(uInt keyword, const String &deflt);
298  static void set(uInt keyword,
299  Int Nname, const String tname[], const String &deflt);
300  static void set(uInt keyword,
301  const Vector<String> &tname, const String &deflt);
302  // </group>
303 
304  // Save a registered keyword value to <src>$HOME/.aipsrc</src>
305  // <group>
306  static void save(uInt keyword);
307  static void save(uInt keyword, const String tname[]);
308  static void save(uInt keyword, const Vector<String> &tname);
309  // </group>
310 
311  // Set an AIPSPATH that should be used in stead of a global AIPSPATH.
312  // This call should be made before any Aipsrc related call. The AIPSPATH
313  // will have up to 4 fields (which can all be empty) giving the root, host,
314  // site and arch directory that will be searched for possible
315  // <src>[.]aipsrc</src> files.
316  static void setAipsPath(const String &path = String());
317 
318  // Returns the appropriate Casacore or system variable values
319  // <group>
320  static const String &aipsRoot();
321  static const String &aipsArch();
322  static const String &aipsSite();
323  static const String &aipsHost();
324  // Returns: <src>~/aips++</src>
325  static const String &aipsHome();
326  // </group>
327 
328  // The <src>reRead()</src> function will reinitialise the static maps and read
329  // the aipsrc files again. It could be useful in some interactive circumstances.
330  // Note: Calling <src>reRead()</src> while using the static maps is not (thread-)safe.
331  // (Getting it right is a lot of work, but why apply settings while processing?)
332  // Note: casa_measures MeasTable.cc reads its <src>iau2000_reg</src> and
333  // <src>iau2000a_reg</src> upon first uses. Those cached values are not re-read,
334  // but only influence what <src>useIAU2000()</src> and <src>useIAU2000A()</src> return.
335  //
336  // <src>lastRead()</src> returns the time last reRead.
337  // <group>
338  static void reRead();
339  static Double lastRead();
340  // </group>
341 
342 
343  // The following functions return the full lists of available data. They could
344  // be useful for debugging purposes.
345  // <group>
346  static const Block<String> &values();
347  static const Block<String> &patterns();
348  // </group>
349 
350  // The following <src>show()</src> function, useful for debugging, outputs
351  // all keyword/value pairs found
352  static void show(ostream &oStream);
353  // Prints all info on cout
354  static void show();
355  // The following set is a general set of functions
356  // <group>
357  // Read aipsrc type files (without wildcards), and return the unique names
358  // and values in the Vector arguments. The return value is number of names.
359  static uInt genRestore(Vector<String> &namlst, Vector<String> &vallst,
360  const String &fileList);
361  // Save the names/values in file
362  static void genSave(Vector<String> &namlst, Vector<String> &vallst,
363  const String &fnam);
364  // Set (new or overwrite) keyword/value pair
365  static void genSet(Vector<String> &namlst, Vector<String> &vallst,
366  const String &nam, const String &val);
367  // Remove a keyword from list (False if not in list)
368  static Bool genUnSet(Vector<String> &namlst, Vector<String> &vallst,
369  const String &nam);
370  // Get the value of a keyword
371  static Bool genGet(String &val, Vector<String> &namlst, Vector<String> &vallst,
372  const String &nam);
373  // </group>
374 
375 protected:
376  // Actual find function
377  static Bool find(String &value, const String &keyword, uInt start);
378  // Actual find function to use during parse() without recursing into parse()
379  static Bool findNoParse(String &value, const String &keyword, uInt start);
380  // The registration function
381  static uInt registerRC(const String &keyword, Block<String> &nlst);
382  // Actual saving
383  static void save(const String keyword, const String val);
384 
385 private:
386  //# Data
387  // Object to ensure safe multi-threaded lazy single initialization
388  static std::once_flag theirCallOnceFlag;
389  // Last time data was (re)read
390  static Double lastParse;
391  // List of values belonging to keywords found
393  // List of patterns deducted from names
395  // The start of the non-home values
396  static uInt fileEnd;
397  // The possibly set external AIPSPATH
399  // AIPSROOT
400  static String root;
401  // AIPSARCH
402  static String arch;
403  // AIPSSITE
404  static String site;
405  // AIPSHOST
406  static String host;
407  // AIPSHOME
408  static String home;
409  // HOME
410  static String uhome;
411  // Indicate above filled
412  static Bool filled;
413  // String register list
414  // <group>
419  // </group>
420 
421  //# General member functions
422  // Read in the aipsrc files. Always called using theirCallOnce (except for reRead()).
423  // <group>
424  static void parse();
425  static void doParse(String &fileList);
426  // </group>
427 
428  // The following parse function can be used for any list of files. It will
429  // return the list of Patterns and values found, and the last keyword number
430  // of first file in list.
433  uInt &fileEnd, const String &fileList);
434 
435  // Locate the right keyword in the static maps
436  static Bool matchKeyword(uInt &where, const String &keyword,
437  uInt start);
438  // Fill in root, arch, site, host and home
439  static void fillAips();
440 };
441 
442 
443 } //# NAMESPACE CASACORE - END
444 
445 #endif
446 
447 
Specialization of AipsrcValue for Bool.
Definition: AipsrcValue.h:253
static uInt registerRC(const String &keyword, const Vector< String > &tname, const String &deflt)
static uInt registerRC(const String &keyword, Int Nname, const String tname[], const String &deflt)
static std::once_flag theirCallOnceFlag
Object to ensure safe multi-threaded lazy single initialization.
Definition: Aipsrc.h:388
static const String & aipsSite()
static String arch
AIPSARCH.
Definition: Aipsrc.h:402
static void reRead()
The reRead() function will reinitialise the static maps and read the aipsrc files again.
static void save(uInt keyword, const String tname[])
static Block< String > strlst
String register list.
Definition: Aipsrc.h:415
static Bool find(String &value, const String &keyword, uInt start)
Actual find function.
static uInt genParse(Block< String > &keywordPattern, Block< String > &keywordValue, uInt &fileEnd, const String &fileList)
The following parse function can be used for any list of files.
static String extAipsPath
The possibly set external AIPSPATH.
Definition: Aipsrc.h:398
static void fillAips()
Fill in root, arch, site, host and home.
static const String & aipsHost()
static void parse()
Read in the aipsrc files.
static String site
AIPSSITE.
Definition: Aipsrc.h:404
static Block< String > keywordPattern
List of patterns deducted from names.
Definition: Aipsrc.h:394
static String root
AIPSROOT.
Definition: Aipsrc.h:400
static Bool matchKeyword(uInt &where, const String &keyword, uInt start)
Locate the right keyword in the static maps.
static const String & aipsHome()
Returns: ~/aips++
static void show(ostream &oStream)
The following show() function, useful for debugging, outputs all keyword/value pairs found.
static const uInt & get(uInt &code, uInt keyword)
get for code
static void setAipsPath(const String &path=String())
Set an AIPSPATH that should be used in stead of a global AIPSPATH.
static void set(uInt keyword, const String &deflt)
Sets allow registered values to be set.
static Block< uInt > codlst
Definition: Aipsrc.h:417
static Bool find(uInt &value, const String &keyword, const Vector< String > &tname)
static void doParse(String &fileList)
static Block< String > ncodlst
Definition: Aipsrc.h:418
static uInt fileEnd
The start of the non-home values.
Definition: Aipsrc.h:396
static const Block< String > & values()
The following functions return the full lists of available data.
static const Block< String > & patterns()
static Bool findDir(String &foundDir, const String &lastPart="", const Vector< String > &prepends=Vector< String >(), const Vector< String > &appends=Vector< String >(), Bool useStds=True)
Sets foundDir to the first /firstPart/lastPart path that it finds present on the system,...
static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[])
These finds check a (possible) value of the keyword against a list of coded values provided,...
static const String & aipsRoot()
Returns the appropriate Casacore or system variable values.
static String uhome
HOME.
Definition: Aipsrc.h:410
static Block< String > keywordValue
List of values belonging to keywords found.
Definition: Aipsrc.h:392
static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[], const String &deflt)
static void set(uInt keyword, Int Nname, const String tname[], const String &deflt)
static Bool genUnSet(Vector< String > &namlst, Vector< String > &vallst, const String &nam)
Remove a keyword from list (False if not in list)
static void save(uInt keyword)
Save a registered keyword value to $HOME/.aipsrc
static Bool filled
Indicate above filled.
Definition: Aipsrc.h:412
static void genSave(Vector< String > &namlst, Vector< String > &vallst, const String &fnam)
Save the names/values in file.
static Bool findNoParse(String &value, const String &keyword, uInt start)
Actual find function to use during parse() without recursing into parse()
static void show()
Prints all info on cout.
static Double lastRead()
static Bool find(uInt &value, const String &keyword, const Vector< String > &tname, const String &deflt)
static String host
AIPSHOST.
Definition: Aipsrc.h:406
static uInt genRestore(Vector< String > &namlst, Vector< String > &vallst, const String &fileList)
The following set is a general set of functions.
static Block< String > nstrlst
Definition: Aipsrc.h:416
static const String & get(uInt keyword)
Gets are like find, but using registered integers rather than names.
static uInt registerRC(const String &keyword, const String &deflt)
Functions to register keywords for later use in get() and set().
static Double lastParse
Last time data was (re)read.
Definition: Aipsrc.h:390
static void genSet(Vector< String > &namlst, Vector< String > &vallst, const String &nam, const String &val)
Set (new or overwrite) keyword/value pair.
static void save(const String keyword, const String val)
Actual saving.
static void save(uInt keyword, const Vector< String > &tname)
static Bool findNoHome(String &value, const String &keyword, const String &deflt)
static uInt registerRC(const String &keyword, Block< String > &nlst)
The registration function.
static Bool findNoHome(String &value, const String &keyword)
static Bool find(String &value, const String &keyword)
static String home
AIPSHOME.
Definition: Aipsrc.h:408
static Bool genGet(String &val, Vector< String > &namlst, Vector< String > &vallst, const String &nam)
Get the value of a keyword.
static const String & aipsArch()
static void set(uInt keyword, const Vector< String > &tname, const String &deflt)
static Bool find(String &value, const String &keyword, const String &deflt)
This find usually saves you some lines of code, since you can supply the default you want to use when...
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
AipsrcValue< Double > AipsrcDouble
Definition: Aipsrc.h:43
AipsrcValue< Bool > AipsrcBool
Definition: Aipsrc.h:48
AipsrcVector< Bool > AipsrcVBool
Definition: Aipsrc.h:52
AipsrcValue< Int > AipsrcInt
Definition: Aipsrc.h:47
unsigned int uInt
Definition: aipstype.h:51
AipsrcVector< Int > AipsrcVInt
Definition: Aipsrc.h:51
AipsrcVector< Double > AipsrcVDouble
Definition: Aipsrc.h:50
int Int
Definition: aipstype.h:50
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.
const Bool True
Definition: aipstype.h:43
double Double
Definition: aipstype.h:55
AipsrcVector< String > AipsrcVString
Definition: Aipsrc.h:53
Aipsrc AipsrcString
Definition: Aipsrc.h:49