ParmParse.H

Go to the documentation of this file.

/*
** (c) 1996-2000 The Regents of the University of California (through
** E.O. Lawrence Berkeley National Laboratory), subject to approval by
** the U.S. Department of Energy.  Your use of this software is under
** license -- the license agreement is attached and included in the
** directory as license.txt or you may contact Berkeley Lab's Technology
** Transfer Department at TTD@lbl.gov.  NOTICE OF U.S. GOVERNMENT RIGHTS.
** The Software was developed under funding from the U.S. Government
** which consequently retains certain rights as follows: the
** U.S. Government has been granted for itself and others acting on its
** behalf a paid-up, nonexclusive, irrevocable, worldwide license in the
** Software to reproduce, prepare derivative works, and perform publicly
** and display publicly.  Beginning five (5) years after the date
** permission to assert copyright is obtained from the U.S. Department of
** Energy, and subject to any subsequent five (5) year renewals, the
** U.S. Government is granted for itself and others acting on its behalf
** a paid-up, nonexclusive, irrevocable, worldwide license in the
** Software to reproduce, prepare derivative works, distribute copies to
** the public, perform publicly and display publicly, and to permit
** others to do so.
*/

#ifndef BL_PARMPARSE_H
#define BL_PARMPARSE_H
//
// $Id: ParmParse.H,v 1.28 2001/08/13 01:54:26 car Exp $
//
#include <stack>
#include <string>
#include <iosfwd>
#include <vector>
#include <list>

//
// ParmParse class implements a simple database for the storage and
// retrieval of command-line and input-file arguments.  The entries are
// stored in a static table in (name,value_list) pairs.
//
// The format of the input file is a series of DEFINITIONS.
//
// A DEFINITION is of the form  <name> = <value> <value> ...
// The equal sign is important since the list of values can span multiple
// lines.
//
// Comments in an input file include all text from a '#' character to the
// end of the line.  Here is an example input file:
//
//   niter = 100                # niter is an integer
//   title = "Double Wammy"     # example of a string with spaces
//   cell_size = 0.5 0.75       # cell spacing in each dimension
//   plot.var = Density 1 10    # a list of values
//   plot.var = Energy  5 12    # another list of values
//   bigarray = 1 2 3 4 5 6 7 8 # first part of array
//              9 10 11 12      # continuation of bigarray
//   test = apple "boy blue" 10 20 30 40
//   FILE = prob_file           # insert contents of this "prob_file" here
//
// The "FILE = <filename>" definition is special.  Rather than just
// adding this entry to the database, it reads the contents of <filename>
// into the database.
//
// ParmParse stores all entries in a static table which is built the
// first time a ParmParse object is constructed (usually in main()).
// Subsequent invocations have access to this table.
// A ParmParse constructor has an optional "prefix" argument that will
// limit the searches to only those entries of the table with this prefix
// in name.  For example:
//     ParmParse pp("plot");
// will find only those entries with name given by "plot.<string>".
//
// All values in the table are stored as strings.  For example, the
// values of "cell_size" in the above input file are stored as the
// strings "0.5" and "0.75".  These strings can be returned as either
// string of numeric values by the query functions.
// Character strings with spaces must be delimited by double quotes
// in the input file but the quotes are stripped before they are entered
// into the table.  For example, 'title' in the above input file has a
// single value, the string 'Double Wammy' (without the quotes).
// Each value in the list associated with a definition can be referred to
// by its index number.  The index numbers start at 0 just like an array
// in the C programming language.  Consider the definition of "test" in
// the above input file.  The first value 'apple'is a string with index
// 0.  The second value 'boy blue' is a string with index 1.  The
// remaining four values are integers indexed 2, 3, 4, and 5.
//
// For a string value to represent an integer or float it must fit the
// following regular experssion:
//   Sign    ::= '+' | '-'
//   Digit   ::= '0' | '1' | ... | '9'
//   Integer ::= [Sign]Digit+
//   Exp     ::= ('e'|'E')Integer
//   Float   ::= ( Integer[.Digit*][Exp] | [Integer].Digit+[Exp] )
//
// Where '+' indicates one or more occurences, '*' represents zero or
// more occurences, '|' means one or the other and '[]' represents zero
// or one occurence.
//
// Note that floats and doubles have the same string representation and
// that the FORTRAN "double" exponent format is not supported.
// That is, 1.0d+3 is not a valid representation of a floating point
// number but that 1.0e+3 is acceptable.
//
// There are a host of functions allowing the user to query the database
// and retrieve values.  Here are some general rules about the names of
// the member functions:
//
// * Functions with the string "get" in their names attempt to get a
//   value or an array of values from the table.  They generate a
//   run-time error if they are not successful.
//
// * Functions with the string "query" in their names attempt to get a
//   value or an array of values from the table.  They return the value 1
//   (true) if they are successful and 0 (false) if not.
//
// * Functions with the string "kth" in their names get values from
//   the Kth entry with the given name in the database.  This is
//   necessary since there may be multiple definitions with the same
//   name in the database.
//
// * Functions without the string "kth" in their names get values from
//   the last entry with the given name in the database.  Note that the
//   definitions from the command line are appended to the database table
//   and hence will be the last entries.
//
// * Functions with the string "arr" in their names get an Array of
//   values from the given entry in the table.  The array argument is
//   resized (if necessary) to hold all the values requested.
//
// * Functions without the string "arr" in their names get single
//   values from the given entry in the table.
//
// The following is a code sample showing how to use ParmParse:
//
// main(int argc, char **argv)
// {
//     char* in_file_name = argv[1];
//     ParmParse::Initialize(argc-2, argv+2, in_file_name);
//
//     // Query table for value of "niter".  If not in table
//     // then set to default value
//     if (!pp.query("niter",niter)) niter = 20;
//
//     // read array of cell sizes if in table
//     Array<float> dx;
//     if (nx=pp.countval("cell_size")) {
//        // get nx values starting at index 0 and store in dx.
//        // dx is automatically resized here.
//        pp.getarr("cell_size",dx,0,nx);
//     }
//     ParmParse::Finalize();
// }
//
// void do_graphics()
// {
//    //
//    // Will only query entries with the "plot" prefix:
//    //
//    ParmParse pp("plot");
//    //
//    // Read all variables with "plot.var" keyword.
//    //
//    std::string var_name;
//    Array<int> range;
//    int num = pp.countname("var");
//    for (int k = 0; k < num; k++)
//    {
//       //
//       // Element 0 in list is a string.
//       //
//       pp.getkth("var",k,var_name,0);
//       //
//       // Elements 1 and 2 are integers.
//       // Note that "range" will be resized to hold 2 elements.
//       //
//       pp.getktharr("var",k,range,1,2);
//       cout << "variable = " << var_name << "lo, hi = ",
//            << range[0] << " " << range[1] << endl;
//    }
// }
// -----------------------------------------------------------------
// -----------------------  END COMMENTS ---------------------------
// -----------------------------------------------------------------


