DIAGNOSTICS

options · option class

{ --foo --bar }+ arg   # 'arg' with '--foo' '--bar'
-arg +{ fox=1 baz=2 }   # 'arg' with 'fox=1' 'baz=2'
{ -f }+ { -b }+ arg +{ f=1 } +{ b=2 } # 'arg' with '-f' 'b' 'f=1' 'b=2'
{ --foo }+ arg1  arg2 +{ --bar }  # 'arg1' with '--foo' and
-                                  # 'arg2' with '--bar'
{--foo}+ arg   # '{--foo}+' ...
-arg+{ --foo }  # 'arg+{' ...
}             # error: unexpected group separator
-}x            # '}x'
-\}            # '}'
-{ \}+ }+ arg  # 'arg' with '}+'
--page-usage print_         # print_usage() in global namespace
---page-usage app::print_    # print_usage() in app namespace
---page-usage print_$name$_  # print_foo_usage() if name is foo
-include <string>;
-
-class options
-{
-  bool --help;
-  std::string --greeting = "Hello";
-  unsigned int --exclamations = 1;
-};
-  
-$ cli hello.cli
-  
-#include <string>
-
-class options
-{
-public:
-  options (int argc, char** argv);
-  options (int argc, char** argv, int& end);
-
-  // Option accessors.
-  //
-public:
-  bool
-  help () const;
-
-  const std::string&
-  greeting () const;
-
-  unsigned int
-  exclamations () const;
-
-private:
-  ..
-};
-  
-#include <iostream>
-#include "hello.hxx"
-
-using namespace std;
-
-void
-usage (ostream& os)
-{
-  os << "usage: driver [options] <names>" << endl
-     << "options:" << endl;
-  options::print_usage (os);
-}
-
-int
-main (int argc, char* argv[])
-{
-  try
-  {
-    int end; // End of options.
-    options o (argc, argv, end);
-
-    if (o.help ())
-    {
-      usage (cout);
-      return 0;
-    }
-
-    if (end == argc)
-    {
-      cerr << "no names provided" << endl;
-      usage (cerr);
-      return 1;
-    }
-
-    // Print the greetings.
-    //
-    for (int i = end; i < argc; i++)
-    {
-      cout << o.greeting () << ", " << argv[i];
-
-      for (unsigned int j = 0; j < o.exclamations (); j++)
-        cout << '!';
-
-      cout << endl;
-    }
-  }
-  catch (const cli::exception& e)
-  {
-    cerr << e << endl;
-    usage (cerr);
-    return 1;
-  }
-}
-
-$ c++ -o driver driver.cxx hello.cxx
-
-$ ./driver world
-Hello, world!
-
-$ ./driver --greeting Hi --exclamations 3 John Jane
-Hi, John!!!
-Hi, Jane!!!
-  
-$ ./driver -n 3 Jane
-unknown option '-n'
-usage: driver [options] <names>
-options:
---help
---greeting <arg>
---exclamations <arg>
-
-$ ./driver --exclamations abc Jane
-invalid value 'abc' for option '--exclamations'
-usage: driver [options] <names>
-options:
---help
---greeting <arg>
---exclamations <arg>
-  
-$ ./driver --help
-usage: driver [options] <names>
-options:
---help
---greeting <arg>
---exclamations <arg>
-  
-include <string>;
-
-class options
-{
-  bool --help {"Print usage information and exit."};
-
-  std::string --greeting = "Hello"
-  {
-    "<text>",
-    "Use <text> as a greeting phrase instead of the default \"Hello\"."
-  };
-
-  unsigned int --exclamations = 1
-  {
-    "<num>",
-    "Print <num> exclamation marks instead of 1 by default."
-  };
-};
-  
-usage: driver [options] <names>
-options:
---help               Print usage information and exit.
---greeting <text>    Use <text> as a greeting phrase instead of the
-                     default "Hello".
---exclamations <num> Print <num> exclamation marks instead of 1 by
-                     default.
-  
-$ cli --generate-html hello.cli
-  
-class options
-{
-  bool --help;
-  int --compression;
-};
-  
-class options
-{
-public:
-  options (int& argc,
-           char** argv,
-           bool erase = false,
-           cli::unknown_mode opt_mode = cli::unknown_mode::fail,
-           cli::unknown_mode arg_mode = cli::unknown_mode::stop);
-
-  options (int start,
-           int& argc,
-           char** argv,
-           bool erase = false,
-           cli::unknown_mode opt_mode = cli::unknown_mode::fail,
-           cli::unknown_mode arg_mode = cli::unknown_mode::stop);
-
-  options (int& argc,
-           char** argv,
-           int& end,
-           bool erase = false,
-           cli::unknown_mode opt_mode = cli::unknown_mode::fail,
-           cli::unknown_mode arg_mode = cli::unknown_mode::stop);
-
-  options (int start,
-           int& argc,
-           char** argv,
-           int& end,
-           bool erase = false,
-           cli::unknown_mode opt_mode = cli::unknown_mode::fail,
-           cli::unknown_mode arg_mode = cli::unknown_mode::stop);
-
-  options (cli::scanner&,
-           cli::unknown_mode opt_mode = cli::unknown_mode::fail,
-           cli::unknown_mode arg_mode = cli::unknown_mode::stop);
-
-  options (const options&);
-
-  options&
-  operator= (const options&);
-
-public:
-  static void
-  print_usage (std::ostream&);
-
-public:
-  bool
-  help () const;
-
-  int
-  compression () const;
-};
-  
-namespace cli
-{
-  class unknown_mode
-  {
-  public:
-    enum value
-    {
-      skip,
-      stop,
-      fail
-    };
-
-    unknown_mode (value v);
-    operator value () const;
-  };
-}
-  
-namespace cli
-{
-  class scanner
-  {
-  public:
-    virtual bool
-    more () = 0;
-
-    virtual const char*
-    peek () = 0;
-
-    virtual const char*
-    next () = 0;
-
-    virtual void
-    skip () = 0;
-  };
-}
-  
-namespace cli
-{
-  class argv_scanner
-  {
-  public:
-    argv_scanner (int& argc, char** argv, bool erase = false);
-    argv_scanner (int start, int& argc, char** argv, bool erase = false);
-
-    int
-    end () const;
-
-    ...
-  };
-}
-  
-namespace cli
-{
-  class argv_file_scanner
-  {
-  public:
-    argv_file_scanner (int& argc,
-                       char** argv,
-                       const std::string& option,
-                       bool erase = false);
-
-    argv_file_scanner (int start,
-                       int& argc,
-                       char** argv,
-                       const std::string& option,
-                       bool erase = false);
-
-    struct option_info
-    {
-      // If search_func is not NULL, it is called, with the arg
-      // value as the second argument, to locate the options file.
-      // If it returns an empty string, then the file is ignored.
-      //
-      const char* option;
-      std::string (*search_func) (const char*, void* arg);
-      void* arg;
-    };
-
-    argv_file_scanner (int& argc,
-                       char** argv,
-                       const option_info* options,
-                       std::size_t options_count,
-                       bool erase = false);
-
-    argv_file_scanner (int start,
-                       int& argc,
-                       char** argv,
-                       const option_info* options,
-                       std::size_t options_count,
-                       bool erase = false);
-    ...
-  };
-}
-  
-#include <exception>
-
-namespace cli
-{
-  class exception: public std::exception
-  {
-  public:
-    virtual void
-    print (std::ostream&) const = 0;
-  };
-
-  inline std::ostream&
-  operator<< (std::ostream& os, const exception& e)
-  {
-    e.print (os);
-    return os;
-  }
-
-  class unknown_option: public exception
-  {
-  public:
-    unknown_option (const std::string& option);
-
-    const std::string&
-    option () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class unknown_argument: public exception
-  {
-  public:
-    unknown_argument (const std::string& argument);
-
-    const std::string&
-    argument () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class missing_value: public exception
-  {
-  public:
-    missing_value (const std::string& option);
-
-    const std::string&
-    option () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class invalid_value: public exception
-  {
-  public:
-    invalid_value (const std::string& option,
-                   const std::string& value);
-
-    const std::string&
-    option () const;
-
-    const std::string&
-    value () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class eos_reached: public exception
-  {
-  public:
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class file_io_failure: public exception
-  {
-  public:
-    file_io_failure (const std::string& file);
-
-    const std::string&
-    file () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-
-  class unmatched_quote: public exception
-  {
-  public:
-    unmatched_quote (const std::string& argument);
-
-    const std::string&
-    argument () const;
-
-    virtual void
-    print (std::ostream&) const;
-
-    virtual const char*
-    what () const throw ();
-  };
-}
-  
-class options
-{
-  int --compression-level | --comp | -c;
-};
-  
-class options
-{
-  int
-  compression_level () const;
-};
-  
-class options
-{
-  bool "int";
-};
-  
-include <string>;
-
-class options
-{
-  int -i1 = 5;
-  int -i2 (5);
-
-  std::string -s1 = "John";
-  std::string -s2 ("Mr John Doe", 8, 3);
-};
-  
-include "constants.hxx"; // Defines default_value.
-
-class options
-{
-  int -a = default_value;
-  int -b (25 * 4);
-  int -c = (25 / default_value + 3);
-};
-  
-include <set>;
-include <vector>;
-
-class options
-{
-  std::vector<int> --vector | -v;
-  std::set<int> --set | -s;
-};
-  
-include <map>;
-include <string>;
-
-class options
-{
-  std::map<std::string, std::string> --map | -m;
-};
-  
-class options
-{
-  int --compression = 5
-  {
-    "<level>",
-    "Set compression to <level> instead of 5 by default.
-
-     With the higher compression levels the program may produce a
-     smaller output but may also take longer and use more memory."
-  };
-};
-  
-include <map>;
-include <string>;
-
-class options
-{
-  std::map<std::string, std::string> --map
-  {
-    "<key>=<value>",
-    "Add the <key>, <value> pair to the map."
-  };
-};
-  
-class options
-{
-  int --compression = 5
-  {
-    "<level>",
-    "Set compression to <level> instead of 5 by default.
-
-     With the higher compression levels the program \i{may}
-     produce a smaller output but may also \b{take longer}
-     and \b{use more memory}."
-  };
-};
-  
-include <string>;
-include "types.hxx"; // Defines the name_type class.
-
-class options
-{
-  std::string --string;
-  name_type --name;
-};
-  
-#include <string>
-#include "types.hxx"
-
-class options
-{
-  ...
-
-  const std::string&
-  string () const;
-
-  const name_type&
-  name () const;
-
-  ...
-};
-  
-namespace compiler
-{
-  namespace lexer
-  {
-    class options
-    {
-      int --warning-level = 0;
-    };
-  }
-
-  namespace parser
-  {
-    class options
-    {
-      int --warning-level = 0;
-    };
-  }
-
-  namespace generator
-  {
-    class options
-    {
-      int --target-width = 32;
-    };
-  }
-}
-  
-namespace compiler
-{
-  namespace lexer
-  {
-    class options
-    {
-      int
-      warning_level () const;
-    };
-  }
-
-  namespace parser
-  {
-    class options
-    {
-      int
-      warning_level () const;
-    };
-  }
-
-  namespace generator
-  {
-    class options
-    {
-      int
-      target_width () const;
-    };
-  }
-}
-

DIAGNOSTICS

BUGS

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

NAME

SYNOPSIS

DESCRIPTION

OPTIONS

DIAGNOSTICS

BUGS

CLI Language

Getting Started Guide

Table of Contents

1 Introduction

2 Hello World Example

2.1 Defining Command Line Interface

2.2 Translating CLI Definitions to C++

2.3 Implementing Application Logic

2.4 Compiling and Running

2.5 Adding Documentation

3 CLI Language

3.1 Option Class Definition

3.2 Option Definition

3.3 Option Documentation

3.4 Include Directive

3.5 Namespace Definition