cmPgmOpts.h/c: Many changes and additions

Parameter type flags (cmBoolPoFl, ...) are now private.
Added 'Flag' parameter type.
Added Enum master help string.
Improved built-in help text content and formatting.
cmHexPoFl is now a parameter configuration flag rather than a type.

cmPgmOpts.c

 #include "cmMallocDebug.h"
 #include "cmLinkedHeap.h"
 #include "cmPgmOpts.h"
+#include "cmText.h"
 #include "config.h"
 
+enum { 
+  kFlagPoFl  = 0x001,
+  kBoolPoFl  = 0x002,  // this parameter does not take a value
+  kCharPoFl  = 0x004,  // parm. value is a character
+  kIntPoFl   = 0x008,  // parm. value is a decimal int
+  kUIntPoFl  = 0x010,  // parm. value is a decimal unsigned int
+  kDblPoFl   = 0x040,  // parm. value is a decimal double
+  kStrPoFl   = 0x080,  // parm. value is a string (default)
+  kEnumPoFl  = 0x100,  // parm. valus is a enum type (automatically set by a non-zero enumId)
+
+  kTypeMaskPoFl = 0x1ff
+};
+
 cmPgmOptH_t cmPgmOptNullHandle = cmSTATIC_NULL_HANDLE;
 
 struct _cmPoArg_str;
   unsigned              numId;      // 
   cmChar_t              charId;     // 
   cmChar_t*             wordId;     //
-  unsigned              flags;      // 
-  unsigned              enumId;     //
-  struct _cmPoOpt_str*  enumPtr;    // pointer to mast enum recd
+  unsigned              sflags;     // state flags (type flags)
+  unsigned              cflags;     // cfg flags (user settable cfg flag)
+  unsigned              enumId;     // enumerated set element id (numId is the group id)
+  struct _cmPoOpt_str*  enumPtr;    // pointer to mast enum recd (the master is the first param. rcvd for a given enum set - so this field is NULL for the master record)
   unsigned              maxInstCnt; //
   _cmPoValue_t          dfltVal;    // default value for this parm 
   _cmPoValPtr_t         retVal;     // client supplied variable which recieves the value of the last arg. parsed for this parm.
   cmChar_t*             helpStr;    //
+  cmChar_t*             mstrStr;
   struct _cmPoOpt_str*  link;       // link used by the _cmPo_t.list linked list
   struct _cmPoArg_str*  inst;       // arg's belonging to this opt record formed by _cmPoArg_t.inst links
 } _cmPoOpt_t;
   bool        execFl;       // set to false in cmPgmOptParse() if only built-in options were selected
 } _cmPo_t;
 
+typedef struct
+{
+  unsigned        id;
+  const cmChar_t* label;
+} _cmPoMap_t;
+
+_cmPoMap_t _cmPoTypeMap[] = 
+{
+  { kFlagPoFl, "" },
+  { kBoolPoFl, "" },
+  { kCharPoFl, "<char>" },
+  { kIntPoFl,  "<int>" },
+  { kUIntPoFl, "<uint>" },
+  { kDblPoFl,  "<real>" },
+  { kStrPoFl,  "<text>" },
+  { kEnumPoFl, "<enum>" },
+  { 0,         "<unknown>"}
+};
+
+const cmChar_t* _cmPoTypeFlagToLabel( unsigned flag, unsigned cflags )
+{
+  if( cmIsFlag(cflags,kHexPoFl) )
+    return "<hex>";
+
+  const _cmPoMap_t* m = _cmPoTypeMap;
+  for(; m->id != 0; ++m)
+    if( m->id == flag )
+      break;
+  return m->label;
+}
+
+bool _cmPoOptUsesValue( const _cmPoOpt_t* r )
+{ 
+  return 
+    cmIsNotFlag(r->sflags,kEnumPoFl) && 
+    cmIsNotFlag(r->sflags,kBoolPoFl) && 
+    cmIsNotFlag(r->sflags,kFlagPoFl);
+}
+
 _cmPo_t* _cmPoHandleToPtr( cmPgmOptH_t h )
 {
   _cmPo_t* p = (_cmPo_t*)h.h;
 
   hp->h = p;
 
-  cmPgmOptInstallBool(*hp, kPrintHelpPoId, 'h', "help",    0, false, NULL,0,"Print this usage information." );
-  cmPgmOptInstallBool(*hp, kVersionPoId,   'v', "version", 0, false, NULL,0,"Print version information." );
-  cmPgmOptInstallBool(*hp, kPrintParmsPoId,'p', "parms",   0, false, NULL,0,"Print the parameter information."); 
-
   return cmErrLastRC(&p->err);
 }
 
     if( r->numId == numId )
     {
 
-      if( cmIsFlag(r->flags,kEnumPoFl) && r->enumPtr!=NULL )
+      if( cmIsFlag(r->sflags,kEnumPoFl) && r->enumPtr!=NULL )
         r = r->enumPtr;
 
       return r;
 }
 
 
