Loading...
Searching...
No Matches
AipsrcValue.h
Go to the documentation of this file.
//# AipsrcValue.h: Class to read values from the Aipsrc general resource files
//# Copyright (C) 1995,1996,1997,1999,2002,2003
//# 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: casa-feedback@nrao.edu.
//# Postal address: AIPS++ Project Office
//# National Radio Astronomy Observatory
//# 520 Edgemont Road
//# Charlottesville, VA 22903-2475 USA
#ifndef CASA_AIPSRCVALUE_H
#define CASA_AIPSRCVALUE_H
#include <casacore/casa/aips.h>
#include <casacore/casa/BasicSL/String.h>
#include <casacore/casa/System/Aipsrc.h>
#include <mutex>
#include <vector>
namespace casacore { //# NAMESPACE CASACORE - BEGIN
//# Forward declarations
class Unit;
// <summary> Class to read values from the Aipsrc general resource files
// </summary>
// <use visibility=export>
// <reviewed reviewer="mhaller" date="1997/10/08" tests="tAipsrcValue" demos="">
// </reviewed>
// <prerequisite>
// <li> <linkto class=Aipsrc>Aipsrc</linkto>
// </prerequisite>
//
// <etymology>
// A class for getting values from the Aipsrc files
// </etymology>
//
// <synopsis>
// The static AipsrcValue class can get typed values from the Aipsrc
// resource files.<br>
// The basic interaction with the class is with the static keyword match
// functions:
// <srcblock>
// Bool AipsrcValue<Type>::find(Type &result, const String &keyword)
// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
// const Type &deflt)
// </srcblock>
// comparable to the standard (String) <linkto class=Aipsrc>Aipsrc</linkto>
// find.<br>
// If the resource file contains a multi-valued keyword, use the
// <linkto class=AipsrcVector>AipsrcVector</linkto> class instead.
//
// The class is templated. For ease of use typedefs are provided for:
// <srcblock>
// AipsrcDouble, AipsrcInt, AipsrcBool, AipsrcString
// AipsrcVDouble, AipsrcVInt, AipsrcVBool, AipsrcVString
// </srcblock>
// In addition to the above finds, special finds:
// <srcblock>
// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
// const Unit &defun, const Unit &resun)
// Bool AipsrcValue<Type>::find(Type &result, const String &keyword,
// const Unit &defun, const Unit &resun,
// const Type &deflt)
// </srcblock>
// are provided. These finds will read the keyword value as a Quantity.
// If no units are given, the defun are assumed. The result is converted
// to the resun, before the value is returned. E.g.
// <srcblock>
// Double x;
// find(x, "time.offset", "h", "d");
// </srcblock>
// will return:
// <ul>
// <li> 2.5/24 for a value specified as 2.5 in resource file
// <li> 2.5/24 for 2:30:00
// <li> 0.5/24 for 30min
// <li> 0.5 for 0.5d
// </ul>
//
// The class has <src>registerRC, get, set</src> functions as described in
// <linkto class=Aipsrc>Aipsrc</linkto>. Note that registration is on a
// per Type basis, and hence registration of the same keyword in different
// types (and possible sets) act on different values, but with the same
// result if no set has been done.
//
// Specialisation exists for <src>Bool</src>, where <src>True</src> is
// any value string starting with one of 'yYtT123456789', and False in
// all other cases, and no finds with Units are provided. Strings are
// supposed to be handled by standard <linkto class=Aipsrc>Aipsrc</linkto>
// class for single values, and a specialisation exists for the
// <linkto class=AipsrcVector>AipsrcVector</linkto> case.
//
// </synopsis>
//
// <example>
// <srcblock>
// String tzoff; // result of keyword find
// if (!AipsrcValue<Double>::find(tzoff, "time.zone.offset")) { // look for key
// tzoff = -5;
// };
// </srcblock>
// A more convenient way of accomplishing the same result is:
// <srcblock>
// AipsrcDouble::find(tzoff, "time.zone.offset", -5);
// </srcblock>
// or even:
// <srcblock>
// AipsrcDouble::find(tzoff, "time.zone.offset",
// "h", "h", -5);
// </srcblock>
// Here the final argument is the default to use if the keyword is not found
// at all.
// </example>
//
//
// <templating>
// <li> All types with a <src>>></src> defined.
// <note role=warning>
// Since interpretation of the keyword value string is done with the standard
// input right-shift operator, specialisations are necessary for non-standard
// cases like Bool. They are provided. String is supposed to be handled by
// standard Aipsrc.
// </note>
// </templating>
//
// <motivation>
// Programs need a way to interact with the AipsrcValue files.
// </motivation>
//
// <thrown>
// <li>AipsError if the environment variables HOME and/or AIPSPATH not set.
// </thrown>
//
// <todo asof="1997/08/07">
// </todo>
template <class T> class AipsrcValue : public Aipsrc {
public:
//# Member functions
// The <src>find()</src> functions will, given a keyword, return the value
// of a matched keyword found in the files. If no match found the
// function will be False, and the default returned if specified.
// <group>
static Bool find(T &value, const String &keyword);
static Bool find(T &value, const String &keyword, const T &deflt);
// </group>
// These <src>find()</src> functions will, given a keyword, read the value
// of a matched keyword as a Quantity. If no unit has been given in the
// keyword value, the default_unit Unit will be assumed. The value returned
// will be converted to the result_unit Unit. If no match found, the default
// value is returned (see example above).
// <group>
static Bool find(T &value, const String &keyword,
const Unit &default_unit, const Unit &result_unit);
static Bool find(T &value, const String &keyword,
const Unit &default_unit, const Unit &result_unit,
const T &deflt);
// </group>
// 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 T &deflt);
static uInt registerRC(const String &keyword,
const Unit &default_unit, const Unit &result_unit,
const T &deflt);
// </group>
// Gets are like find, but using registered integers rather than names. The
// aipsrc file is read only once, and values can be set as well.
// This function can't return a reference, because this would give access to
// the value without protection by the mutex.
// <group>
static const T get(uInt keyword);
// </group>
// Sets allow registered values to be set
// <group>
static void set(uInt keyword, const T &deflt);
// </group>
// Save registered value to <src>$HOME/.aipsrc</src>
static void save(uInt keyword);
private:
//# Data
// The global AipsrcValue object
inline static std::mutex theirMutex;
// Register list
// <group>
inline static std::vector<T> tlst;
inline static std::vector<String> ntlst;
// </group>
};
template <>
Bool AipsrcValue<String>::find(String &value,
const String &keyword,
const Unit &defun, const Unit &resun);
// <summary> Specialization of AipsrcValue for Bool </summary>
// <synopsis>
// </synopsis>
template <> class AipsrcValue<Bool> : public Aipsrc {
public:
static Bool find(Bool &value, const String &keyword);
static Bool find(Bool &value, const String &keyword, const Bool &deflt);
static uInt registerRC(const String &keyword, const Bool &deflt);
static Bool get(uInt keyword);
static void set(uInt keyword, const Bool &deflt);
static void save(uInt keyword);
private:
inline static std::mutex theirMutex;
static_assert(sizeof(unsigned char) == sizeof(bool));
inline static std::vector<unsigned char> tlst;
inline static std::vector<String> ntlst;
};
//# Declare extern templates for often used types.
extern template class AipsrcValue<Bool>;
extern template class AipsrcValue<Int>;
extern template class AipsrcValue<Double>;
extern template class AipsrcValue<String>;
} //# NAMESPACE CASACORE - END
#ifndef CASACORE_NO_AUTO_TEMPLATES
#include <casacore/casa/System/AipsrcValue.tcc>
#endif //# CASACORE_NO_AUTO_TEMPLATES
#endif
casacore::AipsrcValue< Bool >::ntlst
static std::vector< String > ntlst
Definition AipsrcValue.h:242
casacore::AipsrcValue< Bool >::find
static Bool find(Bool &value, const String &keyword)
casacore::AipsrcValue< Bool >::tlst
static std::vector< unsigned char > tlst
Definition AipsrcValue.h:241
casacore::AipsrcValue< Bool >::save
static void save(uInt keyword)
casacore::AipsrcValue< Bool >::find
static Bool find(Bool &value, const String &keyword, const Bool &deflt)
casacore::AipsrcValue< Bool >::get
static Bool get(uInt keyword)
casacore::AipsrcValue< Bool >::registerRC
static uInt registerRC(const String &keyword, const Bool &deflt)
casacore::AipsrcValue< Bool >::theirMutex
static std::mutex theirMutex
Definition AipsrcValue.h:239
casacore::AipsrcValue< Bool >::set
static void set(uInt keyword, const Bool &deflt)
casacore::AipsrcValue
Definition AipsrcValue.h:157
casacore::AipsrcValue::get
static const T get(uInt keyword)
Gets are like find, but using registered integers rather than names.
casacore::AipsrcValue::find
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.
casacore::AipsrcValue::registerRC
static uInt registerRC(const String &keyword, const Unit &default_unit, const Unit &result_unit, const T &deflt)
casacore::AipsrcValue::find
static Bool find(T &value, const String &keyword, const Unit &default_unit, const Unit &result_unit)
These find() functions will, given a keyword, read the value of a matched keyword as a Quantity.
casacore::AipsrcValue< Double >::tlst
static std::vector< Double > tlst
Definition AipsrcValue.h:212
casacore::AipsrcValue::save
static void save(uInt keyword)
Save registered value to $HOME/.aipsrc.
casacore::AipsrcValue::find
static Bool find(T &value, const String &keyword, const T &deflt)
casacore::AipsrcValue::registerRC
static uInt registerRC(const String &keyword, const T &deflt)
Functions to register keywords for later use in get() and set().
casacore::AipsrcValue< Double >::ntlst
static std::vector< String > ntlst
Definition AipsrcValue.h:213
casacore::AipsrcValue::set
static void set(uInt keyword, const T &deflt)
Sets allow registered values to be set.
casacore::AipsrcValue::find
static Bool find(T &value, const String &keyword, const Unit &default_unit, const Unit &result_unit, const T &deflt)
casacore::AipsrcValue< Double >::theirMutex
static std::mutex theirMutex
Definition AipsrcValue.h:209
casacore::Aipsrc::Aipsrc
Aipsrc()=delete
casacore::String
String: the storage and methods of handling collections of characters.
Definition String.h:223
casacore::Unit
Definition Unit.h:187
casacore
this file contains all the compiler specific defines
Definition mainpage.dox:28
casacore::uInt
unsigned int uInt
Definition aipstype.h:49
casacore::Bool
bool Bool
Define the standard types used by Casacore.
Definition aipstype.h:40
casacore::value
NewDelAllocator< T > NewDelAllocator< T >::value
Definition Allocator.h:369