PCLI Class Reference

Command Line Interpreter class. More...

#include <cli.h>

Inheritance diagram for PCLI:


Public Member Functions
Construction
	PCLI (const char *prompt=NULL)
	Contracut a new command line interpreter.
virtual	~PCLI ()
	Destroy the command line interpreter.
Operations
virtual bool	Start (bool runInBackground=true)
	Start a command line interpreter.
virtual void	Stop ()
	Stop and clean up command line interpreters.
bool	StartContext (PChannel *channel, bool autoDelete=true, bool runInBackground=true)
	Open a command line interpreter context.
bool	StartContext (PChannel readChannel, PChannel writeChannel, bool autoDeleteRead=true, bool autoDeleteWrite=true, bool runInBackground=true)
virtual Context *	CreateContext ()
	Create a new context.
virtual Context *	AddContext (Context *context=NULL)
	Add a command line interpreter context to the system.
virtual void	RemoveContext (Context *context)
	Remove the command line interpreter context.
virtual void	GarbageCollection ()
	Remove any closed command line interpreter contexts.
virtual void	OnReceivedLine (Arguments &line)
	Received a completed command line.
virtual bool	OnLogIn (const PString &username, const PString &password)
	Received a login name/pasword to be verified.
void	Broadcast (const PString &message) const
	Set a string to all command line interpreter contexts.
bool	SetCommand (const char command, const PNotifier &notifier, const char help=NULL, const char *usage=NULL)
	Register a new command to be interpreted.
void	ShowHelp (Context &context)
	Show help for registered commands to the context.
Member access
const PString &	GetNewLine () const
	Get new line string output at the end of every line.
void	SetNewLine (const PString &newLine)
	Set new line string output at the end of every line.
bool	GetRequireEcho () const
	Get flag for echo is required for entered characters.
void	SetRequireEcho (bool requireEcho)
	Set flag for echo is required for entered characters.
const PString &	GetEditCharacters () const
	Get characters used for editing (backspace/delete) command lines.
void	SetEditCharacters (const PString &editCharacters)
	Set characters used for editing (backspace/delete) command lines.
const PString &	GetPrompt () const
	Get prompt used for command line interpreter.
void	SetPrompt (const PString &prompt)
	Set prompt used for command line interpreter.
const PString &	GetUsernamePrompt () const
	Get prompt used for login (if enabled).
void	SetUsernamePrompt (const PString &prompt)
	Set prompt used for login (if enabled).
const PString &	GetPasswordPrompt () const
	Get prompt used for password (if enabled).
void	SetPasswordPrompt (const PString &prompt)
	Set prompt used for password (if enabled).
const PString &	GetUsername () const
	Get username for log in validation.
void	SetUsername (const PString &username)
	Set username for log in validation.
const PString &	GetPassword () const
	Get password for log in validation.
void	SetPassword (const PString &password)
	Set password for log in validation.
const PCaselessString &	GetExitCommand () const
	Get command to be used to exit session.
void	SetExitCommand (const PCaselessString &exitCommand)
	Set command to be used to exit session.
const PCaselessString &	GetHelpCommand () const
	Get command to be used to display help.
void	SetHelpCommand (const PCaselessString &helpCommand)
	Set command to be used to display help.
const PString &	GetHelpOnHelp () const
	Get help on help.
void	SetHelpOnHelp (const PCaselessString &helpOnHelp)
	Set help on help.
const PCaselessString &	GetRepeatCommand () const
	Get the command to be used to repeat the last executed command.
void	SetRepeatCommand (const PCaselessString &repeatCommand)
	Set the command to be used to repeat the last executed command.
const PCaselessString &	GetHistoryCommand () const
	Get command that will list/execute command history.
void	SetHistoryCommand (const PCaselessString &historyCommand)
	Set command that will list/execute command history.
const PString &	GetNoHistoryError () const
	Get error message for if there is no history.
void	SetNoHistoryError (const PString &noHistoryError)
	Set error message for if there is no history.
const PString &	GetCommandUsagePrefix () const
	Get usage prefix for if Arguments::WriteUsage() called.
void	SetCommandUsagePrefix (const PString &commandUsagePrefix)
	Set usage prefix for if Arguments::WriteUsage() called.
const PString &	GetCommandErrorPrefix () const
	Get error prefix for if Arguments::WriteError() called.
void	SetCommandErrorPrefix (const PString &commandErrorPrefix)
	Set error prefix for if Arguments::WriteError() called.
const PString &	GetUnknownCommandError () const
	Get error message for if unknown command is entered.
void	SetUnknownCommandError (const PString &unknownCommandError)
	Set error message for if unknown command is entered.
