A basic command line interpreter. More...

#include <tsCommandLine.h>

Inheritance diagram for ts::CommandLine:

Public Member Functions
	CommandLine (Report &report=(ts::CerrReport::Instance()))
	Constructor.

void	addPredefinedCommands ()
	Add the predefined commands help, quit and exit.

bool	analyzeCommand (const UString &command)
	Analyze a command line.

bool	analyzeCommand (const UString &name, const UStringVector &arguments)
	Analyze a command line.

Args *	command (const UString &name, const UString &description=UString(), const UString &syntax=UString(), int flags=0)
	Add the definition of a command to the interpreter, without command handler.

template<class HANDLER > requires std::derived_from<HANDLER, CommandLineHandler>
Args *	command (HANDLER handler, CommandStatus(HANDLER::method)(const UString &, Args &), const UString &name, const UString &description=UString(), const UString &syntax=UString(), int flags=0)
	Add the definition of a command to the interpreter.

UString	getAllHelpText (Args::HelpFormat format, size_t line_width=79) const
	Get a formatted help text for all commands.

CommandStatus	processCommand (const UString &line, Report *redirect=nullptr)
	Analyze and process a command line.

CommandStatus	processCommand (const UString &name, const UStringVector &arguments, Report *redirect=nullptr)
	Analyze and process a command line.

CommandStatus	processCommandFile (const UString &file_name, bool exit_on_error=false, Report *redirect=nullptr)
	Analyze and process all commands from a text file.

CommandStatus	processCommandFiles (const UStringVector &file_names, bool exit_on_error=false, Report *redirect=nullptr)
	Analyze and process all commands from several text files.

CommandStatus	processCommands (UStringVector &lines, bool exit_on_error=false, Report *redirect=nullptr)
	Analyze and process all commands from a vector of text lines.

CommandStatus	processInteractive (bool exit_on_error, Report *redirect=nullptr)
	Analyze and process all commands from an interactive session.

CommandStatus	processInteractive (const UString &prompt=EditLine::DefaultPrompt(), const UString &next_prompt=EditLine::DefaultNextPrompt(), const UString &history_file=EditLine::DefaultHistoryFile(), size_t history_size=EditLine::DefaultHistorySize(), bool exit_on_error=false, Report *redirect=nullptr)
	Analyze and process all commands from an interactive session.

bool	processRedirections (bool on)
	Set command line redirection from files.

template<class HANDLER > requires std::derived_from<HANDLER, CommandLineHandler>
void	setCommandLineHandler (HANDLER handler, CommandStatus(HANDLER::method)(const UString &, Args &), const UString &name=UString())
	Set a new command line handler for one or all commands.

void	setShell (const UString &shell)
	Set the "shell" string for all commands.

Detailed Description

A basic command line interpreter.

Constructor & Destructor Documentation

◆ CommandLine()

ts::CommandLine::CommandLine ( Report & report = (ts::CerrReport::Instance()) )

Constructor.

Parameters

[in,out] report Reference to a report where all messages are displayed. The reference must remain valid as long as this object exists.

Member Function Documentation

◆ setShell()

void ts::CommandLine::setShell ( const UString & shell )

Set the "shell" string for all commands.

Parameters

[in] shell Shell name string.

See also: Args::setShell()

◆ command() [1/2]

Args * ts::CommandLine::command	(	const UString &	name,
		const UString &	description = `UString()`,
		const UString &	syntax = `UString()`,
		int	flags = `0`
	)

inline

Add the definition of a command to the interpreter, without command handler.

Parameters

[in]	name	Command name.
[in]	description	A short one-line description of the command.
[in]	syntax	A short one-line syntax summary, eg. "[options] filename ...".
[in]	flags	An or'ed mask of Args::Flags values.

Returns: A pointer to the Args for this command. The application will typically add options to this Args.

See also: Args::Flags; Args::Args()

◆ command() [2/2]

template<class HANDLER >
requires std::derived_from<HANDLER, CommandLineHandler>

Args * ts::CommandLine::command	(	HANDLER *	handler,
		CommandStatus(HANDLER::*)(const UString &, Args &)	method,
		const UString &	name,
		const UString &	description = `UString()`,
		const UString &	syntax = `UString()`,
		int	flags = `0`
	)

inline

Add the definition of a command to the interpreter.

Template Parameters

HANDLER A subclass of CommandLineHandler.

Parameters

[in]	handler	Command handler object. A null pointer is allowed (unhandled command).
[in]	method	Command handler method. A null pointer is allowed (unhandled command).
[in]	name	Command name.
[in]	description	A short one-line description of the command.
[in]	syntax	A short one-line syntax summary, eg. "[options] filename ...".
[in]	flags	An or'ed mask of Args::Flags values.

Returns: A pointer to the Args for this command. The application will typically add options to this Args.

See also: Args::Flags; Args::Args()

◆ setCommandLineHandler()

template<class HANDLER >
requires std::derived_from<HANDLER, CommandLineHandler>

void ts::CommandLine::setCommandLineHandler	(	HANDLER *	handler,
		CommandStatus(HANDLER::*)(const UString &, Args &)	method,
		const UString &	name = `UString()`
	)

inline

Set a new command line handler for one or all commands.

Template Parameters

HANDLER A subclass of CommandLineHandler.

Parameters

[in]	handler	Command handler object. A null pointer is allowed (unhandled command).
[in]	method	Command handler method. A null pointer is allowed (unhandled command).
[in]	name	Command name. If empty (the default), handler is set on all commands.

◆ addPredefinedCommands()

