NCBI C++ ToolKit
Classes | Public Types | Public Member Functions | Static Public Member Functions | Protected Member Functions | Protected Attributes | Private Types | Private Member Functions | Private Attributes | Friends | List of all members
CArgDescriptions Class Reference

Search Toolkit Book for CArgDescriptions

CArgDescriptions –. More...

#include <corelib/ncbiargs.hpp>

+ Inheritance diagram for CArgDescriptions:
+ Collaboration diagram for CArgDescriptions:

Classes

class  CPrintUsage
 
class  CPrintUsageXml
 
struct  SArgDependency
 

Public Types

enum  EArgSetType { eRegularArgs , eCgiArgs }
 Type of CArgDescriptions For a CGI application positional arguments and flags does not make sense (this syntax cannot be expressed by CGI protocol) More...
 
enum  EArgPositionalMode { ePositionalMode_Strict , ePositionalMode_Loose }
 Processing of positional arguments. More...
 
enum  EType {
  eString = 0 , eBoolean , eInt8 , eInteger ,
  eIntId , eDouble , eInputFile , eOutputFile ,
  eIOFile , eDirectory , eDataSize , eDateTime ,
  k_EType_Size
}
 Available argument types. More...
 
enum  EFlags {
  fPreOpen = (1 << 0) , fBinary = (1 << 1) , fAppend = (1 << 2) , fTruncate = (1 << 12) ,
  fNoCreate = (1 << 11) , fCreatePath = (1 << 8) , fFileFlags = fPreOpen | fBinary | fAppend | fTruncate | fNoCreate | fCreatePath , fAllowMultiple = (1 << 3) ,
  fIgnoreInvalidValue = (1 << 4) , fWarnOnInvalidValue = (1 << 5) , fOptionalSeparator = (1 << 6) , fOptionalSeparatorAllowConflict = (1 << 9) ,
  fMandatorySeparator = (1 << 7) , fHidden = (1 << 10) , fConfidential = (1 << 13)
}
 Additional flags, the first group is file related flags. More...
 
enum  EFlagValue { eFlagHasValueIfMissed = 0 , eFlagHasValueIfSet = 1 }
 Define how flag presence affect CArgValue::HasValue(). More...
 
enum  EConstraintNegate { eConstraintInvert , eConstraint }
 Flag to invert constraint logically. More...
 
enum  EDependency { eRequires , eExcludes }
 Dependencies between arguments. More...
 
enum  EMiscFlags {
  fNoUsage = 1 << 0 , fUsageIfNoArgs = 1 << 1 , fUsageSortArgs = 1 << 2 , fDupErrToCerr = 1 << 3 ,
  fMisc_Default = 0
}
 Miscellaneous flags. More...
 
enum  EHideStdArgs {
  fHideLogfile = 0x01 , fHideConffile = 0x02 , fHideVersion = 0x04 , fHideFullVersion = 0x08 ,
  fHideDryRun = 0x10 , fHideHelp = 0x20 , fHideFullHelp = 0x40 , fHideXmlHelp = 0x80 ,
  fHideAll = 0xFF
}
 Which standard flag's descriptions should not be displayed in the usage message. More...
 
typedef unsigned int TFlags
 Bitwise OR of "EFlags". More...
 
typedef int TMiscFlags
 Bitwise OR of "EMiscFlags". More...
 
typedef int THideStdArgs
 Binary OR of "EHideStdArgs". More...
 

Public Member Functions

 CArgDescriptions (bool auto_help=true, CArgErrorHandler *err_handler=0)
 Constructor. More...
 
virtual ~CArgDescriptions (void)
 Destructor. More...
 
void SetArgsType (EArgSetType args_type)
 Set type of argument description (cmdline vs CGI). More...
 
EArgSetType GetArgsType () const
 
void SetPositionalMode (EArgPositionalMode positional_mode)
 Select mode for processing positional arguments. More...
 
EArgPositionalMode GetPositionalMode () const
 
void AddKey (const string &name, const string &synopsis, const string &comment, EType type, TFlags flags=0)
 Add description for mandatory key. More...
 
void AddOptionalKey (const string &name, const string &synopsis, const string &comment, EType type, TFlags flags=0)
 Add description for optional key without default value. More...
 
void AddDefaultKey (const string &name, const string &synopsis, const string &comment, EType type, const string &default_value, TFlags flags=0, const string &env_var=kEmptyStr, const char *display_value=nullptr)
 Add description for optional key with default value. More...
 