-cmPoRC_t _cmPgmOptInstall( _cmPo_t* p, unsigned numId, const cmChar_t charId, const cmChar_t* wordId, unsigned flags, unsigned enumId, unsigned cnt, const cmChar_t* helpStr, _cmPoOpt_t** rpp )
+cmPoRC_t _cmPgmOptInstall( _cmPo_t* p, unsigned numId, const cmChar_t charId, const cmChar_t* wordId, unsigned cflags, unsigned sflags, unsigned enumId, unsigned cnt, const cmChar_t* helpStr, _cmPoOpt_t** rpp )
 {
   // validate the num. id
-  if( enumId==0 && _cmPgmOptNumIdToOptRecd(p,numId) != NULL )
+  if( cmIsNotFlag(sflags,kEnumPoFl) && _cmPgmOptNumIdToOptRecd(p,numId) != NULL )
     return cmErrMsg(&p->err,kDuplicateIdPoRC,"The numeric id '%i' was already used by another parameter.",numId);
 
   // validate the char. id
   if( _cmPgmOptWordIdToOptRecd(p,wordId) != NULL )
     return cmErrMsg(&p->err,kDuplicateIdPoRC,"The word id --'%s' was already used by another parameter.",wordId);
 
+  // clear the kHexPoFl if this is not an int or uint.
+  if( cmIsNotFlag(sflags,kFlagPoFl) && cmIsNotFlag(sflags,kIntPoFl) && cmIsNotFlag(sflags,kUIntPoFl) )
+    cflags = cmClrFlag(cflags,kHexPoFl);
 
   // allocate the new parm recd
   _cmPoOpt_t* r = cmLhAllocZ( p->lH, _cmPoOpt_t, 1 );
 
 
-  // if enumId != 0 then this is automatically an enum type.
-  if( enumId != 0 )
+  // if this is an enum type.
+  if( cmIsFlag(sflags,kEnumPoFl) )
   {
-    flags = cmClrFlag(flags,kTypeMaskPoFl) | kEnumPoFl;
+    sflags = cmClrFlag(sflags,kTypeMaskPoFl) | kEnumPoFl;
 
     // set the master recd for this enum ptr
     _cmPoOpt_t* erp;
       r->enumPtr = erp->enumPtr==NULL ? erp : erp->enumPtr;  
 
       // if this child enum has it's required flags set 
-      if( cmIsFlag(flags,kReqPoFl) )
+      if( cmIsFlag(cflags,kReqPoFl) )
       {
         // then set the required flag in the parent and clear it in the child
         // (this way both the parent and child will not be required (which would be impossible for an enum))
-        r->enumPtr->flags = cmSetFlag(r->enumPtr->flags,kReqPoFl);
-        flags = cmClrFlag(flags,kReqPoFl);
+        r->enumPtr->cflags = cmSetFlag(r->enumPtr->cflags,kReqPoFl);
+        cflags = cmClrFlag(cflags,kReqPoFl);
       }
     }
   }
 
-  r->flags      = flags; 
+  r->cflags     = cflags; 
+  r->sflags     = sflags;
   r->numId      = numId;
   r->charId     = charId;
   r->wordId     = cmLhAllocStr( p->lH, wordId );
   r->enumId     = enumId;
   r->maxInstCnt = cnt;
   r->helpStr    = helpStr==NULL ? NULL : cmLhAllocStr( p->lH, helpStr );
