Loading...
Searching...
No Matches
juce::ConsoleApplication Struct Reference

`#include <juce_ConsoleApplication.h>`

## Classes

struct | Command

## Public Member Functions

void | addCommand (Command)
void | addDefaultCommand (Command)
void | addVersionCommand (String versionArgument, String versionText)
void | addHelpCommand (String helpArgument, String helpMessage, bool makeDefaultCommand)
void | printCommandList (const ArgumentList &) const
void | printCommandDetails (const ArgumentList &, const Command &) const
int | findAndRunCommand (const ArgumentList &, bool optionMustBeFirstArg=false) const
int | findAndRunCommand (int argc, char *argv[]) const
const Command * | findCommand (const ArgumentList &, bool optionMustBeFirstArg) const
const std::vector< Command > & | getCommands () const

## Static Public Member Functions

static void | fail (String errorMessage, int returnCode=1)
static int | invokeCatchingFailures (std::function< int()> &&functionToCall)

## 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);
}
juce::ConsoleApplication
Definition juce_ConsoleApplication.h:237
juce::ConsoleApplication::findAndRunCommand
int findAndRunCommand(const ArgumentList &, bool optionMustBeFirstArg=false) const
Definition juce_ConsoleApplication.cpp:334
juce::ConsoleApplication::addCommand
void addCommand(Command)
Definition juce_ConsoleApplication.cpp:352
juce::ConsoleApplication::addHelpCommand
void addHelpCommand(String helpArgument, String helpMessage, bool makeDefaultCommand)
Definition juce_ConsoleApplication.cpp:363
juce::ConsoleApplication::addVersionCommand
void addVersionCommand(String versionArgument, String versionText)
Definition juce_ConsoleApplication.cpp:378

See also
  ArgumentList

Definition at line 236 of file juce_ConsoleApplication.h.

## Class Documentation

## juce::ConsoleApplication::Command

struct juce::ConsoleApplication::Command

Represents a command that can be executed if its command-line arguments are matched.

See also
  ConsoleApplication::addCommand(), ConsoleApplication::findAndRunCommand()

Definition at line 246 of file juce_ConsoleApplication.h.

Class Members
String | argumentDescription | A description of the command-line arguments needed for this command, which will be printed as part of the help text.
function< void(const ArgumentList &)> | command | The actual command that should be invoked to perform this action.
String | commandOption | 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 | longDescription | A longer description of this command, for use in extended help.
String | shortDescription | A short (one line) description of this command, which can be printed by ConsoleApplication::printCommandList().

## Member Function Documentation

## addCommand()

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

Adds a command to the list.

Definition at line 352 of file juce_ConsoleApplication.cpp.

Referenced by addDefaultCommand(), addHelpCommand(), and addVersionCommand().

## addDefaultCommand()

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

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

Definition at line 357 of file juce_ConsoleApplication.cpp.

Referenced by addHelpCommand().

## addHelpCommand()

void juce::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.

Definition at line 363 of file juce_ConsoleApplication.cpp.

## addVersionCommand()

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

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

Definition at line 378 of file juce_ConsoleApplication.cpp.

## fail()

void juce::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()

Definition at line 296 of file juce_ConsoleApplication.cpp.

Referenced by juce::ArgumentList::checkMinNumArguments(), juce::ArgumentList::failIfOptionIsMissing(), findAndRunCommand(), and juce::ArgumentList::Argument::resolveAsExistingFolder().

## findAndRunCommand() [1/2]

int juce::ConsoleApplication::findAndRunCommand | ( | const ArgumentList & | args,
|  | 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.

Definition at line 334 of file juce_ConsoleApplication.cpp.

Referenced by findAndRunCommand().

## findAndRunCommand() [2/2]

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

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

Definition at line 347 of file juce_ConsoleApplication.cpp.

## findCommand()

const ConsoleApplication::Command * juce::ConsoleApplication::findCommand | ( | const ArgumentList & | args,
|  | 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.

Definition at line 318 of file juce_ConsoleApplication.cpp.

Referenced by findAndRunCommand().

## getCommands()

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

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

Definition at line 387 of file juce_ConsoleApplication.cpp.

## invokeCatchingFailures()

int juce::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()

Definition at line 301 of file juce_ConsoleApplication.cpp.

Referenced by findAndRunCommand().

## printCommandDetails()

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

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

Definition at line 428 of file juce_ConsoleApplication.cpp.

## printCommandList()

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

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

Definition at line 413 of file juce_ConsoleApplication.cpp.

Referenced by addHelpCommand().

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

- juce_ConsoleApplication.h
- juce_ConsoleApplication.cpp