NCBI C++ ToolKit
ncbiargs.hpp
Go to the documentation of this file.

Go to the SVN repository for this file.

1 #ifndef CORELIB___NCBIARGS__HPP
2 #define CORELIB___NCBIARGS__HPP
3 
4 /* $Id: ncbiargs.hpp 94453 2021-08-05 16:06:49Z lavr $
5  * ===========================================================================
6  *
7  * PUBLIC DOMAIN NOTICE
8  * National Center for Biotechnology Information
9  *
10  * This software/database is a "United States Government Work" under the
11  * terms of the United States Copyright Act. It was written as part of
12  * the author's official duties as a United States Government employee and
13  * thus cannot be copyrighted. This software/database is freely available
14  * to the public for use. The National Library of Medicine and the U.S.
15  * Government have not placed any restriction on its use or reproduction.
16  *
17  * Although all reasonable efforts have been taken to ensure the accuracy
18  * and reliability of the software and data, the NLM and the U.S.
19  * Government do not and cannot warrant the performance or results that
20  * may be obtained by using this software or data. The NLM and the U.S.
21  * Government disclaim all warranties, express or implied, including
22  * warranties of performance, merchantability or fitness for any particular
23  * purpose.
24  *
25  * Please cite the author in any work or product based on this material.
26  *
27  * ===========================================================================
28  *
29  * Author: Denis Vakatov, Andrei Gourianov
30  *
31  *
32  */
33 
34 /// @file ncbiargs.hpp
35 /// Defines command line argument related classes.
36 ///
37 /// The CArgDescriptions and CArgDesc classes are used for describing
38 /// unparsed arguments; CArgs and CArgValue for parsed argument values;
39 /// CArgException and CArgHelpException for argument exceptions; and CArgAllow,
40 /// CArgAllow_{Strings, ..., Integers, Doubles} for argument constraints.
41 ///
42 /// The following description is included as applies to several classes in
43 /// this file:
44 ///
45 /// Parsing and validation of command-line arguments are done according to
46 /// user-provided descriptions. The command line has the following syntax:
47 ///
48 /// Command string:
49 ///
50 /// progname {arg_key, arg_key_opt, arg_key_dflt, arg_flag} [--]
51 /// {arg_pos} {arg_pos_opt, arg_pos_dflt}
52 /// {arg_extra} {arg_extra_opt}
53 ///
54 /// where:
55 ///
56 /// arg_key := -<key> <value> -- (mandatory)
57 /// arg_key_opt := [-<key> <value>] -- (optional, without default value)
58 /// arg_key_dflt := [-<key> <value>] -- (optional, with default value)
59 /// arg_flag := -<flag> -- (always optional)
60 /// "--" is an optional delimiter to indicate the beginning of pos. args
61 /// arg_pos := <value> -- (mandatory)
62 /// arg_pos_opt := [<value>] -- (optional, without default value)
63 /// arg_pos_dflt := [<value>] -- (optional, with default value)
64 /// arg_extra := <value> -- (dep. on the constraint policy)
65 /// arg_extra_opt := [<value>] -- (dep. on the constraint policy)
66 ///
67 /// and:
68 ///
69 /// <key> must be followed by <value>
70 /// <flag> and <key> are case-sensitive, and they can contain
71 /// only alphanumeric characters
72 /// <value> is an arbitrary string (additional constraints can
73 /// be applied in the argument description, see "EType")
74 ///
75 /// {arg_pos***} and {arg_extra***} -- position-dependent arguments, with
76 /// no tag preceding them.
77 /// {arg_pos***} -- have individual names and descriptions (see methods
78 /// AddPositional***).
79 /// {arg_extra***} have one description for all (see method AddExtra).
80 /// User can apply constraints on the number of mandatory and optional
81 /// {arg_extra***} arguments.
82 
83 
84 #include <corelib/ncbiobj.hpp>
85 #include <corelib/ncbi_limits.h>
86 #include <corelib/ncbitime.hpp>
87 #include <corelib/ncbimisc.hpp>
88 #include <memory>
89 #include <set>
90 #include <list>
91 #include <vector>
92 
93 
94 /** @addtogroup Args
95  *
96  * @{
97  */
98 
99 
101 
102 
103 // Some necessary forward declarations.
104 class CNcbiArguments;
105 class CArgAllow;
106 class CDir;
107 class CArgDependencyGroup;
108 
109 
110 /////////////////////////////////////////////////////////////////////////////
111 ///
112 /// CArgException --
113 ///
114 /// Define exceptions class for incorrectly formed arguments.
115 ///
116 /// CArgException inherits its basic functionality from CCoreException
117 /// and defines additional error codes for malformed arguments.
118 
120 {
121 public:
122  /// Error types for improperly formatted arguments.
123  ///
124  /// These error conditions are checked for and caught when processing
125  /// arguments.
126  enum EErrCode {
127  eInvalidArg, ///< Invalid argument
128  eNoValue, ///< Expecting an argument value
129  eExcludedValue, ///< The value is excluded by another argument
130  eWrongCast, ///< Incorrect cast for an argument
131  eConvert, ///< Conversion problem
132  eNoFile, ///< Expecting a file
133  eConstraint, ///< Argument value outside constraints
134  eArgType, ///< Wrong argument type
135  eNoArg, ///< No argument
136  eSynopsis ///< Synopsis error
137  };
138 
139  /// Translate from the error code value to its string representation.
140  virtual const char* GetErrCodeString(void) const override;
141 
142  // Standard exception bolier plate code.
144 };
145 
146 
147 
148 /////////////////////////////////////////////////////////////////////////////
149 ///
150 /// CArgHelpException --
151 ///
152 /// Define exception class that gets thrown for Help messages.
153 ///
154 /// CArgException inherits its basic functionality from CArgException
155 /// and defines an additional error code for help.
156 
158 {
159 public:
160  /// Error type for help exception.
161  enum EErrCode {
162  eHelp, ///< Error code for short help message
163  eHelpFull, ///< Error code for detailed help message
164  eHelpShowAll, ///< Error code for detailed help message which includes hidden arguments
165  eHelpXml, ///< Error code for XML formatted help message
166  eHelpErr ///< Show short help message and return error
167  };
168 
169  /// Translate from the error code value to its string representation.
170  virtual const char* GetErrCodeString(void) const override;
171 
172  // Standard exception bolier plate code.
174 };
175 
176 
177 /////////////////////////////////////////////////////////////////////////////
178 ///
179 /// CArgValue --
180 ///
181 /// Generic abstract base class for argument values.
182 
184 {
185 public:
186  /// Get argument name.
187  const string& GetName(void) const { return m_Name; }
188 
189  /// Check if argument holds a value.
190  ///
191  /// Argument does not hold value if it was described as optional argument
192  /// without default value, and if it was not passed a value in the command
193  /// line. On attempt to retrieve the value from such "no-value" argument,
194  /// exception will be thrown.
195  ///
196  /// NOTE: HasValue() and operator bool() check if the argument has any value,
197  /// they do not return the actual value of boolean arguments.
198  /// if (args["bv"]) ... - check if "bv" has any value
199  /// if (args["bv"].AsBoolean()) ... - check the actual value of "bv" argument
200  virtual bool HasValue(void) const = 0;
201 
202  /// Synonym for HasValue().
204 
205  /// Get the argument's string value.
206  ///
207  /// If it is a value of a flag argument, then return either "true"
208  /// or "false".
209  /// @sa
210  /// AsInteger(), AsInt8(), AsDouble(), AsBoolean()
211  virtual const string& AsString(void) const = 0;
212 
213  /// Get the argument's integer (8-byte long) value.
214  ///
215  /// If you request a wrong value type, such as a call to "AsInt8()"
216  /// for a "boolean" argument, an exception is thrown.
217  /// This will however work okay for "plain integer" argument.
218  /// @sa
219  /// AsInteger(), AsString(), AsDouble, AsBoolean()
220  virtual Int8 AsInt8(void) const = 0;
221 
222  /// Get the argument's integer value.
223  ///
224  /// If you request a wrong value type, such as a call to "AsInteger()"
225  /// for a "boolean" or even "Int8" argument, an exception is thrown.
226  /// @sa
227  /// AsInt8(), AsString(), AsDouble, AsBoolean()
228  virtual int AsInteger(void) const = 0;
229 
230  /// Get the argument's value as an integer id (TIntId). The actual value is
231  /// Int4 or Int8 depending on the NCBI_INT8_GI definition.
232  ///
233  /// If you request a wrong value type, such as a call to "AsIntId()"
234  /// for a "boolean", an exception is thrown. Calling AsIntId() on an
235  /// integer argument is always allowed. For an Int8 argument it will
236  /// throw an exception if NCBI_INT8_GI is not defined.
237  /// @sa
238  /// AsInteger(), AsInt8()
239  virtual TIntId AsIntId(void) const = 0;
240 
241  /// Get the argument's double value.
242  ///
243  /// If you request a wrong value type, such as a call to "AsDouble()"
244  /// for a "boolean" argument, an exception is thrown.
245  /// @sa
246  /// AsString(), AsInt8(), AsInteger, AsBoolean()
247  virtual double AsDouble (void) const = 0;
248 
249  /// Get the argument's boolean value.
250  ///
251  /// If you request a wrong value type, such as a call to "AsBoolean()"
252  /// for a "integer" argument, an exception is thrown.
253  ///
254  /// NOTE: Do not confuse HasValue(), operator bool() and AsBoolean().
255  /// The former two methods check if the argument has any value, they
256  /// do not return its actual value.
257  ///
258  /// @sa
259  /// HasValue(), AsString(), AsInt8(), AsInteger, AsDouble()
260  virtual bool AsBoolean(void) const = 0;
261 
262  enum EFileFlags {
263  fBinary = (1 << 1), ///< Open file in binary mode.
264  fText = 0, ///< Open file in text mode.
265  fAppend = (1 << 2), ///< Open file in append mode.
266  fTruncate = (1 << 12), ///< Open file in truncate mode.
267  fNoCreate = (1 << 11), ///< Open existing file, never create it
268  fCreatePath = (1 << 8) ///< If needed, create directory where the file is located
269  };
270  typedef unsigned int TFileFlags; ///< Bitwise OR of "EFileFlags"
271 
272  /// Get the argument as an input file stream.
273  virtual CNcbiIstream& AsInputFile (TFileFlags flags = 0) const = 0;
274 
275  /// Get the argument as an output file stream.
276  virtual CNcbiOstream& AsOutputFile(TFileFlags flags = 0) const = 0;
277 
278  /// Get the argument as a file stream.
279  virtual CNcbiIostream& AsIOFile(TFileFlags flags = 0) const = 0;
280 
281  /// Get the argument as a directory.
282  virtual const CDir& AsDirectory(void) const = 0;
283 
284  /// Get the argument as a DateTime.
285  virtual const CTime& AsDateTime(void) const = 0;
286 
287  /// Close the file.
288  virtual void CloseFile (void) const = 0;
289 
290  /// Some values types can contain several value lists
291  ///
292  /// Example: CGIs pass list selections by repeating the same name
293  typedef vector<string> TStringArray;
294 
295  /// Get the value list
296  virtual const TStringArray& GetStringList() const;
297 
298  /// Get reference on value list for further modification
299  virtual TStringArray& SetStringList();
300 
301  /// Get ordinal position of the value.
302  /// NOTE: this is not the position in command line, rather
303  /// this reflects the order in which values were added to the list.
304  size_t GetOrdinalPosition(void) const
305  {
306  return m_Ordinal;
307  }
308 
309  /// Whether the argument:
310  /// @sa GetDefault()
312  fArgValue_HasDefault = (1 << 0), ///< Has default value
313  fArgValue_FromDefault = (1 << 1) ///< Not provided in command line
314  };
315  typedef unsigned int TArgValueFlags; ///< Bitwise OR of "EArgValueFlags"
316 
317  /// Get default value of the argument.
318  ///
319  /// @param flags
320  /// Indicate whether the argument has default value, and if the arg's
321  /// value was set from the command line or from the default value.
322  /// @return
323  /// Default value, if specified for this argument.
324  /// If the argument doesn't have a default value: empty string.
325  /// If the argument is a flag: "false" or "true".
326  const string& GetDefault(TArgValueFlags* flags = NULL) const;
327 
328 protected:
329  friend class CArgs;
330  friend class CArgDescDefault;
331  friend class CArgDescMandatory;
332  friend class CArgDesc_Flag;
333 
334  /// Protected constructor and destructor.
335  ///
336  /// Prohibit explicit instantiation of CArgValue with name.
337  CArgValue(const string& name);
338  virtual ~CArgValue(void);
339 
340  void SetOrdinalPosition(size_t pos)
341  {
342  m_Ordinal = pos;
343  }
344  void x_SetDefault(const string& def_value, bool from_def);
345 
346  string m_Name; ///< Argument name
347  size_t m_Ordinal;
348  string m_Default;
350 };
351 
352 
353 // Overload the comparison operator -- to handle "CRef<CArgValue>" elements
354 // in "CArgs::m_Args" stored as "set< CRef<CArgValue> >"
355 //
356 inline bool operator< (const CRef<CArgValue>& x, const CRef<CArgValue>& y)
357 {
358  return x->GetName() < y->GetName();
359 }
360 
361 
362 
363 /////////////////////////////////////////////////////////////////////////////
364 ///
365 /// CArgs --
366 ///
367 /// Defines parsed arguments.
368 ///
369 /// Argument values are obtained from the unprocessed command-line arguments
370 /// (via CNcbiArguments) and then verified and processed according to the
371 /// argument descriptions defined by user in "CArgDescriptions".
372 ///
373 /// NOTE: the extra arguments can be accessed using virtual names:
374 /// "#1", "#2", "#3", ..., "#<GetNExtra()>"
375 /// in the order of insertion (by method Add).
376 ///
377 
379 {
380 public:
381  /// Constructor.
382  CArgs(void);
383 
384  /// Destructor.
385  ~CArgs(void);
386 
387  /// Creating copy of this object usually makes no sense
388  /// if it is really required, please use Assign method
389  NCBI_DEPRECATED_CTOR(CArgs(const CArgs& other));
390 
391  /// Creating copy of this object usually makes no sense
392  /// if it is really required, please use Assign method
393  NCBI_DEPRECATED CArgs& operator=(const CArgs& other);
394 
395  /// Copy contents of another object into this one
396  CArgs& Assign(const CArgs& other);
397 
398  /// Check existence of argument description.
399  ///
400  /// Return TRUE if arg "name" was described in the parent CArgDescriptions.
401  ///
402  /// NOTE: Do not confuse this method with CArgValue::HasValue() which checks
403  /// if the argument not just exists, but was assigned a value (possibly the
404  /// default one).
405  bool Exist(const string& name) const;
406 
407  /// Get value of argument by name. If the name starts with '-'
408  /// (e.g. '-arg') the argument can also be found by 'arg' name if there
409  /// is no another argument named 'arg'.
410  ///
411  /// Throw an exception if such argument does not exist (not described
412  /// in the CArgDescriptions).
413  ///
414  /// @attention CArgValue::operator bool() can return TRUE even if the
415  /// argument was not specified in the command-line -- if the
416  /// argument has a default value.
417  /// @sa
418  /// Exist() above.
419  const CArgValue& operator[] (const string& name) const;
420 
421  /// Get the number of unnamed positional (a.k.a. extra) args.
422  size_t GetNExtra(void) const { return m_nExtra; }
423 
424  /// Return N-th extra arg value, N = 1 to GetNExtra().
425  const CArgValue& operator[] (size_t idx) const;
426 
427  /// Get all available arguments
428  vector< CRef<CArgValue> > GetAll(void) const;
429 
430  /// Print (append) all arguments to the string "str" and return "str".
431  string& Print(string& str) const;
432 
433  /// Add new argument name and value.
434  ///
435  /// Throw an exception if the "name" is not an empty string, and if
436  /// there is an argument with this name already and "update" parameter is
437  /// not set.
438  ///
439  /// HINT: Use empty "name" to add extra (unnamed) args, and they will be
440  /// automagically assigned with the virtual names: "#1", "#2", "#3", etc.
441  ///
442  /// @param arg
443  /// argument value added to the collection
444  /// @param update
445  /// when TRUE and argument already exists it will be replaced
446  /// when FALSE throws an exception
447  /// @param add_value
448  /// when TRUE and argument already exists the value is
449  /// added to the string list (multiple argument)
450  void Add(CArgValue* arg,
451  bool update = false,
452  bool add_value = false);
453 
454  /// Check if there are no arguments in this container.
455  bool IsEmpty(void) const;
456 
457  /// Remove argument of name "name"
458  void Remove(const string& name);
459 
460  /// Remove all arguments
461  void Reset(void);
462 
463  /// Get current command
464  /// @sa CCommandArgDescriptions
465  string GetCommand(void) const
466  {
467  return m_Command;
468  }
469 
470 protected:
471  /// Set current command
472  /// @sa CCommandArgDescriptions
473  CArgs* SetCommand(const string& command)
474  {
475  m_Command = command;
476  return this;
477  }
478 
479 private:
480  typedef set< CRef<CArgValue> > TArgs; ///< Type for arguments
481  typedef TArgs::iterator TArgsI; ///< Type for iterator
482  typedef TArgs::const_iterator TArgsCI; ///< Type for const iterator
483 
484  TArgs m_Args; ///< Assoc. map of arguments' name/value
485  size_t m_nExtra; ///< Cached # of unnamed positional arguments
486  string m_Command;
487 
488  /// Find argument value with name "name".
489  TArgsCI x_Find(const string& name) const;
490  TArgsI x_Find(const string& name);
492 };
493 
494 
495 
496 class CArgDesc;
497 
498 
499 /////////////////////////////////////////////////////////////////////////////
500 ///
501 /// CArgErrorHandler --
502 ///
503 /// Base/default error handler for arguments parsing.
504 
506 {
507 public:
508  /// Process invalid argument value. The base implementation returns NULL
509  /// or throws exception depending on the CArgDesc flags.
510  /// @param arg_desc
511  /// CArgDesc object which failed to initialize.
512  /// @param value
513  /// String value which caused the error.
514  /// @return
515  /// Return new CArgValue object or NULL if the argument should be
516  /// ignored (as if it has not been set in the command line).
517  virtual CArgValue* HandleError(const CArgDesc& arg_desc,
518  const string& value) const;
519 };
520 
521 
522 
523 /////////////////////////////////////////////////////////////////////////////
524 ///
525 /// CArgDescriptions --
526 ///
527 /// Description of unparsed arguments.
528 ///
529 /// Container to store the command-line argument descriptions. Provides the
530 /// means for the parsing and verification of command-line arguments against
531 /// the contained descriptions.
532 ///
533 /// Example: Translating "CNcbiArguments" ---> "CArgs".
534 /// Can also be used to compose and print out the USAGE info.
535 ///
536 /// @sa CInputStreamSource
537 /// CInputStreamSource helper class makes it possible to supply a list of
538 /// input files, or list of directories
539 
541 {
542 public:
543  /// Constructor.
544  ///
545  /// If "auto_help" is passed TRUE, then a special flag "-h" will be added
546  /// to the list of accepted arguments. Passing "-h" in the command line
547  /// will printout USAGE and ignore all other passed arguments.
548  /// Error handler is used to process errors when parsing arguments.
549  /// If not set the default handler is used.
550  CArgDescriptions(bool auto_help = true,
552 
553  /// Destructor.
554  virtual ~CArgDescriptions(void);
555 
556  /// Type of CArgDescriptions
557  /// For a CGI application positional arguments and flags does not make
558  /// sense (this syntax cannot be expressed by CGI protocol)
559  enum EArgSetType {
560  eRegularArgs, ///< Regular application
561  eCgiArgs ///< CGI application
562  };
563 
564  /// Set type of argument description (cmdline vs CGI).
565  /// Method performs verification of arguments,
566  /// throws an exception if it finds positional args set for a CGI
567  void SetArgsType(EArgSetType args_type);
568 
569  EArgSetType GetArgsType() const { return m_ArgsType; }
570 
571  /// Processing of positional arguments.
572  /// In strict mode any value starting with '-' is treated as a key/flag
573  /// unless any positional arguments have already been found (e.g. after
574  /// '--' argument). In loose mode any argument is treated as positional
575  /// if it can not be processed as a valid key or flag.
577  ePositionalMode_Strict, ///< Strict mode (default)
578  ePositionalMode_Loose ///< Loose mode
579  };
580 
581  /// Select mode for processing positional arguments.
582  void SetPositionalMode(EArgPositionalMode positional_mode)
583  { m_PositionalMode = positional_mode; }
584 
585  EArgPositionalMode GetPositionalMode() const { return m_PositionalMode; }
586 
587  /// Available argument types.
588  enum EType {
589  eString = 0, ///< An arbitrary string
590  eBoolean, ///< {'true', 't', 'false', 'f'}, case-insensitive
591  eInt8, ///< Convertible into an integer number (Int8 only)
592  eInteger, ///< Convertible into an integer number (int or Int8)
593  eIntId, ///< Convertible to TIntId (int or Int8 depending on NCBI_INT8_GI)
594  eDouble, ///< Convertible into a floating point number (double)
595  eInputFile, ///< Name of file (must exist and be readable)
596  eOutputFile, ///< Name of file (must be writable)
597  eIOFile, ///< Name of file (must be writable)
598  eDirectory, ///< Name of file directory
599  eDataSize, ///< Integer number with possible "software" qualifiers (KB, KiB, et al)
600  eDateTime, ///< DateTime string, formats:
601  ///< "M/D/Y h:m:s", "Y-M-DTh:m:g", "Y/M/D h:m:g", "Y-M-D h:m:g".
602  ///< Time string can have trailing 'Z' symbol, specifying that
603  ///< it represent time in the UTC format.
604  k_EType_Size ///< For internal use only
605  };
606 
607  /// Get argument type's name.
608  static const char* GetTypeName(EType type);
609 
610  /// Additional flags, the first group is file related flags.
611  ///
612  /// Must match the argument type, or an exception will be thrown.
613  /// ( File related are for eInputFile and eOutputFiler argument types.)
614  enum EFlags {
615  // File related flags:
616 
617  /// Open file right away; for eInputFile, eOutputFile, eIOFile
618  fPreOpen = (1 << 0),
619  /// Open as binary file; for eInputFile, eOutputFile, eIOFile
620  fBinary = (1 << 1),
621  /// Append to end-of-file; for eOutputFile or eIOFile
622  fAppend = (1 << 2),
623  /// Delete contents of an existing file; for eOutputFile or eIOFile
624  fTruncate = (1 << 12),
625  /// If the file does not exist, do not create it; for eOutputFile or eIOFile
626  fNoCreate = (1 << 11),
627  /// If needed, create directory where the file is located
628  fCreatePath = (1 << 8),
629 
630  /// Mask for all file-related flags
631  fFileFlags = fPreOpen | fBinary | fAppend | fTruncate | fNoCreate | fCreatePath,
632  // multiple keys flag:
633 
634  /// Repeated key arguments are legal (use with AddKey)
635  fAllowMultiple = (1 << 3),
636 
637  // Error handling flags:
638 
639  /// Ignore invalid argument values. If not set, exceptions will be
640  /// thrown on invalid values.
641  fIgnoreInvalidValue = (1 << 4),
642  /// Post warning when an invalid value is ignored (no effect
643  /// if fIgnoreInvalidValue is not set).
644  fWarnOnInvalidValue = (1 << 5),
645 
646  /// Allow to ignore separator between the argument's name and value.
647  /// Usual ' ' or '=' separators can still be used with the argument.
648  /// The following restrictions apply to a no-separator argument:
649  /// - the argument must be a key (including optional or default);
650  /// - the argument's name must be a single char;
651  /// - no other argument's name can start with the same char,
652  /// unless fOptionalSeparatorAllowConflict is also specified.
653  fOptionalSeparator = (1 << 6),
654  /// For arguments with fOptionalSeparator flag, allow
655  /// other arguments which names begin with the same char.
656  fOptionalSeparatorAllowConflict = (1 << 9),
657 
658  /// Require '=' separator
659  fMandatorySeparator = (1 << 7),
660 
661  /// Hide it in Usage
662  fHidden = (1 << 10),
663 
664  /// Confidential argument
665  /// Such arguments can be read from command line, from file, or from
666  /// console.
667  /// On command line, they can appear in one of the following forms:
668  /// -key -- read value from console, with automatically
669  /// generated prompt
670  /// -key-file fname -- read value from file 'fname',
671  /// if 'fname' equals '-', read value from
672  /// standard input (stdin) without any prompt
673  /// -key-verbatim value -- read value from the command line, as is
674  fConfidential = (1 << 13)
675  };
676  typedef unsigned int TFlags; ///< Bitwise OR of "EFlags"
677 
678  /// Add description for mandatory key.
679  ///
680  /// Mandatory key has the syntax:
681  ///
682  /// arg_key := -<key> <value>
683  ///
684  /// Will throw exception CArgException if:
685  /// - description with name "name" already exists
686  /// - "name" contains symbols other than {alnum, '-', '_'}
687  /// - "name" starts with more than one '-'
688  /// - "synopsis" contains symbols other than {alnum, '_'}
689  /// - "flags" are inconsistent with "type"
690  ///
691  /// Any argument can be later referenced using its unique name "name".
692  void AddKey(const string& name, ///< Name of argument key
693  const string& synopsis, ///< Synopsis for argument
694  const string& comment, ///< Argument description
695  EType type, ///< Argument type
696  TFlags flags = 0 ///< Optional flags
697  );
698 
699  /// Add description for optional key without default value.
700  ///
701  /// Optional key without default value has the following syntax:
702  ///
703  /// arg_key_opt := [-<key> <value>]
704  ///
705  /// Will throw exception CArgException if:
706  /// - description with name "name" already exists
707  /// - "name" contains symbols other than {alnum, '-', '_'}
708  /// - "name" starts with more than one '-'
709  /// - "synopsis" contains symbols other than {alnum, '_'}
710  /// - "flags" are inconsistent with "type"
711  ///
712  /// Any argument can be later referenced using its unique name "name".
713  void AddOptionalKey(const string& name, ///< Name of argument key
714  const string& synopsis, ///< Synopsis for argument
715  const string& comment, ///< Argument description
716  EType type, ///< Argument type
717  TFlags flags = 0 ///< Optional flags
718  );
719 
720  /// Add description for optional key with default value.
721  ///
722  /// Optional key with default value has the following syntax:
723  ///
724  /// arg_key_dflt := [-<key> <value>]
725  ///
726  /// Will throw exception CArgException if:
727  /// - description with name "name" already exists
728  /// - "name" contains symbols other than {alnum, '-', '_'}
729  /// - "name" starts with more than one '-'
730  /// - "synopsis" contains symbols other than {alnum, '_'}
731  /// - "flags" are inconsistent with "type"
732  ///
733  /// Any argument can be later referenced using its unique name "name".
734  void AddDefaultKey(const string& name, ///< Name of argument key
735  const string& synopsis, ///< Synopsis for argument
736  const string& comment, ///< Argument description
737  EType type, ///< Argument type
738  const string& default_value, ///< Default value
739  TFlags flags = 0, ///< Optional flags
740  /// Optional name of environment variable that
741  /// contains default value
742  const string& env_var = kEmptyStr,
743  /// Default value shown in Usage
744  const char* display_value = nullptr
745  );
746 
747  /// Define how flag presence affect CArgValue::HasValue().
748  /// @sa AddFlag
749  enum EFlagValue {
750  eFlagHasValueIfMissed = 0,
751  eFlagHasValueIfSet = 1
752  };
753 
754  /// Add description for flag argument.
755  ///
756  /// Flag argument has the following syntax:
757  ///
758  /// arg_flag := -<flag>, <flag> := "name"
759  ///
760  /// If argument "set_value" is eFlagHasValueIfSet (TRUE), then:
761  /// - if the flag is provided (in the command-line), then the resultant
762  /// CArgValue::HasValue() will be TRUE;
763  /// - else it will be FALSE.
764  ///
765  /// Setting argument "set_value" to FALSE will reverse the above meaning.
766  ///
767  /// NOTE: If CArgValue::HasValue() is TRUE, then AsBoolean() is
768  /// always TRUE.
769  void AddFlag(const string& name, ///< Name of argument
770  const string& comment, ///< Argument description
771  CBoolEnum<EFlagValue> set_value = eFlagHasValueIfSet,
772  TFlags flags = 0 ///< Optional flags
773  );
774 
775  /// Add description of mandatory opening positional argument.
776  ///
777  /// Mandatory opening argument has the following syntax:
778  /// arg_pos := <value>
779  ///
780  /// NOTE:
781  /// In command line, mandatory opening arguments must go first,
782  /// before any other arguments; their order is defined by the order
783  /// in which they were described and added into CArgDescriptions.
784  ///
785  /// Will throw exception CArgException if:
786  /// - description with name "name" already exists
787  /// - "name" contains symbols other than {alnum, '-', '_'}
788  /// - "name" starts with more than one '-'
789  /// - "flags" are inconsistent with "type"
790  ///
791  /// Any argument can be later referenced using its unique name "name".
792  void AddOpening(const string& name, ///< Name of argument
793  const string& comment, ///< Argument description
794  EType type, ///< Argument type
795  TFlags flags = 0 ///< Optional flags
796  );
797 
798  /// Add description for mandatory positional argument.
799  ///
800  /// Mandatory positional argument has the following syntax:
801  ///
802  /// arg_pos := <value>
803  ///
804  /// NOTE: For all types of positional arguments:
805  /// - The order is important! That is, the N-th positional argument passed
806  /// in the cmd.-line will be matched against (and processed according to)
807  /// the N-th added named positional argument description.
808  /// - Mandatory positional args always go first.
809  ///
810  /// Will throw exception CArgException if:
811  /// - description with name "name" already exists
812  /// - "name" contains symbols other than {alnum, '-', '_'}
813  /// - "name" starts with more than one '-'
814  /// - "flags" are inconsistent with "type"
815  ///
816  /// Any argument can be later referenced using its unique name "name".
817  void AddPositional(const string& name, ///< Name of argument
818  const string& comment, ///< Argument description
819  EType type, ///< Argument type
820  TFlags flags = 0 ///< Optional flags
821  );
822 
823  /// Add description for optional positional argument without default
824  /// value.
825  ///
826  /// Optional positional argument, without default value has the following
827  /// syntax:
828  ///
829  /// arg_pos_opt := [<value>]
830  ///
831  /// Will throw exception CArgException if:
832  /// - description with name "name" already exists
833  /// - "name" contains symbols other than {alnum, '-', '_'}
834  /// - "name" starts with more than one '-'
835  /// - "flags" are inconsistent with "type"
836  ///
837  /// Any argument can be later referenced using its unique name "name".
838  /// @sa
839  /// NOTE for AddPositional()
840  void AddOptionalPositional(const string& name, ///< Name of argument
841  const string& comment, ///< Argument descr.
842  EType type, ///< Argument type
843  TFlags flags = 0 ///< Optional flags
844  );
845 
846  /// Add description for optional positional argument with default value.
847  ///
848  /// Optional positional argument with default value has the following
849  /// syntax:
850  ///
851  /// arg_pos_dflt := [<value>]
852  ///
853  /// Will throw exception CArgException if:
854  /// - description with name "name" already exists
855  /// - "name" contains symbols other than {alnum, '-', '_'}
856  /// - "name" starts with more than one '-'
857  /// - "flags" are inconsistent with "type"
858  ///
859  /// @sa
860  /// NOTE for AddPositional()
861  void AddDefaultPositional(const string& name, ///< Name of argument
862  const string& comment,///< Argument description
863  EType type, ///< Argument type
864  const string& default_value, ///< Default value
865  TFlags flags = 0, ///< Optional flags
866  /// Optional name of environment variable that
867  /// contains default value
868  const string& env_var = kEmptyStr,
869  /// Default value shown in Usage
870  const char* display_value = nullptr
871  );
872 
873  /// Add description for the extra, unnamed positional arguments.
874  ///
875  /// The name of this description is always an empty string.
876  /// Names of the resulting arg.values will be: "#1", "#2", ...
877  /// By default, no extra args are allowed.
878  ///
879  /// To allow an unlimited # of optional argumens pass
880  /// "n_optional" = kMax_UInt.
881  ///
882  /// Will throw exception CArgException if:
883  /// - description with name "name" already exists
884  /// - "flags" are inconsistent with "type"
885  void AddExtra(unsigned n_mandatory, ///< Number of mandatory args
886  unsigned n_optional, ///< Number of optional args
887  const string& comment, ///< Argument description
888  EType type, ///< Argument type
889  TFlags flags = 0 ///< Optional flags
890  );
891 
892  /// Add argument alias. The alias can be used in the command line instead
893  /// of the original argument. Accessing argument value by its alias is
894  /// not allowed (will be reported as an unknown argument). The alias will
895  /// be printed in USAGE after the original argument name.
896  /// @param alias
897  /// New alias for a real argument.
898  /// @param arg_name
899  /// The real argument's name.
900  void AddAlias(const string& alias, const string& arg_name);
901  /// Add negated alias for a flag argument. Using the alias in the
902  /// command line produces the same effect as using the original
903  /// flag with the opposite value. If 'arg_name' does not describe
904  /// a flag argument, an exception is thrown.
905  /// @sa
906  /// AddAlias()
907  void AddNegatedFlagAlias(const string& alias,
908  const string& arg_name,
909  const string& comment = kEmptyStr);
910 
911  /// Add a dependency group.
912  /// The argument constraints specified by the dependency group(s)
913  /// will be processed only after all regular dependencies for arguments and
914  /// dependency groups have been processed.
915  /// @attention
916  /// The "dep_group" will be added by reference, and its lifetime will then
917  /// be managed according to the usual CObject/CRef rules.
918  /// @sa SetDependency()
919  void AddDependencyGroup(CArgDependencyGroup* dep_group);
920 
921  /// Flag to invert constraint logically
923  eConstraintInvert, ///< Logical NOT
924  eConstraint ///< Constraint is not inverted (taken as is)
925  };
926 
927  /// Set additional user defined constraint on argument value.
928  ///
929  /// Constraint is defined by CArgAllow and its derived classes.
930  /// The constraint object must be allocated by "new", and it must NOT be
931  /// freed by "delete" after it has been passed to CArgDescriptions!
932  ///
933  /// @param name
934  /// Name of the parameter(flag) to check
935  /// @param constraint
936  /// The constraint object.
937  /// NOTE: A CRef will always be taken on the object, and its lifetime
938  /// will be controlled by the CObject's smart-pointer mechanism.
939  /// @param negate
940  /// Flag indicates if this is inverted(NOT) constaint
941  ///
942  /// @sa
943  /// See "CArgAllow_***" classes for some pre-defined constraints
944  void SetConstraint(const string& name,
945  const CArgAllow* constraint,
946  EConstraintNegate negate = eConstraint);
947 
948  /// This version of SetConstraint doesn't take the ownership of object
949  /// 'constraint'. Rather, it creates and uses a clone of the object.
950  void SetConstraint(const string& name,
951  const CArgAllow& constraint,
952  EConstraintNegate negate = eConstraint);
953 
954  /// Dependencies between arguments.
955  enum EDependency {
956  eRequires, ///< One argument requires another
957  eExcludes ///< One argument excludes another
958  };
959 
960  /// Define a dependency. If arg1 was specified and requires arg2,
961  /// arg2 is treated as a mandatory one even if was defined as optional.
962  /// If arg1 excludes arg2, arg2 must not be set even if it's mandatory.
963  /// This allows to create a set of arguments exactly one of which
964  /// must be set.
965  void SetDependency(const string& arg1,
966  EDependency dep,
967  const string& arg2);
968 
969  /// Set current arguments group name. When printing descriptions for
970  /// optional arguments (on -help command), they will be arranged by
971  /// group name. Empty group name resets the group. Arguments without
972  /// group are listed first immediately after mandatory arguments.
973  void SetCurrentGroup(const string& group);
974 
975  /// Set individual error handler for the argument.
976  /// The handler overrides the default one (if any) provided through
977  /// the constructor. The same handler may be shared by several arguments.
978  /// The handler object must be allocated by "new", and it must NOT be
979  /// freed by "delete" after it has been passed to CArgDescriptions!
980  ///
981  /// @param name
982  /// Name of the parameter (flag) to set handler for
983  /// @param err_handler
984  /// Error handler
985  void SetErrorHandler(const string& name,
987 
988  /// Check if there is already an argument description with specified name.
989  bool Exist(const string& name) const;
990 
991  /// Delete description of argument with name "name".
992  /// Extra arguments get deleted by the name passed as "".
993  ///
994  /// Throw the CArgException (eSynopsis error code) exception if the
995  /// specified name cannot be found.
996  void Delete(const string& name);
997 
998  /// Set extra info to be used by PrintUsage().
999  /// If "usage_name" is empty, it will be initialized using
1000  /// CNcbiApplicationAPI::GetProgramDisplayName
1001  /// @sa SetDetailedDescription
1002  void SetUsageContext(const string& usage_name, ///< Program name
1003  const string& usage_description, ///< Usage descr.
1004  bool usage_sort_args = false,///< Sort args.
1005  SIZE_TYPE usage_width = 78); ///< Format width
1006 
1007  /// Set detailed usage description
1008  ///
1009  /// In short help message, program will print short
1010  /// description defined in SetUsageContext method.
1011  /// In detailed help message, program will use detailed
1012  /// description defined here.
1013  ///
1014  /// @param usage_description
1015  /// Detailed usage description
1016  /// @sa SetUsageContext
1017  void SetDetailedDescription(const string& usage_description);
1018 
1019  /// Print usage and exit.
1020  ///
1021  /// Force to print USAGE unconditionally (and then exit) if no
1022  /// command-line args are present.
1023  /// @deprecated Use SetMiscFlags(fUsageIfNoArgs) instead.
1024  NCBI_DEPRECATED void PrintUsageIfNoArgs(bool do_print = true);
1025 
1026  /// Miscellaneous flags.
1027  enum EMiscFlags {
1028  fNoUsage = 1 << 0, ///< Do not print USAGE on argument error.
1029  fUsageIfNoArgs = 1 << 1, ///< Force printing USAGE (and then exit)
1030  ///< if no command line args are present.
1031  fUsageSortArgs = 1 << 2, ///< Sort args when printing USAGE.
1032  fDupErrToCerr = 1 << 3, ///< Print arg error to both log and cerr.
1033 
1034  fMisc_Default = 0
1035  };
1036  typedef int TMiscFlags; ///< Bitwise OR of "EMiscFlags"
1037 
1038  /// Set the selected flags.
1040  {
1041  m_MiscFlags |= flags;
1042  }
1043 
1044  /// Clear the selected usage flags.
1046  {
1047  m_MiscFlags &= ~flags;
1048  }
1049 
1050  /// Check if the flag is set.
1051  bool IsSetMiscFlag(EMiscFlags flag) const
1052  {
1053  return (m_MiscFlags & flag) != 0;
1054  }
1055 
1056  /// Which standard flag's descriptions should not be displayed in
1057  /// the usage message.
1058  ///
1059  /// Do not display descriptions of the standard flags such as the
1060  /// -h, -logfile, -conffile, -version
1061  /// flags in the usage message. Note that you still can pass them in
1062  /// the command line.
1064  fHideLogfile = 0x01, ///< Hide log file description
1065  fHideConffile = 0x02, ///< Hide configuration file description
1066  fHideVersion = 0x04, ///< Hide version description
1067  fHideFullVersion = 0x08, ///< Hide full version description
1068  fHideDryRun = 0x10, ///< Hide dryrun description
1069  fHideHelp = 0x20, ///< Hide help description
1070  fHideFullHelp = 0x40, ///< Hide full help description
1071  fHideXmlHelp = 0x80, ///< Hide XML help description
1072  fHideAll = 0xFF ///< Hide all standard argument descriptions
1073  };
1074  typedef int THideStdArgs; ///< Binary OR of "EHideStdArgs"
1075 
1076  /// Print usage message to end of specified string.
1077  ///
1078  /// Printout USAGE and append to the string "str" using provided
1079  /// argument descriptions and usage context.
1080  /// @return
1081  /// Appended "str"
1082  virtual string& PrintUsage(string& str, bool detailed = false) const;
1083 
1084  /// Print argument description in XML format
1085  ///
1086  /// @param out
1087  /// Print into this output stream
1088  virtual void PrintUsageXml(CNcbiOstream& out) const;
1089 
1090  /// Verify if argument "name" is spelled correctly.
1091  ///
1092  /// Argument name can contain only alphanumeric characters, dashes ('-')
1093  /// and underscore ('_'), or be empty. If the leading dash is present,
1094  /// it must be followed by a non-dash char ('-' or '--foo' are not valid
1095  /// names).
1096  static bool VerifyName(const string& name, bool extended = false);
1097 
1098  /// See if special flag "-h" is activated
1099  bool IsAutoHelpEnabled(void) const
1100  {
1101  return m_AutoHelp;
1102  }
1103 
1104  /// Include hidden arguments into USAGE
1105  CArgDescriptions* ShowAllArguments(bool show_all);
1106 
1107  /// Add standard arguments
1108  virtual void AddStdArguments(THideStdArgs mask);
1109  /// Add logfile and conffile arguments
1110  void AddDefaultFileArguments(const string& default_config);
1111 
1112 private:
1113  typedef set< AutoPtr<CArgDesc> > TArgs; ///< Argument descr. type
1114  typedef TArgs::iterator TArgsI; ///< Arguments iterator
1115  typedef TArgs::const_iterator TArgsCI; ///< Const arguments iterator
1116  typedef /*deque*/vector<string> TPosArgs; ///< Positional arg. vector
1117  typedef list<string> TKeyFlagArgs; ///< List of flag arguments
1118  typedef vector<string> TArgGroups; ///< Argument groups
1119 
1120  // Dependencies
1122  {
1123  SArgDependency(const string arg, EDependency dep)
1124  : m_Arg(arg), m_Dep(dep) {}
1125  string m_Arg;
1127  };
1128  // Map arguments to their dependencies
1131 
1132 private:
1133  EArgSetType m_ArgsType; ///< Type of arguments
1134  TArgs m_Args; ///< Assoc.map of arguments' name/descr
1135  TPosArgs m_PosArgs; ///< Pos. args, ordered by position in cmd.-line
1136  TPosArgs m_OpeningArgs; ///< Opening args, ordered by position in cmd.-line
1137  TKeyFlagArgs m_KeyFlagArgs; ///< Key/flag args, in order of insertion
1138  string m_NoSeparator; ///< Arguments allowed to use no separator
1139  unsigned m_nExtra; ///> # of mandatory extra args
1140  unsigned m_nExtraOpt; ///< # of optional extra args
1141  TArgGroups m_ArgGroups; ///< Argument groups
1142  size_t m_CurrentGroup; ///< Currently selected group (0 = no group)
1143  EArgPositionalMode m_PositionalMode; ///< Processing of positional args
1144  TDependencies m_Dependencies; ///< Arguments' dependencies
1145  TMiscFlags m_MiscFlags; ///< Flags for USAGE, error handling etc.
1147 
1148  // Extra USAGE info
1149 protected:
1150  string m_UsageName; ///< Program name
1151  string m_UsageDescription; ///< Program description
1152  string m_DetailedDescription; ///< Program long description
1153  SIZE_TYPE m_UsageWidth; ///< Maximum length of a usage line
1154  bool m_AutoHelp; ///< Special flag "-h" activated
1155  bool m_HasHidden; ///< Has hidden arguments
1157 
1158 private:
1159 
1160  CRef<CArgErrorHandler> m_ErrorHandler; ///< Global error handler or NULL
1161 
1162  // Internal methods
1163 
1164  void x_PrintAliasesAsXml(CNcbiOstream& out, const string& name,
1165  bool negated=false) const;
1166 
1167  /// Helper method to find named parameter.
1168  /// 'negative' (if provided) will indicate if the name referred to a
1169  /// negative alias.
1170  TArgsI x_Find(const string& name,
1171  bool* negative = NULL);
1172 
1173  /// Helper method to find named parameter -- const version.
1174  /// 'negative' (if provided) will indicate if the name referred to a
1175  /// negative alias.
1176  TArgsCI x_Find(const string& name,
1177  bool* negative = NULL) const;
1178 
1179  /// Get group index. Returns group index in the m_ArgGroups, 0 for empty
1180  /// group name or the next group number for undefined group.
1181  size_t x_GetGroupIndex(const string& group) const;
1182 
1183  /// Helper method for adding description.
1184  void x_AddDesc(CArgDesc& arg);
1185 
1186  /// Helper method for doing pre-processing consistency checks.
1187  void x_PreCheck(void) const;
1188 
1189  void x_PrintComment(list<string>& arr,
1190  const CArgDesc& arg,
1191  SIZE_TYPE width) const;
1192 
1193  /// Process arguments.
1194  ///
1195  /// Helper method to process arguments and build a CArgs object that is
1196  /// passed as the args parameter.
1197  /// @return
1198  /// TRUE if specified "arg2" was used.
1199  bool x_CreateArg(const string& arg1, ///< Argument to process
1200  bool have_arg2, ///< Is there an arg. that follows?
1201  const string& arg2, ///< Following argument
1202  unsigned* n_plain, ///< Indicates number of args
1203  CArgs& args ///< Contains processed args
1204  ) const;
1205 
1206  /// @return
1207  /// TRUE if specified "arg2" was used.
1208  bool x_CreateArg(const string& arg1,
1209  const string& name,
1210  bool have_arg2,
1211  const string& arg2,
1212  unsigned int n_plain,
1213  CArgs& args,
1214  bool update = false,
1215  CArgValue** new_value = 0) const;
1216 
1217  /// @sa x_PostCheck()
1219  eCreateArgs, ///< called by CreateArgs()
1220  eConvertKeys ///< called by ConvertKeys()
1221  };
1222  /// Helper method for doing post-processing consistency checks.
1223  void x_PostCheck(CArgs& args,
1224  unsigned int n_plain,
1225  EPostCheckCaller caller)
1226  const;
1227 
1228  /// Returns TRUE if parameter supports multiple arguments
1229  bool x_IsMultiArg(const string& name) const;
1230 
1231 protected:
1232 
1233  /// Helper method for checking if auto help requested and throw
1234  /// CArgHelpException if help requested.
1235  void x_CheckAutoHelp(const string& arg) const;
1236 
1237 // PrintUsage helpers
1239  {
1240  public:
1241  CPrintUsage(const CArgDescriptions& desc);
1242  ~CPrintUsage();
1243  void AddSynopsis(list<string>& arr, const string& intro, const string& prefix) const;
1244  void AddDescription(list<string>& arr, bool detailed) const;
1245  void AddCommandDescription(list<string>& arr, const string& cmd,
1246  const map<string,string>* aliases, size_t max_cmd_len, bool detailed) const;
1247  void AddDetails(list<string>& arr) const;
1248  private:
1250  list<const CArgDesc*> m_args;
1251  };
1253  {
1254  public:
1256  ~CPrintUsageXml();
1257  void PrintArguments(const CArgDescriptions& desc) const;
1258  private:
1261  };
1262 
1263 public:
1264  /// Create parsed arguments in CArgs object.
1265  ///
1266  /// Parse command-line arguments, and create "CArgs" args object
1267  /// from the passed command-line arguments "argc" and "argv".
1268  ///
1269  /// Throw
1270  /// - CArgException on error
1271  /// - CArgHelpException if USAGE printout was requested ("-h" flag)
1272  ///
1273  /// @note Deallocate the resulting "CArgs" object using 'delete'.
1274  ///
1275  /// @attention
1276  /// This function is not suitable for parsing URL-encoded _CGI_ arg
1277  /// outside of the CCgiApplication framework.
1278  template<class TSize, class TArray>
1279  CArgs* CreateArgs(TSize argc, TArray argv) const
1280  {
1281  // Check the consistency of argument descriptions
1282  x_PreCheck();
1283 
1284  // Create new "CArgs" to fill up, and parse cmd.-line args into it
1285  unique_ptr<CArgs> args(new CArgs());
1286 
1287  // Special case for CGI -- a lone positional argument
1288  if (GetArgsType() == eCgiArgs && argc == 2) {
1289  x_CheckAutoHelp(argv[1]);
1290  return args.release();
1291  }
1292 
1293  // Regular case for both CGI and non-CGI
1294  unsigned int n_plain = kMax_UInt;
1295  for (TSize i = 1; i < argc; i++) {
1296  bool have_arg2 = (i + 1 < argc);
1297  if ( x_CreateArg(argv[i], have_arg2,
1298  have_arg2 ? (string) argv[i+1] : kEmptyStr,
1299  &n_plain, *args) ) {
1300  i++;
1301  }
1302  }
1303 
1304  // Check if there were any arguments at all
1305  if (n_plain == kMax_UInt) {
1306  n_plain = 0;
1307  }
1308 
1309  // Extra checks for the consistency of resultant argument values
1310  x_PostCheck(*args, n_plain, eCreateArgs);
1311  return args.release();
1312  }
1313 
1314  /// Parse command-line arguments 'argv' out of CNcbiArguments
1315  virtual CArgs* CreateArgs(const CNcbiArguments& argv) const;
1316 
1317  /// Convert argument map (key-value pairs) into arguments in accordance
1318  /// with the argument descriptions
1319  template<class T>
1320  void ConvertKeys(CArgs* args, const T& arg_map, bool update) const
1321  {
1322  // Check the consistency of argument descriptions
1323  x_PreCheck();
1324 
1325  // Retrieve the arguments and their values
1326  ITERATE(TKeyFlagArgs, it, m_KeyFlagArgs) {
1327  const string& param_name = *it;
1328 
1329  // find first element in the input multimap
1330  typename T::const_iterator vit = arg_map.find(param_name);
1331  typename T::const_iterator vend = arg_map.end();
1332 
1333  if (vit != vend) { // at least one value found
1334  CArgValue* new_arg_value;
1335  x_CreateArg(param_name, param_name,
1336  true, /* value is present */
1337  vit->second,
1338  1,
1339  *args,
1340  update,
1341  &new_arg_value);
1342 
1343  if (new_arg_value && x_IsMultiArg(param_name)) {
1344  CArgValue::TStringArray& varr =
1345  new_arg_value->SetStringList();
1346 
1347  // try to add all additional arguments to arg value
1348  for (++vit; vit != vend; ++vit) {
1349  if (vit->first != param_name)
1350  break;
1351  varr.push_back(vit->second);
1352  }
1353  }
1354  }
1355  } // ITERATE
1356 
1357  // Extra checks for the consistency of resultant argument values
1358  x_PostCheck(*args, 0, eConvertKeys);
1359  }
1360 
1361  virtual list<CArgDescriptions*> GetAllDescriptions(void) {
1362  return list<CArgDescriptions*>({this});
1363  }
1364 };
1365 
1366 /////////////////////////////////////////////////////////////////////////////
1367 ///
1368 /// CCommandArgDescriptions --
1369 ///
1370 /// Container for several CArgDescriptions objects.
1371 ///
1372 /// Sometimes, it is convenient to use a command line tool as follows:
1373 /// tool <command> [options] [args]
1374 /// Here, <command> is an alphanumeric string,
1375 /// and options and arguments are different for each command.
1376 /// With this mechanism, it is possible to describe arguments for
1377 /// each command separately. At run time, argument parser will choose
1378 /// proper CArgDescriptions object based on the value of the first argument.
1379 
1381 {
1382 public:
1383 
1385  eCommandMandatory = 0, ///< Nonempty command is required
1386  eCommandOptional = 1, ///< Command is not necessary
1387  eNoSortCommands = (1<<1), ///< On PrintUsage, keep commands unsorted
1388  eNoSortGroups = (1<<2) ///< On PrintUsage, keep command groups unsorted
1389  };
1390  typedef unsigned int TCommandArgFlags; ///< Bitwise OR of ECommandArgFlags
1391 
1392  /// Constructor.
1393  ///
1394  /// If "auto_help" is passed TRUE, then a special flag "-h" will be added
1395  /// to the list of accepted arguments. Passing "-h" in the command line
1396  /// will printout USAGE and ignore all other passed arguments.
1397  /// Error handler is used to process errors when parsing arguments.
1398  /// If not set the default handler is used.
1399  CCommandArgDescriptions(bool auto_help = true,
1401  TCommandArgFlags cmd_flags = eCommandMandatory);
1402  /// Destructor.
1403  virtual ~CCommandArgDescriptions(void);
1404 
1405  /// Set current command group name. When printing help,
1406  /// commands will be arranged by group name.
1407  void SetCurrentCommandGroup(const string& group);
1408 
1411  eHidden = 1 ///< Hide command in Usage
1412  };
1413 
1414  /// Add command argument descriptions
1415  ///
1416  /// @param cmd
1417  /// Command string
1418  /// @param description
1419  /// Argument description
1420  /// @param alias
1421  /// Alternative name of the command
1422  /// @param flags
1423  /// Optional flags
1424  void AddCommand(const string& cmd, CArgDescriptions* description,
1425  const string& alias = kEmptyStr, ECommandFlags flags = eDefault);
1426 
1427  /// Parse command-line arguments 'argv'
1428  virtual CArgs* CreateArgs(const CNcbiArguments& argv) const;
1429 
1430  virtual void AddStdArguments(THideStdArgs mask);
1431 
1432  /// Print usage message to end of specified string.
1433  ///
1434  /// Printout USAGE and append to the string "str" using provided
1435  /// argument descriptions and usage context.
1436  /// @return
1437  /// Appended "str"
1438  virtual string& PrintUsage(string& str, bool detailed = false) const;
1439 
1440  /// Print argument description in XML format
1441  ///
1442  /// @param out
1443  /// Print into this output stream
1444  virtual void PrintUsageXml(CNcbiOstream& out) const;
1445 
1446  virtual list<CArgDescriptions*> GetAllDescriptions(void);
1447 
1448 private:
1449  // not allowed
1450  void SetArgsType(EArgSetType /*args_type*/) { }
1451 
1452  bool x_IsCommandMandatory(void) const;
1453  size_t x_GetCommandGroupIndex(const string& group) const;
1454  string x_IdentifyCommand(const string& command) const;
1455 
1458  TDescriptions m_Description; ///< command to ArgDescriptions
1459  map<string, size_t > m_Groups; ///< command to group #
1460  map<string,string> m_Aliases; ///< command to alias; one alias only
1461  list<string> m_Commands; ///< command names, and order
1462  list<string> m_CmdGroups; ///< group names, and order
1463  size_t m_CurrentCmdGroup; ///< current group #
1464  mutable string m_Command; ///< current command
1465 };
1466 
1467 
1468 
1469 /////////////////////////////////////////////////////////////////////////////
1470 ///
1471 /// CArgAllow --
1472 ///
1473 /// Abstract base class for defining argument constraints.
1474 ///
1475 /// Other user defined constraints are defined by deriving from this abstract
1476 /// base class:
1477 ///
1478 /// - CArgAllow_Symbols -- symbol from a set of allowed symbols
1479 /// - CArgAllow_String -- string to contain only allowed symbols
1480 /// - CArgAllow_Strings -- string from a set of allowed strings
1481 /// - CArgAllow_Int8s -- Int8 value to fall within a given interval
1482 /// - CArgAllow_Integers -- integer value to fall within a given interval
1483 /// - CArgAllow_Doubles -- floating-point value to fall in a given interval
1484 ///
1485 /// @sa CArgAllow_Regexp
1486 
1488 {
1489 public:
1490  /// Verify if specified value is allowed.
1491  virtual bool Verify(const string &value) const = 0;
1492 
1493  /// Get usage information.
1494  virtual
1495  string GetUsage(void) const = 0;
1496 
1497  /// Print constraints in XML format
1498  virtual void PrintUsageXml(CNcbiOstream& out) const;
1499 
1500  virtual ~CArgAllow(void);
1501 
1502  /// Create object's clone, moving it from stack memory into heap.
1503  /// The method is required only when using objects created on stack.
1504  ///
1505  /// NOTE: Default implementation returns NULL.
1506  /// Inherited classes must override this method.
1507  ///
1508  /// @sa CArgDescriptions::SetConstraint
1509  virtual CArgAllow* Clone(void) const;
1510 
1511 protected:
1512  // In the absence of the following constructor, new compilers (as required
1513  // by the new C++ standard) may fill the object memory with zeros,
1514  // erasing flags set by CObject::operator new (see CXX-1808)
1515  CArgAllow(void) {}
1516 };
1517 
1518 
1519 
1520 /////////////////////////////////////////////////////////////////////////////
1521 ///
1522 /// CArgAllow_Symbols --
1523 ///
1524 /// Define constraint to describe exactly one symbol.
1525 ///
1526 /// Argument to be exactly one symbol from the specified set of symbols.
1527 ///
1528 /// Examples:
1529 /// - To allow only symbols 'a', 'b' and 'Z' for argument "MyArg":
1530 /// SetConstraint("MyArg", new CArgAllow_Symbols("abZ"))
1531 /// - To allow only printable symbols (according to "isprint()" from <ctype.h>):
1532 /// SetConstraint("MyArg", new CArgAllow_Symbols(CArgAllow_Symbols::ePrint))
1533 
1535 {
1536 public:
1537  /// Symbol class for defining sets of characters.
1538  ///
1539  /// Symbol character classes patterned after those defined in <ctype.h>.
1541  // Standard character class from <ctype.h>: isalpha(), isdigit(), etc.
1542  eAlnum, ///< Alphanumeric characters
1543  eAlpha, ///< Alphabet characters
1544  eCntrl, ///< Control characters
1545  eDigit, ///< Digit characters
1546  eGraph, ///< Graphical characters
1547  eLower, ///< Lowercase characters
1548  ePrint, ///< Printable characters
1549  ePunct, ///< Punctuation characters
1550  eSpace, ///< Space characters
1551  eUpper, ///< Uppercase characters
1552  eXdigit, ///< Hexadecimal characters
1553  eUser ///< User defined characters using constructor with string&
1554  };
1555 
1556  /// Constructor.
1557  CArgAllow_Symbols(ESymbolClass symbol_class);
1558 
1559  /// Constructor for user defined eUser class.
1560  CArgAllow_Symbols(const string& symbol_set);
1561 
1562  /// Add allowed symbols
1563  CArgAllow_Symbols& Allow(ESymbolClass symbol_class);
1564  CArgAllow_Symbols& Allow(const string& symbol_set);
1565 
1566 protected:
1567  /// Verify if specified value is allowed.
1568  virtual bool Verify(const string& value) const;
1569 
1570  /// Get usage information.
1571  virtual string GetUsage(void) const;
1572 
1573  /// Print constraints in XML format
1574  virtual void PrintUsageXml(CNcbiOstream& out) const;
1575 
1577  }
1578  virtual CArgAllow* Clone(void) const;
1579 
1580  typedef pair<ESymbolClass, string> TSymClass;
1582 };
1583 
1584 
1585 /////////////////////////////////////////////////////////////////////////////
1586 ///
1587 /// CArgAllow_String --
1588 ///
1589 /// Define constraint to describe string argument.
1590 ///
1591 /// Argument to be a string containing only allowed symbols.
1592 ///
1593 /// Examples:
1594 /// - To allow string containing only symbols 'a', 'b' and 'Z' for arg MyArg:
1595 /// SetConstraint("MyArg", new CArgAllow_String("abZ"))
1596 /// - To allow only numeric symbols (according to "isdigit()" from <ctype.h>):
1597 /// SetConstraint("MyArg", new CArgAllow_String(CArgAllow_String::eDigit))
1598 
1600 {
1601 public:
1602  /// Constructor.
1603  CArgAllow_String(ESymbolClass symbol_class);
1604 
1605  /// Constructor for user defined eUser class.
1606  CArgAllow_String(const string& symbol_set);
1607 
1608 protected:
1609  /// Verify if specified value is allowed.
1610  virtual bool Verify(const string& value) const;
1611 
1612  /// Get usage information.
1613  virtual string GetUsage(void) const;
1614 
1615  /// Print constraints in XML format
1616  virtual void PrintUsageXml(CNcbiOstream& out) const;
1617 
1619  }
1620  virtual CArgAllow* Clone(void) const;
1621 };
1622 
1623 
1624 
1625 /////////////////////////////////////////////////////////////////////////////
1626 ///
1627 /// CArgAllow_Strings --
1628 ///
1629 /// Define constraint to describe set of string values.
1630 ///
1631 /// Argument to have only particular string values. Use the Allow() method to
1632 /// add the allowed string values, which can be daisy-chained.
1633 ///
1634 /// Examples:
1635 /// - SetConstraint("a", (new CArgAllow_Strings)->
1636 /// Allow("foo")->Allow("bar")->Allow("etc"))
1637 /// - You can use "operator,()" to shorten the notation:
1638 /// SetConstraint("b", &(*new CArgAllow_Strings, "foo", "bar", "etc"))
1639 
1641 {
1642 public:
1643  /// Constructor
1644  /// @param use_case
1645  /// If to ignore the case of the characters
1647 
1648  /// Constructor
1649  /// @param values
1650  /// Strings to add to the set of allowed string values
1651  /// @param use_case
1652  /// If to ignore the case of the characters
1653  CArgAllow_Strings(initializer_list<string> values, NStr::ECase use_case = NStr::eCase);
1654 
1655  /// Add allowed string values
1656  /// @param value
1657  /// String to add to the set of allowed string values
1658  CArgAllow_Strings* Allow(const string& value);
1659 
1660  /// Add allowed string values
1661  /// @param value
1662  /// String to add to the set of allowed string values
1663  CArgAllow_Strings& AllowValue(const string& value);
1664 
1665  /// Short notation operator for adding allowed string values
1666  /// @param value
1667  /// String to add to the set of allowed string values
1668  /// @sa
1669  /// Allow()
1671  return AllowValue(value);
1672  }
1673 
1674 protected:
1675  /// Verify if specified value is allowed.
1676  virtual bool Verify(const string& value) const;
1677 
1678  /// Get usage information.
1679  virtual string GetUsage(void) const;
1680 
1681  /// Print constraints in XML format
1682  virtual void PrintUsageXml(CNcbiOstream& out) const;
1683 
1684  virtual CArgAllow* Clone(void) const;
1685 
1686  /// Type of the container that contains the allowed string values
1687  /// @sa m_Strings
1689 
1690  TStrings m_Strings; ///< Set of allowed string values
1691 };
1692 
1693 
1694 /////////////////////////////////////////////////////////////////////////////
1695 ///
1696 /// CArgAllow_Int8s --
1697 ///
1698 /// Define constraint to describe range of 8-byte integer values and TIntIds.
1699 ///
1700 /// Argument to have only integer values falling within given interval.
1701 ///
1702 /// Example:
1703 /// - SetConstraint("a2", new CArgAllow_Int8s(-1001, 123456789012))
1704 
1706 {
1707 public:
1708  /// Constructor specifying an allowed integer value.
1709  CArgAllow_Int8s(Int8 x_value);
1710 
1711  /// Constructor specifying range of allowed integer values.
1712  CArgAllow_Int8s(Int8 x_min, Int8 x_max);
1713 
1714  /// Add allow values
1715  CArgAllow_Int8s& AllowRange(Int8 from, Int8 to);
1716  CArgAllow_Int8s& Allow(Int8 value);
1717 
1718 protected:
1719  /// Verify if specified value is allowed.
1720  virtual bool Verify(const string& value) const;
1721 
1722  /// Get usage information.
1723  virtual string GetUsage(void) const;
1724 
1725  /// Print constraints in XML format
1726  virtual void PrintUsageXml(CNcbiOstream& out) const;
1727 
1729  }
1730  virtual CArgAllow* Clone(void) const;
1731 
1732 
1733  typedef pair<Int8, Int8> TInterval;
1735 };
1736 
1737 
1738 
1739 /////////////////////////////////////////////////////////////////////////////
1740 ///
1741 /// CArgAllow_Integers --
1742 ///
1743 /// Define constraint to describe range of integer id values.
1744 ///
1745 /// Argument to have only integer values falling within given interval.
1746 ///
1747 /// Example:
1748 /// - SetConstraint("i", new CArgAllow_Integers(kMin_Int, 34))
1749 
1751 {
1752 public:
1753  /// Constructor specifying an allowed integer value.
1754  CArgAllow_Integers(int x_value);
1755  /// Constructor specifying range of allowed integer values.
1756  CArgAllow_Integers(int x_min, int x_max);
1757 
1758 protected:
1759  /// Get usage information.
1760  virtual string GetUsage(void) const;
1761 
1763  }
1764  virtual CArgAllow* Clone(void) const;
1765 };
1766 
1767 
1768 
1769 /////////////////////////////////////////////////////////////////////////////
1770 ///
1771 /// CArgAllow_Doubles --
1772 ///
1773 /// Define constraint to describe range of double values.
1774 ///
1775 /// Argument to have only double values falling within given interval.
1776 ///
1777 /// Example:
1778 /// - SetConstraint("d", new CArgAllow_Doubles(0.01, 0.99))
1779 
1781 {
1782 public:
1783  /// Constructor specifying an allowed double value.
1784  CArgAllow_Doubles(double x_value);
1785 
1786  /// Constructor specifying range of allowed double values.
1787  CArgAllow_Doubles(double x_min, double x_max);
1788 
1789  /// Add allowed values
1790  CArgAllow_Doubles& AllowRange(double from, double to);
1791  CArgAllow_Doubles& Allow(double value);
1792 
1793 protected:
1794  /// Verify if specified value is allowed.
1795  virtual bool Verify(const string& value) const;
1796 
1797  /// Get usage information.
1798  virtual string GetUsage(void) const;
1799 
1800  /// Print constraints in XML format
1801  virtual void PrintUsageXml(CNcbiOstream& out) const;
1802 
1804  }
1805  virtual CArgAllow* Clone(void) const;
1806 
1807  typedef pair<double,double> TInterval;
1809 };
1810 
1811 
1812 
1813 /////////////////////////////////////////////////////////////////////////////
1814 ///
1815 /// CArgDesc --
1816 ///
1817 /// Base class for the description of various types of argument.
1818 ///
1819 /// This was a pre-declaration; in MSVC, a predeclaration here causes a heap
1820 /// corruption on termination because this class's virtual destructor isn't
1821 /// defined at the moment the compiler instantiates the destructor of
1822 /// AutoPtr<CArgDesc>.
1823 
1825 {
1826 public:
1827  /// Constructor.
1828  CArgDesc(const string& name, ///< Argument name
1829  const string& comment, ///< Argument description
1831  );
1832 
1833  /// Destructor.
1834  virtual ~CArgDesc(void);
1835 
1836  /// Get argument name.
1837  const string& GetName (void) const { return m_Name; }
1838 
1839  /// Get argument description.
1840  const string& GetComment(void) const { return m_Comment; }
1841 
1842  /// Get argument group
1843  virtual size_t GetGroup(void) const { return 0; }
1844  /// Set argument group
1845  virtual void SetGroup(size_t /* group */) {}
1846 
1847  /// Get usage synopsis.
1848  virtual string GetUsageSynopsis(bool name_only = false) const = 0;
1849 
1850  /// Get usage comment attribute.
1851  virtual string GetUsageCommentAttr(void) const = 0;
1852 
1853  /// Process argument with specified value.
1854  virtual CArgValue* ProcessArgument(const string& value) const = 0;
1855 
1856  /// Process argument default.
1857  virtual CArgValue* ProcessDefault(void) const = 0;
1858 
1859  /// Verify argument default value.
1860  virtual void VerifyDefault (void) const;
1861 
1862  /// Set argument constraint.
1863  /// @param constraint
1864  /// The constraint object.
1865  /// ATTN: A CRef must always be taken on the object by the
1866  /// derived class's implementation of this method!
1867  virtual
1868  void SetConstraint(const CArgAllow* constraint,
1871 
1872  /// Returns TRUE if associated constraint is inverted (NOT)
1873  /// @sa SetConstraint
1874  virtual bool IsConstraintInverted() const { return false; }
1875 
1876  /// Get argument constraint.
1877  virtual const CArgAllow* GetConstraint(void) const;
1878 
1879  /// Get usage constraint.
1880  string GetUsageConstraint(void) const;
1881 
1882  /// Get error handler for the argument
1883  virtual const CArgErrorHandler* GetErrorHandler(void) const { return 0; }
1884  /// Set error handler for the argument
1885  virtual void SetErrorHandler(CArgErrorHandler*) { return; }
1886 
1887  /// Get argument flags
1889 
1890  /// Print description in XML format
1891  string PrintXml(CNcbiOstream& out) const;
1892 
1893 private:
1894  string m_Name; ///< Argument name
1895  string m_Comment; ///< Argument description
1897 };
1898 
1899 /////////////////////////////////////////////////////////////////////////////
1900 
1902 {
1903 public:
1904  /// Create new dependency group.
1905  /// @param name
1906  /// Name of the group
1907  /// @param description
1908  /// User-provided description of the dependency group (for Usage).
1909  /// A generated description will be added to it.
1910  static CRef<CArgDependencyGroup> Create(
1911  const string& name, const string& description = kEmptyStr);
1912 
1913  virtual ~CArgDependencyGroup(void);
1914 
1915  /// @param min_members
1916  /// Mark this group as "set" (in the context of
1917  /// CArgDescriptions::EDependency) if at least "min_members" of its
1918  /// members (args or groups listed in this group) are set.
1919  /// @note This condition can be weakened by "eInstantSet" mechanism.
1920  /// @sa EInstantSet
1921  /// @return "*this"
1922  CArgDependencyGroup& SetMinMembers(size_t min_members);
1923 
1924  /// @param max_members
1925  /// No more than "max_members" of members (args or immediate groups
1926  /// listed in this group) are allowed to be in the "set" state.
1927  /// If this condition is not met, then this group will be marked
1928  /// as "not set".
1929  /// @return "*this"
1930  CArgDependencyGroup& SetMaxMembers(size_t max_members);
1931 
1932  /// Control whether the "setting" of this particular member marks the
1933  /// whole group as "set" regardless of the value passed to SetMinMembers()
1934  /// @sa SetMinMembers(), Add()
1937  eInstantSet
1938  };
1939 
1940  /// Make a regular argument a member of this dependency group.
1941  /// An argument with this name will need to be added separately using
1942  /// CArgDescriptions::AddXXX().
1943  /// @param arg_name
1944  /// Name of the argument, as specified in CArgDescriptions::AddXXX()
1945  /// @param instant_set
1946  /// "eInstantSet" means that if the added argument ("arg_name") is
1947  /// set, then the SetMinMembers() condition doesn't apply anymore.
1948  /// @return "*this"
1949  CArgDependencyGroup& Add(const string& arg_name,
1950  EInstantSet instant_set = eNoInstantSet);
1951 
1952  /// Make another dependency group a member of this dependency group.
1953  /// @attention
1954  /// The "dep_group" will be added by reference, and its lifetime will
1955  /// be managed according to the usual CObject/CRef rules.
1956  /// @param instant_set
1957  /// "eInstantSet" means that if the added group ("dep_group") is
1958  /// set, then the SetMinMembers() condition doesn't apply anymore.
1959  /// @return "*this"
1960  CArgDependencyGroup& Add(CArgDependencyGroup* dep_group,
1961  EInstantSet instant_set = eNoInstantSet);
1962 
1963 private:
1964  bool x_Evaluate( const CArgs& args, string* arg_set, string* arg_unset) const;
1965 
1966  string m_Name;
1968  size_t m_MinMembers, m_MaxMembers;
1971 
1972  // prohibit unwanted ctors and assignments
1973  CArgDependencyGroup(void);
1976 
1977 public:
1978  void PrintUsage(list<string>& arr, size_t offset) const;
1979  void PrintUsageXml(CNcbiOstream& out) const;
1980  void Evaluate( const CArgs& args) const;
1981 };
1982 
1984 
1985 
1986 /* @} */
1987 
1988 #endif /* CORELIB___NCBIARGS__HPP */
ncbi::TMaskedQueryRegions mask
CArgAllow_Doubles –.
Definition: ncbiargs.hpp:1781
CArgAllow_Int8s –.
Definition: ncbiargs.hpp:1706
CArgAllow_Integers –.
Definition: ncbiargs.hpp:1751
CArgAllow_String –.
Definition: ncbiargs.hpp:1600
CArgAllow_Strings –.
Definition: ncbiargs.hpp:1641
CArgAllow_Symbols –.
Definition: ncbiargs.hpp:1535
CArgAllow –.
Definition: ncbiargs.hpp:1488
CArgDesc –.
Definition: ncbiargs.hpp:1825
CArgDescriptions –.
Definition: ncbiargs.hpp:541
CArgErrorHandler –.
Definition: ncbiargs.hpp:506
CArgException –.
Definition: ncbiargs.hpp:120
CArgHelpException –.
Definition: ncbiargs.hpp:158
CArgValue –.
Definition: ncbiargs.hpp:184
CArgs –.
Definition: ncbiargs.hpp:379
Template used to replace bool type arguments with some strict equivalent.
Definition: ncbimisc.hpp:310
CCommandArgDescriptions –.
Definition: ncbiargs.hpp:1381
CCoreException –.
Definition: ncbiexpt.hpp:1476
CDir –.
Definition: ncbifile.hpp:1695
CNcbiArguments –.
Definition: ncbienv.hpp:236
CObject –.
Definition: ncbiobj.hpp:180
CTime –.
Definition: ncbitime.hpp:296
Definition: set.hpp:45
parent_type::iterator iterator
Definition: set.hpp:80
parent_type::const_iterator const_iterator
Definition: set.hpp:79
void Print(const CCompactSAMApplication::AlignInfo &ai)
static uch flags
#define T(s)
Definition: common.h:230
std::ofstream out("events_result.xml")
main entry point for tests
static CS_COMMAND * cmd
Definition: ct_dynamic.c:26
static int err_handler(DBPROCESS *dbproc, int severity, int dberr, int oserr, char *dberrstr, char *oserrstr)
static const char * str(char *buf, int n)
Definition: stats.c:84
int offset
Definition: replacements.h:160
#define NCBI_DEPRECATED_CTOR(decl)
Macro used to mark a constructor as deprecated.
Definition: ncbimisc.hpp:1209
#define ITERATE(Type, Var, Cont)
ITERATE macro to sequence through container elements.
Definition: ncbimisc.hpp:815
Int8 TIntId
Definition: ncbimisc.hpp:999
virtual list< CArgDescriptions * > GetAllDescriptions(void)
Definition: ncbiargs.hpp:1361
EFlags
Additional flags, the first group is file related flags.
Definition: ncbiargs.hpp:614
size_t GetOrdinalPosition(void) const
Get ordinal position of the value.
Definition: ncbiargs.hpp:304
unsigned int TCommandArgFlags
Bitwise OR of ECommandArgFlags.
Definition: ncbiargs.hpp:1390
TArgs::const_iterator TArgsCI
Type for const iterator.
Definition: ncbiargs.hpp:482
virtual bool AsBoolean(void) const =0
Get the argument's boolean value.
TArgGroups m_ArgGroups
Argument groups.
Definition: ncbiargs.hpp:1141
virtual CArgValue * ProcessDefault(void) const =0
Process argument default.
CArgs * CreateArgs(TSize argc, TArray argv) const
Create parsed arguments in CArgs object.
Definition: ncbiargs.hpp:1279
CArgDescriptions::TFlags GetFlags(void) const
Get argument flags.
Definition: ncbiargs.hpp:1888
CArgAllow(void)
Definition: ncbiargs.hpp:1515
void x_CheckAutoHelp(const string &arg) const
Helper method for checking if auto help requested and throw CArgHelpException if help requested.
Definition: ncbiargs.cpp:2840
map< string, EInstantSet > m_Arguments
Definition: ncbiargs.hpp:1969
TArgsI x_Find(const string &name, bool *negative=NULL)
Helper method to find named parameter.
Definition: ncbiargs.cpp:2736
set< string, PNocase_Conditional > TStrings
Type of the container that contains the allowed string values.
Definition: ncbiargs.hpp:1688
string m_Name
Argument name.
Definition: ncbiargs.hpp:1894
virtual const string & AsString(void) const =0
Get the argument's string value.
list< const CArgDesc * > m_args
Definition: ncbiargs.hpp:1250
virtual double AsDouble(void) const =0
Get the argument's double value.
string m_Command
Definition: ncbiargs.hpp:486
void x_PrintAliasesAsXml(CNcbiOstream &out, const string &name, bool negated=false) const
Definition: ncbiargs.cpp:3959
string m_Command
current command
Definition: ncbiargs.hpp:1464
map< CConstRef< CArgDependencyGroup >, EInstantSet > m_Groups
Definition: ncbiargs.hpp:1970
TArgs m_Args
Assoc.map of arguments' name/descr.
Definition: ncbiargs.hpp:1134
string m_Name
Argument name.
Definition: ncbiargs.hpp:346
CRef< CArgErrorHandler > m_ErrorHandler
Global error handler or NULL.
Definition: ncbiargs.hpp:1160
size_t x_GetGroupIndex(const string &group) const
Get group index.
Definition: ncbiargs.cpp:2755
const string & GetName(void) const
Get argument name.
Definition: ncbiargs.hpp:1837
virtual string GetUsageSynopsis(bool name_only=false) const =0
Get usage synopsis.
TPosArgs m_OpeningArgs
Opening args, ordered by position in cmd.-line.
Definition: ncbiargs.hpp:1136
CArgDependencyGroup(const CArgDependencyGroup &dep_group)
TArgValueFlags m_Flags
Definition: ncbiargs.hpp:349
set< AutoPtr< CArgDesc > > TArgs
Argument descr. type.
Definition: ncbiargs.hpp:1113
unsigned m_nExtra
Definition: ncbiargs.hpp:1139
set< CRef< CArgValue > > TArgs
Type for arguments.
Definition: ncbiargs.hpp:480
EMiscFlags
Miscellaneous flags.
Definition: ncbiargs.hpp:1027
void SetMiscFlags(TMiscFlags flags)
Set the selected flags.
Definition: ncbiargs.hpp:1039
SIZE_TYPE m_UsageWidth
Maximum length of a usage line.
Definition: ncbiargs.hpp:1153
multimap< string, SArgDependency > TDependencies
Definition: ncbiargs.hpp:1129
virtual const CDir & AsDirectory(void) const =0
Get the argument as a directory.
void SetArgsType(EArgSetType)
Definition: ncbiargs.hpp:1450
bool IsAutoHelpEnabled(void) const
See if special flag "-h" is activated.
Definition: ncbiargs.hpp:1099
TStrings m_Strings
Set of allowed string values.
Definition: ncbiargs.hpp:1690
list< string > m_CmdGroups
group names, and order
Definition: ncbiargs.hpp:1462
virtual const CArgErrorHandler * GetErrorHandler(void) const
Get error handler for the argument.
Definition: ncbiargs.hpp:1883
string m_Comment
Argument description.
Definition: ncbiargs.hpp:1895
TDependencies::const_iterator TDependency_CI
Definition: ncbiargs.hpp:1130
bool operator<(const CRef< CArgValue > &x, const CRef< CArgValue > &y)
Definition: ncbiargs.hpp:356
virtual void SetErrorHandler(CArgErrorHandler *)
Set error handler for the argument.
Definition: ncbiargs.hpp:1885
void SetPositionalMode(EArgPositionalMode positional_mode)
Select mode for processing positional arguments.
Definition: ncbiargs.hpp:582
virtual bool IsConstraintInverted() const
Returns TRUE if associated constraint is inverted (NOT)
Definition: ncbiargs.hpp:1874
unsigned int TFileFlags
Bitwise OR of "EFileFlags".
Definition: ncbiargs.hpp:270
EErrCode
Error types for improperly formatted arguments.
Definition: ncbiargs.hpp:126
vector< string > TArgGroups
Argument groups.
Definition: ncbiargs.hpp:1118
void x_PreCheck(void) const
Helper method for doing pre-processing consistency checks.
Definition: ncbiargs.cpp:2769
EArgSetType GetArgsType() const
Definition: ncbiargs.hpp:569
virtual CNcbiIostream & AsIOFile(TFileFlags flags=0) const =0
Get the argument as a file stream.
virtual string GetUsage(void) const =0
Get usage information.
CArgAllow_Strings & operator,(const string &value)
Short notation operator for adding allowed string values.
Definition: ncbiargs.hpp:1670
EArgPositionalMode GetPositionalMode() const
Definition: ncbiargs.hpp:585
void x_PrintComment(list< string > &arr, const CArgDesc &arg, SIZE_TYPE width) const
Definition: ncbiargs.cpp:3428
CArgs * SetCommand(const string &command)
Set current command.
Definition: ncbiargs.hpp:473
virtual CNcbiIstream & AsInputFile(TFileFlags flags=0) const =0
Get the argument as an input file stream.
TArgs::iterator TArgsI
Type for iterator.
Definition: ncbiargs.hpp:481
bool x_CreateArg(const string &arg1, bool have_arg2, const string &arg2, unsigned *n_plain, CArgs &args) const
Process arguments.
Definition: ncbiargs.cpp:2857
void ResetMiscFlags(TMiscFlags flags)
Clear the selected usage flags.
Definition: ncbiargs.hpp:1045
virtual string GetUsageCommentAttr(void) const =0
Get usage comment attribute.
string m_Default
Definition: ncbiargs.hpp:348
string m_UsageName
Program name.
Definition: ncbiargs.hpp:1150
SArgDependency(const string arg, EDependency dep)
Definition: ncbiargs.hpp:1123
NCBI_EXCEPTION_DEFAULT(CArgException, CCoreException)
EArgSetType m_ArgsType
Type of arguments.
Definition: ncbiargs.hpp:1133
const string & GetName(void) const
Get argument name.
Definition: ncbiargs.hpp:187
void SetOrdinalPosition(size_t pos)
Definition: ncbiargs.hpp:340
set< TSymClass > m_SymClass
Definition: ncbiargs.hpp:1581
CArgDescriptions::TFlags m_Flags
Definition: ncbiargs.hpp:1896
string GetCommand(void) const
Get current command.
Definition: ncbiargs.hpp:465
EArgValueFlags
Whether the argument:
Definition: ncbiargs.hpp:311
size_t m_CurrentCmdGroup
current group #
Definition: ncbiargs.hpp:1463
pair< double, double > TInterval
Definition: ncbiargs.hpp:1807
set< CConstRef< CArgDependencyGroup > > m_DependencyGroups
Definition: ncbiargs.hpp:1146
virtual void SetGroup(size_t)
Set argument group.
Definition: ncbiargs.hpp:1845
map< string, AutoPtr< CArgDescriptions > > TDescriptions
Definition: ncbiargs.hpp:1456
virtual bool Verify(const string &value) const =0
Verify if specified value is allowed.
list< string > m_Commands
command names, and order
Definition: ncbiargs.hpp:1461
size_t m_Ordinal
Definition: ncbiargs.hpp:347
TArgs::iterator TArgsI
Arguments iterator.
Definition: ncbiargs.hpp:1114
EArgSetType
Type of CArgDescriptions For a CGI application positional arguments and flags does not make sense (th...
Definition: ncbiargs.hpp:559
bool m_HasHidden
Has hidden arguments.
Definition: ncbiargs.hpp:1155
TDependencies m_Dependencies
Arguments' dependencies.
Definition: ncbiargs.hpp:1144
map< string, string > m_Aliases
command to alias; one alias only
Definition: ncbiargs.hpp:1460
virtual CNcbiOstream & AsOutputFile(TFileFlags flags=0) const =0
Get the argument as an output file stream.
unsigned int TFlags
Bitwise OR of "EFlags".
Definition: ncbiargs.hpp:676
virtual bool HasValue(void) const =0
Check if argument holds a value.
DECLARE_OPERATOR_BOOL(HasValue())
Synonym for HasValue().
TArgs m_Args
Assoc. map of arguments' name/value.
Definition: ncbiargs.hpp:484
size_t m_nExtra
Cached # of unnamed positional arguments.
Definition: ncbiargs.hpp:485
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.
Definition: ncbiargs.hpp:1320
set< TInterval > m_MinMax
Definition: ncbiargs.hpp:1808
EFlagValue
Define how flag presence affect CArgValue::HasValue().
Definition: ncbiargs.hpp:749
list< string > TKeyFlagArgs
List of flag arguments.
Definition: ncbiargs.hpp:1117
CArgAllow_String(void)
Definition: ncbiargs.hpp:1618
virtual CArgValue * ProcessArgument(const string &value) const =0
Process argument with specified value.
EDependency
Dependencies between arguments.
Definition: ncbiargs.hpp:955
void x_AddDesc(CArgDesc &arg)
Helper method for adding description.
Definition: ncbiargs.cpp:3368
virtual size_t GetGroup(void) const
Get argument group.
Definition: ncbiargs.hpp:1843
EInstantSet
Control whether the "setting" of this particular member marks the whole group as "set" regardless of ...
Definition: ncbiargs.hpp:1935
size_t m_CurrentGroup
Currently selected group (0 = no group)
Definition: ncbiargs.hpp:1142
virtual void CloseFile(void) const =0
Close the file.
string m_DetailedDescription
Program long description.
Definition: ncbiargs.hpp:1152
EType
Available argument types.
Definition: ncbiargs.hpp:588
TMiscFlags m_MiscFlags
Flags for USAGE, error handling etc.
Definition: ncbiargs.hpp:1145
string m_UsageDescription
Program description.
Definition: ncbiargs.hpp:1151
TDescriptions m_Description
command to ArgDescriptions
Definition: ncbiargs.hpp:1458
virtual int AsInteger(void) const =0
Get the argument's integer value.
const string & GetComment(void) const
Get argument description.
Definition: ncbiargs.hpp:1840
EHideStdArgs
Which standard flag's descriptions should not be displayed in the usage message.
Definition: ncbiargs.hpp:1063
string m_NoSeparator
Arguments allowed to use no separator.
Definition: ncbiargs.hpp:1138
virtual TStringArray & SetStringList()
Get reference on value list for further modification.
Definition: ncbiargs.cpp:167
int THideStdArgs
Binary OR of "EHideStdArgs".
Definition: ncbiargs.hpp:1074
unsigned int TArgValueFlags
Bitwise OR of "EArgValueFlags".
Definition: ncbiargs.hpp:315
virtual const CTime & AsDateTime(void) const =0
Get the argument as a DateTime.
bool m_AutoHelp
Special flag "-h" activated.
Definition: ncbiargs.hpp:1154
EArgPositionalMode
Processing of positional arguments.
Definition: ncbiargs.hpp:576
TArgs::const_iterator TArgsCI
Const arguments iterator.
Definition: ncbiargs.hpp:1115
pair< ESymbolClass, string > TSymClass
Definition: ncbiargs.hpp:1580
vector< string > TStringArray
Some values types can contain several value lists.
Definition: ncbiargs.hpp:293
set< TInterval > m_MinMax
Definition: ncbiargs.hpp:1734
vector< string > TPosArgs
Positional arg. vector.
Definition: ncbiargs.hpp:1116
ESymbolClass
Symbol class for defining sets of characters.
Definition: ncbiargs.hpp:1540
const CArgDescriptions & m_desc
Definition: ncbiargs.hpp:1249
const CArgDescriptions & m_desc
Definition: ncbiargs.hpp:1259
EArgPositionalMode m_PositionalMode
Processing of positional args.
Definition: ncbiargs.hpp:1143
CArgAllow_Int8s(void)
Definition: ncbiargs.hpp:1728
virtual Int8 AsInt8(void) const =0
Get the argument's integer (8-byte long) value.
unsigned m_nExtraOpt
> # of mandatory extra args
Definition: ncbiargs.hpp:1140
virtual TIntId AsIntId(void) const =0
Get the argument's value as an integer id (TIntId).
TKeyFlagArgs m_KeyFlagArgs
Key/flag args, in order of insertion.
Definition: ncbiargs.hpp:1137
EConstraintNegate
Flag to invert constraint logically.
Definition: ncbiargs.hpp:922
size_t GetNExtra(void) const
Get the number of unnamed positional (a.k.a. extra) args.
Definition: ncbiargs.hpp:422
map< string, size_t > m_Groups
command to group #
Definition: ncbiargs.hpp:1459
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
TPosArgs m_PosArgs
Pos. args, ordered by position in cmd.-line.
Definition: ncbiargs.hpp:1135
bool x_IsMultiArg(const string &name) const
Returns TRUE if parameter supports multiple arguments.
Definition: ncbiargs.cpp:3145
pair< Int8, Int8 > TInterval
Definition: ncbiargs.hpp:1733
int TMiscFlags
Bitwise OR of "EMiscFlags".
Definition: ncbiargs.hpp:1036
TCommandArgFlags m_Cmd_req
Definition: ncbiargs.hpp:1457
void x_PostCheck(CArgs &args, unsigned int n_plain, EPostCheckCaller caller) const
Helper method for doing post-processing consistency checks.
Definition: ncbiargs.cpp:3162
bool IsSetMiscFlag(EMiscFlags flag) const
Check if the flag is set.
Definition: ncbiargs.hpp:1051
NCBI_EXCEPTION_DEFAULT(CArgHelpException, CArgException)
@ eConvertKeys
called by ConvertKeys()
Definition: ncbiargs.hpp:1220
@ eCreateArgs
called by CreateArgs()
Definition: ncbiargs.hpp:1219
@ eHelpShowAll
Error code for detailed help message which includes hidden arguments.
Definition: ncbiargs.hpp:164
@ eHelp
Error code for short help message.
Definition: ncbiargs.hpp:162
@ eHelpXml
Error code for XML formatted help message.
Definition: ncbiargs.hpp:165
@ eHelpFull
Error code for detailed help message.
Definition: ncbiargs.hpp:163
@ eExcludedValue
The value is excluded by another argument.
Definition: ncbiargs.hpp:129
@ eNoFile
Expecting a file.
Definition: ncbiargs.hpp:132
@ eNoArg
No argument.
Definition: ncbiargs.hpp:135
@ eNoValue
Expecting an argument value.
Definition: ncbiargs.hpp:128
@ eWrongCast
Incorrect cast for an argument.
Definition: ncbiargs.hpp:130
@ eArgType
Wrong argument type.
Definition: ncbiargs.hpp:134
@ eConvert
Conversion problem.
Definition: ncbiargs.hpp:131
@ eConstraint
Argument value outside constraints.
Definition: ncbiargs.hpp:133
@ eInvalidArg
Invalid argument.
Definition: ncbiargs.hpp:127
@ eRegularArgs
Regular application.
Definition: ncbiargs.hpp:560
@ eRequires
One argument requires another.
Definition: ncbiargs.hpp:956
@ eInt8
Convertible into an integer number (Int8 only)
Definition: ncbiargs.hpp:591
@ eInputFile
Name of file (must exist and be readable)
Definition: ncbiargs.hpp:595
@ eBoolean
{'true', 't', 'false', 'f'}, case-insensitive
Definition: ncbiargs.hpp:590
@ eDouble
Convertible into a floating point number (double)
Definition: ncbiargs.hpp:594
@ eDataSize
Integer number with possible "software" qualifiers (KB, KiB, et al)
Definition: ncbiargs.hpp:599
@ eIntId
Convertible to TIntId (int or Int8 depending on NCBI_INT8_GI)
Definition: ncbiargs.hpp:593
@ eIOFile
Name of file (must be writable)
Definition: ncbiargs.hpp:597
@ eOutputFile
Name of file (must be writable)
Definition: ncbiargs.hpp:596
@ eInteger
Convertible into an integer number (int or Int8)
Definition: ncbiargs.hpp:592
@ eDirectory
Name of file directory.
Definition: ncbiargs.hpp:598
@ ePositionalMode_Strict
Strict mode (default)
Definition: ncbiargs.hpp:577
@ eLower
Lowercase characters.
Definition: ncbiargs.hpp:1547
@ eAlnum
Alphanumeric characters.
Definition: ncbiargs.hpp:1542
@ eGraph
Graphical characters.
Definition: ncbiargs.hpp:1546
@ ePrint
Printable characters.
Definition: ncbiargs.hpp:1548
@ eSpace
Space characters.
Definition: ncbiargs.hpp:1550
@ eDigit
Digit characters.
Definition: ncbiargs.hpp:1545
@ eUpper
Uppercase characters.
Definition: ncbiargs.hpp:1551
@ eXdigit
Hexadecimal characters.
Definition: ncbiargs.hpp:1552
@ eCntrl
Control characters.
Definition: ncbiargs.hpp:1544
@ ePunct
Punctuation characters.
Definition: ncbiargs.hpp:1549
@ eAlpha
Alphabet characters.
Definition: ncbiargs.hpp:1543
@ eConstraintInvert
Logical NOT.
Definition: ncbiargs.hpp:923
@ eConstraint
Constraint is not inverted (taken as is)
Definition: ncbiargs.hpp:924
#define NULL
Definition: ncbistd.hpp:225
CException & operator=(const CException &)
Private assignment operator to prohibit assignment.
TFlags m_Flags
Flags, hints, attributes.
Definition: ncbiexpt.hpp:1134
virtual const char * GetErrCodeString(void) const override
Translate from the error code value to its string representation.
Definition: ncbiexpt.cpp:757
#define NCBI_DEPRECATED
int64_t Int8
8-byte (64-bit) signed integer
Definition: ncbitype.h:104
#define kMax_UInt
Definition: ncbi_limits.h:185
#define END_NCBI_SCOPE
End previously defined NCBI scope.
Definition: ncbistl.hpp:103
#define BEGIN_NCBI_SCOPE
Define ncbi namespace.
Definition: ncbistl.hpp:100
IO_PREFIX::ostream CNcbiOstream
Portable alias for ostream.
Definition: ncbistre.hpp:149
IO_PREFIX::iostream CNcbiIostream
Portable alias for iostream.
Definition: ncbistre.hpp:152
IO_PREFIX::istream CNcbiIstream
Portable alias for istream.
Definition: ncbistre.hpp:146
NCBI_NS_STD::string::size_type SIZE_TYPE
Definition: ncbistr.hpp:132
#define kEmptyStr
Definition: ncbistr.hpp:123
ECase
Which type of string comparison.
Definition: ncbistr.hpp:1204
@ eCase
Case sensitive compare.
Definition: ncbistr.hpp:1205
#define NCBI_XNCBI_EXPORT
Definition: ncbi_export.h:1283
int i
@ fNoCreate
Command does not create blob if it does not exist.
const GenericPointer< typename T::ValueType > T2 value
Definition: pointer.h:1227
Miscellaneous common-use basic types and functionality.
Portable reference counted smart and weak pointers using CWeakRef, CRef, CObject and CObjectEx.
Defines: CTimeFormat - storage class for time format.
const char * command
T negative(T x_)
static const char * prefix[]
Definition: pcregrep.c:405
Definition: type.c:6
Modified on Thu Apr 11 15:04:10 2024 by modify_doxy.py rev. 669887