README.md

   1 # Command
   2
   3 C++ library for handling command line arguments.
   4
   5 ## Installation
   6
   7 ### debian package
   8
   9     $ wget https://github.com/quayle/command/releases/download/v0.2.1-deb/command_0.2.1_all.deb
  10     $ sudo dpkg -i command_0.2.1_all.deb
  11
  12 ### from sources
  13
  14 You will need to have autotools installed (automake, autoconf, ...)
  15
  16     $ ./autogen.sh
  17     $ ./configure
  18     $ make
  19     $ sudo make install
  20
  21 ## Configuration
  22
  23 You need to enable c++11 support in your compiler. You can achieve that in
  24 g++ and clang++ by adding `-std=c++11` compilation flag.
  25
  26 As this is header-only library, you don't need any additional steps.
  27
  28 ## Usage
  29
  30 example.cpp:
  31
  32     #include <iostream>
  33     #include <command/command.h>
  34     #include <command/option.h>
  35
  36     using namespace command;
  37
  38     int main(int argc, char *argv[]) {
  39         try {
  40             Command command(argc, argv, {
  41                 new Option<void>("-h", "Help", [](void) { std::cout << "Help information\n"; })
  42             });
  43         }
  44         catch(const std::exception & e) {
  45             return 1;
  46         }
  47
  48         return 0;
  49     }
  50
  51 Now program can be compiled & run using following commands:
  52
  53     $ g++ -std=c++11 example.cpp
  54     $ ./a.out -h
  55     Help information
  56
  57 ### Possible classes to use:
  58
  59 Arguments are non-named program parameters. They must have some description and
  60 function handling when argument is passed:
  61
  62     new Argument<bool>("Bool argument", [](bool value) { });
  63
  64 Options are named program parameters. Option need name (e.g.: "i"), description,
  65 and function.
  66
  67     new Option<int>("name", "Integer option", [](int value) { });
  68
  69 Options could also be set as containing no value. In that case they become just
  70 a simple switches (some kind of mix between Argument and Option). They are used
  71 just to invoke some function if specific name was passed:
  72
  73     new Option<void>("v", "Verbose mode of program", [](void) { });
  74
  75 ### Behaviours
  76
  77 Parameters (Options and Arguments) can also be wrapped in Behaviours.
  78
  79 Required behaviour - if specific parameter was not passed and is required,
  80 exception is thrown (missingRequiredParameter):
  81
  82     new Required(
  83         new Argument<bool>("Bool argument", [](bool value) { })
  84     );
  85
  86 MultiValue behaviour - given parameter can handle more than one value. Values are
  87 separated by given separator. For each value passed function is invoked:
  88
  89     new MultiValue(",",
  90         new Option<std::string>("input", "Input file", [](std::string value) { })
  91     )
  92
  93 More complex example:
  94
  95     (...)
  96     void argument_function(bool a) {
  97         std::cout << "Argument: " << a << std::endl;
  98     }
  99
 100     void option_function(std::string a) {
 101         std::cout << "Option function " << a << std::endl;
 102     }
 103
 104     void void_function(void) {
 105         std::cout << "Void function " << std::endl;
 106     }
 107
 108     Command command(argc, argv, {
 109         new Required(
 110             new MultiValue("-",
 111                 new Argument<bool>("Input values", argument_function)
 112             )
 113         ),
 114         new MultiValue(",",
 115             new Option<std::string>("f", "Optional file", option_function)
 116         )
 117         new Option<void>("h", "Help", void_function)
 118     });
 119     (...)
 120
 121 Above code allows us to:
 122
 123 Parameters wrapped in Required class, have validator which checks if argument is
 124 passed:
 125
 126     $ ./a.out
 127     *Input values* is required
 128
 129     $ ./a.out 1
 130     Argument: 1
 131
 132     $ ./a.out 0
 133     Argument: 0
 134
 135     $ ./command 0 f
 136     Option: f requires value to be specified after equal sign, but no equal sign was found
 137
 138     $ ./command 0 f=
 139     Option: f failed value conversion to the required type
 140
 141 For MultiValue Parameters each value is passed to the given function:
 142
 143     $ ./a.out 1-0-1
 144     Argument: 1
 145     Argument: 0
 146     Argument: 1
 147
 148     $ ./command 0 f=one,two,three
 149     Argument: 0
 150     Option function one
 151     Option function two
 152     Option function three
 153
 154 ## Documentation
 155
 156 Current documentation can be found at:
 157 http://dlugolecki.net.pl/software/command/docs/
 158
 159 If for some reason it is unavailable, you can build it yourself. The only
 160 requirement is to have [Doxygen](http://www.doxygen.org/) installed when `make` command is invoked.