/* ============================================================================== This file is part of the JUCE library. Copyright (c) 2017 - ROLI Ltd. JUCE is an open source library subject to commercial or open-source licensing. The code included in this file is provided under the terms of the ISC license http://www.isc.org/downloads/software-support-policy/isc-license. Permission To use, copy, modify, and/or distribute this software for any purpose with or without fee is hereby granted provided that the above copyright notice and this permission notice appear in all copies. JUCE IS PROVIDED "AS IS" WITHOUT ANY WARRANTY, AND ALL WARRANTIES, WHETHER EXPRESSED OR IMPLIED, INCLUDING MERCHANTABILITY AND FITNESS FOR PURPOSE, ARE DISCLAIMED. ============================================================================== */ namespace juce { //============================================================================== /** Holds a list of command-line arguments, and provides useful methods for searching and operating on them. You can create an ArgumentList manually, or give it some argv/argc values from a main() function to parse. @see ConsoleApplication */ struct ArgumentList { /** Creates an argument list for a given executable. */ ArgumentList (String executable, StringArray arguments); /** Parses a standard argv/argc pair to create an argument list. */ ArgumentList (int argc, char* argv[]); /** Tokenises a string containing all the arguments to create an argument list. */ ArgumentList (const String& executable, const String& arguments); ArgumentList (const ArgumentList&) = default; ArgumentList& operator= (const ArgumentList&) = default; //============================================================================== /** One of the arguments in an ArgumentList. */ struct Argument { /** The original text of this argument. */ String text; /** Resolves this argument as an absolute File, using the current working directory as a base for resolving relative paths, and stripping quotes, etc. */ File resolveAsFile() const; /** Resolves this argument as an absolute File, using the current working directory as a base for resolving relative paths, and also doing a check to make sure the file exists. If the file doesn't exist, this will call fail() with a suitable error. @see resolveAsFile, resolveAsExistingFolder */ File resolveAsExistingFile() const; /** Resolves a user-supplied folder name into an absolute File, using the current working directory as a base for resolving relative paths, and also doing a check to make sure the folder exists. If the folder doesn't exist, this will call fail() with a suitable error. @see resolveAsFile, resolveAsExistingFile */ File resolveAsExistingFolder() const; /** Returns true if this argument starts with a double dash. */ bool isLongOption() const; /** Returns true if this argument starts with a single dash. */ bool isShortOption() const; /** Returns true if this argument starts with a double dash, followed by the given string. */ bool isLongOption (const String& optionRoot) const; /** If this argument is a long option with a value, this returns the value. e.g. for "--foo=bar", this would return 'bar'. */ String getLongOptionValue() const; /** Returns true if this argument starts with a single dash and then contains the given character somewhere inside it. */ bool isShortOption (char shortOptionCharacter) const; /** Returns true if this argument starts with one or more dashes. */ bool isOption() const; /** Compares this argument against a string. The string may be a pipe-separated list of options, e.g. "--help|-h" */ bool operator== (StringRef stringToCompare) const; /** Compares this argument against a string. The string may be a pipe-separated list of options, e.g. "--help|-h" */ bool operator!= (StringRef stringToCompare) const; }; //============================================================================== /** Returns the number of arguments in the list. */ int size() const; /** Returns one of the arguments */ Argument operator[] (int index) const; /** Throws an error unless there are at least the given number of arguments. */ void checkMinNumArguments (int expectedMinNumberOfArgs) const; /** Returns true if the given string matches one of the arguments. The option can also be a list of different versions separated by pipes, e.g. "--help|-h" */ bool containsOption (StringRef option) const; /** Returns the index of the given string if it matches one of the arguments, or -1 if it doesn't. The option can also be a list of different versions separated by pipes, e.g. "--help|-h" */ int indexOfOption (StringRef option) const; /** Throws an error unless the given option is found in the argument list. */ void failIfOptionIsMissing (StringRef option) const; /** Looks for a given argument and returns either its assigned value (for long options) or the string that follows it (for short options). The option can also be a list of different versions separated by pipes, e.g. "--help|-h" If it finds a long option, it will look for an assignment with a '=' sign, e.g. "--file=foo.txt", and will return the string following the '='. If there's no '=', it will return an empty string. If it finds a short option, it will attempt to return the argument that follows it, unless it's another option. If the argument isn't found, this returns an empty string. */ String getValueForOption (StringRef option) const; /** Looks for the value of argument using getValueForOption() and tries to parse that value as a file. If the option isn't found, or if the value can't be parsed as a filename, it will throw an error. */ File getFileForOption (StringRef option) const; /** Looks for a file argument using getFileForOption() and fails with a suitable error if the file doesn't exist. */ File getExistingFileForOption (StringRef option) const; /** Looks for a filename argument using getFileForOption() and fails with a suitable error if the file isn't a folder that exists. */ File getExistingFolderForOption (StringRef option) const; /** The name or path of the executable that was invoked, as it was specified on the command-line. */ String executableName; /** The list of arguments (not including the name of the executable that was invoked). */ Array arguments; }; //============================================================================== /** Represents a the set of commands that a console app can perform, and provides helper functions for performing them. When using these helper classes to implement a console app, you probably want to do something along these lines: @code int main (int argc, char* argv[]) { ConsoleApplication app; app.addHelpCommand ("--help|-h", "Usage:", true); app.addVersionCommand ("--version|-v", "MyApp version 1.2.3"); app.addCommand ({ "--foo", "--foo filename", "Performs a foo operation on the given file", [] (const auto& args) { doFoo (args); }}); return app.findAndRunCommand (argc, argv); } @endcode @see ArgumentList */ struct ConsoleApplication { //============================================================================== /** Represents a command that can be executed if its command-line arguments are matched. @see ConsoleApplication::addCommand(), ConsoleApplication::findAndRunCommand() */ struct Command { /** The option string that must appear in the argument list for this command to be invoked. This can also be a list of different versions separated by pipes, e.g. "--help|-h" */ String commandOption; /** A description of the command-line arguments needed for this command, which will be printed as part of the help text. */ String argumentDescription; /** A short (one line) description of this command, which can be printed by ConsoleApplication::printCommandList(). */ String shortDescription; /** A longer description of this command, for use in extended help. */ String longDescription; /** The actual command that should be invoked to perform this action. */ std::function command; }; //============================================================================== /** Adds a command to the list. */ void addCommand (Command); /** Adds a command to the list, and marks it as one which is invoked if no other command matches. */ void addDefaultCommand (Command); /** Adds a command that will print the given text in response to the "--version" option. */ void addVersionCommand (String versionArgument, String versionText); /** Adds a help command to the list. This command will print the user-supplied message that's passed in here as an argument, followed by a list of all the registered commands. */ void addHelpCommand (String helpArgument, String helpMessage, bool makeDefaultCommand); /** Prints out the list of commands and their short descriptions in a format that's suitable for use as help. */ void printCommandList (const ArgumentList&) const; //============================================================================== /** Throws a failure exception to cause a command-line app to terminate. This is intended to be called from code in a Command, so that the exception will be automatically caught and turned into a printed error message and a return code which will be returned from main(). @see ConsoleApplication::invokeCatchingFailures() */ static void fail (String errorMessage, int returnCode = 1); /** Invokes a function, catching any fail() calls that it might trigger, and handling them by printing their error message and returning their error code. @see ConsoleApplication::fail() */ static int invokeCatchingFailures (std::function&& functionToCall); //============================================================================== /** Looks for the first command in the list which matches the given arguments, and tries to invoke it. If no command is found, and if there is no default command to run, it fails with a suitable error message. If the command calls the fail() function, this will throw an exception that gets automatically caught and handled, and this method will return the error code that was passed into the fail() call. If optionMustBeFirstArg is true, then only the first argument will be looked at when searching the available commands - this lets you do 'git' style commands where the executable name is followed by a verb. */ int findAndRunCommand (const ArgumentList&, bool optionMustBeFirstArg = false) const; /** Creates an ArgumentList object from the argc and argv variablrs, and invokes findAndRunCommand() using it. */ int findAndRunCommand (int argc, char* argv[]) const; /** Looks for the first command in the list which matches the given arguments. If none is found, this returns either the default command (if one is set) or nullptr. If optionMustBeFirstArg is true, then only the first argument will be looked at when searching the available commands - this lets you do 'git' style commands where the executable name is followed by a verb. */ const Command* findCommand (const ArgumentList&, bool optionMustBeFirstArg) const; /** Gives read-only access to the list of registered commands. */ const std::vector& getCommands() const; private: //============================================================================== std::vector commands; int commandIfNoOthersRecognised = -1; }; } // namespace juce