Fix missing multiValue library
[command.git] / 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.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.