README.md

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