PTLib  Version 2.10.11
PCLI Class Reference

Command Line Interpreter class. More...

#include <cli.h>

Inheritance diagram for PCLI:
PObject PCLISocket PCLIStandard PCLITelnet

Classes

class  Arguments
 This class is an enhancement to PArgList to add context. More...
 
class  Context
 Context for command line interpreter. More...
 
struct  InternalCommand
 

Public Member Functions

virtual ContextStartForeground ()
 Initialise a foreground context and return it. More...
 
virtual bool RunContext (Context *context)
 Run a context. More...
 
Construction
 PCLI (const char *prompt=NULL)
 Contracut a new command line interpreter. More...
 
virtual ~PCLI ()
 Destroy the command line interpreter. More...
 
Operations
virtual bool Start (bool runInBackground=true)
 Start a command line interpreter. More...
 
virtual void Stop ()
 Stop and clean up command line interpreters. More...
 
bool StartContext (PChannel *channel, bool autoDelete=true, bool runInBackground=true)
 Open a command line interpreter context. More...
 
bool StartContext (PChannel *readChannel, PChannel *writeChannel, bool autoDeleteRead=true, bool autoDeleteWrite=true, bool runInBackground=true)
 
virtual ContextCreateContext ()
 Create a new context. More...
 
virtual ContextAddContext (Context *context=NULL)
 Add a command line interpreter context to the system. More...
 
virtual void RemoveContext (Context *context)
 Remove the command line interpreter context. More...
 
virtual void GarbageCollection ()
 Remove any closed command line interpreter contexts. More...
 
virtual void OnReceivedLine (Arguments &line)
 Received a completed command line. More...
 
virtual bool OnLogIn (const PString &username, const PString &password)
 Received a login name/pasword to be verified. More...
 
void Broadcast (const PString &message) const
 Set a string to all command line interpreter contexts. More...
 
bool SetCommand (const char *command, const PNotifier &notifier, const char *help=NULL, const char *usage=NULL)
 Register a new command to be interpreted. More...
 
void ShowHelp (Context &context)
 Show help for registered commands to the context. More...
 
Member access
const PStringGetNewLine () const
 Get new line string output at the end of every line. More...
 
void SetNewLine (const PString &newLine)
 Set new line string output at the end of every line. More...
 
bool GetRequireEcho () const
 Get flag for echo is required for entered characters. More...
 
void SetRequireEcho (bool requireEcho)
 Set flag for echo is required for entered characters. More...
 
const PStringGetEditCharacters () const
 Get characters used for editing (backspace/delete) command lines. More...
 
void SetEditCharacters (const PString &editCharacters)
 Set characters used for editing (backspace/delete) command lines. More...
 
const PStringGetPrompt () const
 Get prompt used for command line interpreter. More...
 
void SetPrompt (const PString &prompt)
 Set prompt used for command line interpreter. More...
 
const PStringGetUsernamePrompt () const
 Get prompt used for login (if enabled). More...
 
void SetUsernamePrompt (const PString &prompt)
 Set prompt used for login (if enabled). More...
 
const PStringGetPasswordPrompt () const
 Get prompt used for password (if enabled). More...
 
void SetPasswordPrompt (const PString &prompt)
 Set prompt used for password (if enabled). More...
 
const PStringGetUsername () const
 Get username for log in validation. More...
 
void SetUsername (const PString &username)
 Set username for log in validation. More...
 
const PStringGetPassword () const
 Get password for log in validation. More...
 
void SetPassword (const PString &password)
 Set password for log in validation. More...
 
const PCaselessStringGetExitCommand () const
 Get command to be used to exit session. More...
 
void SetExitCommand (const PCaselessString &exitCommand)
 Set command to be used to exit session. More...
 
const PCaselessStringGetHelpCommand () const
 Get command to be used to display help. More...
 
void SetHelpCommand (const PCaselessString &helpCommand)
 Set command to be used to display help. More...
 
const PStringGetHelpOnHelp () const
 Get help on help. More...
 
void SetHelpOnHelp (const PCaselessString &helpOnHelp)
 Set help on help. More...
 
const PCaselessStringGetRepeatCommand () const
 Get the command to be used to repeat the last executed command. More...
 
void SetRepeatCommand (const PCaselessString &repeatCommand)
 Set the command to be used to repeat the last executed command. More...
 
const PCaselessStringGetHistoryCommand () const
 Get command that will list/execute command history. More...
 
void SetHistoryCommand (const PCaselessString &historyCommand)
 Set command that will list/execute command history. More...
 
const PStringGetNoHistoryError () const
 Get error message for if there is no history. More...
 
void SetNoHistoryError (const PString &noHistoryError)
 Set error message for if there is no history. More...
 
const PStringGetCommandUsagePrefix () const
 Get usage prefix for if Arguments::WriteUsage() called. More...
 
void SetCommandUsagePrefix (const PString &commandUsagePrefix)
 Set usage prefix for if Arguments::WriteUsage() called. More...
 
const PStringGetCommandErrorPrefix () const
 Get error prefix for if Arguments::WriteError() called. More...
 
