home | help 
sc::KeyVal(3)			      MPQC			   sc::KeyVal(3)

NAME
     sc::KeyVal - The KeyVal class is designed to simplify the process of allow-
     ing a user to specify keyword/value associations to a C++ program.

SYNOPSIS
     #include <keyval.h>

     Inherits sc::RefCount.

     Inherited by sc::AggregateKeyVal, sc::AssignedKeyVal, sc::PrefixKeyVal, and
     sc::StringKeyVal.

   Public Types
     enum { MaxKeywordLength = 256 }
     enum  KeyValError	{  OK,	HasNoValue,  WrongType,  UnknownKeyword,  Opera-
	 tionFailed }

   Public Member Functions
     int exists (const char *)
	 This takes as its only argument a keyword.
     int count (const char *=0)
	 If the value of a keyword is an array, then return its length.
     Ref< KeyValValue > value (const char *=0,	const  KeyValValue  &def=KeyVal-
	 Value())
	 Return the value associated with the keyword.
     int  booleanvalue	(const	char *key=0, const KeyValValue &def=KeyValValue-
	 boolean())
	 Returns the boolean value (0 = false, 1 = true) of key.
     double doublevalue (const char *key=0, const KeyValValue  &def=KeyValValue-
	 double())
	 Returns the double value of key.
     float  floatvalue	(const	char *key=0, const KeyValValue &def=KeyValValue-
	 float())
	 Returns the float value of key.
     char  charvalue  (const  char  *key=0,  const  KeyValValue  &def=KeyValVal-
	 uechar())
	 Returns the char value of key.
     int intvalue (const char *key=0, const KeyValValue &def=KeyValValueint())
	 Returns the int value of key.
     size_t  sizevalue	(const	char *key=0, const KeyValValue &def=KeyValValue-
	 size())
	 Returns the size_t value of key.
     char * pcharvalue (const char *key=0, const  KeyValValue  &def=KeyValValue-
	 pchar())
	 Returns a copy of the string representation of the key's value.
     std::string  stringvalue (const char *key=0, const KeyValValue &def=KeyVal-
	 Valuestring())
	 Returns a string representation of the key's value.
     Ref< DescribedClass > describedclassvalue (const char *key=0, const KeyVal-
	 Value &def=KeyValValueRefDescribedClass())
	 Returns a reference to an object of type DescribedClass.

     Reading Vectors.
     These members correspond to the above members, but take an additional inte-
     ger argument, i, which is a vector index.

     This  is  equivalent   to	 getting   a   value   for   a	 keyword   named
     '<i>key</i>:<i>i</i>'.  The routines that do not take key arguments get the
     value for the keyword named '<i>i</i>'.

	 int exists (const char *key, int i)
	 int count (const char *key, int i)
	 int booleanvalue (const char *key, int i, const  KeyValValue  &def=Key-
	     ValValueboolean())
	 double doublevalue (const char *key, int i, const KeyValValue &def=Key-
	     ValValuedouble())
	 float	floatvalue  (const char *key, int i, const KeyValValue &def=Key-
	     ValValuefloat())
	 char charvalue (const char *key, int i, const KeyValValue  &def=KeyVal-
	     Valuechar())
	 int intvalue (const char *key, int i, const KeyValValue &def=KeyValVal-
	     ueint())
	 size_t  sizevalue  (const char *key, int i, const KeyValValue &def=Key-
	     ValValuesize())
	 char * pcharvalue (const char *key, int i, const KeyValValue  &def=Key-
	     ValValuepchar())
	 std::string  stringvalue  (const  char  *key,	int i, const KeyValValue
	     &def=KeyValValuestring())
	 Ref< DescribedClass > describedclassvalue (const char *key, int,  const
	     KeyValValue &def=KeyValValueRefDescribedClass())
	 int exists (int i)
	 int count (int i)
	 int booleanvalue (int i, const KeyValValue &def=KeyValValueboolean())
	 double doublevalue (int i, const KeyValValue &def=KeyValValuedouble())
	 float floatvalue (int i, const KeyValValue &def=KeyValValuefloat())
	 char charvalue (int i, const KeyValValue &def=KeyValValuechar())
	 int intvalue (int i, const KeyValValue &def=KeyValValueint())
	 size_t sizevalue (int i, const KeyValValue &def=KeyValValuesize())
	 char * pcharvalue (int i, const KeyValValue &def=KeyValValuepchar())
	 std::string  stringvalue  (int  i,  const  KeyValValue  &def=KeyValVal-
	     uestring())
	 Ref< DescribedClass > describedclassvalue  (int  i,  const  KeyValValue
	     &def=KeyValValueRefDescribedClass())

     Reading 2D Arrays.
     These  members correspond to the above members, but take additional integer
     arguments, i and j, which is an array index.

     This  is  equivalent   to	 getting   a   value   for   a	 keyword   named
     '<i>key</i>:<i>i</i>:<i>j</i>'. The routines that do not take key arguments
     get the value for the keyword named '<i>i</i>:<i>j</i>'.

	 int exists (const char *, int, int)
	 int count (const char *, int, int)
	 int  booleanvalue  (const char *, int, int, const KeyValValue &def=Key-
	     ValValueboolean())
	 double doublevalue  (const  char  *key,  int,	int,  const  KeyValValue
	     &def=KeyValValuedouble())
	 float	 floatvalue  (const  char  *key,  int,	int,  const  KeyValValue
	     &def=KeyValValuefloat())
	 char charvalue (const char *key, int, int, const KeyValValue  &def=Key-
	     ValValuechar())
	 int intvalue (const char *key, int, int, const KeyValValue &def=KeyVal-
	     Valueint())
	 size_t   sizevalue  (const  char  *key,  int,	int,  const  KeyValValue
	     &def=KeyValValuesize())
	 char *  pcharvalue  (const  char  *key,  int,	int,  const  KeyValValue
	     &def=KeyValValuepchar())
	 std::string  stringvalue  (const char *key, int, int, const KeyValValue
	     &def=KeyValValuestring())
	 Ref< DescribedClass > describedclassvalue (const char *key,  int,  int,
	     const KeyValValue &def=KeyValValueRefDescribedClass())
	 int exists (int i, int j)
	 int count (int i, int j)
	 int  booleanvalue  (int  i,  int j, const KeyValValue &def=KeyValValue-
	     boolean())
	 double doublevalue (int i, int j, const  KeyValValue  &def=KeyValValue-
	     double())
	 float	floatvalue  (int  i,  int j, const KeyValValue &def=KeyValValue-
	     float())
	 char charvalue (int i, int j, const KeyValValue &def=KeyValValuechar())
	 int intvalue (int i, int j, const KeyValValue &def=KeyValValueint())
	 size_t sizevalue (int i, int  j,  const  KeyValValue  &def=KeyValValue-
	     size())
	 char  *  pcharvalue  (int i, int j, const KeyValValue &def=KeyValValue-
	     pchar())
	 std::string stringvalue (int i, int j, const  KeyValValue  &def=KeyVal-
	     Valuestring())
	 Ref<  DescribedClass > describedclassvalue (int i, int j, const KeyVal-
	     Value &def=KeyValValueRefDescribedClass())

     Reading 3D Arrays.
     These members correspond to the above members, but can be used to	read  in
     arrays with more than two dimensions.

     The  nindex  argument is the number of indices in the array. It is followed
     by an int giving the value of each index.

	 int Va_exists (const char *key, int nindex,...)
	 int Va_count (const char *key, int nindex,...)
	 int Va_booleanvalue (const char *key, int nindex,...)
	 double Va_doublevalue (const char *key, int nindex,...)
	 float Va_floatvalue (const char *key, int nindex,...)
	 char Va_charvalue (const char *key, int nindex,...)
	 int Va_intvalue (const char *key, int nindex,...)
	 size_t Va_sizevalue (const char *key, int nindex,...)
	 char * Va_pcharvalue (const char *key, int nindex,...)
	 std::string Va_stringvalue (const char *key, int nindex,...)
	 Ref< DescribedClass > Va_describedclassvalue (const char *key, int nin-
	     dex,...)
	 KeyValError error ()
	     Return the current error condition.
	 const char * errormsg (KeyValError err)
	     Return a textual representation of err.
	 const char * errormsg ()
	     Return a textual representation of the current error.
	 virtual void errortrace (std::ostream &fp=ExEnv::err0())
	     Write a message to fp describing the error.
	 virtual void dump (std::ostream &fp=ExEnv::err0())
	     Write a message to fp describing the error.
	 virtual void print_unseen (std::ostream &fp=ExEnv::out0())
	     Print keywords that were never looked at, if possible.
	 virtual int have_unseen ()
	     Return 1 if there were unseen keywords, 0 if there are none, or  -1
	     this keyval doesn't keep track of unseen keywords.
	 void verbose (int v)
	     Control printing of assignments.
	 int verbose () const
	     Returns nonzero if assignments are printed.

     Public Member Functions inherited from sc::RefCount
     int lock_ptr () const
	 Lock this object.
     int unlock_ptr () const
	 Unlock this object.
     void use_locks (bool inVal)
	 start and stop using locks on this object
     refcount_t nreference () const
	 Return the reference count.
     refcount_t reference ()
	 Increment the reference count and return the new count.
     refcount_t dereference ()
	 Decrement the reference count and return the new count.
     int managed () const
     void unmanage ()
	 Turn off the reference counting mechanism for this object.
     int managed () const
	 Return 1 if the object is managed. Otherwise return 0.

     Public Member Functions inherited from sc::Identity
     Identifier identifier ()
	 Return the Identifier for this argument.

   Protected Member Functions
     void seterror (KeyValError err)
	 Set the current error condition.
     void seterror (KeyValValue::KeyValValueError err)
	 Set the current error condition.
     virtual int key_exists (const char *)=0
	 Ultimately called by exists.
     virtual int key_count (const char *=0)
	 Ultimately called by count.
     virtual  Ref<  KeyValValue  >  key_value  (const  char *, const KeyValValue
	 &def)=0
	 Ultimately called by value.
     virtual int key_booleanvalue (const char *, const KeyValValue &def)
	 Ultimately called by booleanvalue.
     virtual double key_doublevalue (const char *key, const KeyValValue &def)
	 Ultimately called by doublevalue.
     virtual float key_floatvalue (const char *key, const KeyValValue &def)
	 Ultimately called by floatvalue.
     virtual char key_charvalue (const char *key, const KeyValValue &def)
	 Ultimately called by charvalue.
     virtual int key_intvalue (const char *key, const KeyValValue &def)
	 Ultimately called by intvalue.
     virtual size_t key_sizevalue (const char *key, const KeyValValue &def)
	 Ultimately called by sizevalue.
     virtual char * key_pcharvalue (const char *key, const KeyValValue &def)
	 Ultimately called by pcharvalue.
     virtual std::string key_stringvalue (const  char  *key,  const  KeyValValue
	 &def)
	 Ultimately called by stringvalue.
     virtual  Ref<  DescribedClass  >  key_describedclassvalue (const char *key,
	 const KeyValValue &def)
	 Ultimately called by describedclassvalue.

     Protected Member Functions inherited from sc::RefCount
     RefCount (const RefCount &)
     RefCount & operator= (const RefCount &)

   Protected Attributes
     int verbose_

   Friends
     class AggregateKeyVal
     class PrefixKeyVal

