OpenShot Library | libopenshot-audio  0.1.9
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 */
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. */
49  ArgumentList (const String& executable, const String& arguments);
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  */
96  String getLongOptionValue() const;
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  */
107  bool operator== (StringRef stringToCompare) const;
108 
109  /** Compares this argument against a string.
110  The string may be a pipe-separated list of options, e.g. "--help|-h"
111  */
112  bool operator!= (StringRef stringToCompare) const;
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. */
123  void checkMinNumArguments (int expectedMinNumberOfArgs) const;
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. */
136  void failIfOptionIsMissing (StringRef option) const;
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  */
147  String getValueForOption (StringRef option) const;
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  */
154  File getFileForOption (StringRef option) const;
155 
156  /** Looks for a file argument using getFileForOption() and fails with a suitable error if
157  the file doesn't exist.
158  */
159  File getExistingFileForOption (StringRef option) const;
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  */
239  void addDefaultCommand (Command);
240 
241  /** Adds a command that will print the given text in response to the "--version" option. */
242  void addVersionCommand (String versionArgument, String versionText);
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  */
248  void addHelpCommand (String helpArgument, String helpMessage, bool makeDefaultCommand);
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  */
284  int findAndRunCommand (const ArgumentList&,
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 
304 private:
305  //==============================================================================
306  std::vector<Command> commands;
307  int commandIfNoOthersRecognised = -1;
308 };
309 
310 } // namespace juce
311 
312 /** @}*/
Array< Argument > arguments
The list of arguments (not including the name of the executable that was invoked).
String getLongOptionValue() const
If this argument is a long option with a value, this returns the value.
ArgumentList(String executable, StringArray arguments)
Creates an argument list for a given executable.
bool isShortOption() const
Returns true if this argument starts with a single dash.
bool isOption() const
Returns true if this argument starts with one or more dashes.
String text
The original text of this argument.
String getValueForOption(StringRef option) const
Looks for a given argument and returns either its assigned value (for long options) or the string tha...
A simple class for holding temporary references to a string literal or String.
int indexOfOption(StringRef option) const
Returns the index of the given string if it matches one of the arguments, or -1 if it doesn&#39;t...
Holds a list of command-line arguments, and provides useful methods for searching and operating on th...
File getFileForOption(StringRef option) const
Looks for the value of argument using getValueForOption() and tries to parse that value as a file...
String shortDescription
A short (one line) description of this command, which can be printed by ConsoleApplication::printComm...
A special array for holding a list of strings.
The JUCE String class!
Definition: juce_String.h:42
String commandOption
The option string that must appear in the argument list for this command to be invoked.
String argumentDescription
A description of the command-line arguments needed for this command, which will be printed as part of...
Represents a command that can be executed if its command-line arguments are matched.
Argument operator[](int index) const
Returns one of the arguments.
bool operator!=(StringRef stringToCompare) const
Compares this argument against a string.
File resolveAsExistingFolder() const
Resolves a user-supplied folder name into an absolute File, using the current working directory as a ...
One of the arguments in an ArgumentList.
Represents a local file or directory.
Definition: juce_File.h:44
Holds a resizable array of primitive or copy-by-value objects.
Definition: juce_Array.h:59
File resolveAsFile() const
Resolves this argument as an absolute File, using the current working directory as a base for resolvi...
File resolveAsExistingFile() const
Resolves this argument as an absolute File, using the current working directory as a base for resolvi...
File getExistingFileForOption(StringRef option) const
Looks for a file argument using getFileForOption() and fails with a suitable error if the file doesn&#39;...
void checkMinNumArguments(int expectedMinNumberOfArgs) const
Throws an error unless there are at least the given number of arguments.
String executableName
The name or path of the executable that was invoked, as it was specified on the command-line.
bool operator==(StringRef stringToCompare) const
Compares this argument against a string.
void failIfOptionIsMissing(StringRef option) const
Throws an error unless the given option is found in the argument list.
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...
bool isLongOption() const
Returns true if this argument starts with a double dash.
File getExistingFolderForOption(StringRef option) const
Looks for a filename argument using getFileForOption() and fails with a suitable error if the file is...
String longDescription
A longer description of this command, for use in extended help.
std::function< void(const ArgumentList &)> command
The actual command that should be invoked to perform this action.
bool containsOption(StringRef option) const
Returns true if the given string matches one of the arguments.