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
38namespace casacore { //# NAMESPACE CASACORE - BEGIN
39
40//# Forward declarations
41template <class T> class AipsrcValue;
42template <class T> class AipsrcVector;
43class 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
219class Aipsrc {
220
221public:
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.
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)
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
375protected:
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
385private:
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
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 String arch
AIPSARCH.
Definition: Aipsrc.h:402
static const String & aipsHost()
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 const String & aipsArch()
static Bool find(String &value, const String &keyword, uInt start)
Actual find function.
static const String & aipsHome()
Returns: ~/aips++
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 & aipsRoot()
Returns the appropriate Casacore or system variable values.
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 & get(uInt keyword)
Gets are like find, but using registered integers rather than names.
static void show(ostream &oStream)
The following show() function, useful for debugging, outputs all keyword/value pairs found.
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 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 Block< String > & patterns()
static const String & aipsSite()
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 const uInt & get(uInt &code, uInt keyword)
get for code
static const Block< String > & values()
The following functions return the full lists of available data.
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 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 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:46
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