Protected Types
typedef std::map< PString, InternalCommand >	CommandMap_t
typedef std::list< Context * >	ContextList_t
Protected Attributes
PString	m_newLine
bool	m_requireEcho
PString	m_editCharacters
PString	m_prompt
PString	m_usernamePrompt
PString	m_passwordPrompt
PString	m_username
PString	m_password
PCaselessString	m_exitCommand
PCaselessString	m_helpCommand
PString	m_helpOnHelp
PCaselessString	m_repeatCommand
PCaselessString	m_historyCommand
PString	m_noHistoryError
PString	m_commandUsagePrefix
PString	m_commandErrorPrefix
PString	m_unknownCommandError
CommandMap_t	m_commands
ContextList_t	m_contextList
PMutex	m_contextMutex
Classes
class	Arguments
	This class is an enhancement to PArgList to add context. More...
class	Context
	Context for command line interpreter. More...
struct	InternalCommand

Detailed Description

Command Line Interpreter class.

This class contains a set of commands, which are executed via a PNotifier, when entered via a PChannel.

The system supports multiple simultaneous interpreter which may access the same command set. For example several telnet sessions.

Note that the various command interpreters could be operating in different threads, so care should be taken for sybchronisation issues on the object being acted upon via the PNotifiers.

Member Typedef Documentation

typedef std::map<PString, InternalCommand> PCLI::CommandMap_t [protected]

typedef std::list<Context *> PCLI::ContextList_t [protected]

Constructor & Destructor Documentation

PCLI::PCLI ( const char * prompt = NULL )

Contracut a new command line interpreter.

virtual PCLI::~PCLI ( ) [virtual]

Destroy the command line interpreter.

This will call Stop() to assure everything is cleaned up before exiting.

Member Function Documentation

virtual Context* PCLI::AddContext ( Context * context = NULL ) [virtual]

Add a command line interpreter context to the system.

If context is NULL then CreateContext() is called to create one.

Parameters:

context

New context to add to the system.

void PCLI::Broadcast ( const PString & message ) const

Set a string to all command line interpreter contexts.

Parameters:

message

Message to broadcast.

virtual Context* PCLI::CreateContext ( ) [virtual]

Create a new context.

Users may use this to create derived classes for their own use.

virtual void PCLI::GarbageCollection ( ) [virtual]

Remove any closed command line interpreter contexts.

const PString& PCLI::GetCommandErrorPrefix ( ) const [inline]

Get error prefix for if Arguments::WriteError() called.

Default is ": error: ", always prefixed by command name.

const PString& PCLI::GetCommandUsagePrefix ( ) const [inline]

Get usage prefix for if Arguments::WriteUsage() called.

Default is "Usage: ".

const PString& PCLI::GetEditCharacters ( ) const [inline]

Get characters used for editing (backspace/delete) command lines.

Default is "\b\x7f".

const PCaselessString& PCLI::GetExitCommand ( ) const [inline]

Get command to be used to exit session.

Default is "exit\nquit".

const PCaselessString& PCLI::GetHelpCommand ( ) const [inline]

Get command to be used to display help.

Default is "?\nhelp".

const PString& PCLI::GetHelpOnHelp ( ) const [inline]

Get help on help.

This string is output before the individual help is output for each command. Default describes ?, !, !n, !! followed by "Command available are:".

const PCaselessString& PCLI::GetHistoryCommand ( ) const [inline]

Get command that will list/execute command history.

Default is "!".

const PString& PCLI::GetNewLine ( ) const [inline]

Get new line string output at the end of every line.

Default is "\n".

const PString& PCLI::GetNoHistoryError ( ) const [inline]

Get error message for if there is no history.

Default is "No command history".

const PString& PCLI::GetPassword ( ) const [inline]

Get password for log in validation.

Default is empty string, disabling entry of password.

const PString& PCLI::GetPasswordPrompt ( ) const [inline]

Get prompt used for password (if enabled).

Default is "Password: ".

const PString& PCLI::GetPrompt ( ) const [inline]

Get prompt used for command line interpreter.

Default is "CLI> ".

const PCaselessString& PCLI::GetRepeatCommand ( ) const [inline]

Get the command to be used to repeat the last executed command.

Default is "!!".

bool PCLI::GetRequireEcho ( ) const [inline]

Get flag for echo is required for entered characters.

Default is false.

const PString& PCLI::GetUnknownCommandError ( ) const [inline]

Get error message for if unknown command is entered.

Default is "Unknown command".

const PString& PCLI::GetUsername ( ) const [inline]

Get username for log in validation.

Default is empty string, disabling entry of username/password.

const PString& PCLI::GetUsernamePrompt ( ) const [inline]

Get prompt used for login (if enabled).

Default is "Username: ".

virtual bool PCLI::OnLogIn	(	const PString &	username,
		const PString &	password
	)			`[virtual]`

Received a login name/pasword to be verified.

Note that the m_username or m_password field must be non-empty for a log in sequence to occur, even if this function is overridden and the memnbers not actually used for validation.