-  r->link       = p->list;
-  p->list       = r;
+
+
+  _cmPoOpt_t* rp = p->list;
+  while( rp != NULL && rp->link != NULL )
+    rp = rp->link;
+
+  if( rp == NULL )
+    p->list = r;
+  else
+    rp->link = r;
+
+  //r->link       = p->list;
+  //p->list       = r;
 
   *rpp = r;
 
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kCharPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kCharPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.c = dfltVal;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kBoolPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kBoolPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.b = dfltVal;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kIntPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kIntPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.i = dfltVal;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kUIntPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kUIntPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.u = dfltVal;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kDblPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kDblPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.d = dfltVal;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kStrPoFl;
 
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, 0, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kStrPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.s = dfltVal;
   return rc;
 }
 
-cmPoRC_t cmPgmOptInstallEnum(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* wordId, unsigned flags, unsigned enumId, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr  )
+cmPoRC_t cmPgmOptInstallEnum(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* wordId, unsigned flags, unsigned enumId, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr, const cmChar_t* mstrHelpStr  )
 {
   cmPoRC_t    rc;
   _cmPoOpt_t* r     = NULL;
   _cmPo_t*    p     = _cmPoHandleToPtr(h);
 
-  flags = cmClrFlag(flags,kTypeMaskPoFl) | kEnumPoFl;
-
-  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, enumId, cnt, helpStr, &r )) != kOkPoRC )
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kEnumPoFl, enumId, cnt, helpStr, &r )) != kOkPoRC )
     return rc;
 
   r->dfltVal.u = dfltVal;
     r->retVal.u  = retValPtr;
     *r->retVal.u = dfltVal;
   }
+
+  if( mstrHelpStr != NULL )
+  {
+    _cmPoOpt_t* rp = r->enumPtr == NULL ? r : r->enumPtr;
+    rp->mstrStr = cmLhAllocStr(p->lH,mstrHelpStr);
+  }
+  return rc;
+}
+
+cmPoRC_t cmPgmOptInstallFlag(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* wordId, unsigned flags, unsigned         dfltVal, unsigned*       retValPtr, unsigned cnt, const cmChar_t* helpStr )
+{
+  cmPoRC_t    rc;
+  _cmPoOpt_t* r     = NULL;
+  _cmPo_t*    p     = _cmPoHandleToPtr(h);
+
+  if((rc= _cmPgmOptInstall(p, numId, charId, wordId, flags, kFlagPoFl, 0, cnt, helpStr, &r )) != kOkPoRC )
+    return rc;
+
+  r->dfltVal.u = dfltVal;
+  if( retValPtr != NULL )
+  {
+    r->retVal.u  = retValPtr;
+    // Unlike other parameters we don't set the initial value of flag parameter 
+    // because we don't want to destroy any default flag that may be set there
+  }
+
   return rc;
 }
 
   //  a->u.b = true;
 
   // if this is an enumerated type
-  if( cmIsFlag(r->flags,kEnumPoFl) )
+  if( cmIsFlag(r->sflags,kEnumPoFl) )
   {
     a->u.u = enumId;
 
     if( e->retVal.u != NULL )
       *e->retVal.u = enumId;
   }
+
+  // if this is a flag type
+  if( cmIsFlag(r->sflags,kFlagPoFl) )
+  {
+    a->u.u = r->dfltVal.u;
+    if( r->retVal.u != NULL )
+      *r->retVal.u |= a->u.u;
+  }
   return a;
 }
 
   a->valStr = valStr;
 
   errno = 0;