// :

class Box;
class IntVect;

class ParmParse
{
public:
    class Frame;
    class Record;

    enum { LAST = -1, FIRST = 0, ALL = -1 };

    explicit ParmParse (const std::string& prefix = std::string());
    
    //
    //
    bool contains (const char* name) const;

    int countval (const char* name,
                  int         n = LAST) const;

    int countname (const std::string& name) const;

    int countRecords (const std::string& name) const;

    Record getRecord (const std::string& name, int n = LAST) const;

    //
    //
    static void dumpTable (std::ostream& os);

    void getkth (const char* name,
                 int         k,
                 bool&        ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              bool&        ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  bool&       ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               bool&        ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 int&        ref,
                 int         ival = FIRST) const;

    //
    void get (const char* name,
              int&        ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  int&        ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               int&        ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 float&      ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              float&      ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  float&      ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               float&      ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 double&     ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              double&     ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  double&     ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               double&     ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 std::string&    ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              std::string&    ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  std::string&   ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               std::string&    ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 IntVect&    ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              IntVect&    ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  IntVect&   ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               IntVect&    ref,
               int         ival = FIRST) const;

    void getkth (const char* name,
                 int         k,
                 Box&        ref,
                 int         ival = FIRST) const;
    //
    //
    void get (const char* name,
              Box&        ref,
              int         ival = FIRST) const;

    int querykth (const char* name,
                  int         k,
                  Box&        ref,
                  int         ival = FIRST) const;
    //
    //
    int query (const char* name,
               Box&        ref,
               int         ival = FIRST) const;

    void getktharr (const char* name,
                    int         k,
                    std::vector<int>& ref,
                    int         start_ix = FIRST,
                    int         num_val = ALL) const;
    //
    //
    void getarr (const char* name,
                 std::vector<int>& ref,
                 int         start_ix = FIRST,
                 int         num_val = ALL) const;
    //
    //
    int queryktharr (const char* name,
                     int         k,
                     std::vector<int>& ref,
                     int         start_ix = FIRST,
                     int         num_val = ALL) const;
    //
    //
    int queryarr (const char* name,
                  std::vector<int>& ref,
                  int         start_ix = FIRST,
                  int         num_val = ALL) const;

