Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
FBB::Arg(3bobcat)	    Command Line Arguments	     FBB::Arg(3bobcat)

NAME
       FBB::Arg	- A singleton class interfacing	command	line arguments

SYNOPSIS
       #include	<bobcat/arg>
       Linking option: -lbobcat

DESCRIPTION
       Singleton  class	 (see Gamma et al., 1995) built	around getopt()(3) and
       getopt_long()(3). The class handles short- and  long  command-line  op-
       tions,

NAMESPACE
       FBB
       All  constructors,  members,  operators	and manipulators, mentioned in
       this man-page, are defined in the namespace FBB.

INHERITS FROM
       -

ENUMERATION
       The FBB::Arg::Type enumeration is defined by the	FBB::Arg class.	It has
       the following values intended for public	use: None, Required, Optional.
       These values are	used when constructing objects	of  the	 nested	 class
       FBB::Arg::LongOption, see below.

CONSTRUCTORS
       Since  the  class is a Singleton, no public constructors	are available.
       Instead,	static members are offered to initialize and access the	single
       FBB::Arg	object.	See below.

STATIC MEMBERS
       o      FBB::Arg	&initialize(char  const	 *optstring,  int  argc,  char
	      **argv):
	      Initializes the FBB::Arg singleton. Must be  called  only	 once.
	      Throws  an  FBB::Exception  exception if called repeatedly or if
	      called with argv not containing a	defined	option (which is shown
	      by  the  FBB::Exception's	what() member).	Returns	a reference to
	      the singleton object, allowing code initializing Arg to use  the
	      initialized object immediately.

       o      FBB::Arg	&initialize(char  const	*optstring, LongOption const *
	      const begin, LongOption  const  *	 const	end,  int  argc,  char
	      **argv):
	      Initializes  the FBB::Arg	singleton. Accepts two iterators of an
	      array of Arg::LongOption objects,	holding	long-options. Must  be
	      called  only  once. Throws an FBB::Exception exception if	called
	      repeatedly or if called with argv	not containing a  defined  op-
	      tion  (which  is	shown  by the FBB::Exception's what() member).
	      See the description of Arg::LongOption below.  Returns a	refer-
	      ence  to the singleton object, allowing code initializing	Arg to
	      use the initialized object immediately.

	      optstring	should consist of letters, possibly postfixed by:

       o      a	colon (:), indicating  that  the  option  requires  an	option
	      value.

       o      a	 double	 colon	(::), indicating that the option itself	has an
	      optional argument. With short options the	option value  is  con-
	      sidered  absent  unless  it immediately follows the short	option
	      (e.g., -tvalue for a short option	-t). Long  options  optionally
	      accepting	arguments should always	immediately be followed	by a =
	      character. Here the option's value must immediately follow the =
	      character, and must start	with a non-blank character, or the op-
	      tion's value is considered absent. E.g., --value=	 indicates  an
	      absent  option  value, --value=text indicates the	option's value
	      equals text.  If an option  value	 itself	 contains  blanks,  it
	      should  be  surrounded by	single or double quotes	(e.g., -t'this
	      value', or --text='this value'). The  surrounding	 quotes	 them-
	      selves are not part of the option's value.

       o      FBB::Arg &instance():
	      Returns  the instance of the Arg object, available after calling
	      one of the Arg::initialize() members.  If	called before initial-
	      ization, an FBB::Exception exception is thrown.

OVERLOADED OPERATOR
       o      char const *operator[](size_t idx) const:
	      Returns  argument[idx],  after  having removed all specified op-
	      tions.  0	is returned if no arg[x] is  available.	  The  program
	      name  (argv[0]) is NOT counted here: index 0 refers to the first
	      ARGUMENT,	e.g., the program's argv[1].

NON-STATIC MEMBER FUNCTIONS
       o      char const **argPointers():
	      Returns argv-like	set of pointers	to  all	 remaining  arguments.
	      The  last	 element  is  guaranteed  to be	a 0-pointer. The first
	      nArg() elements point to the respective C-string values  of  the
	      arguments.

       o      std::string const	&basename() const:
	      Returns the program's basename.

       o      size_t beyondDashes() const:
	      Returns  the  index of the first argument	after a	-- argument or
	      nArgs() if no -- argument	was encountered.
	      A	-- argument ends Arg's argument	processing, and	all  arguments
	      beyond  the first	-- argument are	kept `as is'. The beyondDashes
	      member returns the index of the first argument beyond the	-- ar-
	      gument,  which itself is removed from the	remaining set of argu-
	      ments.

       o      size_t nArgs() const:
	      Returns the number of arguments left after option-removal.   The
	      program name argv[0] is NOT counted here.

       o      size_t nLongOptions() const:
	      Returns  the  number  of	long options for which no short	option
	      synonym exist. If	long options are multiply specified, then each
	      specification is counted.

       o      size_t nOptions()	const:
	      Returns  the  number  of	specified single character options. If
	      short options have long option synonyms, then these long	option
	      synonyms are counted as if they were specified as	single charac-
	      ter options. If single character options (or their  long	option
	      synonyms)	 are  multiply	specified,  then each specification is
	      counted.

       o      size_t option(int	option)	const:
	      The number of times `option' (or its long	option synonym,	if de-
	      fined) was specified is returned.

       o      size_t option(std::string	const &options)	const:
	      The number of times one of the options specified in the `option'
	      argument (or their long option synonyms)	were  present  is  re-
	      turned.

       o      size_t option(string *value, int option) const:
	      Returns the number of times the provided option (or its long op-
	      tion synonym) was	present. If the	return value is	non-zero  then
	      the  value  of  the first	occurrence of this option is stored in
	      *value, which is left untouched if `option' was not  present.  0
	      may  be  specified for value if the option does not have a value
	      or if the	value should not be stored.

       o      size_t option(size_t idx,	string *value, int option) const:
	      Returns the number of times the provided option (or its long op-
	      tion  synonym) was present. If the return	value is non-zero then
	      the value	of the idxth occurrence	(0-based offset) of  this  op-
	      tion  is	stored	in *value, which is left untouched if `option'
	      was not present or if idx	is or exceeds the number of specifica-
	      tions  of	 the  provided option. 0 may be	specified for value if
	      the option does not have a value or if the value should  not  be
	      stored.

       o      size_t option(size_t *idx, string	*value,	int option) const:
	      Returns the number of times the provided option (or its long op-
	      tion synonym) was	present. If the	return value is	non-zero  then
	      the  offset  (within the series of option	specifications)	of the
	      first option having a non-empty  option  value  is  returned  in
	      *idx,  while  its	 option	value is stored	in *value. Both	*value
	      and *idx are left	untouched if `option' was not present.	0  may
	      be specified for value if	the option does	not have a value or if
	      the value	should not be stored.

       o      size_t option(string *value, char	const *longOption) const:
	      Returns the number of times the specified	long option (not  hav-
	      ing  a  single-character synonym)	was present. Its value is then
	      stored in	*value,	which is left untouched	if the long option was
	      not present. 0 may be specified for value	if the option does not
	      have a value or if the value should not be stored.

       o      size_t option(size_t idx,	string *value, char  const  *  longOp-
	      tion) const:
	      Returns the number of times the provided long option (not	having
	      a	single-character synonym) was present. If the return value  is
	      non-zero then the	value of the idxth occurrence (0-based offset)
	      of this long option is stored in *value, which is	left untouched
	      if  the  long option was not present or if idx is	or exceeds the
	      number of	specifications of the provided long option. 0  may  be
	      specified	 for value if the long option does not have a value or
	      if the value should not be stored.

       o      size_t option(size_t *idx, string	*value,	int longOption)	const:
	      Returns the number of times the provided long option (not	having
	      a	 single-character synonym) was present.	If the return value is
	      non-zero then the	offset (within the series of this long	option
	      specifications)  of the first long option	having a non-empty op-
	      tion value is returned in	*idx, while its	option value is	stored
	      in  *value.  Both	*value and *idx	are left untouched if long op-
	      tion was not present. 0 may be specified for value if  the  long
	      option  does  not	 have  a  value	 or if the value should	not be
	      stored.

       o      void  versionHelp(void  (*usage)(std::string  const  &progname),
	      char  const  *version,  size_t  minArgs, int helpFlag = 'h', int
	      versionFlag = 'v') const:
	      If versionFlag was specified, and	the helpFlag was not specified
	      the  program's  name (using basename()) and version is displayed
	      to std::cout. Otherwise, if the  helpFlag	 was  provided	or  if
	      there  are  fewer	 arguments than	minArgs	usage()	is called with
	      argument basename(). If either version- or help  information  is
	      shown, the int value 1 is	thrown as an exception.
	      Note that	versionhelp compares minArgs against nArgs. If minArgs
	      should be	compaired against the number of	arguments up to	a pos-
	      sible `--' argument (i.e., beyondDashes' return value), then add
	      nArgs() -	beyondDashes() to the minArg argument. E.g.,

		  arg.versionHelp(usage, version, 2 + arg.nArgs() - arg.beyondDashes());

	      The address of the usage() function, the current version and the
	      minimum  number of arguments must	be specified. Default argument
	      values are provided for the option flags.

THE NESTED CLASS FBB::Arg::LongOption
       Long  options  are  defined  using  objects   of	  the	nested	 class
       FBB::Arg::LongOption. This class	offers the following constructors:

       o      FBB::Arg::LongOption(char	 const	*name,	FBB::Arg::Type	type =
	      None):
	      This constructor is used to define a long	option	for  which  no
	      corresponding short option is defined. The parameter name	is the
	      name of the long option (without prefixing  the  --  characters,
	      which are	required when specifying the long option).

       o      FBB::Arg::LongOption(char	const *name, int optionChar):
	      This  constructor	 is  used  to define a long option for which a
	      corresponding short option is defined. The parameter name	is the
	      name  of	the  long option (without prefixing the	-- characters,
	      which are	required when specifying the long option).  In a  pro-
	      gram, long options may be	specified as follows:

       o      First, construct an array

		  FBB::Arg::LongOption longOptions[] = { c1, c2, ... cn	}

	      Where   c1,  c2,	...,  cn  are  n  constructor  invocations  of
	      FBB::Arg::LongOption() constructors

       o      Next, pass longOptions, LongOptions + n as 2nd and 3rd arguments
	      to initialize()

EXAMPLE
       The  following  example	illustrates defining long options and shows an
       initialization. It is not a full-fledched example in  the  sense	 of  a
       small runnable program.

       #include	<bobcat/arg>

       using namespace FBB;

       namespace   // the anonymous namespace can be used here
       {
	   Arg::LongOption longOptions[] =
	   {
	       Arg::LongOption("debug"),
	       Arg::LongOption("filenames", 'f'),
	       Arg::LongOption("help", 'h'),
	       Arg::LongOption("version", 'v'),
	   };
	   auto	longEnd	= longOptions +	sizeof(longOptions) / sizeof(longOptions[0]);
       }

       int main(int argc, char **argv)
       try
       {
	   Arg &arg = Arg::initialize("df:hv",
			   longOptions,	longEnd, argc, argv);

	   // code using arg, etc.
       }
       catch(Exception const &err)     // handle exceptions
       {
	   cerr	<< err.what() << endl;
	   return err.which();
       }
       catch(int x)
       {
	   return x;
       }

FILES
       bobcat/arg - defines the	class interface

SEE ALSO
       bobcat(7)

BUGS
       None Reported.

DISTRIBUTION FILES
       o      bobcat_3.25.01-x.dsc: detached signature;

       o      bobcat_3.25.01-x.tar.gz: source archive;

       o      bobcat_3.25.01-x_i386.changes: change log;

       o      libbobcat1_3.25.01-x_*.deb:   debian  package  holding  the  li-
	      braries;

       o      libbobcat1-dev_3.25.01-x_*.deb: debian package holding  the  li-
	      braries, headers and manual pages;

       o      http://sourceforge.net/projects/bobcat: public archive location;

BOBCAT
       Bobcat is an acronym of `Brokken's Own Base Classes And Templates'.

COPYRIGHT
       This  is	 free software,	distributed under the terms of the GNU General
       Public License (GPL).

AUTHOR
       Frank B.	Brokken	(f.b.brokken@rug.nl).

libbobcat-dev_3.25.01-x.tar.gz	   2005-2015		     FBB::Arg(3bobcat)

NAME | SYNOPSIS | DESCRIPTION | NAMESPACE | INHERITS FROM | ENUMERATION | CONSTRUCTORS | STATIC MEMBERS | OVERLOADED OPERATOR | NON-STATIC MEMBER FUNCTIONS | THE NESTED CLASS FBB::Arg::LongOption | EXAMPLE | FILES | SEE ALSO | BUGS | DISTRIBUTION FILES | BOBCAT | COPYRIGHT | AUTHOR

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=arg&sektion=3&manpath=FreeBSD+12.0-RELEASE+and+Ports>

home | help