Detailed Description
     The KeyVal class is designed to simplify the process of allowing a user  to
     specify keyword/value associations to a C++ program.

     A	flexible input style and ease of use for the programmer is achieved with
     this method. Keywords are represented by null terminated character  arrays.
     The  keywords  are  organized hierarchially, in a manner similar to the way
     that many file systems are organized. One character is special, ':',  which
     is  used  to separate the various hierarchial labels, which are referred to
     as 'segments', in the keyword.

     A convention for specifying arrays is provided by KeyVal. Each index of the
     array is given by appending a segment containing the character  representa-
     tion  of  the index. Thus, 'array:3:4' would be a the keyword corresponding
     to fourth row and fifth column of 'array', since indexing starts at zero.

     To allow the KeyVal class to have associations that can represent data  for
     classes,  the  keyword  can  be associated with a class as well as a value.
     This permits polymorphic data  to	be  unambiguously  represented	by  key-
     word/value  associations.	Most  use  of  KeyVal need not be concerned with
     this.

Member Function Documentation
   int sc::KeyVal::count (const char * = 0)
     If the value of a keyword is an array, then return its length. If no  argu-
     ments are given then the top level will be checked to see if it is an array
     and, if so, the number of elements will be counted.

   virtual void sc::KeyVal::dump (std::ostream & fp = ExEnv::err0()) [virtual]
     Write a message to fp describing the error.

     Reimplemented  in	sc::StringKeyVal, sc::AggregateKeyVal, sc::PrefixKeyVal,
     and sc::ParsedKeyVal.

   virtual void sc::KeyVal::errortrace (std::ostream & fp = ExEnv::err0()) [vir-
     tual]
     Write a message to fp describing the error.

     Reimplemented in sc::StringKeyVal,  sc::AggregateKeyVal,  sc::PrefixKeyVal,
     and sc::ParsedKeyVal.

   int sc::KeyVal::exists (const char *)
     This  takes  as its only argument a keyword. Returns 1 if the keyword has a
     value and 0 otherwise.

   virtual int sc::KeyVal::have_unseen () [virtual]
     Return 1 if there were unseen keywords, 0 if there are  none,  or	-1  this
     keyval doesn't keep track of unseen keywords.

     Reimplemented in sc::ParsedKeyVal.

   virtual  int  sc::KeyVal::key_exists  (const char *) [protected],  [pure vir-
     tual]
     Ultimately called by exists.

     Implemented in sc::AssignedKeyVal, sc::StringKeyVal, and  sc::AggregateKey-
     Val.

   virtual Ref< KeyValValue > sc::KeyVal::key_value (const char *, const KeyVal-
     Value & def) [protected],	[pure virtual]
     Ultimately called by value.

     Implemented  in sc::AssignedKeyVal, sc::StringKeyVal, and sc::AggregateKey-
     Val.

   char * sc::KeyVal::pcharvalue (const char * key = 0, const KeyValValue &  def
     = KeyValValuepchar())
     Returns a copy of the string representation of the key's value. Storage for
     the copy is obtained with new.

   virtual  void  sc::KeyVal::print_unseen  (std::ostream  & fp = ExEnv::out0())
     [virtual]
     Print keywords that were never looked at, if possible.

     Reimplemented in sc::ParsedKeyVal.

Author
     Generated automatically by Doxygen for MPQC from the source code.

Version 2.3.1			 Thu Sep 3 2026 		   sc::KeyVal(3)
home | help