OpenShot Library | libopenshot-audio 0.2.0
juce_ConsoleApplication.h
1
2/** @weakgroup juce_core-misc
3 * @{
4 */
5/*
6 ==============================================================================
7
8 This file is part of the JUCE library.
9 Copyright (c) 2017 - ROLI Ltd.
10
11 JUCE is an open source library subject to commercial or open-source
12 licensing.
13
14 The code included in this file is provided under the terms of the ISC license
15 http://www.isc.org/downloads/software-support-policy/isc-license. Permission
16 To use, copy, modify, and/or distribute this software for any purpose with or
17 without fee is hereby granted provided that the above copyright notice and
18 this permission notice appear in all copies.
19
20 JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER
21 EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE
22 DISCLAIMED.
23
24 ==============================================================================
25*/
26
27namespace juce
28{
29
30//==============================================================================
31/**
32 Holds a list of command-line arguments, and provides useful methods for searching
33 and operating on them.
34
35 You can create an ArgumentList manually, or give it some argv/argc values from a
36 main() function to parse.
37
38 @see ConsoleApplication
39*/
41{
42 /** Creates an argument list for a given executable. */
44
45 /** Parses a standard argv/argc pair to create an argument list. */
46 ArgumentList (int argc, char* argv[]);
47
48 /** Tokenises a string containing all the arguments to create an argument list. */
50
51 ArgumentList (const ArgumentList&) = default;
52 ArgumentList& operator= (const ArgumentList&) = default;
53
54 //==============================================================================
55 /**
56 One of the arguments in an ArgumentList.
57 */
58 struct Argument
59 {
60 /** The original text of this argument. */
62
63 /** Resolves this argument as an absolute File, using the current working
64 directory as a base for resolving relative paths, and stripping quotes, etc.
65 */
66 File resolveAsFile() const;
67
68 /** Resolves this argument as an absolute File, using the current working
69 directory as a base for resolving relative paths, and also doing a check to
70 make sure the file exists.
71 If the file doesn't exist, this will call fail() with a suitable error.
72 @see resolveAsFile, resolveAsExistingFolder
73 */
75
76 /** Resolves a user-supplied folder name into an absolute File, using the current working
77 directory as a base for resolving relative paths, and also doing a check to make
78 sure the folder exists.
79 If the folder doesn't exist, this will call fail() with a suitable error.
80 @see resolveAsFile, resolveAsExistingFile
81 */
83
84 /** Returns true if this argument starts with a double dash. */
85 bool isLongOption() const;
86
87 /** Returns true if this argument starts with a single dash. */
88 bool isShortOption() const;
89
90 /** Returns true if this argument starts with a double dash, followed by the given string. */
91 bool isLongOption (const String& optionRoot) const;
92
93 /** If this argument is a long option with a value, this returns the value.
94 e.g. for "--foo=bar", this would return 'bar'.
95 */
97
98 /** Returns true if this argument starts with a single dash and then contains the given character somewhere inside it. */
99 bool isShortOption (char shortOptionCharacter) const;
100
101 /** Returns true if this argument starts with one or more dashes. */
102 bool isOption() const;
103
104 /** Compares this argument against a string.
105 The string may be a pipe-separated list of options, e.g. "--help|-h"
106 */
108
109 /** Compares this argument against a string.
110 The string may be a pipe-separated list of options, e.g. "--help|-h"
111 */
113 };
114
115 //==============================================================================
116 /** Returns the number of arguments in the list. */
117 int size() const;
118
119 /** Returns one of the arguments */
120 Argument operator[] (int index) const;
121
122 /** Throws an error unless there are at least the given number of arguments. */
124
125 /** Returns true if the given string matches one of the arguments.
126 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
127 */
128 bool containsOption (StringRef option) const;
129
130 /** Returns the index of the given string if it matches one of the arguments, or -1 if it doesn't.
131 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
132 */
133 int indexOfOption (StringRef option) const;
134
135 /** Throws an error unless the given option is found in the argument list. */
137
138 /** Looks for a given argument and returns either its assigned value (for long options) or the
139 string that follows it (for short options).
140 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
141 If it finds a long option, it will look for an assignment with a '=' sign, e.g. "--file=foo.txt",
142 and will return the string following the '='. If there's no '=', it will return an empty string.
143 If it finds a short option, it will attempt to return the argument that follows it, unless
144 it's another option.
145 If the argument isn't found, this returns an empty string.
146 */
148
149 /** Looks for the value of argument using getValueForOption() and tries to parse that value
150 as a file.
151 If the option isn't found, or if the value can't be parsed as a filename, it will throw
152 an error.
153 */
155
156 /** Looks for a file argument using getFileForOption() and fails with a suitable error if
157 the file doesn't exist.
158 */
160
161 /** Looks for a filename argument using getFileForOption() and fails with a suitable error if
162 the file isn't a folder that exists.
163 */
165
166 /** The name or path of the executable that was invoked, as it was specified on the command-line. */
168
169 /** The list of arguments (not including the name of the executable that was invoked). */
171};
172
173
174//==============================================================================
175/**
176 Represents a the set of commands that a console app can perform, and provides
177 helper functions for performing them.
178
179 When using these helper classes to implement a console app, you probably want to
180 do something along these lines:
181
182 @code
183 int main (int argc, char* argv[])
184 {
185 ConsoleApplication app;
186
187 app.addHelpCommand ("--help|-h", "Usage:", true);
188 app.addVersionCommand ("--version|-v", "MyApp version 1.2.3");
189
190 app.addCommand ({ "--foo",
191 "--foo filename",
192 "Performs a foo operation on the given file",
193 [] (const auto& args) { doFoo (args); }});
194
195 return app.findAndRunCommand (argc, argv);
196 }
197 @endcode
198
199 @see ArgumentList
200*/
202{
203 //==============================================================================
204 /**
205 Represents a command that can be executed if its command-line arguments are matched.
206 @see ConsoleApplication::addCommand(), ConsoleApplication::findAndRunCommand()
207 */
208 struct Command
209 {
210 /** The option string that must appear in the argument list for this command to be invoked.
211 This can also be a list of different versions separated by pipes, e.g. "--help|-h"
212 */
214
215 /** A description of the command-line arguments needed for this command, which will be
216 printed as part of the help text.
217 */
219
220 /** A short (one line) description of this command, which can be printed by
221 ConsoleApplication::printCommandList().
222 */
224
225 /** A longer description of this command, for use in extended help. */
227
228 /** The actual command that should be invoked to perform this action. */
229 std::function<void(const ArgumentList&)> command;
230 };
231
232 //==============================================================================
233 /** Adds a command to the list. */
234 void addCommand (Command);
235
236 /** Adds a command to the list, and marks it as one which is invoked if no other
237 command matches.
238 */
240
241 /** Adds a command that will print the given text in response to the "--version" option. */
243
244 /** Adds a help command to the list.
245 This command will print the user-supplied message that's passed in here as an
246 argument, followed by a list of all the registered commands.
247 */
249
250 /** Prints out the list of commands and their short descriptions in a format that's
251 suitable for use as help.
252 */
253 void printCommandList (const ArgumentList&) const;
254
255 //==============================================================================
256 /** Throws a failure exception to cause a command-line app to terminate.
257 This is intended to be called from code in a Command, so that the
258 exception will be automatically caught and turned into a printed error message
259 and a return code which will be returned from main().
260 @see ConsoleApplication::invokeCatchingFailures()
261 */
262 static void fail (String errorMessage, int returnCode = 1);
263
264 /** Invokes a function, catching any fail() calls that it might trigger, and handling
265 them by printing their error message and returning their error code.
266 @see ConsoleApplication::fail()
267 */
268 static int invokeCatchingFailures (std::function<int()>&& functionToCall);
269
270 //==============================================================================
271 /** Looks for the first command in the list which matches the given arguments, and
272 tries to invoke it.
273
274 If no command is found, and if there is no default command to run, it fails with
275 a suitable error message.
276 If the command calls the fail() function, this will throw an exception that gets
277 automatically caught and handled, and this method will return the error code that
278 was passed into the fail() call.
279
280 If optionMustBeFirstArg is true, then only the first argument will be looked at
281 when searching the available commands - this lets you do 'git' style commands where
282 the executable name is followed by a verb.
283 */
285 bool optionMustBeFirstArg = false) const;
286
287 /** Creates an ArgumentList object from the argc and argv variablrs, and invokes
288 findAndRunCommand() using it.
289 */
290 int findAndRunCommand (int argc, char* argv[]) const;
291
292 /** Looks for the first command in the list which matches the given arguments.
293 If none is found, this returns either the default command (if one is set)
294 or nullptr.
295 If optionMustBeFirstArg is true, then only the first argument will be looked at
296 when searching the available commands - this lets you do 'git' style commands where
297 the executable name is followed by a verb.
298 */
299 const Command* findCommand (const ArgumentList&, bool optionMustBeFirstArg) const;
300
301 /** Gives read-only access to the list of registered commands. */
302 const std::vector<Command>& getCommands() const;
303
304private:
305 //==============================================================================
306 std::vector<Command> commands;
307 int commandIfNoOthersRecognised = -1;
308};
309
310} // namespace juce
311
312/** @}*/
Holds a resizable array of primitive or copy-by-value objects.
Definition juce_Array.h:60
Represents a local file or directory.
Definition juce_File.h:45
A special array for holding a list of strings.
A simple class for holding temporary references to a string literal or String.
The JUCE String class!
Definition juce_String.h:43
String argumentDescription
A description of the command-line arguments needed for this command, which will be printed as part of...
String commandOption
The option string that must appear in the argument list for this command to be invoked.
std::function< void(const ArgumentList &)> command
The actual command that should be invoked to perform this action.
String shortDescription
A short (one line) description of this command, which can be printed by ConsoleApplication::printComm...
String longDescription
A longer description of this command, for use in extended help.
Represents a command that can be executed if its command-line arguments are matched.
One of the arguments in an ArgumentList.
bool operator!=(StringRef stringToCompare) const
Compares this argument against a string.
File resolveAsExistingFile() const
Resolves this argument as an absolute File, using the current working directory as a base for resolvi...
String text
The original text of this argument.
bool isLongOption() const
Returns true if this argument starts with a double dash.
File resolveAsExistingFolder() const
Resolves a user-supplied folder name into an absolute File, using the current working directory as a ...
bool isShortOption() const
Returns true if this argument starts with a single dash.
File resolveAsFile() const
Resolves this argument as an absolute File, using the current working directory as a base for resolvi...
bool operator==(StringRef stringToCompare) const
Compares this argument against a string.
String getLongOptionValue() const
If this argument is a long option with a value, this returns the value.
bool isOption() const
Returns true if this argument starts with one or more dashes.
Holds a list of command-line arguments, and provides useful methods for searching and operating on th...
File getExistingFileForOption(StringRef option) const
Looks for a file argument using getFileForOption() and fails with a suitable error if the file doesn'...
File getExistingFolderForOption(StringRef option) const
Looks for a filename argument using getFileForOption() and fails with a suitable error if the file is...
int indexOfOption(StringRef option) const
Returns the index of the given string if it matches one of the arguments, or -1 if it doesn't.
String executableName
The name or path of the executable that was invoked, as it was specified on the command-line.
File getFileForOption(StringRef option) const
Looks for the value of argument using getValueForOption() and tries to parse that value as a file.
void failIfOptionIsMissing(StringRef option) const
Throws an error unless the given option is found in the argument list.
Array< Argument > arguments
The list of arguments (not including the name of the executable that was invoked).
bool containsOption(StringRef option) const
Returns true if the given string matches one of the arguments.
void checkMinNumArguments(int expectedMinNumberOfArgs) const
Throws an error unless there are at least the given number of arguments.
String getValueForOption(StringRef option) const
Looks for a given argument and returns either its assigned value (for long options) or the string tha...
Argument operator[](int index) const
Returns one of the arguments.
int size() const
Returns the number of arguments in the list.
Represents a the set of commands that a console app can perform, and provides helper functions for pe...
int findAndRunCommand(const ArgumentList &, bool optionMustBeFirstArg=false) const
Looks for the first command in the list which matches the given arguments, and tries to invoke it.
void addDefaultCommand(Command)
Adds a command to the list, and marks it as one which is invoked if no other command matches.
void printCommandList(const ArgumentList &) const
Prints out the list of commands and their short descriptions in a format that's suitable for use as h...
const Command * findCommand(const ArgumentList &, bool optionMustBeFirstArg) const
Looks for the first command in the list which matches the given arguments.
void addCommand(Command)
Adds a command to the list.
static int invokeCatchingFailures(std::function< int()> &&functionToCall)
Invokes a function, catching any fail() calls that it might trigger, and handling them by printing th...
void addHelpCommand(String helpArgument, String helpMessage, bool makeDefaultCommand)
Adds a help command to the list.
void addVersionCommand(String versionArgument, String versionText)
Adds a command that will print the given text in response to the "--version" option.
static void fail(String errorMessage, int returnCode=1)
Throws a failure exception to cause a command-line app to terminate.
const std::vector< Command > & getCommands() const
Gives read-only access to the list of registered commands.