If the m_username is an empty string, but m_password is not, then it the username not prompted for, just the password is required. The reverse is also poassible and only a username entry required.

Default returns true if parameters are equal to m_username, m_password respectively.

virtual void PCLI::OnReceivedLine ( Arguments & line ) [virtual]

Received a completed command line.

The completed command line is parsed into arguments by the PArgList class, and passed to this function.

The default behaviour searches the list of registered commands for a PNotifier to execute.

virtual void PCLI::RemoveContext ( Context * context ) [virtual]

Remove the command line interpreter context.

The context thread is stopped, the channel closed and memory deleted.

Parameters:

context

Context to remove

bool PCLI::SetCommand	(	const char *	command,
		const PNotifier &	notifier,
		const char *	help = `NULL`,
		const char *	usage = `NULL`
	)

Note the command may be a series of synonyms of the same command separated by the '
' character.

The command may also contain spaces which separates sub-commands, e.g. "list users".

Returns false if one of the command synonyms was a dupicate of an existing command.

Parameters:

command	Command(s) to register
notifier	Callback to execute when command interpreted
help	Help text on command (what it does)
usage	Usage text on command (syntax/options)

void PCLI::SetCommandErrorPrefix ( const PString & commandErrorPrefix ) [inline]

Set error prefix for if Arguments::WriteError() called.

Default is ": error: ", always prefixed by command name.

void PCLI::SetCommandUsagePrefix ( const PString & commandUsagePrefix ) [inline]

Set usage prefix for if Arguments::WriteUsage() called.

Default is "Usage: ".

void PCLI::SetEditCharacters ( const PString & editCharacters ) [inline]

Set characters used for editing (backspace/delete) command lines.

Default is "\b\x7f".

void PCLI::SetExitCommand ( const PCaselessString & exitCommand ) [inline]

Set command to be used to exit session.

Default is "exit\nquit".

void PCLI::SetHelpCommand ( const PCaselessString & helpCommand ) [inline]

Set command to be used to display help.

Default is "?\nhelp".

void PCLI::SetHelpOnHelp ( const PCaselessString & helpOnHelp ) [inline]

Set help on help.

This string is output before the individual help is output for each command. Default describes ?, !, !n, !! followed by "Command available are:".

void PCLI::SetHistoryCommand ( const PCaselessString & historyCommand ) [inline]

Set command that will list/execute command history.

Default is "!".

void PCLI::SetNewLine ( const PString & newLine ) [inline]

Set new line string output at the end of every line.

Default is "\n".

void PCLI::SetNoHistoryError ( const PString & noHistoryError ) [inline]

Set error message for if there is no history.

Default is "No command history".

void PCLI::SetPassword ( const PString & password ) [inline]

Set password for log in validation.

Default is empty string, disabling entry of password.

void PCLI::SetPasswordPrompt ( const PString & prompt ) [inline]

Set prompt used for password (if enabled).

Default is "Password: ".

void PCLI::SetPrompt ( const PString & prompt ) [inline]

Set prompt used for command line interpreter.

Default is "CLI> ".

void PCLI::SetRepeatCommand ( const PCaselessString & repeatCommand ) [inline]

Set the command to be used to repeat the last executed command.

Default is "!!".

void PCLI::SetRequireEcho ( bool requireEcho ) [inline]

Set flag for echo is required for entered characters.

Default is false.

void PCLI::SetUnknownCommandError ( const PString & unknownCommandError ) [inline]

Set error message for if unknown command is entered.

Default is "Unknown command".

void PCLI::SetUsername ( const PString & username ) [inline]

Set username for log in validation.

Default is empty string, disabling entry of username/password.

void PCLI::SetUsernamePrompt ( const PString & prompt ) [inline]

Set prompt used for login (if enabled).

Default is "Username: ".

void PCLI::ShowHelp ( Context & context )

Show help for registered commands to the context.

Parameters:

context

Context to output help to.

virtual bool PCLI::Start ( bool runInBackground = true ) [virtual]

Start a command line interpreter.

If runInBackground is true the all the command line interpreter contexts that have been added will have their background threads started.

If runInBackground is false, then there must only be one context added and that context is continuously read until it's channel is closed or returns end of file.

Parameters:

runInBackground

Spawn a thread to read and interpret commands

Reimplemented in PCLIStandard, and PCLISocket.

bool PCLI::StartContext	(	PChannel *	readChannel,
		PChannel *	writeChannel,
		bool	autoDeleteRead = `true`,
		bool	autoDeleteWrite = `true`,
		bool	runInBackground = `true`
	)

Parameters:

readChannel	Channel to be used for both read operations.
writeChannel	Channel to be used for both write operations.
autoDeleteRead	Automatically delete the read channel
autoDeleteWrite	Automatically delete the write channel
runInBackground	Spawn a thread to read and interpret commands