casa  5.7.0-16
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Macros Groups Pages
DisplayOptions.h
Go to the documentation of this file.
1 //# DisplayOptions.h: option parsing for display classes
2 //# Copyright (C) 1999,2000,2002
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 DISPLAY_DISPLAYOPTIONS_H
29 #define DISPLAY_DISPLAYOPTIONS_H
30 
31 #include <casa/aips.h>
32 #include <casa/Containers/Record.h>
33 #include <casa/Arrays/Array.h>
35 
36 namespace casa { //# NAMESPACE CASA - BEGIN
37 
38 // <summary>
39 // Class to provide option parsing routines for display classes.
40 // </summary>
41 
42 // <use visibility=local>
43 
44 // <reviewed reviewer="Peter Barnes" date="1999/10/27" tests="tDisplayOptions" demos="">
45 // </reviewed>
46 
47 // <prerequisite>
48 // <li> <linkto class=casacore::Record>Record</linkto>
49 // </prerequisite>
50 
51 // <etymology>
52 // DisplayOptions contains methods for parsing "Options" for
53 // various "Display" classes.
54 // </etymology>
55 
56 // <synopsis>
57 // DisplayOptions is a simple class which provides methods for parsing
58 // Records containing fields which conform to "options" as used in the
59 // Display Library classes. Consider a record having the following
60 // structure:
61 // <srcblock>
62 // rec.minimum.value = 4.0
63 // rec.minimum.otherfield = "some text"
64 // rec.maximum = 8.0
65 // </srcblock>
66 // The DisplayOptions methods can be used to extract the values of the
67 // <src>minimum</src> and <src>maximum</src> fields of the Record
68 // <src>rec</src>, regardless of whether the value itself is stored in
69 // a <src>value</src> sub-field, or at the next higher level. The
70 // DisplayOptions methods also offer the capability to detect "unset"
71 // casacore::Record values.
72 //
73 // This class can be used as-is, or inherited from by higher-level
74 // classes.
75 // </synopsis>
76 
77 // <example>
78 // The following example shows the use of DisplayOptions as a
79 // stand-alone class.
80 // <srcblock>
81 // /* assume some casacore::Record "rec" is to be parsed */
82 // DisplayOptions dopt;
83 // casacore::Bool error;
84 //
85 // casacore::Float min = 0.0;
86 // if (dopt.readOptionRecord(min, error, rec, "minimum") && !error) {
87 // cerr << "minimum found and changed, new value is " << min << endl;
88 // }
89 //
90 // casacore::String color;
91 // casacore::Bool colorIsUnset = false;
92 // if (dopt.readOptionRecord(color, colorIsUnset, error,
93 // rec, "color") && !error) {
94 // if (colorIsUnset) {
95 // cerr << "color found and unset" << endl;
96 // } else {
97 // cerr << "color found and changed, new value is " << color << endl;
98 // }
99 // }
100 // </srcblock>
101 // </example>
102 
103 // <motivation>
104 // Options are used prolifically throughout the display classes,
105 // so some unified processing of options is desirable.
106 // </motivation>
107 
108 // <thrown>
109 // None.
110 // </thrown>
111 
112 // <todo asof="1999/08/26">
113 // <li> add unset support for casacore::Bool, casacore::Float and casacore::Int types
114 // </todo>
115 
117 
118  public:
119 
120  // Constructor.
121  DisplayOptions();
122 
123  // Destructor.
124  virtual ~DisplayOptions() { };
125 
126  // Find the field <src>fieldname</src> in casacore::Record <src>rec</src>,
127  // containing the requested type (casacore::Bool, casacore::String, casacore::Float, casacore::Int) in
128  // itself or its "value" sub-field, and return the value in
129  // <src>target</src>. If the field doesn't exist, or does not
130  // contain the requested type, or a "value" sub-field containing the
131  // requested type, then <src>error</src> is set true. When
132  // <src>error</src> is false, the return value indicates whether
133  // <src>target</src> was modified. The casacore::Float version will also read
134  // records containing Ints or Doubles, and cast their value to
135  // Float.
136  // <group>
137 
138  template <class T> casacore::Bool readOptionRecord(casacore::Vector<T> &target, casacore::Bool &error,
139  const casacore::Record &rec,
140  const casacore::String &fieldname) const;
141 
142  template <class T> casacore::Bool readOptionRecord(T &target, casacore::Bool &error, const casacore::Record &rec,
143  const casacore::String &fieldname) const;
144  // </group>
145 
146  // Find the field <src>fieldname</src> in casacore::Record <src>rec</src>,
147  // containing the requested type (casacore::String) in itself or its "value"
148  // sub-field, and return the value in <src>target</src>. If the
149  // field (or "value" sub-field) instead contains an "unset" casacore::Record,
150  // then <src>unsetTarget</src> is set true. If the field doesn't
151  // exist, or does not contain the requested type (casacore::String) or an
152  // "unset" casacore::Record, or a "value" sub-field containing either of
153  // these, then <src>error</src> is set true. When <src>error</src>
154  // is false, the return value indicates whether <src>target</src>
155  // (or <src>unsetTarget</src>) was modified.
156  virtual casacore::Bool readOptionRecord(casacore::String &target, casacore::Bool &unsetTarget,
157  casacore::Bool &error, const casacore::Record &rec,
158  const casacore::String &fieldname) const;
159 
160  // Return a casacore::Record which is an "unset" casacore::Record, ie. has a field with
161  // name <src>casacore::String("i_am_unset")</src> whose value is
162  // <src>casacore::String("i_am_unset")</src>.
164  return itsUnsetRecord;
165  }
166 
167  // Return true or false indicating if the provided casacore::Record is equal
168  // to an "unset" Record.
169  casacore::Bool isUnset(const casacore::Record &rec) const;
170 
171  protected:
172 
173  // (Required) copy constructor.
174  DisplayOptions(const DisplayOptions &other);
175 
176  // (Required) copy assignment.
177  void operator=(const DisplayOptions &other);
178 
179  private:
180  // A utility to check if two types are compatible. (I.e. double is
181  // "compatible" with int. Used by readOptionRecord.
182  casacore::Bool compatible(const casacore::DataType &compareme, const casacore::DataType &tome) const;
183 
184  // An unset record to return with protected <src>unset()</src>
185  // function.
187 
188  };
189 
190 
191 } //# NAMESPACE CASA - END
192 #ifndef AIPS_NO_TEMPLATE_SRC
193 #include <display/Utilities/DisplayOptionsTemplate.tcc>
194 #endif
195 #endif
virtual ~DisplayOptions()
Destructor.
A 1-D Specialization of the Array class.
Class to provide option parsing routines for display classes.
casacore::Record unset() const
Return a casacore::Record which is an &quot;unset&quot; casacore::Record, ie.
casacore::Bool compatible(const casacore::DataType &compareme, const casacore::DataType &tome) const
A utility to check if two types are compatible.
casacore::Record itsUnsetRecord
An unset record to return with protected unset() function.
casacore::Bool isUnset(const casacore::Record &rec) const
Return true or false indicating if the provided casacore::Record is equal to an &quot;unset&quot; Record...
A hierarchical collection of named fields of various types.
Definition: Record.h:180
bool Bool
Define the standard types used by Casacore.
Definition: aipstype.h:42
void operator=(const DisplayOptions &other)
(Required) copy assignment.
casacore::Bool readOptionRecord(casacore::Vector< T > &target, casacore::Bool &error, const casacore::Record &rec, const casacore::String &fieldname) const
Find the field fieldname in casacore::Record rec, containing the requested type (casacore::Bool, casacore::String, casacore::Float, casacore::Int) in itself or its &quot;value&quot; sub-field, and return the value in target.
String: the storage and methods of handling collections of characters.
Definition: String.h:223
DisplayOptions()
Constructor.