DIAGNOSTICS

options · option class

+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

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