Aipsrc.h

Classes

Aipsrc -- Class to read the aipsrc general resource files (full description)

class Aipsrc

Interface

Public Members

static Bool find(String &value, const String &keyword)

static Bool findNoHome(String &value, const String &keyword)

static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[])

static Bool find(uInt &value, const String &keyword, const Vector<String> &tname)

static Bool find(String &value, const String &keyword, const String &deflt)

static Bool findNoHome(String &value, const String &keyword, const String &deflt)

static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[], const String &deflt)

static Bool find(uInt &value, const String &keyword, const Vector<String> &tname, const String &deflt)

static uInt registerRC(const String &keyword, const String &deflt)

static uInt registerRC(const String &keyword, Int Nname, const String tname[], const String &deflt)

static uInt registerRC(const String &keyword, const Vector<String> &tname, const String &deflt)

static const String &get(uInt keyword)

static const uInt &get(uInt &code, uInt keyword)

static void set(uInt keyword, const String &deflt)

static void set(uInt keyword, Int Nname, const String tname[], const String &deflt)

static void set(uInt keyword, const Vector<String> &tname, const String &deflt)

static void save(uInt keyword)

static void save(uInt keyword, const String tname[])

static void save(uInt keyword, const Vector<String> &tname)

static void setAipsPath(const String &path = String())

static const String &aipsRoot()

static const String &aipsArch()

static const String &aipsSite()

static const String &aipsHost()

static const String &aipsHome()

static void reRead()

static Double lastRead()

static const Block<String> &values()

static const Block<String> &patterns()

static void show(ostream &oStream)

static void show()

static uInt genRestore(Vector<String> &namlst, Vector<String> &vallst, const String &fileList)

static void genSave(Vector<String> &namlst, Vector<String> &vallst, const String &fnam)

static void genSet(Vector<String> &namlst, Vector<String> &vallst, const String &nam, const String &val)

static Bool genUnSet(Vector<String> &namlst, Vector<String> &vallst, const String &nam)

static Bool genGet(String &val, Vector<String> &namlst, Vector<String> &vallst, const String &nam)

Protected Members

static Bool find(String &value, const String &keyword, uInt start)

static uInt registerRC(const String &keyword, Block<String> &nlst)

static void save(const String keyword, const String val)

Private Members

static uInt parse()

static uInt parse(String &fileList)

static uInt genParse(Block<String> &keywordPattern, Block<String> &keywordValue, uInt &fileEnd, const String &fileList)

static Bool matchKeyword(uInt &where, const String &keyword, uInt start)

static const String &fillAips(const String &nam)

Description

Review Status

Reviewed By:

wyoung

Date Reviewed:

1996/11/25

Programs:

Tests:

tAipsrc

Prerequisite

None

Etymology

A class for getting values from the aipsrc files

Synopsis

The static Aipsrc class can get information from the aipsrc resource files. It has the same functionality as getrc (c program used for aips++ installation scripts).
In addition it acts as a central clearing house between system and software by providing functionality to obtain aips++ system parameters (like AIPSPATH elements), and the possibility of storing system wide information provided by a class for reference by other classes.
The format of a line in a resource file is:

	# Line starting with an # in column 1 is a comment (as is an empty line)
	keyword:   value
	keyword:   value

The keyword (starting at first non-blank) consists in general of keyword fields separated by periods:

	printer.ps.page
	measures.precession.d_interval
 	measures.nutation.d_interval

