OpenShot Library | OpenShotAudio 0.2.2
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
40 @tags{Core}
41*/
43{
44 /** Creates an argument list for a given executable. */
46
47 /** Parses a standard argv/argc pair to create an argument list. */
48 ArgumentList (int argc, char* argv[]);
49
50 /** Tokenises a string containing all the arguments to create an argument list. */
51 ArgumentList (const String& executable, const String& arguments);
52
53 ArgumentList (const ArgumentList&) = default;
54 ArgumentList& operator= (const ArgumentList&) = default;
55
56 //==============================================================================
57 /**
58 One of the arguments in an ArgumentList.
59
60 @tags{Core}
61 */
62 struct Argument
63 {
64 /** The original text of this argument. */
66
67 /** Resolves this argument as an absolute File, using the current working
68 directory as a base for resolving relative paths, and stripping quotes, etc.
69 */
70 File resolveAsFile() const;
71
72 /** Resolves this argument as an absolute File, using the current working
73 directory as a base for resolving relative paths, and also doing a check to
74 make sure the file exists.
75 If the file doesn't exist, this will call fail() with a suitable error.
76 @see resolveAsFile, resolveAsExistingFolder
77 */
79
80 /** Resolves a user-supplied folder name into an absolute File, using the current working
81 directory as a base for resolving relative paths, and also doing a check to make
82 sure the folder exists.
83 If the folder doesn't exist, this will call fail() with a suitable error.
84 @see resolveAsFile, resolveAsExistingFile
85 */
87
88 /** Returns true if this argument starts with a double dash. */
89 bool isLongOption() const;
90
91 /** Returns true if this argument starts with a single dash. */
92 bool isShortOption() const;
93
94 /** Returns true if this argument starts with a double dash, followed by the given string. */
95 bool isLongOption (const String& optionRoot) const;
96
97 /** If this argument is a long option with a value, this returns the value.
98 e.g. for "--foo=bar", this would return 'bar'.
99 */
101
102 /** Returns true if this argument starts with a single dash and then contains the given character somewhere inside it. */
103 bool isShortOption (char shortOptionCharacter) const;
104
105 /** Returns true if this argument starts with one or more dashes. */
106 bool isOption() const;
107
108 /** Compares this argument against a string.
109 The string may be a pipe-separated list of options, e.g. "--help|-h"
110 */
111 bool operator== (StringRef stringToCompare) const;
112
113 /** Compares this argument against a string.
114 The string may be a pipe-separated list of options, e.g. "--help|-h"
115 */
116 bool operator!= (StringRef stringToCompare) const;
117 };
118
119 //==============================================================================
120 /** Returns the number of arguments in the list. */
121 int size() const;
122
123 /** Returns one of the arguments */
124 Argument operator[] (int index) const;
125
126 /** Throws an error unless there are at least the given number of arguments. */
127 void checkMinNumArguments (int expectedMinNumberOfArgs) const;
128
129 /** Returns true if the given string matches one of the arguments.
130 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
131 @see removeOptionIfFound
132 */
133 bool containsOption (StringRef option) const;
134
135 /** Returns true if the given string matches one of the arguments, and also removes the
136 argument from the list if found.
137 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
138 @see containsOption
139 */
140 bool removeOptionIfFound (StringRef option);
141
142 /** Returns the index of the given string if it matches one of the arguments, or -1 if it doesn't.
143 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
144 */
145 int indexOfOption (StringRef option) const;
146
147 /** Throws an error unless the given option is found in the argument list. */
148 void failIfOptionIsMissing (StringRef option) const;
149
150 /** Looks for a given argument and returns either its assigned value (for long options) or the
151 string that follows it (for short options).
152 The option can also be a list of different versions separated by pipes, e.g. "--help|-h"
153 If it finds a long option, it will look for an assignment with a '=' sign, e.g. "--file=foo.txt",
154 and will return the string following the '='. If there's no '=', it will return an empty string.
155 If it finds a short option, it will attempt to return the argument that follows it, unless
156 it's another option.
157 If the argument isn't found, this returns an empty string.
158 */
159 String getValueForOption (StringRef option) const;
160
161 /** Looks for a given argument and returns either its assigned value (for long options) or the
162 string that follows it (for short options).
163 This works like getValueForOption() but also removes the option argument (and any value arguments)
164 from the list if they are found.
165 */
167
168 /** Looks for the value of argument using getValueForOption() and tries to parse that value as a file.
169 If the option isn't found, or if the value can't be parsed as a filename, it will throw an error.
170 */
171 File getFileForOption (StringRef option) const;
172
173 /** Looks for the value of argument using getValueForOption() and tries to parse that value as a file.
174 This works like getFileForOption() but also removes the option argument (and any value arguments)
175 from the list if they are found.
176 */
178
179 /** Looks for a file argument using getFileForOption() and fails with a suitable error if
180 the file doesn't exist.
181 */
183
184 /** Looks for a file argument using getFileForOption() and fails with a suitable error if
185 the file doesn't exist.
186 This works like getExistingFileForOption() but also removes the option argument (and any
187 value arguments) from the list if they are found.
188 */
190
191 /** Looks for a filename argument using getFileForOption() and fails with a suitable error if
192 the file isn't a folder that exists.
193 */
195
196 /** Looks for a filename argument using getFileForOption() and fails with a suitable error if
197 the file isn't a folder that exists.
198 This works like getExistingFolderForOption() but also removes the option argument (and any
199 value arguments) from the list if they are found.
200 */
202
203 /** The name or path of the executable that was invoked, as it was specified on the command-line. */
205
206 /** The list of arguments (not including the name of the executable that was invoked). */
208};
209
210
211//==============================================================================
212/**
213 Represents a the set of commands that a console app can perform, and provides
214 helper functions for performing them.
215
216 When using these helper classes to implement a console app, you probably want to
217 do something along these lines:
218
219 @code
220 int main (int argc, char* argv[])
221 {
222 ConsoleApplication app;
223
224 app.addHelpCommand ("--help|-h", "Usage:", true);
225 app.addVersionCommand ("--version|-v", "MyApp version 1.2.3");
226
227 app.addCommand ({ "--foo",
228 "--foo filename",
229 "Performs a foo operation on the given file",
230 [] (const auto& args) { doFoo (args); }});
231
232 return app.findAndRunCommand (argc, argv);
233 }
234 @endcode
235
236 @see ArgumentList
237
238 @tags{Core}
239*/
241{
242 //==============================================================================
243 /**
244 Represents a command that can be executed if its command-line arguments are matched.
245
246 @see ConsoleApplication::addCommand(), ConsoleApplication::findAndRunCommand()
247
248 @tags{Core}
249 */
250 struct Command
251 {
252 /** The option string that must appear in the argument list for this command to be invoked.
253 This can also be a list of different versions separated by pipes, e.g. "--help|-h"
254 */
256
257 /** A description of the command-line arguments needed for this command, which will be
258 printed as part of the help text.
259 */
261
262 /** A short (one line) description of this command, which can be printed by
263 ConsoleApplication::printCommandList().
264 */
266
267 /** A longer description of this command, for use in extended help. */
269
270 /** The actual command that should be invoked to perform this action. */
271 std::function<void(const ArgumentList&)> command;
272 };
273
274 //==============================================================================
275 /** Adds a command to the list. */
276 void addCommand (Command);
277
278 /** Adds a command to the list, and marks it as one which is invoked if no other
279 command matches.
280 */
282
283 /** Adds a command that will print the given text in response to the "--version" option. */
284 void addVersionCommand (String versionArgument, String versionText);
285
286 /** Adds a help command to the list.
287 This command will print the user-supplied message that's passed in here as an
288 argument, followed by a list of all the registered commands.
289 */
290 void addHelpCommand (String helpArgument, String helpMessage, bool makeDefaultCommand);
291
292 /** Prints out the list of commands and their short descriptions in a format that's
293 suitable for use as help.
294 */
295 void printCommandList (const ArgumentList&) const;
296
297 /** Prints out a longer description of a particular command, based on its
298 longDescription member.
299 */
300 void printCommandDetails (const ArgumentList&, const Command&) const;
301
302 //==============================================================================
303 /** Throws a failure exception to cause a command-line app to terminate.
304 This is intended to be called from code in a Command, so that the
305 exception will be automatically caught and turned into a printed error message
306 and a return code which will be returned from main().
307 @see ConsoleApplication::invokeCatchingFailures()
308 */
309 static void fail (String errorMessage, int returnCode = 1);
310
311 /** Invokes a function, catching any fail() calls that it might trigger, and handling
312 them by printing their error message and returning their error code.
313 @see ConsoleApplication::fail()
314 */
315 static int invokeCatchingFailures (std::function<int()>&& functionToCall);
316
317 //==============================================================================
318 /** Looks for the first command in the list which matches the given arguments, and
319 tries to invoke it.
320
321 If no command is found, and if there is no default command to run, it fails with
322 a suitable error message.
323 If the command calls the fail() function, this will throw an exception that gets
324 automatically caught and handled, and this method will return the error code that
325 was passed into the fail() call.
326
327 If optionMustBeFirstArg is true, then only the first argument will be looked at
328 when searching the available commands - this lets you do 'git' style commands where
329 the executable name is followed by a verb.
330 */
332 bool optionMustBeFirstArg = false) const;
333
334 /** Creates an ArgumentList object from the argc and argv variablrs, and invokes
335 findAndRunCommand() using it.
336 */
337 int findAndRunCommand (int argc, char* argv[]) const;
338
339 /** Looks for the first command in the list which matches the given arguments.
340 If none is found, this returns either the default command (if one is set)
341 or nullptr.
342 If optionMustBeFirstArg is true, then only the first argument will be looked at
343 when searching the available commands - this lets you do 'git' style commands where
344 the executable name is followed by a verb.
345 */
346 const Command* findCommand (const ArgumentList&, bool optionMustBeFirstArg) const;
347
348 /** Gives read-only access to the list of registered commands. */
349 const std::vector<Command>& getCommands() const;
350
351private:
352 //==============================================================================
353 std::vector<Command> commands;
354 int commandIfNoOthersRecognised = -1;
355};
356
357} // namespace juce
358
359/** @}*/
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 getExistingFileForOptionAndRemove(StringRef option)
Looks for a file argument using getFileForOption() and fails with a suitable error if the file doesn'...
String removeValueForOption(StringRef option)
Looks for a given argument and returns either its assigned value (for long options) or the string tha...
File getExistingFileForOption(StringRef option) const
Looks for a file argument using getFileForOption() and fails with a suitable error if the file doesn'...
bool removeOptionIfFound(StringRef option)
Returns true if the given string matches one of the arguments, and also removes the argument from the...
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.
ArgumentList(String executable, StringArray arguments)
Creates an argument list for a given executable.
File getFileForOptionAndRemove(StringRef option)
Looks for the value of argument using getValueForOption() and tries to parse that value as a file.
File getExistingFolderForOptionAndRemove(StringRef option)
Looks for a filename argument using getFileForOption() and fails with a suitable error if the file is...
Represents a the set of commands that a console app can perform, and provides helper functions for pe...
void printCommandDetails(const ArgumentList &, const Command &) const
Prints out a longer description of a particular command, based on its longDescription member.
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.