casa  $Rev:20696$
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines
Param.h
Go to the documentation of this file.
00001 //# Param: A simple keyword/value pair with internal help Strings.
00002 //# Copyright (C) 1993,1994,1995,1999,2000,2001
00003 //# Associated Universities, Inc. Washington DC, USA.
00004 //#
00005 //# This library is free software; you can redistribute it and/or modify it
00006 //# under the terms of the GNU Library General Public License as published by
00007 //# the Free Software Foundation; either version 2 of the License, or (at your
00008 //# option) any later version.
00009 //#
00010 //# This library is distributed in the hope that it will be useful, but WITHOUT
00011 //# ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
00012 //# FITNESS FOR A PARTICULAR PURPOSE.  See the GNU Library General Public
00013 //# License for more details.
00014 //#
00015 //# You should have received a copy of the GNU Library General Public License
00016 //# along with this library; if not, write to the Free Software Foundation,
00017 //# Inc., 675 Massachusetts Ave, Cambridge, MA 02139, USA.
00018 //#
00019 //# Correspondence concerning AIPS++ should be addressed as follows:
00020 //#        Internet email: aips2-request@nrao.edu.
00021 //#        Postal address: AIPS++ Project Office
00022 //#                        National Radio Astronomy Observatory
00023 //#                        520 Edgemont Road
00024 //#                        Charlottesville, VA 22903-2475 USA
00025 //#
00026 //# $Id: Param.h 20551 2009-03-25 00:11:33Z Malte.Marquarding $
00027 
00028 #ifndef CASA_PARAM_H
00029 #define CASA_PARAM_H
00030 
00031 
00032 #include <casa/aips.h>
00033 #include <casa/Containers/Block.h>
00034 #include <casa/BasicSL/String.h>
00035 #include <casa/IO/AipsIO.h>
00036 #include <casa/stdlib.h>
00037 #include <casa/string.h>             // need things like strlen() and such
00038 
00039 //# Forward declarations
00040 #include <casa/iosfwd.h>
00041 
00042 namespace casa { //# NAMESPACE CASA - BEGIN
00043 
00044 // <summary> 
00045 // A simple keyword/value pair with internal help Strings.
00046 // </summary>
00047 
00048 // <use visibility=local>
00049 
00050 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tParam.cc" demos="">
00051 //</reviewed>
00052 
00053 // <prerequisite>
00054 //   <li> none noted
00055 // </prerequisite>
00056 //
00057 // <etymology>
00058 // The Param class name is a shortening of "parameter" and is indicative of 
00059 // the class being designed as a keyword/value pair relating to command line
00060 // arguments.  The existing Keyword class does a much better job for most
00061 // other purposes.
00062 // </etymology>
00063 //
00064 // <synopsis>
00065 // The Param is constructed with all arguments being Strings.  This is a 
00066 // reflection of the C-type command line argument method of passing 
00067 // an integer (argc or argument count) and an array of pointers to characters
00068 // (argv or argument vector.)  If "char* argv[]" is broken into its individual
00069 // arguments they may be used to fill a Param.  The constructor pairs up a 
00070 // "key" to a value.  A help String argument is provided to assist in prompted
00071 // filling of Param values.  The expected return type may be entered as well 
00072 // as a range of potential values.  Finally, the units of the value are also 
00073 // specified.  The intent is to provide a well documented value and a "key"
00074 // by which to "call" it.
00075 //
00076 // The "getWhatever" member functions of Param convert the internal Strings 
00077 // into the desired output data type.  The Strings themselves may also be 
00078 // returned.
00079 // </synopsis> 
00080 //
00081 // <example>
00082 // <srcblock>
00083 // // we will create a Param which contains the boundary for an iteration loop.
00084 // String key("IterBound");
00085 // // give "IterBound" a default value
00086 // String value("200");
00087 // // a help String for prompting
00088 // String help("The Boundary value for the chutzpah iterator.");
00089 // // The expected return type is an integer
00090 // String type("Int");
00091 // // The range of "legal" values 
00092 // String range("10-10000");
00093 // // the units of the value
00094 // String unit("unitless"):
00095 // // Now we may build our Param
00096 // Param PleaseDontTouchMeThere(key, value, help, type, range, unit);
00097 // // to retrieve the value we use the GetInt function
00098 // for (Int i=0, i<PleaseDontTouchMeThere.getInt(); i++, chutzpah++);
00099 // </srcblock></example>
00100 //
00101 // <motivation>
00102 // The Param class was an early attempt at keywords within AIPS++.  They have 
00103 // become obsolete but hang on due to their relationship with the Input class.
00104 // </motivation>
00105 //
00106 // <todo asof="Thu 1995/04/06 21:26:43 GMT">
00107 //   <li> fix the GetStringArray() function
00108 //   <li> convert from Block<T> to Array<T> as return values.
00109 //   <li> replace entirely with AIPS++ Keywords?
00110 // </todo>
00111 
00112 
00113 class Param
00114 {
00115 public:
00116                                 // constructors and destructor
00117   // default constructor
00118   Param();
00119 
00120   // normal constructor with optional value and help strings
00121   Param (const String& key, const String& value, const String& help,
00122          const String& type, const String& range, const String& unit);
00123   
00124   // copy constructor
00125   Param (const Param&);
00126   
00127   // destructor
00128   ~Param();
00129   
00130   // assignment operator
00131   Param& operator= (const Param&);
00132   
00133   // Equality comparitor.
00134   // <note role=warning> This function ALWAYS returns 
00135   // false.  I have no idea why it was designed to do this. </note>
00136   Bool operator== (const Param&) const;
00137   
00138   // I/O operators
00139   //<group>
00140   friend ostream& operator<< (ostream&, const Param& p);
00141   friend istream& operator>> (istream&, Param& p);
00142   friend AipsIO& operator<< (AipsIO&, const Param& p);
00143   friend AipsIO& operator>> (AipsIO&, Param& p);
00144   //</group>
00145   
00146   // get a double parameter value; prompt if switch is TRUE
00147   Double getDouble (Bool do_prompt=False) const;
00148 
00149   // get a Block<double> parameter value; prompt if switch is TRUE
00150   Block<Double> getDoubleArray (Bool do_prompt=False) const;
00151   
00152   // get an Int parameter value; prompt if switch is TRUE
00153   Int getInt (Bool do_prompt=False) const;
00154 
00155   // get an Block<Int> parameter value; prompt if switch is TRUE
00156   Block<Int> getIntArray (Bool do_prompt=False) const;
00157   
00158   // get a String parameter value; prompt if switch is TRUE
00159   const String& getString (Bool do_prompt=False) const;
00160 
00161   // get a Block<String> parameter value; prompt if switch is TRUE
00162   Block<String> getStringArray (Bool do_prompt=False) const;
00163   
00164   // get a Boolean parameter value; prompt if switch is TRUE
00165   Bool getBool (Bool do_prompt=False) const;
00166   
00167   // get parameter value as a string
00168   const String& get() const
00169     { return value; }
00170   
00171   // get parameter help string
00172   const String& getHelp() const
00173     { return help; }
00174   
00175   // get parameter name 
00176   const String& getKey() const
00177     { return key; }
00178   
00179   // get the string `key = value' for the parameter
00180   String keyVal() const
00181     { return key + "=" + value; }
00182   
00183   // get the type of a parameter
00184   const String& getType() const
00185     { return type; }
00186   
00187   // get the valid range of a parameter
00188   const String& getRange() const
00189     { return range; }
00190   
00191   // get the units of a parameter
00192   const String& getUnit() const
00193     { return unit; }
00194   
00195   // set new parameter value; return FALSE if invalid value
00196   Bool put (const String& a_value);
00197   
00198   // set a parameter as a system parameter
00199   void setSystem (Bool val)
00200     { system = val; }
00201   
00202   // check if a parameter is a system parameter
00203   Bool isSystem() const
00204     { return system; }
00205   
00206   // set an index for a program parameter
00207   void setIndex (Int inx)
00208     { index = inx; }
00209 
00210   // get the index of a parameter
00211   Int getIndex() const
00212     { return index; }
00213 
00214 
00215 private:
00216   // parameter name
00217   String key;
00218 
00219   // parameter value
00220   String value;
00221 
00222   // help string
00223   String help;
00224 
00225   // type of parameter          
00226   String type;
00227 
00228   // range/validity/pre-check
00229   String range;  
00230 
00231   // optional unit associated with value
00232   String unit;
00233   
00234   // boolean data member which indicates the Param's key has a value.
00235   Bool hasvalue;     
00236 
00237   // boolean data member which indicates the Param is system wide.
00238   Bool system;
00239 
00240   // index for program keywords (>=1)
00241   Int index;
00242 };
00243 
00244 
00245 
00246 } //# NAMESPACE CASA - END
00247 
00248 #endif
00249 
00250 
00251