void AddFlag (const string &name, const string &comment, CBoolEnum< EFlagValue > set_value=eFlagHasValueIfSet, TFlags flags=0)
 Add description for flag argument. More...
 
void AddOpening (const string &name, const string &comment, EType type, TFlags flags=0)
 Add description of mandatory opening positional argument. More...
 
void AddPositional (const string &name, const string &comment, EType type, TFlags flags=0)
 Add description for mandatory positional argument. More...
 
void AddOptionalPositional (const string &name, const string &comment, EType type, TFlags flags=0)
 Add description for optional positional argument without default value. More...
 
void AddDefaultPositional (const string &name, const string &comment, EType type, const string &default_value, TFlags flags=0, const string &env_var=kEmptyStr, const char *display_value=nullptr)
 Add description for optional positional argument with default value. More...
 
void AddExtra (unsigned n_mandatory, unsigned n_optional, const string &comment, EType type, TFlags flags=0)
 Add description for the extra, unnamed positional arguments. More...
 
void AddAlias (const string &alias, const string &arg_name)
 Add argument alias. More...
 
void AddNegatedFlagAlias (const string &alias, const string &arg_name, const string &comment=kEmptyStr)
 Add negated alias for a flag argument. More...
 
void AddDependencyGroup (CArgDependencyGroup *dep_group)
 Add a dependency group. More...
 
void SetConstraint (const string &name, const CArgAllow *constraint, EConstraintNegate negate=eConstraint)
 Set additional user defined constraint on argument value. More...
 
void SetConstraint (const string &name, const CArgAllow &constraint, EConstraintNegate negate=eConstraint)
 This version of SetConstraint doesn't take the ownership of object 'constraint'. More...
 
void SetDependency (const string &arg1, EDependency dep, const string &arg2)
 Define a dependency. More...
 
void SetCurrentGroup (const string &group)
 Set current arguments group name. More...
 
void SetErrorHandler (const string &name, CArgErrorHandler *err_handler)
 Set individual error handler for the argument. More...
 
bool Exist (const string &name) const
 Check if there is already an argument description with specified name. More...
 
void Delete (const string &name)
 Delete description of argument with name "name". More...
 
void SetUsageContext (const string &usage_name, const string &usage_description, bool usage_sort_args=false, SIZE_TYPE usage_width=78)
 Set extra info to be used by PrintUsage(). More...
 
void SetDetailedDescription (const string &usage_description)
 Set detailed usage description. More...
 
void PrintUsageIfNoArgs (bool do_print=true)
 Print usage and exit. More...
 
void SetMiscFlags (TMiscFlags flags)
 Set the selected flags. More...
 
void ResetMiscFlags (TMiscFlags flags)
 Clear the selected usage flags. More...
 
bool IsSetMiscFlag (EMiscFlags flag) const
 Check if the flag is set. More...
 
virtual stringPrintUsage (string &str, bool detailed=false) const
 Print usage message to end of specified string. More...
 
virtual void PrintUsageXml (CNcbiOstream &out) const
 Print argument description in XML format. More...
 
bool IsAutoHelpEnabled (void) const
 See if special flag "-h" is activated. More...
 
CArgDescriptionsShowAllArguments (bool show_all)
 Include hidden arguments into USAGE. More...
 
virtual void AddStdArguments (THideStdArgs mask)
 Add standard arguments. More...
 
void AddDefaultFileArguments (const string &default_config)
 Add logfile and conffile arguments. More...
 
template<class TSize , class TArray >
CArgsCreateArgs (TSize argc, TArray argv) const
 Create parsed arguments in CArgs object. More...
 
virtual CArgsCreateArgs (const CNcbiArguments &argv) const
 Parse command-line arguments 'argv' out of CNcbiArguments. More...
 
template<class T >
void ConvertKeys (CArgs *args, const T &arg_map, bool update) const
 Convert argument map (key-value pairs) into arguments in accordance with the argument descriptions. More...
 
virtual list< CArgDescriptions * > GetAllDescriptions (void)
 

Static Public Member Functions

static const char * GetTypeName (EType type)
 Get argument type's name. More...
 
static bool VerifyName (const string &name, bool extended=false)
 Verify if argument "name" is spelled correctly. More...
 

Protected Member Functions

