casacore
Param.h
Go to the documentation of this file.
1 //# Param: A simple keyword/value pair with internal help Strings.
2 //# Copyright (C) 1993,1994,1995,1999,2000,2001
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_PARAM_H
29 #define CASA_PARAM_H
30 
31 
32 #include <casacore/casa/aips.h>
33 #include <casacore/casa/Containers/Block.h>
34 #include <casacore/casa/BasicSL/String.h>
35 #include <casacore/casa/IO/AipsIO.h>
36 #include <casacore/casa/stdlib.h>
37 #include <casacore/casa/string.h> // need things like strlen() and such
38 
39 //# Forward declarations
40 #include <casacore/casa/iosfwd.h>
41 
42 namespace casacore { //# NAMESPACE CASACORE - BEGIN
43 
44 // <summary>
45 // A simple keyword/value pair with internal help Strings.
46 // </summary>
47 
48 // <use visibility=local>
49 
50 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" tests="tParam.cc" demos="">
51 //</reviewed>
52 
53 // <prerequisite>
54 // <li> none noted
55 // </prerequisite>
56 //
57 // <etymology>
58 // The Param class name is a shortening of "parameter" and is indicative of
59 // the class being designed as a keyword/value pair relating to command line
60 // arguments. The existing Keyword class does a much better job for most
61 // other purposes.
62 // </etymology>
63 //
64 // <synopsis>
65 // The Param is constructed with all arguments being Strings. This is a
66 // reflection of the C-type command line argument method of passing
67 // an integer (argc or argument count) and an array of pointers to characters
68 // (argv or argument vector.) If "char* argv[]" is broken into its individual
69 // arguments they may be used to fill a Param. The constructor pairs up a
70 // "key" to a value. A help String argument is provided to assist in prompted
71 // filling of Param values. The expected return type may be entered as well
72 // as a range of potential values. Finally, the units of the value are also
73 // specified. The intent is to provide a well documented value and a "key"
74 // by which to "call" it.
75 //
76 // The "getWhatever" member functions of Param convert the internal Strings
77 // into the desired output data type. The Strings themselves may also be
78 // returned.
79 // </synopsis>
80 //
81 // <example>
82 // <srcblock>
83 // // we will create a Param which contains the boundary for an iteration loop.
84 // String key("IterBound");
85 // // give "IterBound" a default value
86 // String value("200");
87 // // a help String for prompting
88 // String help("The Boundary value for the chutzpah iterator.");
89 // // The expected return type is an integer
90 // String type("Int");
91 // // The range of "legal" values
92 // String range("10-10000");
93 // // the units of the value
94 // String unit("unitless"):
95 // // Now we may build our Param
96 // Param PleaseDontTouchMeThere(key, value, help, type, range, unit);
97 // // to retrieve the value we use the GetInt function
98 // for (Int i=0, i<PleaseDontTouchMeThere.getInt(); i++, chutzpah++);
99 // </srcblock></example>
100 //
101 // <motivation>
102 // The Param class was an early attempt at keywords within Casacore. They have
103 // become obsolete but hang on due to their relationship with the Input class.
104 // </motivation>
105 //
106 // <todo asof="Thu 1995/04/06 21:26:43 GMT">
107 // <li> fix the GetStringArray() function
108 // <li> convert from Block<T> to Array<T> as return values.
109 // <li> replace entirely with Casacore Keywords?
110 // </todo>
111 
112 
113 class Param
114 {
115 public:
116  // constructors and destructor
117  // default constructor
118  Param();
119 
120  // normal constructor with optional value and help strings
121  Param (const String& key, const String& value, const String& help,
122  const String& type, const String& range, const String& unit);
123 
124  // copy constructor
125  Param (const Param&);
126 
127  // destructor
129 
130  // assignment operator
132 
133  // Equality comparitor.
134  // <note role=warning> This function ALWAYS returns
135  // false. I have no idea why it was designed to do this. </note>
136  Bool operator== (const Param&) const;
137 
138  // I/O operators
139  //<group>
140  friend ostream& operator<< (ostream&, const Param& p);
141  friend istream& operator>> (istream&, Param& p);
142  friend AipsIO& operator<< (AipsIO&, const Param& p);
144  //</group>
145 
146  // get a double parameter value; prompt if switch is TRUE
147  Double getDouble (Bool do_prompt=False) const;
148 
149  // get a Block<double> parameter value; prompt if switch is TRUE
151 
152  // get an Int parameter value; prompt if switch is TRUE
153  Int getInt (Bool do_prompt=False) const;
154 
155  // get an Block<Int> parameter value; prompt if switch is TRUE
156  Block<Int> getIntArray (Bool do_prompt=False) const;
157 
158  // get a String parameter value; prompt if switch is TRUE
159  const String& getString (Bool do_prompt=False) const;
160 
161  // get a Block<String> parameter value; prompt if switch is TRUE
163 
164  // get a Boolean parameter value; prompt if switch is TRUE
165  Bool getBool (Bool do_prompt=False) const;
166 
167  // get parameter value as a string
168  const String& get() const
169  { return value; }
170 
171  // get parameter help string
172  const String& getHelp() const
173  { return help; }
174 
175  // get parameter name
176  const String& getKey() const
177  { return key; }
178 
179  // get the string `key = value' for the parameter
180  String keyVal() const
181  { return key + "=" + value; }
182 
183  // get the type of a parameter
184  const String& getType() const
185  { return type; }
186 
187  // get the valid range of a parameter
188  const String& getRange() const
189  { return range; }
190 
191  // get the units of a parameter
192  const String& getUnit() const
193  { return unit; }
194 
195  // set new parameter value; return FALSE if invalid value
196  Bool put (const String& a_value);
197 
198  // set a parameter as a system parameter
199  void setSystem (Bool val)
200  { system = val; }
201 
202  // check if a parameter is a system parameter
203  Bool isSystem() const
204  { return system; }
205 
206  // set an index for a program parameter
207  void setIndex (Int inx)
208  { index = inx; }
209 
210  // get the index of a parameter
211  Int getIndex() const
212  { return index; }
213 
214 
215 private:
216  // parameter name
218 
219  // parameter value
221 
222  // help string
224 
225  // type of parameter
227 
228  // range/validity/pre-check
230 
231  // optional unit associated with value
233 
234  // boolean data member which indicates the Param's key has a value.
236 
237  // boolean data member which indicates the Param is system wide.
239 
240  // index for program keywords (>=1)
242 };
243 
244 
245 
246 } //# NAMESPACE CASACORE - END
247 
248 #endif
249 
250 
251 
Bool getBool(Bool do_prompt=False) const
get a Boolean parameter value; prompt if switch is TRUE
String key
parameter name
Definition: Param.h:217
Double getDouble(Bool do_prompt=False) const
get a double parameter value; prompt if switch is TRUE
const String & getUnit() const
get the units of a parameter
Definition: Param.h:192
Block< Int > getIntArray(Bool do_prompt=False) const
get an Block<Int> parameter value; prompt if switch is TRUE
String keyVal() const
get the string ‘key = value’ for the parameter
Definition: Param.h:180
const String & getHelp() const
get parameter help string
Definition: Param.h:172
Param(const Param &)
copy constructor
void setSystem(Bool val)
set a parameter as a system parameter
Definition: Param.h:199
Int getInt(Bool do_prompt=False) const
get an Int parameter value; prompt if switch is TRUE
Param & operator=(const Param &)
assignment operator
Int index
index for program keywords (>=1)
Definition: Param.h:241
friend istream & operator>>(istream &, Param &p)
const String & getRange() const
get the valid range of a parameter
Definition: Param.h:188
Block< String > getStringArray(Bool do_prompt=False) const
get a Block<String> parameter value; prompt if switch is TRUE
String range
range/validity/pre-check
Definition: Param.h:229
Bool system
boolean data member which indicates the Param is system wide.
Definition: Param.h:238
const String & getType() const
get the type of a parameter
Definition: Param.h:184
~Param()
destructor
Param()
constructors and destructor default constructor
void setIndex(Int inx)
set an index for a program parameter
Definition: Param.h:207
Int getIndex() const
get the index of a parameter
Definition: Param.h:211
const String & getString(Bool do_prompt=False) const
get a String parameter value; prompt if switch is TRUE
Bool isSystem() const
check if a parameter is a system parameter
Definition: Param.h:203
String type
type of parameter
Definition: Param.h:226
String value
parameter value
Definition: Param.h:220
const String & getKey() const
get parameter name
Definition: Param.h:176
Bool put(const String &a_value)
set new parameter value; return FALSE if invalid value
Bool operator==(const Param &) const
Equality comparitor.
const String & get() const
get parameter value as a string
Definition: Param.h:168
String unit
optional unit associated with value
Definition: Param.h:232
Block< Double > getDoubleArray(Bool do_prompt=False) const
get a Block<double> parameter value; prompt if switch is TRUE
friend ostream & operator<<(ostream &, const Param &p)
I/O operators.
String help
help string
Definition: Param.h:223
Bool hasvalue
boolean data member which indicates the Param's key has a value.
Definition: Param.h:235
Param(const String &key, const String &value, const String &help, const String &type, const String &range, const String &unit)
normal constructor with optional value and help strings
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
const Bool False
Definition: aipstype.h:44
int Int
Definition: aipstype.h:50
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
double Double
Definition: aipstype.h:55