and, by preference, in lower case (but search is case sensitive) with an _ as word-parts separator.
The keyword and value are separated by a :. The value is the string from the first non-whitespace character after the separator to the end of the line. Interpretation of the string is in general the program's responsibility, but special find() calls (see below) exist to aid.
Any part of the keyword string can be replaced by a wildcard * to indicate all values with that structure (e.g. *.d_interval would indicate in the example above both the precession and the nutation d_interval.
A match between a keyword to be found and a keyword in the resource files will be the first match (taking wildcards into account) encountered in the search through the resource files. The resource files searched are (in the given order):

   ~/.aipsrc
   $AIPSROOT/.aipsrc
   $AIPSHOST/aipsrc
   $AIPSSITE/aipsrc
   $AIPSARCH/aipsrc

It is not an error for any of the aipsrc files to be absent or empty. However, it is an error if either HOME or AIPSPATH has not been set: an exception will occur. AIPSPATH will in general be read from the global environment variables, but can, before any other Aipsrc related call, be set with the setAipsPath() call.
The basic interaction with the class is with the static keyword match function

    Bool Aipsrc::find(String &result, const String &keyword)

A set of

    Bool AipsrcValue::find(Type &result, const String &keyword, ...)

are available to interpret the string value found. (see AipsrcValue).
All the find functions have the ability to set a default if there is no match, while also unit conversion is possible.
The Bool return indicates if the keyword was found, and, in the case of the interpretative finds, if an 'important' format error was found (e.g. '+12a' will be accepted as a Double, with a result of '12', since the standard double conversion in >> will produce this result.)

The search keyword (unlike the file keyword) has no wildcards. The real name should, of course, be looked for.

To aid in other places, the following (static) methods are available to get the requested information (derived from HOME and AIPSPATH, computer system information and/or aipsrc keywords):

const String &Aipsrc::aipsRoot()
const String &Aipsrc::aipsArch()
const String &Aipsrc::aipsSite()
const String &Aipsrc::aipsHost()
const String &Aipsrc::aipsHome() -- ~/aips++

Other, numeric, system information can be found in AipsrcValue.

Given an AIPSPATH of

/epp/aips++ sun4sol_gnu epping norma

aipsSite will return

/epp/aips++/sun4sol_gnu/epping

The basic find above reacts with the aipsrc files available. If regular access is necessary (e.g. a lot of routines have to check independently a certain integration time limit), keywords can be registered to enable:

fast access with integer code, rather than string
ability to set values from programs if no aipsrc information given (a dynamic default)
update the $HOME/.aipsrc keyword/value list with save()

The registered value is never equal to zero, hence a zero value can be used to check if registration is done. Also, registering the same keyword twice is safe, and will produce the same value.

When saving a keyword/value pair in $HOME/.aipsrc, the old version is saved in $HOME/.aipsrc.old, before the keyword/value pair is prepended to the file. A limited number of edits of the same keyword is preserved only (default 5, changeable with the user.aipsrc.edit.keep keyword.

Example

  String printerPage;		// result of keyword find
  if(!Aipsrc::find(printerPage, "printer.ps.page")) {	// look for keyword match
    printerPage = "notSet";
  };

A more convenient way of accomplishing the same result is:

    Aipsrc::find(printerPage, "printer.ps.page", "notSet");

Here the final argument is the default to use if the keyword is not found at all.
If you often want to know, dynamically, the current 'printer.ps.page' value, you could do something like:

	static uInt pp = Aipsrc::registerRC("printer.ps.page", "noSet");
	String printerPage = Aipsrc::get(pp);
 // Processing, and maybe somewhere else:
	Aipsrc::set(pp, "nowSet");
 // ...
	printerPage = Aipsrc::get(pp);
 // and save it to the <src>$HOME/.aipsrc list
	Aipsrc::save(pp);
 
 

 
Motivation
 Programs need a way to interact with the aipsrc files.
 

 
Thrown Exceptions

    AipsError if the environment variables HOME and/or AIPSPATH not set.
 

 
To Do

 

Member Description

static Bool find(String &value, const String &keyword)

static Bool findNoHome(String &value, const String &keyword)




 
Thrown Exceptions

  AipsError if HOME or AIPSPATH environment variable not set
  
 The find() functions will, given a keyword, return the value
 with a matched keyword found in the files. If no match found the
 function will be False. The findNoHome() emulates the -i
 switch of getrc by bypassing the ~/.aipsrc file.
 

static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[])

static Bool find(uInt &value, const String &keyword, const Vector<String> &tname)


 These finds check a (possible) value of the keyword against a list
 of coded values provided, and return an index into the list (N if not
 found). Matching is minimax, case insensitive. Always better to use
 the one with default. return is False if no keyword or no match.
 

static Bool find(String &value, const String &keyword, const String &deflt)

static Bool findNoHome(String &value, const String &keyword, const String &deflt)

static Bool find(uInt &value, const String &keyword, Int Nname, const String tname[], const String &deflt)

static Bool find(uInt &value, const String &keyword, const Vector<String> &tname, const String &deflt)

 This find usually saves you some lines of code, since you can supply the
 default you want to use when no such keyword is defined.
 If the return value is False, the keyword was not found and the default
 was used.
 

static uInt registerRC(const String &keyword, const String &deflt)

static uInt registerRC(const String &keyword, Int Nname, const String tname[], const String &deflt)

static uInt registerRC(const String &keyword, const Vector<String> &tname, const String &deflt)


 Functions to register keywords for later use in get() and set(). The
 returned value is the index for get() and set().
 
static const uInt &get(uInt &code, uInt keyword)

 Gets are like find, but using registered integers rather than names.
 

 get for code

static const String &get(uInt keyword)


 Gets are like find, but using registered integers rather than names.
 

static void set(uInt keyword, const String &deflt)

static void set(uInt keyword, Int Nname, const String tname[], const String &deflt)

static void set(uInt keyword, const Vector<String> &tname, const String &deflt)


 Sets allow registered values to be set
 

static void save(uInt keyword)

static void save(uInt keyword, const String tname[])

static void save(uInt keyword, const Vector<String> &tname)


 Save a registered keyword value to $HOME/.aipsrc
 
static void setAipsPath(const String &path = String())

 Set an AIPSPATH that should be used in stead of a global AIPSPATH.
 This call should be made before any Aipsrc related call. The AIPSPATH
 will have up to 4 fields (which can all be empty) giving the root, host,
 site and arch directory that will be searched for possible
 [.]aipsrc files.
static const String &aipsHome()

 Returns the appropriate AIPS++ or system variable values
 

 Returns: ~/aips++

static const String &aipsRoot()

static const String &aipsArch()

static const String &aipsSite()

static const String &aipsHost()


 Returns the appropriate AIPS++ or system variable values
 

static void reRead()

static Double lastRead()


 The reRead() function, will reinitialise the static maps and read the
 aipsrc files again. It could be useful in some interactive or multi-processor 
 circumstances. lastRead() returns the time last reRead.
 

static const Block<String> &values()

static const Block<String> &patterns()



 The following functions return the full lists of available data. They could
 be useful for debugging purposes.
 
static void show(ostream &oStream)

 The following show() function, useful for debugging, outputs 
 all keyword/value pairs found
static void show()
 Prints all info on cout
static uInt genRestore(Vector<String> &namlst, Vector<String> &vallst, const String &fileList)
 The following set is a general set of functions
 

 Read aipsrc type files (without wildcards), and return the unique names
 and values in the Vector arguments. The return value is number of names.
static void genSave(Vector<String> &namlst, Vector<String> &vallst, const String &fnam)
 The following set is a general set of functions
 

 Save the names/values in file
static void genSet(Vector<String> &namlst, Vector<String> &vallst, const String &nam, const String &val)
 The following set is a general set of functions
 

 Set (new or overwrite) keyword/value pair
static Bool genUnSet(Vector<String> &namlst, Vector<String> &vallst, const String &nam)
 The following set is a general set of functions
 

 Remove a keyword from list (False if not in list)
static Bool genGet(String &val, Vector<String> &namlst, Vector<String> &vallst, const String &nam)
 The following set is a general set of functions
 

 Get the value of a keyword
static Bool find(String &value, const String &keyword, uInt start)
 Actual find function
static uInt registerRC(const String &keyword, Block<String> &nlst)
 The registration function
static void save(const String keyword, const String val)
 Actual saving

static uInt parse()

static uInt parse(String &fileList)


 Read in the aipsrc files, returning the number of lines found
 
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. It will
 return the list of Patterns and values found, and the last keyword number
 of first file in list.
static Bool matchKeyword(uInt &where, const String &keyword, uInt start)

 Locate the right keyword in the static maps
static const String &fillAips(const String &nam)
 Fill in root, arch, site, host and home, and return requested nam