    void getktharr (const char*   name,
                    int           k,
                    std::vector<float>& ref,
                    int           start_ix = FIRST,
                    int           num_val = ALL) const;
    //
    //
    void getarr (const char*   name,
                 std::vector<float>& ref,
                 int           start_ix = FIRST,
                 int           num_val = ALL) const;
    //
    //
    int queryktharr (const char*   name,
                     int           k,
                     std::vector<float>& ref,
                     int           start_ix = FIRST,
                     int           num_val = ALL) const;
    //
    //
    int queryarr (const char*   name,
                  std::vector<float>& ref,
                  int           start_ix = FIRST,
                  int           num_val = ALL) const;

    void getktharr (const char*    name,
                    int            k,
                    std::vector<double>& ref,
                    int            start_ix = FIRST,
                    int            num_val = ALL) const;
    //
    //
    void getarr (const char*    name,
                 std::vector<double>& ref,
                 int            start_ix = FIRST,
                 int            num_val = ALL) const;
    //
    //
    int queryktharr (const char*    name,
                     int            k,
                     std::vector<double>& ref,
                     int            start_ix = FIRST,
                     int            num_val = ALL) const;
    //
    //
    int queryarr (const char*    name,
                  std::vector<double>& ref,
                  int            start_ix = FIRST,
                  int            num_val = ALL) const;

    void getktharr (const char*     name,
                    int             k,
                    std::vector<std::string>& ref,
                    int             start_ix = FIRST,
                    int             num_val = ALL) const;
    //
    //
    void getarr (const char*     name,
                 std::vector<std::string>& ref,
                 int             start_ix = FIRST,
                 int             num_val = ALL) const;
    //
    //
    int queryktharr (const char*     name,
                     int             k,
                     std::vector<std::string>& ref,
                     int             start_ix = FIRST,
                     int             num_val = ALL) const;
    //
    //
    int queryarr (const char*     name,
                  std::vector<std::string>& ref,
                  int             start_ix = FIRST,
                  int             num_val = ALL) const;

    void getktharr (const char*     name,
                    int             k,
                    std::vector<IntVect>& ref,
                    int             start_ix = FIRST,
                    int             num_val = ALL) const;
    //
    //
    void getarr (const char*     name,
                 std::vector<IntVect>& ref,
                 int             start_ix = FIRST,
                 int             num_val = ALL) const;
    //
    //
    int queryktharr (const char*     name,
                     int             k,
                     std::vector<IntVect>& ref,
                     int             start_ix = FIRST,
                     int             num_val = ALL) const;
    //
    //
    int queryarr (const char*     name,
                  std::vector<IntVect>& ref,
                  int             start_ix = FIRST,
                  int             num_val = ALL) const;

    void getktharr (const char*     name,
                    int             k,
                    std::vector<Box>& ref,
                    int             start_ix = FIRST,
                    int             num_val = ALL) const;
    //
    //
    void getarr (const char*     name,
                 std::vector<Box>& ref,
                 int             start_ix = FIRST,
                 int             num_val = ALL) const;
    //
    //
    int queryktharr (const char*     name,
                     int             k,
                     std::vector<Box>& ref,
                     int             start_ix = FIRST,
                     int             num_val = ALL) const;
    //
    //
    int queryarr (const char*     name,
                  std::vector<Box>& ref,
                  int             start_ix = FIRST,
                  int             num_val = ALL) const;

    static void Initialize(int         argc,
               char**      argv,
               const char* parfile);


    static void Finalize();

    /* publicly needed helpers */
    struct PP_entry;
    typedef std::list<PP_entry> Table;
private:
    friend class Frame;
    friend class Record;
    explicit ParmParse (const Table& tbl);
    std::string getPrefix() const;
    std::string setPrefix(const std::string& str);
    void pushPrefix(const std::string& str);
    void popPrefix();
    std::string prefixedName (const std::string& str) const;
    //
    // Prefix used in keyword search.
    //
    std::stack<std::string> m_pstack;
    const Table& m_table;
};

struct ParmParse::PP_entry
{
    PP_entry (const std::string&            name,
              const std::list<std::string>& vals);
    PP_entry (const std::string& name,
          const Table& table);
    PP_entry (const PP_entry& pe);
    PP_entry& operator= (const PP_entry& pe);
    ~PP_entry ();
    std::string        m_name;
    std::vector<std::string> m_vals;
    Table*                   m_table;
    mutable bool             m_queried;
};


class ParmParse::Frame
{
public:
    Frame (ParmParse& pp, const std::string& str);
    ~Frame ();
    void push(const std::string& str);
    void pop();
    std::string getPrefix() const;
private:
    ParmParse& m_pp;
    int m_np;
};

class ParmParse::Record
{
public:
    const ParmParse* operator->() const;
    const ParmParse& operator* () const;
private:
    friend class ParmParse;
    explicit Record (const ParmParse& pp);
    ParmParse m_pp;
};

#endif /*BL_PARMPARSE_H*/

---