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 
27 namespace 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  */
100  String getLongOptionValue() const;
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  */
182  File getExistingFileForOption (StringRef option) const;
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  */
281  void addDefaultCommand (Command);
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  */
331  int findAndRunCommand (const ArgumentList&,
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 
351 private:
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
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.
String argumentDescription
A description of the command-line arguments needed for this command, which will be printed as part of...
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...
String commandOption
The option string that must appear in the argument list for this command to be invoked.
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.
std::function< void(const ArgumentList &)> command
The actual command that should be invoked to perform this action.
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.
String shortDescription
A short (one line) description of this command, which can be printed by ConsoleApplication::printComm...
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.
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.