/usr/include/casacore/casa/System/Aipsrc.h is in casacore-dev 2.2.0-2.
This file is owned by root:root, with mode 0o644.
The actual contents of the file can be viewed below.
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 197 198 199 200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 215 216 217 218 219 220 221 222 223 224 225 226 227 228 229 230 231 232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251 252 253 254 255 256 257 258 259 260 261 262 263 264 265 266 267 268 269 270 271 272 273 274 275 276 277 278 279 280 281 282 283 284 285 286 287 288 289 290 291 292 293 294 295 296 297 298 299 300 301 302 303 304 305 306 307 308 309 310 311 312 313 314 315 316 317 318 319 320 321 322 323 324 325 326 327 328 329 330 331 332 333 334 335 336 337 338 339 340 341 342 343 344 345 346 347 348 349 350 351 352 353 354 355 356 357 358 359 360 361 362 363 364 365 366 367 368 369 370 371 372 373 374 375 376 377 378 379 380 381 382 383 384 385 386 387 388 389 390 391 392 393 394 395 396 397 398 399 400 401 402 403 404 405 406 407 408 409 410 411 412 413 414 415 416 417 418 419 420 421 422 423 424 425 426 427 428 429 430 431 432 433 434 435 436 437 438 | //# Aipsrc.h: Class to read the casa general resource files
//# Copyright (C) 1995,1996,1997,1998,1999,2002,2004
//# Associated Universities, Inc. Washington DC, USA.
//#
//# This library is free software; you can redistribute it and/or modify it
//# under the terms of the GNU Library General Public License as published by
//# the Free Software Foundation; either version 2 of the License, or (at your
//# option) any later version.
//#
//# This library is distributed in the hope that it will be useful, but WITHOUT
//# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
//# FITNESS FOR A PARTICULAR PURPOSE. See the GNU Library General Public
//# License for more details.
//#
//# You should have received a copy of the GNU Library General Public License
//# along with this library; if not, write to the Free Software Foundation,
//# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
//#
//# Correspondence concerning AIPS++ should be addressed as follows:
//# Internet email: aips2-request@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
//#
//# $Id$
#ifndef CASA_AIPSRC_H
#define CASA_AIPSRC_H
#include <casacore/casa/aips.h>
#include <casacore/casa/BasicSL/String.h>
#include <casacore/casa/Containers/Block.h>
#include <casacore/casa/Arrays/Vector.h>
#include <casacore/casa/OS/Mutex.h>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward declarations
template <class T> class AipsrcValue;
template <class T> class AipsrcVector;
class Aipsrc;
//# Typedefs
typedef AipsrcValue<Double> AipsrcDouble;
typedef AipsrcValue<Int> AipsrcInt;
typedef AipsrcValue<Bool> AipsrcBool;
typedef Aipsrc AipsrcString;
typedef AipsrcVector<Double> AipsrcVDouble;
typedef AipsrcVector<Int> AipsrcVInt;
typedef AipsrcVector<Bool> AipsrcVBool;
typedef AipsrcVector<String> AipsrcVString;
// <summary> Class to read the casa general resource files </summary>
// <use visibility=export>
// <reviewed reviewer="wyoung" date="1996/11/25" tests="tAipsrc" demos="">
// </reviewed>
// <prerequisite>
// <li> None
// </prerequisite>
//
// <etymology>
// A class for getting values from the casa resource files
// </etymology>
//
// <synopsis>
// The static Aipsrc class can get information from the casa resource files.
// It has the same functionality as getrc (c program used for Casacore
// installation scripts).<br>
// In addition it acts as a central clearing house between system and
// software by providing functionality to obtain Casacore system parameters
// (like AIPSPATH elements), and the possibility of storing system wide
// information provided by a class for reference by other classes. <br>
// The format of a line in a resource file is:
// <srcblock>
// # Line starting with an # in column 1 is a comment (as is an empty line)
// keyword: value
// keyword: value
// </srcblock>
// The keyword (starting at first non-blank)
// consists in general of keyword fields separated by periods:
//<srcblock>
// printer.ps.page
// measures.precession.d_interval
// measures.nutation.d_interval
// </srcblock>
// and, by preference, in lower case (but
// search is case sensitive) with an <src>_</src> as word-parts separator. <br>
// The keyword and value are separated by a <src>:</src>. 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 <src>find()</src> calls (see below) exist to
// aid.<br>
// Any part of the keyword string can be replaced by a wildcard <src>*</src>
// to indicate all values with that structure (e.g.
// <src>*.d_interval</src> would indicate in the example above both the
// precession and the nutation <src>d_interval</src>.<br>
// 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 to be looked at can be defined in the environment
// variable CASARCFILES. If undefined, the resource files searched are (in the
// given order):
// <srcblock>
// ~/.casarc
// ~/.casa/rc
// ~/.aipsrc
// $AIPSROOT/.aipsrc
// $AIPSHOST/aipsrc
// $AIPSSITE/aipsrc
// $AIPSARCH/aipsrc
// </srcblock>
// It is not an error for any of the aipsrc files to be absent or empty.
// However, it is an error if <em>HOME</em> has not been set:
// an exception will occur. AIPSPATH will in general be
// read from the global environment variables, but can, before any other
// <src>Aipsrc</src> related call, be set with the
// <src>setAipsPath()</src> call.<br>
// If AIPSPATH is not set in either way, it is set to the home directory.
// <p>
// The basic interaction with the class is with the static keyword match function
// <srcblock>Bool Aipsrc::find(String &result, const String &keyword)
// </srcblock>
// A set of
// <srcblock>Bool AipsrcValue::find(Type &result, const String &keyword, ...)
// </srcblock>
// are available to interpret the string value found.
// (see <linkto class="AipsrcValue">AipsrcValue</linkto>).<br>
// All the <src>find</src>
// functions have the ability to set a default if there is no match,
// while also unit conversion is possible.<br>
// 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 <src>>></src> will produce this result.)
// <note role=caution> The search keyword (unlike the file keyword) has no
// wildcards. The real name should, of course, be looked for.</note>
// To aid in other places, the following (static) methods are available
// to get the requested information (derived from <src>HOME</src> and
// <src>AIPSPATH</src>, computer system information and/or aipsrc keywords):
// <ul>
// <li> const String &Aipsrc::aipsRoot()
// <li> const String &Aipsrc::aipsArch()
// <li> const String &Aipsrc::aipsSite()
// <li> const String &Aipsrc::aipsHost()
// <li> const String &Aipsrc::aipsHome()
// </ul>
// Other, numeric, system information can be found in
// <linkto class=AipsrcValue>AipsrcValue</linkto>.<br>
//
// Given an AIPSPATH of
// <srcblock>/epp/aips++ sun4sol_gnu epping norma</srcblock>
// aipsSite will return
// <srcblock>/epp/aips++/sun4sol_gnu/epping</srcblock>.
//
// 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 <em>registered</em> to
// enable:
// <ul>
// <li> fast access with integer code, rather than string
// <li> ability to set values from programs if no aipsrc information given
// (a dynamic default)
// <li> update the <src>$HOME/.aipsrc</src> keyword/value list with save()
// </ul>
// <note role=tip> 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.</note>
// When saving a keyword/value pair in <src>$HOME/.aipsrc</src>, the old
// version is saved in <src>$HOME/.aipsrc.old</src>, 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
// <src>user.aipsrc.edit.keep</src> keyword.
// </synopsis>
//
// <example>
// <srcblock>
// String printerPage; // result of keyword find
// if(!Aipsrc::find(printerPage, "printer.ps.page")) { // look for keyword match
// printerPage = "notSet";
// };
// </srcblock>
// A more convenient way of accomplishing the same result is:
// <srcblock>
// Aipsrc::find(printerPage, "printer.ps.page", "notSet");
// </srcblock>
// Here the final argument is the default to use if the keyword is not found
// at all.<br>
// If you often want to know, dynamically, the current 'printer.ps.page'
// value, you could do something like:
// <srcblock>
// 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</src> list
// Aipsrc::save(pp);
// </srcblock>
// </example>
//
// <motivation>
// Programs need a way to interact with the aipsrc files.
// </motivation>
//
// <thrown>
// <li>AipsError if the environment variables HOME and/or AIPSPATH not set.
// </thrown>
//
// <todo asof="1997/08/07">
// </todo>
class Aipsrc {
public:
//# Constructors
//# Destructor
//# Copy assignment
//# Member functions
// <thrown>
// <li> AipsError if HOME environment variable not set
// </thrown>
// The <src>find()</src> 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 <src>findNoHome()</src> emulates the <src>-i</src>
// switch of getrc by bypassing the <src>~/.aipsrc</src> file.
// <group>
static Bool find(String &value, const String &keyword);
static Bool findNoHome(String &value, const String &keyword);
// </group>
// 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.
// <group>
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);
// </group>
// 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.
// <group>
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);
// </group>
// Sets foundDir to the first /firstPart/lastPart path that it finds
// present on the system, where /firstPart comes from, in order,
// this list:
// contents of prepends
// + useStd ? (., aipsHome(), aipsRoot()) : ()
// + contents of appends
static Bool findDir(String& foundDir, const String& lastPart="",
const Vector<String>& prepends=Vector<String>(),
const Vector<String>& appends=Vector<String>(),
Bool useStds=True);
// Functions to register keywords for later use in get() and set(). The
// returned value is the index for get() and set().
// <group>
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);
// </group>
// Gets are like find, but using registered integers rather than names.
// <group>
static const String &get(uInt keyword);
// get for code
static const uInt &get(uInt &code, uInt keyword);
// </group>
// Sets allow registered values to be set
// <group>
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);
// </group>
// Save a registered keyword value to <src>$HOME/.aipsrc</src>
// <group>
static void save(uInt keyword);
static void save(uInt keyword, const String tname[]);
static void save(uInt keyword, const Vector<String> &tname);
// </group>
// 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
// <src>[.]aipsrc</src> files.
static void setAipsPath(const String &path = String());
// Returns the appropriate Casacore or system variable values
// <group>
static const String &aipsRoot();
static const String &aipsArch();
static const String &aipsSite();
static const String &aipsHost();
// Returns: <src>~/aips++</src>
static const String &aipsHome();
// </group>
// The <src>reRead()</src> function, will reinitialise the static maps and read the
// aipsrc files again. It could be useful in some interactive or multi-processor
// circumstances. <src>lastRead()</src> returns the time last reRead.
// <group>
static void reRead();
static Double lastRead();
// </group>
// The following functions return the full lists of available data. They could
// be useful for debugging purposes.
// <group>
static const Block<String> &values();
static const Block<String> &patterns();
// </group>
// The following <src>show()</src> function, useful for debugging, outputs
// all keyword/value pairs found
static void show(ostream &oStream);
// Prints all info on cout
static void show();
// The following set is a general set of functions
// <group>
// 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 uInt genRestore(Vector<String> &namlst, Vector<String> &vallst,
const String &fileList);
// Save the names/values in file
static void genSave(Vector<String> &namlst, Vector<String> &vallst,
const String &fnam);
// Set (new or overwrite) keyword/value pair
static void genSet(Vector<String> &namlst, Vector<String> &vallst,
const String &nam, const String &val);
// Remove a keyword from list (False if not in list)
static Bool genUnSet(Vector<String> &namlst, Vector<String> &vallst,
const String &nam);
// Get the value of a keyword
static Bool genGet(String &val, Vector<String> &namlst, Vector<String> &vallst,
const String &nam);
// </group>
protected:
// Actual find function
static Bool find(String &value, const String &keyword,
uInt start);
// The registration function
static uInt registerRC(const String &keyword, Block<String> &nlst);
// Actual saving
static void save(const String keyword, const String val);
private:
//# Data
static Mutex theirMutex;
// Indicate files read
static volatile Bool doInit;
// Last time data was (re)read
static Double lastParse;
// List of values belonging to keywords found
static Block<String> keywordValue;
// List of patterns deducted from names
static Block<String> keywordPattern;
// The start of the non-home values
static uInt fileEnd;
// The possibly set external AIPSPATH
static String extAipsPath;
// AIPSROOT
static String root;
// AIPSARCH
static String arch;
// AIPSSITE
static String site;
// AIPSHOST
static String host;
// AIPSHOME
static String home;
// HOME
static String uhome;
// Indicate above filled
static Bool filled;
// String register list
// <group>
static Block<String> strlst;
static Block<String> nstrlst;
static Block<uInt> codlst;
static Block<String> ncodlst;
// </group>
//# General member functions
// Read in the aipsrc files, returning the number of lines found
// <group>
static void parse(Bool force=False);
static void doParse(String &fileList);
// </group>
// 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 uInt genParse(Block<String> &keywordPattern,
Block<String> &keywordValue,
uInt &fileEnd, const String &fileList);
// Locate the right keyword in the static maps
static Bool matchKeyword(uInt &where, const String &keyword,
uInt start);
// Fill in root, arch, site, host and home, and return requested nam
static const String &fillAips(const String &nam);
};
} //# NAMESPACE CASACORE - END
#endif
|