JUCE: ConsoleApplication Struct Reference

JUCE

Classes | Public Member Functions | Static Public Member Functions | List of all members
ConsoleApplication Struct Reference
juce_core » misc

Represents a the set of commands that a console app can perform, and provides helper functions for performing them. More...

`#include <juce_ConsoleApplication.h>`

## Classes
struct | Command
| Represents a command that can be executed if its command-line arguments are matched. More...

## Public Member Functions
void | addCommand (Command)
| Adds a command to the list. More...
void | addDefaultCommand (Command)
| Adds a command to the list, and marks it as one which is invoked if no other command matches. More...
void | addVersionCommand (String versionArgument, String versionText)
| Adds a command that will print the given text in response to the "--version" option. More...
void | addHelpCommand (String helpArgument, String helpMessage, bool makeDefaultCommand)
| Adds a help command to the list. More...
void | printCommandList (const ArgumentList &) const
| Prints out the list of commands and their short descriptions in a format that's suitable for use as help. More...
void | printCommandDetails (const ArgumentList &, const Command &) const
| Prints out a longer description of a particular command, based on its longDescription member. More...
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. More...
int | findAndRunCommand (int argc, char *argv[]) const
| Creates an ArgumentList object from the argc and argv variablrs, and invokes findAndRunCommand() using it. More...
const Command * | findCommand (const ArgumentList &, bool optionMustBeFirstArg) const
| Looks for the first command in the list which matches the given arguments. More...
const std::vector< Command > & | getCommands () const
| Gives read-only access to the list of registered commands. More...

## Static Public Member Functions
static void | fail (String errorMessage, int returnCode=1)
| Throws a failure exception to cause a command-line app to terminate. More...
static int | invokeCatchingFailures (std::function< int()> &&functionToCall)
| Invokes a function, catching any fail() calls that it might trigger, and handling them by printing their error message and returning their error code. More...

## Detailed Description

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:

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);
}
ConsoleApplication
Represents a the set of commands that a console app can perform, and provides helper functions for pe...
Definition: juce_ConsoleApplication.h:238
ConsoleApplication::findAndRunCommand
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.
ConsoleApplication::addCommand
void addCommand(Command)
Adds a command to the list.
ConsoleApplication::addVersionCommand
void addVersionCommand(String versionArgument, String versionText)
Adds a command that will print the given text in response to the "--version" option.
ConsoleApplication::addHelpCommand
void addHelpCommand(String helpArgument, String helpMessage, bool makeDefaultCommand)
Adds a help command to the list.

See also
  ArgumentList

## Member Function Documentation

## ◆ addCommand()

void ConsoleApplication::addCommand | ( | Command |  | ) |

Adds a command to the list.

## ◆ addDefaultCommand()

void ConsoleApplication::addDefaultCommand | ( | Command |  | ) |

Adds a command to the list, and marks it as one which is invoked if no other command matches.

## ◆ addVersionCommand()

void ConsoleApplication::addVersionCommand | ( | String | versionArgument,
|  | String | versionText
| ) |  |

Adds a command that will print the given text in response to the "--version" option.

## ◆ addHelpCommand()

void ConsoleApplication::addHelpCommand | ( | String | helpArgument,
|  | String | helpMessage,
|  | bool | makeDefaultCommand
| ) |  |

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.

## ◆ printCommandList()

void ConsoleApplication::printCommandList | ( | const ArgumentList & |  | ) | const

Prints out the list of commands and their short descriptions in a format that's suitable for use as help.

## ◆ printCommandDetails()

void ConsoleApplication::printCommandDetails | ( | const ArgumentList & | ,
|  | const Command & |
| ) |  | const

Prints out a longer description of a particular command, based on its longDescription member.

## ◆ fail()

static void ConsoleApplication::fail | ( | String | errorMessage,
|  | int | returnCode = `1`
| ) |  |
| static

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 also
  ConsoleApplication::invokeCatchingFailures()

## ◆ invokeCatchingFailures()

static int ConsoleApplication::invokeCatchingFailures | ( | std::function< int()> && | functionToCall | ) |
| static

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 also
  ConsoleApplication::fail()

## ◆ findAndRunCommand() [1/2]

int ConsoleApplication::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.

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.

## ◆ findAndRunCommand() [2/2]

int ConsoleApplication::findAndRunCommand | ( | int | argc,
|  | char * | argv[]
| ) |  | const

Creates an ArgumentList object from the argc and argv variablrs, and invokes findAndRunCommand() using it.

## ◆ findCommand()

const Command * ConsoleApplication::findCommand | ( | const ArgumentList & | ,
|  | bool | optionMustBeFirstArg
| ) |  | 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.

## ◆ getCommands()

const std::vector< Command > & ConsoleApplication::getCommands | ( |  | ) | const

Gives read-only access to the list of registered commands.

The documentation for this struct was generated from the following file:

- juce_ConsoleApplication.h