-  switch( r->flags & kTypeMaskPoFl )
+  switch( r->sflags & kTypeMaskPoFl )
   {
+    // case kFlagPoFl: 
+    // enum values get set in _cmPgmOptInsertArg()
+
+
     case kBoolPoFl: 
       //rc = _cmPgmOptParseBool(p,valStr,&a->u.b); 
       a->u.b = true;
       break;
 
     case kIntPoFl:  
-      a->u.i = strtol(valStr,NULL,10); 
+      a->u.i = strtol(valStr,NULL, cmIsFlag(r->cflags,kHexPoFl) ? 16 : 10); 
       if( r->retVal.i != NULL )
         *r->retVal.i = a->u.i;
       break;
 
     case kUIntPoFl: 
-      a->u.u = strtol(valStr,NULL,10); 
+      a->u.u = strtol(valStr,NULL, cmIsFlag(r->cflags,kHexPoFl) ? 16 : 10); 
       if( r->retVal.u != NULL )
         *r->retVal.u = a->u.u;
       break;
       // case kEnumPoFl: 
       // enum values get set in _cmPgmOptInsertArg()
 
-    case kHexPoFl:  
-      a->u.u = strtol(valStr,NULL,16); 
-      if( r->retVal.u != NULL )
-        *r->retVal.u = a->u.u;
-      break;
-
     case kDblPoFl:  
       a->u.d = strtod(valStr,NULL);    
       if( r->retVal.d != NULL )
       if( r->retVal.s != NULL )
         *r->retVal.s = a->u.s;
       break;
+
+    default:
+      { assert(0); }
   }
 
 
   return false;
 }
 
+cmPoRC_t  _cmPgmOptMissingEnumError( _cmPo_t* p, _cmPoOpt_t* r )
+{
+  _cmPoOpt_t* mstr = r->enumPtr==NULL ? r : r->enumPtr;
+  _cmPoOpt_t* rp  = p->list;
+  cmChar_t*   msg = cmTsPrintfP(NULL,"No argument was supplied for the required enumerated parameter containing the following set of possible flags: { ");
+  
+  for(; rp!=NULL; rp=rp->link)
+    if( cmIsFlag(rp->sflags,kEnumPoFl) && (rp==mstr || rp->enumPtr==mstr) )
+    {
+      msg = cmTextAppendSS(msg,rp->wordId);
+      msg = cmTextAppendSS(msg," ");
+    }
+
+  msg = cmTextAppendSS(msg,"}");
+  
+  cmPoRC_t rc = cmErrMsg(&p->err,kNoReqArgPoRC,msg);
+
+  cmMemFree(msg);
+  
+  return rc;
+}
+
 // check that all required arg.s were actually given and that the actual
 // number of instances does not exceed the defined limit
 cmPoRC_t _cmPgmOptCheckReqArgs( _cmPo_t* p )
   _cmPoOpt_t* r = p->list;
   while( r != NULL )
   {
-    if( cmIsFlag(r->flags, kReqPoFl ) )
+    if( cmIsFlag(r->cflags, kReqPoFl ) )
     {
       _cmPoArg_t* a = p->args;
       while( a != NULL )
       }
     
       if( a == NULL )
-        rc = cmErrMsg(&p->err,kNoReqArgPoRC,"No argument was supplied for the required parameter '%s'.",r->wordId);
+      {
+        if( cmIsFlag(r->sflags, kEnumPoFl ) )
+          rc =  _cmPgmOptMissingEnumError(p,r);
+        else
+          rc = cmErrMsg(&p->err,kNoReqArgPoRC,"No argument was supplied for the required parameter '%s'.",r->wordId);
+      }
 
     }
 
   _cmPoArg_t* a     = NULL;
   int         i     = 0; // arg index
   int         j     = 0; // arg label character index