void SetCommandErrorPrefix (const PString &commandErrorPrefix)
 Set error prefix for if Arguments::WriteError() called. More...
 
const PStringGetUnknownCommandError () const
 Get error message for if unknown command is entered. More...
 
void SetUnknownCommandError (const PString &unknownCommandError)
 Set error message for if unknown command is entered. More...
 
- Public Member Functions inherited from PObject
virtual ~PObject ()
 
virtual PObjectClone () const
 Create a copy of the class on the heap. More...
 
virtual PINDEX HashFunction () const
 This function yields a hash value required by the PDictionary class. More...
 
virtual Comparison Compare (const PObject &obj) const
 Compare the two objects and return their relative rank. More...
 
virtual Comparison CompareObjectMemoryDirect (const PObject &obj) const
 Determine the byte wise comparison of two objects. More...
 
bool operator== (const PObject &obj) const
 Compare the two objects. More...
 
bool operator!= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator< (const PObject &obj) const
 Compare the two objects. More...
 
bool operator> (const PObject &obj) const
 Compare the two objects. More...
 
bool operator<= (const PObject &obj) const
 Compare the two objects. More...
 
bool operator>= (const PObject &obj) const
 Compare the two objects. More...
 
virtual const char * GetClass (unsigned ancestor=0) const
 Get the current dynamic type of the object instance. More...
 
PBoolean IsClass (const char *cls) const
 
virtual PBoolean InternalIsDescendant (const char *clsName) const
 Determine if the dynamic type of the current instance is a descendent of the specified class. More...
 
virtual void PrintOn (ostream &strm) const
 Output the contents of the object to the stream. More...
 
virtual void ReadFrom (istream &strm)
 Input the contents of the object from the stream. More...
 

Protected Types

typedef std::map< PString, InternalCommandCommandMap_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
 

Additional Inherited Members

- Public Types inherited from PObject
enum  Comparison { LessThan = -1, EqualTo = 0, GreaterThan = 1 }
 Result of the comparison operation performed by the Compare() function. More...
 
- Static Public Member Functions inherited from PObject
static Comparison InternalCompareObjectMemoryDirect (const PObject *obj1, const PObject *obj2, PINDEX size)
 Internal function caled from CompareObjectMemoryDirect() More...
 
static const char * Class ()
 Get the name of the class as a C string. More...
 
- Protected Member Functions inherited from PObject
 PObject ()
 Constructor for PObject, made protected so cannot ever create one on its own. More...
 

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
contextNew context to add to the system.
void PCLI::Broadcast ( const PString message) const

Set a string to all command line interpreter contexts.

Parameters
messageMessage 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.

References m_commandErrorPrefix.

const PString& PCLI::GetCommandUsagePrefix ( ) const
inline

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

Default is "Usage: ".

References m_commandUsagePrefix.

const PString& PCLI::GetEditCharacters ( ) const
inline

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

Default is "\b\x7f".

References m_editCharacters.

const PCaselessString& PCLI::GetExitCommand ( ) const
inline

Get command to be used to exit session.

Default is "exit\nquit".

References m_exitCommand.

const PCaselessString& PCLI::GetHelpCommand ( ) const
inline

Get command to be used to display help.

Default is "?\nhelp".

References m_helpCommand.

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:".

References m_helpOnHelp.

const PCaselessString& PCLI::GetHistoryCommand ( ) const
inline

Get command that will list/execute command history.

Default is "!".

References m_historyCommand.

const PString& PCLI::GetNewLine ( ) const
inline

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

Default is "\n".

References m_newLine.

const PString& PCLI::GetNoHistoryError ( ) const
inline

Get error message for if there is no history.

Default is "No command history".

References m_noHistoryError.

const PString& PCLI::GetPassword ( ) const
inline

Get password for log in validation.

Default is empty string, disabling entry of password.

References m_password.

const PString& PCLI::GetPasswordPrompt ( ) const
inline

Get prompt used for password (if enabled).

Default is "Password: ".

References m_passwordPrompt.

const PString& PCLI::GetPrompt ( ) const
inline

Get prompt used for command line interpreter.

Default is "CLI> ".

References m_prompt.

const PCaselessString& PCLI::GetRepeatCommand ( ) const
inline

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

Default is "!!".

References m_repeatCommand.

bool PCLI::GetRequireEcho ( ) const
inline

Get flag for echo is required for entered characters.

Default is false.

References m_requireEcho.

const PString& PCLI::GetUnknownCommandError ( ) const
inline

Get error message for if unknown command is entered.

Default is "Unknown command".

References m_unknownCommandError.

const PString& PCLI::GetUsername ( ) const
inline

Get username for log in validation.

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

References m_username.

const PString& PCLI::GetUsernamePrompt ( ) const
inline

Get prompt used for login (if enabled).

Default is "Username: ".

References m_usernamePrompt.

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
contextContext to remove
virtual bool PCLI::RunContext ( Context context)
virtual

Run a context.

Referenced by SetUnknownCommandError().

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

Register a new command to be interpreted.

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
commandCommand(s) to register
notifierCallback to execute when command interpreted
helpHelp text on command (what it does)
usageUsage 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.

References m_commandErrorPrefix.

