PCLI Class Reference

Command Line Interpreter class. More...

`#include <cli.h>`

Inheritance diagram for PCLI:

## 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 Context * | StartForeground ()
| 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 Context * | CreateContext ()
| Create a new context. More...
virtual Context * | AddContext (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 PString & | GetNewLine () 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 PString & | GetEditCharacters () 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 PString & | GetPrompt () const
| Get prompt used for command line interpreter. More...
void | SetPrompt (const PString &prompt)
| Set prompt used for command line interpreter. More...
const PString & | GetUsernamePrompt () const
| Get prompt used for login (if enabled). More...
void | SetUsernamePrompt (const PString &prompt)
| Set prompt used for login (if enabled). More...
const PString & | GetPasswordPrompt () const
| Get prompt used for password (if enabled). More...
void | SetPasswordPrompt (const PString &prompt)
| Set prompt used for password (if enabled). More...
const PString & | GetUsername () const
| Get username for log in validation. More...
void | SetUsername (const PString &username)
| Set username for log in validation. More...
const PString & | GetPassword () const
| Get password for log in validation. More...
void | SetPassword (const PString &password)
| Set password for log in validation. More...
const PCaselessString & | GetExitCommand () 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 PCaselessString & | GetHelpCommand () 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 PString & | GetHelpOnHelp () const
| Get help on help. More...
void | SetHelpOnHelp (const PCaselessString &helpOnHelp)
| Set help on help. More...
const PCaselessString & | GetRepeatCommand () 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 PCaselessString & | GetHistoryCommand () 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 PString & | GetNoHistoryError () 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 PString & | GetCommandUsagePrefix () 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 PString & | GetCommandErrorPrefix () 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 PString & | GetUnknownCommandError () 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 PObject * | Clone () 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, 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

## 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

  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.

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

  context | Context to remove

virtual bool PCLI::RunContext | ( | Context * | context | ) |

virtual

Run a context.

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

  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.

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.

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

  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 PCLISocket, and PCLIStandard.

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

Open a command line interpreter context.

Parameters

  channel | Channel to read/write
  autoDelete | Automatically delete channel on exit
  runInBackground | Spawn a thread to read and interpret commands

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

virtual Context* PCLI::StartForeground | ( |  | ) |

virtual

Initialise a foreground context and return it.

Reimplemented in PCLIStandard.

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

Referenced by GetCommandErrorPrefix(), and SetCommandErrorPrefix().

CommandMap_t PCLI::m_commands

protected

PString PCLI::m_commandUsagePrefix

protected

Referenced by GetCommandUsagePrefix(), and SetCommandUsagePrefix().

ContextList_t PCLI::m_contextList

protected

PMutex PCLI::m_contextMutex

protected

PString PCLI::m_editCharacters

protected

Referenced by GetEditCharacters(), and SetEditCharacters().

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

Referenced by GetHistoryCommand(), and SetHistoryCommand().

PString PCLI::m_newLine

protected

Referenced by GetNewLine(), and SetNewLine().

PString PCLI::m_noHistoryError

protected

Referenced by GetNoHistoryError(), and SetNoHistoryError().

PString PCLI::m_password

protected

Referenced by GetPassword(), and SetPassword().

PString PCLI::m_passwordPrompt

protected

Referenced by GetPasswordPrompt(), and SetPasswordPrompt().

PString PCLI::m_prompt

protected

Referenced by GetPrompt(), and SetPrompt().

PCaselessString PCLI::m_repeatCommand

protected

Referenced by GetRepeatCommand(), and SetRepeatCommand().

bool PCLI::m_requireEcho

protected

Referenced by GetRequireEcho(), and SetRequireEcho().

PString PCLI::m_unknownCommandError

protected

Referenced by GetUnknownCommandError(), and SetUnknownCommandError().

PString PCLI::m_username

protected

Referenced by GetUsername(), and SetUsername().

PString PCLI::m_usernamePrompt

protected

Referenced by GetUsernamePrompt(), and SetUsernamePrompt().

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

- cli.h