Inputs.h

Go to the documentation of this file.
00001 //# Inputs.h: a module for simple command line user interface classes
00002 //# Copyright (C) 1994,1995,1996,1999,2000
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$
00027 
00028 #ifndef CASA_INPUTS_H
00029 #define CASA_INPUTS_H
00030 
00031 #include <casacore/casa/aips.h>
00032 
00033 #include <casacore/casa/Inputs/Input.h>
00034 #include <casacore/casa/Inputs/Param.h>
00035 
00036 namespace casacore { //# NAMESPACE CASACORE - BEGIN
00037 
00038 // <module> 
00039 //
00040 // <summary> 
00041 // A module for simple command line user interface classes
00042 // </summary>
00043 
00044 // <prerequisite>
00045 //   <li> String
00046 //   <li> The C language int main(int argc, const char* argv[]) convention.
00047 // </prerequisite>
00048 
00049 // <reviewed reviewer="UNKNOWN" date="before2004/08/25" demos="">
00050 //</reviewed>
00051 
00052 // <etymology> 
00053 // The Inputs module name reflects the Casacore convention of pluralizing 
00054 // the name of the major class it contains.
00055 // The Input class name is a reflection of it's role as the early command 
00056 // line user interface for Casacore applications. This class provides "inputs" 
00057 // in the form "key=value" or "-key value."  
00058 //</etymology> 
00059 //
00060 // <synopsis> 
00061 
00062 // During the old AIPS++ prototyping stage a basic command line user
00063 // interface was developed. This attempt at easing the trouble of passing
00064 // information to an executable program resulted in a set of C++ classes
00065 // called Param and Input.  The programmer may simply include the Input
00066 // class into their code and have immediate Command Line User Interface
00067 // (CLUI) capabilities.  The programmer's Casacore application is run from
00068 // the unix level prompt by invoking its name and listing linearly on the
00069 // same command line the "keyword=values" or "-keyword values" associated
00070 // with proper execution.  The Input and Param classes will successfully
00071 // parse the command line into the executable program and check for
00072 // appropriateness.
00073 
00074 // The CLUI capabilities are further extended to a Graphical User
00075 // Interface through the use of the Khoros Cantata environment. The user
00076 // starts up Cantata from the unix prompt and, by utilizing a series of
00077 // pull down windows, invisibly creates an X-based window for visual
00078 // display of all parameters associated with the Casacore application's
00079 // need for external input.
00080 
00081 // The basic command line user interface is an ordered series of
00082 // "keyword=value" pairs, which we call parameters. The names parameter
00083 // and keyword may correctly be used to refer to each other.
00084 // 
00085 // The class Param (see Param.h) implements one single such parameter.
00086 // Values may be Int, Block<Int>, double, Block<double>, Bool, or
00087 // Strings.  In addition to a name and a value, a Param parameter has a
00088 // variety of other attributes, such as a one-line help string (useful
00089 // when being prompted for input or with hypertext identifiers, etc...),
00090 // a type, a range and optional units.  All of these attributes are
00091 // character strings; parsing and error checking is done at a different
00092 // (hidden) level.  The programmer, however, will never interact with a
00093 // parameter through it's Param class interface.  Interaction is done
00094 // with the class Input, which is a container of Param's, with a variety
00095 // of user interface attributes (help-level, debug-level, etc...).
00096 // 
00097 // Although the programmer must supply the user interface with a number
00098 // of predefined program parameters, the user interface itself will
00099 // create a small number of system parameters (help=, debug=).  The
00100 // purpose of these is to tell the task how to communicate with the user
00101 // and it's environment, and give the user control over these items.  For
00102 // example, the user may want to see (debug) messages above a certain
00103 // threshold level.  The programmer simply adds debug levels to their
00104 // code and allows the user to specify how deeply they wish the debugging
00105 // to progress.
00106 // 
00107 // For example, a interactive UNIX shell session may look like:
00108 // 
00109 //<srcblock>
00110 //     1% MyProgram key1=val1 key3=val3
00111 //     2% MyProgram key1=val1 key2=val3 debug=5
00112 //     3% MyProgram help=prompt
00113 //     4% MyProgram help=pane > prog.pane
00114 //</srcblock>
00115 // 
00116 // In command 1% the user has set several parameters for the program
00117 // MyProgram to applicable values.  The 2% command line invokes the
00118 // executable and sets the level of displayed debugging to the programmer
00119 // specified 5th level.  Command 3%: the user is prompted, and parameter
00120 // default values are restored.  Command 4% gives an example of the
00121 // self-describing mode of programs, where a pane description file for
00122 // Khoros has been constructed.  The latter is the first step toward
00123 // building a Khoros Graphic User Interface.
00124 // 
00125 // The Input class is a means for building a linked list of parameters
00126 // and gaining access to them once created.  Input takes care of
00127 // system/environment variables and assigns their values within the
00128 // programmer's code.  The linked list of parameters is limited only by
00129 // the number of names the programmer can dream up.  The programmer need
00130 // not think hard on the order of definition of parameters in Input. The
00131 // list of key=values given on the command line by the user need not be
00132 // in any specific order.
00133 // 
00134 // The definition of parameters is by simply creating an Input and then
00135 // using the appropriate Input Create member function.  Then the
00136 // programmer adds to the list of parameters as necessary.
00137 // </synopsis> 
00138 //
00139 // <example>
00140 // <srcblock>
00141 // 01 #include <casacore/casa/Inputs/Input.h>      // need this if you want it to work
00142 // 02 #include <aips/Plot.h>
00143 // 03 int main(int argc, const char* argv[])
00144 // 04 {
00145 // 05    Input inputs(1);
00146 // 06    // Define our input structure
00147 // 07    inputs.version("Id: xyPlot.C,v 1.1 1993/01/29 20:45:48 bglenden Exp");
00148 // 08    inputs.create("xyfile", 
00149 // 09                "/tmp/xy.aipsio",
00150 // 10                "File which contains xy vectors",
00151 // 11                "InFile");
00152 // 12    inputs.create("overplot", "False", "Multiple plots?", "Bool");
00153 // 13    inputs.create("lines", "True", "Plot lines or points?", "Bool");
00154 // 14    
00155 // 15    // and Fill them from the command line
00156 // 16    inputs.readArguments(argc, argv);
00157 // 17
00158 // 18    try {
00159 // 19      const Char *filename = inputs.getString("xyfile");
00160 // 20      AipsIO xyfile(filename, ByteIO::Old);
00161 // 21      Vector<float> x, y;
00162 // 22      Plot plot;
00163 // 23
00164 // 24      xyfile >> x >> y; // initial vectors
00165 // 25      plot(x,y,inputs.getBool("lines"));
00166 // 26
00167 // 27      for (;;) { // forever
00168 // 28          xyfile >> x >> y;
00169 // 29          if (inputs.getBool("overplot") == True) {
00170 // 30              plot(x,y,inputs.getBool("lines"));
00171 // 31          } else {
00172 // 32              plot.newPlot();
00173 // 33              plot(x,y,inputs.getBool("lines"));
00174 // 34          }
00175 // 35      }
00176 // 36  } catch (AipsIOError x) {
00177 // 37       ; // nothing - no more data
00178 // 38  } catch (AllocError x) {
00179 // 39       cerr << "AllocError : " << x.getMesg() << endl;
00180 // 40       cerr << "Size is : " << x.size() << endl;
00181 // 41  } catch (AipsError x) {
00182 // 42       cerr << "aipserror: error " << x.getMesg() << endl;
00183 // 43       return 1;
00184 // 44  }
00185 // 45
00186 // 46    cout << "Any key to exit:\n";
00187 // 47
00188 // 48  char ch;
00189 // 49  cin.get(ch);
00190 // 50
00191 // 51  return 0;
00192 // 52 }
00193 // </srcblock>
00194 // Let us discuss this program line for line.
00195 // 
00196 // 03 - This is the method of passing the command line through to the
00197 // main body of code.  This obviously makes it mandatory.  The inclusion
00198 // of the argc, argv is very well discussed in Stroustrup, The
00199 // C++ Programming Language, page 87.
00200 // 
00201 // 05 - The instantiation of Input in the variable inputs(1) is done with
00202 // an integer argument of (1) to indicate the constructor should build
00203 // inputs with a pair of system parameters and read in values for them.
00204 // An argument of (0) would build an Input that was empty and would
00205 // obligate the programmer to build a list of Params explicitly.
00206 // 
00207 // 07 - The version of the code is stored within the Input.  Note the
00208 // optional use of RCS keyword substitution.  See the "co" man page for
00209 // details. This allows the code to be automatically updated.
00210 // 
00211 // 08-11 - The create member function of Input builds, in this case, a
00212 // parameter called xyfile, immediately filled with the String containing
00213 // the directory that holds the data. The help String is useful for new
00214 // users or prompting.  The fourth argument of InFile is the optional
00215 // type of the parameter's value.  Any suitable String may be used.
00216 // Missing from this example are the optional fifth and sixth arguments,
00217 // the parameter's value's range and units, respectively.
00218 // 
00219 // 12 - This is another instantiation of a Param inside of Input.  This
00220 // parameter will be referenced by the keyword "overplot".  It is
00221 // initialized to False and is of type Bool.
00222 // 
00223 // 13 - This line is the third and final Param placed in inputs and is
00224 // recognized by the code when accessed with keyword "lines".
00225 // 
00226 // 16 - The call of readArguments(argc, argv) should be done after the
00227 // list of Params has been completed.  This line of code fills the values
00228 // from the command line. A keyword that doesn't match will throw an
00229 // error.
00230 // 
00231 // 19 - At this point the local variable filename is initialized to the
00232 // String value held within the parameter accessed through the key
00233 // "xyfile".  Recall that the value of xyfile was originally set to
00234 // "/tmp/xy.aipsio" but would be replaced with the proper value at
00235 // execution.  The getString member function returns either the default
00236 // value specified during the xyfile parameter's instantiation or the
00237 // value placed into it from the command line use of xyfile=myfile.
00238 // 
00239 // 25 - Here the boolean value of the Param called lines is inserted into
00240 // the call to the function plot.
00241 // 
00242 // 29 - Again the Input interface has its parameter called overplot
00243 // return a boolean to be used as a test for an "if".  The getBool(key)
00244 // Input member function may be reading the default value of the
00245 // appropriate parameter called key or using the value passed from the
00246 // command line.
00247 // 
00248 // 30 & 33 - Another call to plot that uses the boolean value stored in
00249 // the parameter called lines.
00250 // </example> 
00251 // 
00252 //<motivation> 
00253 // This module fit the early needs of a a simple user interface.
00254 // </motivation>
00255 
00256 // <todo asof="Thu 199504/06 21:26:43 GMT">
00257 //   <li> possibly replace the Param class with Keywords
00258 // </todo>
00259 
00260 // </module>
00261 
00262 
00263 } //# NAMESPACE CASACORE - END
00264 
00265 #endif
00266 
00267 
00268 
00269 
00270 
00271 
 All Classes Namespaces Files Functions Variables Typedefs Enumerations Enumerator Friends Defines

Generated on 31 Aug 2016 for casa by  doxygen 1.6.1