void x_CheckAutoHelp (const string &arg) const
 Helper method for checking if auto help requested and throw CArgHelpException if help requested. More...
 

Protected Attributes

string m_UsageName
 Program name. More...
 
string m_UsageDescription
 Program description. More...
 
string m_DetailedDescription
 Program long description. More...
 
SIZE_TYPE m_UsageWidth
 Maximum length of a usage line. More...
 
bool m_AutoHelp
 Special flag "-h" activated. More...
 
bool m_HasHidden
 Has hidden arguments. More...
 

Private Types

enum  EPostCheckCaller { eCreateArgs , eConvertKeys }
 
typedef set< AutoPtr< CArgDesc > > TArgs
 Argument descr. type. More...
 
typedef TArgs::iterator TArgsI
 Arguments iterator. More...
 
typedef TArgs::const_iterator TArgsCI
 Const arguments iterator. More...
 
typedef vector< stringTPosArgs
 Positional arg. vector. More...
 
typedef list< stringTKeyFlagArgs
 List of flag arguments. More...
 
typedef vector< stringTArgGroups
 Argument groups. More...
 
typedef multimap< string, SArgDependencyTDependencies
 
typedef TDependencies::const_iterator TDependency_CI
 

Private Member Functions

void x_PrintAliasesAsXml (CNcbiOstream &out, const string &name, bool negated=false) const
 
TArgsI x_Find (const string &name, bool *negative=NULL)
 Helper method to find named parameter. More...
 
TArgsCI x_Find (const string &name, bool *negative=NULL) const
 Helper method to find named parameter – const version. More...
 
size_t x_GetGroupIndex (const string &group) const
 Get group index. More...
 
void x_AddDesc (CArgDesc &arg)
 Helper method for adding description. More...
 
void x_PreCheck (void) const
 Helper method for doing pre-processing consistency checks. More...
 
void x_PrintComment (list< string > &arr, const CArgDesc &arg, SIZE_TYPE width) const
 
bool x_CreateArg (const string &arg1, bool have_arg2, const string &arg2, unsigned *n_plain, CArgs &args) const
 Process arguments. More...
 
bool x_CreateArg (const string &arg1, const string &name, bool have_arg2, const string &arg2, unsigned int n_plain, CArgs &args, bool update=false, CArgValue **new_value=0) const
 
void x_PostCheck (CArgs &args, unsigned int n_plain, EPostCheckCaller caller) const
 Helper method for doing post-processing consistency checks. More...
 
bool x_IsMultiArg (const string &name) const
 Returns TRUE if parameter supports multiple arguments. More...
 

Private Attributes

EArgSetType m_ArgsType
 Type of arguments. More...
 
TArgs m_Args
 Assoc.map of arguments' name/descr. More...
 
TPosArgs m_PosArgs
 Pos. args, ordered by position in cmd.-line. More...
 
TPosArgs m_OpeningArgs
 Opening args, ordered by position in cmd.-line. More...
 
TKeyFlagArgs m_KeyFlagArgs
 Key/flag args, in order of insertion. More...
 
string m_NoSeparator
 Arguments allowed to use no separator. More...
 
unsigned m_nExtra
 
unsigned m_nExtraOpt
 > # of mandatory extra args More...
 
TArgGroups m_ArgGroups
 Argument groups. More...
 
size_t m_CurrentGroup
 Currently selected group (0 = no group) More...
 
EArgPositionalMode m_PositionalMode
 Processing of positional args. More...
 
TDependencies m_Dependencies
 Arguments' dependencies. More...
 
TMiscFlags m_MiscFlags
 Flags for USAGE, error handling etc. More...
 
set< CConstRef< CArgDependencyGroup > > m_DependencyGroups
 
CRef< CArgErrorHandlerm_ErrorHandler
 Global error handler or NULL. More...
 

Friends

class CCommandArgDescriptions
 

Detailed Description

CArgDescriptions –.

Description of unparsed arguments.

Container to store the command-line argument descriptions. Provides the means for the parsing and verification of command-line arguments against the contained descriptions.

Example: Translating "CNcbiArguments" —> "CArgs". Can also be used to compose and print out the USAGE info.

See also
CInputStreamSource CInputStreamSource helper class makes it possible to supply a list of input files, or list of directories

Definition at line 540 of file ncbiargs.hpp.


The documentation for this class was generated from the following files:
Modified on Wed Apr 17 13:08:56 2024 by modify_doxy.py rev. 669887