README

   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.3-deb/command_0.3_all.deb
  10     $ sudo dpkg -i command_0.3_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 <string>
  34     #include <command/command.h>
  35     #include <command/option.h>
  36     #include <command/argument.h>
  37
  38     using namespace command;
  39
  40     class MyClass {
  41         std::string _value = "Default";
  42     public:
  43         void setValue(std::string value) {
  44             this->_value = value;
  45         }
  46         std::string getValue() {
  47             return std::string("Value from MyClass: ") + this->_value;
  48         }
  49     };
  50
  51     int main(int argc, char *argv[]) {
  52         MyClass myClass;
  53         try {
  54             Command command(argc, argv, {
  55                 new Option<void>("-h", "Help", [](void) {
  56                     std::cout << "Help information\n";
  57                 }),
  58                 new Argument<std::string>("Value for MyClass",
  59                     std::bind(&MyClass::setValue, &myClass, std::placeholders::_1)
  60                 )
  61             });
  62         }
  63         catch(const std::exception & e) {
  64             return 1;
  65         }
  66
  67         std::cout << myClass.getValue() << std::endl;
  68
  69         return 0;
  70     }
  71
  72 Now program can be compiled & run using following commands:
  73
  74     $ g++ -std=c++11 example.cpp
  75     $ ./a.out -h
  76     Help information
  77     Value from MyClass: Default
  78
  79     $ ./a.out someArg
  80     Value from MyClass: someArg
  81
  82     $ ./a.out someArg -h
  83     Help information
  84     Value from MyClass: someArg
  85
  86 ### Possible classes to use:
  87
  88 Arguments are non-named program parameters. They must have some description and
  89 function handling when argument is passed:
  90
  91     new Argument<bool>("Bool argument", [](bool value) { });
  92
  93 Options are named program parameters. Option need name (e.g.: "i"), description,
  94 and function.
  95
  96     new Option<int>("name", "Integer option", [](int value) { });
  97
  98 Options could also be set as containing no value. In that case they become just
  99 a simple switches (some kind of mix between Argument and Option). They are used
 100 just to invoke some function if specific name was passed:
 101
 102     new Option<void>("v", "Verbose mode of program", [](void) { });
 103
 104 ### Behaviours
 105
 106 Parameters (Options and Arguments) can also be wrapped in Behaviours.
 107
 108 Required behaviour - if specific parameter was not passed and is required,
 109 exception is thrown (missingRequiredParameter):
 110
 111     new Required(
 112         new Argument<bool>("Bool argument", [](bool value) { })
 113     );
 114
 115 MultiValue behaviour - given parameter can handle more than one value. Values are
 116 separated by given separator. For each value passed function is invoked:
 117
 118     new MultiValue(",",
 119         new Option<std::string>("input", "Input file", [](std::string value) { })
 120     )
 121
 122 More complex example:
 123
 124     (...)
 125     void argument_function(bool a) {
 126         std::cout << "Argument: " << a << std::endl;
 127     }
 128
 129     void option_function(std::string a) {
 130         std::cout << "Option function " << a << std::endl;
 131     }
 132
 133     void void_function(void) {
 134         std::cout << "Void function " << std::endl;
 135     }
 136
 137     Command command(argc, argv, {
 138         new Required(
 139             new MultiValue("-",
 140                 new Argument<bool>("Input values", argument_function)
 141             )
 142         ),
 143         new MultiValue(",",
 144             new Option<std::string>("f", "Optional file", option_function)
 145         )
 146         new Option<void>("h", "Help", void_function)
 147     });
 148     (...)
 149
 150 Above code allows us to:
 151
 152 Parameters wrapped in Required class, have validator which checks if argument is
 153 passed:
 154
 155     $ ./a.out
 156     *Input values* is required
 157
 158     $ ./a.out 1
 159     Argument: 1
 160
 161     $ ./a.out 0
 162     Argument: 0
 163
 164     $ ./command 0 f
 165     Option: f requires value to be specified after equal sign, but no equal sign was found
 166
 167     $ ./command 0 f=
 168     Option: f failed value conversion to the required type
 169
 170 For MultiValue Parameters each value is passed to the given function:
 171
 172     $ ./a.out 1-0-1
 173     Argument: 1
 174     Argument: 0
 175     Argument: 1
 176
 177     $ ./command 0 f=one,two,three
 178     Argument: 0
 179     Option function one
 180     Option function two
 181     Option function three
 182
 183 ## Documentation
 184
 185 Current documentation can be found at:
 186 http://dlugolecki.net.pl/software/command/docs/
 187
 188 If for some reason it is unavailable, you can build it yourself. The only
 189 requirement is to have [Doxygen](http://www.doxygen.org/) installed when `make` command is invoked.