void PCLI::SetCommandUsagePrefix ( const PString commandUsagePrefix)
inline

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

Default is "Usage: ".

References m_commandUsagePrefix.

void PCLI::SetEditCharacters ( const PString editCharacters)
inline

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

Default is "\b\x7f".

References m_editCharacters.

void PCLI::SetExitCommand ( const PCaselessString exitCommand)
inline

Set command to be used to exit session.

Default is "exit\nquit".

References m_exitCommand.

void PCLI::SetHelpCommand ( const PCaselessString helpCommand)
inline

Set command to be used to display help.

Default is "?\nhelp".

References m_helpCommand.

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:".

References m_helpOnHelp.

void PCLI::SetHistoryCommand ( const PCaselessString historyCommand)
inline

Set command that will list/execute command history.

Default is "!".

References m_historyCommand.

void PCLI::SetNewLine ( const PString newLine)
inline

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

Default is "\n".

References m_newLine.

void PCLI::SetNoHistoryError ( const PString noHistoryError)
inline

Set error message for if there is no history.

Default is "No command history".

References m_noHistoryError.

void PCLI::SetPassword ( const PString password)
inline

Set password for log in validation.

Default is empty string, disabling entry of password.

References m_password.

void PCLI::SetPasswordPrompt ( const PString prompt)
inline

Set prompt used for password (if enabled).

Default is "Password: ".

References m_passwordPrompt.

void PCLI::SetPrompt ( const PString prompt)
inline

Set prompt used for command line interpreter.

Default is "CLI> ".

References m_prompt.

void PCLI::SetRepeatCommand ( const PCaselessString repeatCommand)
inline

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

Default is "!!".

References m_repeatCommand.

void PCLI::SetRequireEcho ( bool  requireEcho)
inline

Set flag for echo is required for entered characters.

Default is false.

References m_requireEcho.

void PCLI::SetUnknownCommandError ( const PString unknownCommandError)
inline

Set error message for if unknown command is entered.

Default is "Unknown command".

References m_unknownCommandError, RunContext(), and StartForeground().

void PCLI::SetUsername ( const PString username)
inline

Set username for log in validation.

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

References m_username.

void PCLI::SetUsernamePrompt ( const PString prompt)
inline

Set prompt used for login (if enabled).

Default is "Username: ".

References m_usernamePrompt.

void PCLI::ShowHelp ( Context context)

Show help for registered commands to the context.

Parameters
contextContext 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
runInBackgroundSpawn a thread to read and interpret commands

Reimplemented in PCLISocket, and PCLIStandard.

bool PCLI::StartContext ( PChannel channel,
bool  autoDelete = true,
bool  runInBackground = true 
)

Open a command line interpreter context.

Parameters
channelChannel to read/write
autoDeleteAutomatically delete channel on exit
runInBackgroundSpawn a thread to read and interpret commands
bool PCLI::StartContext ( PChannel readChannel,
PChannel writeChannel,
bool  autoDeleteRead = true,
bool  autoDeleteWrite = true,
bool  runInBackground = true 
)
Parameters
readChannelChannel to be used for both read operations.
writeChannelChannel to be used for both write operations.
autoDeleteReadAutomatically delete the read channel
autoDeleteWriteAutomatically delete the write channel
runInBackgroundSpawn a thread to read and interpret commands
virtual Context* PCLI::StartForeground ( )
virtual

Initialise a foreground context and return it.

Reimplemented in PCLIStandard.

Referenced by SetUnknownCommandError().

virtual void PCLI::Stop ( )
virtual

Stop and clean up command line interpreters.

All the running contexts threads will be stopped, closing the channels and memory cleaned up.

Reimplemented in PCLISocket.

Member Data Documentation

PString PCLI::m_commandErrorPrefix
protected
CommandMap_t PCLI::m_commands
protected
PString PCLI::m_commandUsagePrefix
protected
ContextList_t PCLI::m_contextList
protected
PMutex PCLI::m_contextMutex
protected
PString PCLI::m_editCharacters
protected
PCaselessString PCLI::m_exitCommand
protected

Referenced by GetExitCommand(), and SetExitCommand().

PCaselessString PCLI::m_helpCommand
protected

Referenced by GetHelpCommand(), and SetHelpCommand().

PString PCLI::m_helpOnHelp
protected

Referenced by GetHelpOnHelp(), and SetHelpOnHelp().

PCaselessString PCLI::m_historyCommand
protected
PString PCLI::m_newLine
protected

Referenced by GetNewLine(), and SetNewLine().

PString PCLI::m_noHistoryError
protected
PString PCLI::m_password
protected

Referenced by GetPassword(), and SetPassword().

PString PCLI::m_passwordPrompt
protected
PString PCLI::m_prompt
protected

Referenced by GetPrompt(), and SetPrompt().

PCaselessString PCLI::m_repeatCommand
protected
bool PCLI::m_requireEcho
protected

Referenced by GetRequireEcho(), and SetRequireEcho().

PString PCLI::m_unknownCommandError
protected
PString PCLI::m_username
protected

Referenced by GetUsername(), and SetUsername().

PString PCLI::m_usernamePrompt
protected

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