+
+
+  if( _cmPgmOptNumIdToOptRecd(p,kPrintHelpPoId) == NULL )
+    cmPgmOptInstallBool(h, kPrintHelpPoId, 'h', "help",    0, false, NULL,0,"Print this usage information." );
+
+  if( _cmPgmOptNumIdToOptRecd(p,kVersionPoId) == NULL )
+    cmPgmOptInstallBool(h, kVersionPoId,   'v', "version", 0, false, NULL,0,"Print version information." );
+
+  if( _cmPgmOptNumIdToOptRecd(p,kPrintParmsPoId) == NULL )
+    cmPgmOptInstallBool(h, kPrintParmsPoId,'p', "parms",   0, false, NULL,0,"Print the arguments."); 
+
   
   while(i<argCnt)
   {
           if((r = _cmPgmOptCharIdToOptRecd(p,argArray[i][j])) == NULL )
             return cmErrMsg(&p->err,kSyntaxErrPoRC,"The program option selector char '%c' is not valid.",argArray[i][j]);
 
-          // if this charId is not a bool or enum then it must be followed by a value.
-          if( cmIsFlag(r->flags,kBoolPoFl)==false && cmIsFlag(r->flags,kEnumPoFl)==false )
+          // if this charId is not a flag,bool or enum then it must be followed by a value.
+          if( _cmPoOptUsesValue(r) )
             ++i;
           else // otherwise process the next char id in this charId token            
             ++j;
         // create an arg record for the cur char or word id.
         a = _cmPgmOptInsertArg(p, r );
 
-        // and the value type is not 'bool' or 'enum'
-        if( cmIsFlag(r->flags,kBoolPoFl)== false && cmIsFlag(r->flags,kEnumPoFl)==false )
+        // and the value type is not 'flag','bool' or 'enum'
+        if( _cmPoOptUsesValue(r) )
           state = kArgVal;
 
         switch(state)
   unsigned          n = 0;
   const _cmPoArg_t* a = p->args;
 
-  while( a != NULL && idx < n )
+  while( a != NULL && n < idx )
   {
     ++n;
     a = a->link;
   return kOkPoRC;
 }
   
-unsigned cmPgmOptSelId( cmPgmOptH_t h, unsigned argIdx )
+unsigned cmPgmOptNumId( cmPgmOptH_t h, unsigned argIdx )
 {
   const _cmPoArg_t* a;
   cmPoRC_t          rc;
   return a->opt->numId;
 }
 
+unsigned cmPgmOptCharId( cmPgmOptH_t h, unsigned argIdx )
+{
+  const _cmPoArg_t* a;
+  cmPoRC_t          rc;
+  if((rc = _cmPgmOptIndexToPtr(_cmPoHandleToPtr(h),argIdx,&a)) != kOkPoRC )
+    return cmInvalidId;
+  return a->opt->charId;
+}
+
+const cmChar_t* cmPgmOptWordId( cmPgmOptH_t h, unsigned argIdx )
+{
+  const _cmPoArg_t* a;
+  cmPoRC_t          rc;
+  if((rc = _cmPgmOptIndexToPtr(_cmPoHandleToPtr(h),argIdx,&a)) != kOkPoRC )
+    return NULL;
+  return a->opt->wordId;
+}
+
 cmPoRC_t  _cmPgmOptArgPtr( _cmPo_t* p, unsigned argIdx, const _cmPoArg_t** app )
 {
   cmPoRC_t rc;
   if(_cmPgmOptInstPtr(p,numId,instIdx,&rp,&vp) != kOkPoRC )
     return 0;
 
-  if( cmIsFlag(rp->flags,kCharPoFl) )
+  if( cmIsFlag(rp->sflags,kCharPoFl) )
   {
     cmErrMsg(&p->err,kTypeErrPoRC,"The parameter '%s' is not a 'char'.",rp->wordId);
     return 0;
   if((rc = _cmPgmOptInstPtr(p,numId,instIdx,&rp,&vp)) != kOkPoRC )
     return rc;
  
-  switch( rp->flags & kTypeMaskPoFl )
+  switch( rp->sflags & kTypeMaskPoFl )
   {
+    case kFlagPoFl: v = vp->u; break;
     case kBoolPoFl: v = vp->b; break;
     case kCharPoFl: v = vp->c; break;
     case kIntPoFl:
     case kEnumPoFl: v = vp->i; break;
     case kUIntPoFl:
-    case kHexPoFl:  v = vp->u; break;
     case kDblPoFl:  v = roundl(vp->d); break;
     case kStrPoFl:  
       cmErrMsg(&p->err,kTypeErrPoRC,"The string parameter '%s' cannot be converted to an integer.",rp->wordId);
   if((rc = _cmPgmOptInstPtr(p,numId,instIdx,&rp,&vp)) != kOkPoRC )
     return rc;
  
-  switch( rp->flags & kTypeMaskPoFl )
+  switch( rp->sflags & kTypeMaskPoFl )
   {
+    case kFlagPoFl: v = vp->u; break;
     case kBoolPoFl: v = vp->b; break;
     case kCharPoFl: v = vp->c; break;
     case kEnumPoFl:
     case kIntPoFl:  v = vp->i; break;
-    case kHexPoFl:  
     case kUIntPoFl: v = vp->u; break;
     case kDblPoFl:  v = vp->d; break;
     case kStrPoFl:  
     return NULL;
 
   // if the requested param is a defined as a string
-  if( cmIsFlag(rp->flags,kStrPoFl) )
+  if( cmIsFlag(rp->sflags,kStrPoFl) )
     return vp->s;
 
   // otherwise the requested param is not defined as a string - so try to return the instance string value
   if( p->helpBegStr != NULL )
     cmRptPrintf(rpt,"%s\n",p->helpBegStr);
 
-  while( r != NULL )
+  for(; r != NULL; r=r->link )
   {
-    cmRptPrintf(rpt,"-%c --%-20s ",r->charId,r->wordId);
+    const cmChar_t* reqStr = "(required)";
+    const cmChar_t* valueTypeLabel = "";
+    const cmChar_t* reqLabel = "";
+    const cmChar_t* indentStr = "";
+
+    const _cmPoOpt_t* mstr = NULL;
+
+    if( cmIsFlag(r->sflags,kEnumPoFl) )
+    {
+      if( r->enumPtr == NULL )
+        mstr     = r;
+      indentStr = "    ";
+    }
+
+    if( _cmPoOptUsesValue(r) ) 
+      valueTypeLabel = _cmPoTypeFlagToLabel(r->sflags & kTypeMaskPoFl,r->cflags);
+
+    if( cmIsNotFlag(r->sflags,kEnumPoFl)  && cmIsFlag(r->sflags,kReqPoFl) )
+      reqLabel = reqStr;
+
+    if( mstr != NULL )
+      cmRptPrintf(rpt,"Enumerated group: %s %s",mstr->mstrStr==NULL ? "" : mstr->mstrStr, cmIsFlag(mstr->cflags,kReqPoFl) ? reqStr : "" );
+   
+    cmRptPrintf(rpt,"%s-%c --%s %s %s",indentStr,r->charId,r->wordId,valueTypeLabel,reqLabel);
 
     if( r->helpStr != NULL )
       cmRptPrintf(rpt,"    %s\n",r->helpStr);
 
-    r = r->link;
   }
   
 
 bool _cmPgmOptPrint( _cmPo_t* p, cmRpt_t* rpt, const _cmPoOpt_t* r, const _cmPoValue_t* v, const cmChar_t* valStr )
 {
   const _cmPoOpt_t* e = r;
-  if( cmIsFlag(r->flags,kEnumPoFl) )
+  if( cmIsFlag(r->sflags,kEnumPoFl) )
   {
     if( r->enumPtr != NULL )
       return false;
   }
 
   cmRptPrintf(rpt,"-%c --%-20s %i ",e->charId,e->wordId, _cmPgmOptInstCount(r));
-  switch(r->flags & kTypeMaskPoFl)
+  switch(r->sflags & kTypeMaskPoFl)
   {
+    case kFlagPoFl: cmRptPrintf(rpt,r->cflags & kHexPoFl ? "0x%x ": "%u ",v->u ); break;
     case kBoolPoFl: cmRptPrintf(rpt,"%c ",  v->b ? 'T' : 'F'); break;
     case kCharPoFl: cmRptPrintf(rpt,"%c ",  v->c); break;
-    case kIntPoFl:  cmRptPrintf(rpt,"%i ",  v->i); break;
-    case kUIntPoFl: cmRptPrintf(rpt,"%u ",  v->u); break;
-    case kHexPoFl:  cmRptPrintf(rpt,"0x%x ",v->u); break;
+    case kIntPoFl:  cmRptPrintf(rpt,r->cflags & kHexPoFl ? "0x%x ": "%i ",  v->i); break;
+    case kUIntPoFl: cmRptPrintf(rpt,r->cflags & kHexPoFl ? "0x%x ": "%u ",  v->u); break;
     case kDblPoFl:  cmRptPrintf(rpt,"%f ",  v->d); break;
     case kStrPoFl:  cmRptPrintf(rpt,"%s ",  v->s); break;
     case kEnumPoFl: cmRptPrintf(rpt,"%i ",  v->u); break;

cmPgmOpts.h

 
   // Flag used by the 'flags' arg. to cmPgmOptInstall().
   enum { 
-    kNoPoFlags = 0x000, 
-    kReqPoFl   = 0x001,  // this is a required parameter
-    kBoolPoFl  = 0x002,  // this parameter takes a value
-    kCharPoFl  = 0x004,  // parm. value is a character
-    kIntPoFl   = 0x008,  // parm. value is a decimal int
-    kUIntPoFl  = 0x010,  // parm. value is a decimal unsigned int
-    kHexPoFl   = 0x020,  // parm. value is a hex. unsigned int 
-    kDblPoFl   = 0x040,  // parm. value is a decimal double
-    kStrPoFl   = 0x080,  // parm. value is a string (default)
-    kEnumPoFl  = 0x100,  // parm. valus is a enum type (automatically set by a non-zero enumId)
-
-    kTypeMaskPoFl = 0x1f6
+    kReqPoFl   = 0x01,  // this is a required parameter
+    kHexPoFl   = 0x02   // this integer must be given in hexidecimal or output an integer in hex.
   };
 
 
   // Define a parameter.
   //
-  // unsigned        numId,   - numeric id used to identify this parameter 
-  // const cmChar_t  charId,  - a character used to identify this parameter
-  // const cmChar_t* wordId,  - a label used to identify this parameter
+  // unsigned        numId,   - Numeric id used to identify this parameter. The min. numId should be kPoBaseId.
+  // const cmChar_t  charId,  - A character used to identify this parameter.
+  // const cmChar_t* wordId,  - A label used to identify this parameter.
   // unsigned        flags,   - kNoPoFlags | kReqPoFl (the type flags are automatically assigned)
   // unsigned        enumId,  - non-zero value used to group enumerated parameter values  (ignored for non-enum types)
+  //                 dfltVal  - The default value for this parameter.
+  //                 retValPtr- Optional pointer to a variable to receive the argument value for this parameter.
   // unsigned        cnt,     - count of times this parameter may repeated or 0 for an unlimited repetitions
   // const cmChar_t* helpStr  - a textual description of this parameter
   //
   // Notes
-  // 1) 'numId','charId', and 'wordId' must all be unique among all parameter definitions.
-  // 2) If no  parameter value type flag is given then the type is assumed to be of type bool.
-  // 3) For all parameter value types except the string type arguments are automatically parsed to the
+  // 1) 'numId','charId', and 'wordId' must all be unique among all parameter definitions.  
+  //    An error will be generated if they are not.
+  // 2) For all parameter value types except the string type arguments are automatically parsed to the
   //    defined type. To avoid automatic parsing simply define the type as a string (using cmPgmOptInstallStr()).
-  // 4) All expected parameters must be defined prior to calling cmPgmOptParse().
-  // 5) One call to cmPgmOPtInstallEnum() is made for each possible enumeration value - where the 'enumId' gives the value.
-  //    A given set of associated enum values is grouped by giving a common 'numId'.
+  // 3) All expected parameters must be defined prior to calling cmPgmOptParse().
+  // 4) One call to cmPgmOptInstallEnum() is made for each possible enumeration value - where the 'enumId' gives the value.
+  //    A given set of associated enum values is grouped by giving a common 'numId'. 
+  //    Include a master help string in one of the enumerated elements to give documentation 
+  //    text for the entire set of values.
   //    Example:
-  //     cmPgmOptInstallEnum(h,colorId,...,redId,...); 
-  //     cmPgmOptInstallEnum(h,colorId,...,greenId,...); 
-  //     cmPgmOptInstallEnum(h,colorId,...,blueId,...);   
+  //     cmPgmOptInstallEnum(h,colorId,...,redId,...,"Red","Select a color"); 
+  //     cmPgmOptInstallEnum(h,colorId,...,greenId,..."Green",NULL); 
+  //     cmPgmOptInstallEnum(h,colorId,...,blueId,...,"Blue",NULL);   
   //
-  // 6) The following id's are used for built-in actions and are therefore restricted from use by the client:
+  // 5) The following id's are used for built-in actions and are therefore restricted from use by the client:
   //    a. -h --help    Print the program usage information.
   //    b. -v --version Print the program version informatoin.
   //    c. -p --parms   Print the program parameter values.
   //
+  // 6) If a retValPtr is specified then *retValPtr it is assigned 'dfltVal' as part of the
+  //    call to cmPgmOptInstXXX().
+  // 
+  // 7) The default value of 'Flag' type parameters is always zero. 
+  //    If the 'char' or 'word' id of the Flag parameter appears in the
+  //    actual argument list then the value of the argument is 'onValue'.
+  //    Unlike other parameters Flag parameters do not initialize *regValPtr. 
+  //    If the retValPtr is given and the flag is set in the arg. list then
+  //    the retValPtr is set by bitwise assignment (i.e. *retValPtr |= dfltFlagValue).
+  //    This allows multiple Flag parameters to use the same retValPtr and
+  //    set independent bit fields in it.
   cmPoRC_t cmPgmOptInstallChar(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, cmChar_t        dfltVal, cmChar_t*        retValPtr, unsigned cnt, const cmChar_t* helpStr );
   cmPoRC_t cmPgmOptInstallBool(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, bool            dfltVal, bool*            retValPtr, unsigned cnt, const cmChar_t* helpStr );
   cmPoRC_t cmPgmOptInstallInt( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, int             dfltVal, int*             retValPtr, unsigned cnt, const cmChar_t* helpStr );
   cmPoRC_t cmPgmOptInstallUInt(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned        dfltVal, unsigned*        retValPtr, unsigned cnt, const cmChar_t* helpStr );
   cmPoRC_t cmPgmOptInstallDbl( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, double          dfltVal, double*          retValPtr, unsigned cnt, const cmChar_t* helpStr );
   cmPoRC_t cmPgmOptInstallStr( cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, const cmChar_t* dfltVal, const cmChar_t** retValPtr, unsigned cnt, const cmChar_t* helpStr );
-  cmPoRC_t cmPgmOptInstallEnum(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned enumId, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr  );
+  cmPoRC_t cmPgmOptInstallEnum(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned enumId, unsigned dfltVal, unsigned* retValPtr, unsigned cnt, const cmChar_t* helpStr, const cmChar_t* mstrHelpStr  );
+  cmPoRC_t cmPgmOptInstallFlag(cmPgmOptH_t h, unsigned numId, cmChar_t charId, const cmChar_t* worldId, unsigned flags, unsigned         onValue, unsigned*       retValPtr, unsigned cnt, const cmChar_t* helpStr );
 
   // Parse a set of command line arguments.
+  //
+  // 1) If only built-in parameters were specified then the NO check is done 
+  //    to verify that required arguments were provided.  However, if any non-built-in
+  //    arguments are provided then a check is performed to be sure that any 
+  //    parameters specified with the kPoReqFl have associated argument values.
+  //
+  // 2) If a parameter was specified with a 'retValPtr' then *retValPtr is
+  //    set to the value of the last argument associated with the given parameter.
+  //    This means that 'retValPtr' is generally only useful when the
+  //    parameter instance count limit (the 'cnt' param to cmPgmOptInstallXXX())
+  //    was set to 1.
+  //
+  //    
   cmPoRC_t cmPgmOptParse( cmPgmOptH_t h, unsigned argCnt, char* argArray[] );
   
   // Get the total count of arguments passed to cmPgmOptParse().
   // Get the numeric id associated with each argument.
   unsigned cmPgmOptNumId( cmPgmOptH_t h, unsigned argIdx );
 
+  // Get the character id associated with this argument.
+  unsigned cmPgmOptCharId( cmPgmOptH_t h, unsigned argIdx );
+
+  // Get the word id associated with this argument.
+  const cmChar_t* cmPgmOptWordId( cmPgmOptH_t h, unsigned argIdx );
+
   // Manually convert each argument string into the specified type.
   // These functions are useful if all of the parameters were defined using cmPgmOptInstallStr().
   // Use cmPgmOptRC() to check for errors.