void ts::CommandLine::addPredefinedCommands ( )

Add the predefined commands help, quit and exit.

Useful for interactive interpreters.

◆ processRedirections()

bool ts::CommandLine::processRedirections ( bool on )

Set command line redirection from files.

Parameters

[in] on If true, process command line arguments redirection. All lines with the form '@filename' are replaced by the content The initial default is false.

Returns: The previous state of the redirections.

◆ analyzeCommand() [1/2]

bool ts::CommandLine::analyzeCommand ( const UString & command )

Analyze a command line.

Parameters

[in] command Full command line, with command name and parameters. Parameters are separated with spaces. Special characters and spaces must be escaped or quoted in the parameters.

Returns: True if the command is correct, false otherwise.

◆ analyzeCommand() [2/2]

bool ts::CommandLine::analyzeCommand	(	const UString &	name,
		const UStringVector &	arguments
	)

Analyze a command line.

Parameters

[in]	name	Command name.
[in]	arguments	Arguments from command line.

Returns: True if the command is correct, false otherwise.

◆ processCommand() [1/2]

CommandStatus ts::CommandLine::processCommand	(	const UString &	line,
		Report *	redirect = `nullptr`
	)

Analyze and process a command line.

Parameters

[in]	line	Full command line, with command name and parameters. Parameters are separated with spaces. Special characters and spaces must be escaped or quoted in the parameters.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status.

◆ processCommand() [2/2]

CommandStatus ts::CommandLine::processCommand	(	const UString &	name,
		const UStringVector &	arguments,
		Report *	redirect = `nullptr`
	)

Analyze and process a command line.

Parameters

[in]	name	Command name.
[in]	arguments	Arguments from command line.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status.

◆ processCommands()

CommandStatus ts::CommandLine::processCommands	(	UStringVector &	lines,
		bool	exit_on_error = `false`,
		Report *	redirect = `nullptr`
	)

Analyze and process all commands from a vector of text lines.

Parameters

[in,out]	lines	Lines of text. Lines starting with a '#' are considered as comments and removed. A line ending with a backslash means that the command continues on the next line. Such lines are reassembled.
[in]	exit_on_error	If true, exit command session on first error.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status of the last command.

◆ processCommandFile()

CommandStatus ts::CommandLine::processCommandFile	(	const UString &	file_name,
		bool	exit_on_error = `false`,
		Report *	redirect = `nullptr`
	)

Analyze and process all commands from a text file.

Lines starting with a '#' are considered as comments and ignored. A line ending with a backslash means that the command continues on the next line.

Parameters

[in]	file_name	File name. If empty or "-", execute an interactive session from the standard input.
[in]	exit_on_error	If true, exit command session on first error.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status of the last command.

◆ processCommandFiles()

CommandStatus ts::CommandLine::processCommandFiles	(	const UStringVector &	file_names,
		bool	exit_on_error = `false`,
		Report *	redirect = `nullptr`
	)

Analyze and process all commands from several text files.

Lines starting with a '#' are considered as comments and ignored. A line ending with a backslash means that the command continues on the next line.

Parameters

[in]	file_names	Vector of file name. If one file name is empty or "-", execute an interactive session from the standard input.
[in]	exit_on_error	If true, exit command session on first error.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status of the last command.

◆ processInteractive() [1/2]

CommandStatus ts::CommandLine::processInteractive	(	const UString &	prompt = `EditLine::DefaultPrompt()`,
		const UString &	next_prompt = `EditLine::DefaultNextPrompt()`,
		const UString &	history_file = `EditLine::DefaultHistoryFile()`,
		size_t	history_size = `EditLine::DefaultHistorySize()`,
		bool	exit_on_error = `false`,
		Report *	redirect = `nullptr`
	)

Analyze and process all commands from an interactive session.

Parameters

[in]	prompt	Command line prompt.
[in]	next_prompt	Command line prompt for continuation lines.
[in]	history_file	File to load/save the history. If empty, no history is loaded or saved.
[in]	history_size	Maximum number of history lines to save.
[in]	exit_on_error	If true, exit command session on first error.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status of the last command.

See also: EditLine

◆ processInteractive() [2/2]

CommandStatus ts::CommandLine::processInteractive	(	bool	exit_on_error,
		Report *	redirect = `nullptr`
	)

Analyze and process all commands from an interactive session.

Use all defaults for prompts and history.

Parameters

[in]	exit_on_error	If true, exit command session on first error.
[in]	redirect	If not null, temporarily redirect errors here.

Returns: Command status of the last command.

See also: EditLine

◆ getAllHelpText()

UString ts::CommandLine::getAllHelpText	(	Args::HelpFormat	format,
		size_t	line_width = `79`
	)		const

Get a formatted help text for all commands.

Parameters

[in]	format	Requested format of the help text.
[in]	line_width	Maximum width of text lines.

Returns: The formatted help text.

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

tsCommandLine.h

Public Member Functions

Detailed Description

Constructor & Destructor Documentation

◆ CommandLine()

Member Function Documentation

◆ setShell()

◆ command() [1/2]

◆ command() [2/2]

◆ setCommandLineHandler()

◆ addPredefinedCommands()

◆ processRedirections()

◆ analyzeCommand() [1/2]

◆ analyzeCommand() [2/2]

◆ processCommand() [1/2]

◆ processCommand() [2/2]

◆ processCommands()

◆ processCommandFile()

◆ processCommandFiles()

◆ processInteractive() [1/2]

◆ processInteractive() [2/2]

◆ getAllHelpText()