cli.h
Go to the documentation of this file.
/*
* cli.h
*
* Command line interpreter
*
* Copyright (C) 2006-2008 Post Increment
*
* The contents of this file are subject to the Mozilla Public License
* Version 1.0 (the "License"); you may not use this file except in
* compliance with the License. You may obtain a copy of the License at
* http://www.mozilla.org/MPL/
*
* Software distributed under the License is distributed on an "AS IS"
* basis, WITHOUT WARRANTY OF ANY KIND, either express or implied. See
* the License for the specific language governing rights and limitations
* under the License.
*
* The Original Code is WOpenMCU
*
* The Initial Developer of the Original Code is Post Increment
*
* Contributor(s): Craig Southeren (craigs@postincrement.com)
* Robert Jongbloed (robertj@voxlucida.com.au)
*
* Portions of this code were written by Post Increment (http://www.postincrement.com)
* with the assistance of funding from US Joint Forces Command Joint Concept Development &
* Experimentation (J9) http://www.jfcom.mil/about/abt_j9.htm
*
* Further assistance for enhancements from Imagicle spa
*
* $Revision: 24931 $
* $Author: csoutheren $
* $Date: 2010-12-07 20:01:15 -0600 (Tue, 07 Dec 2010) $
*/
#ifndef PTLIB_CLI_H
#define PTLIB_CLI_H
#include <ptlib.h>
#include <ptlib/sockets.h>
#include <list>
class PCLI : public PObject
{
PCLASSINFO(PCLI, PObject);
public:
class Context;
class Context : public PIndirectChannel
{
public:
Context(
PCLI & cli
);
virtual ~Context();
virtual PBoolean Write(
const void * buf,
PINDEX len
);
bool Start();
void Stop();
virtual void OnStart();
virtual void OnStop();
virtual bool WritePrompt();
virtual bool ReadAndProcessInput();
virtual bool ProcessInput(int ch);
virtual bool ProcessInput(const PString & line);
virtual void OnCompletedLine();
PCLI & GetCLI() const { return m_cli; }
bool IsProcessingCommand() const { return m_state == e_ProcessingCommand; }
protected:
PDECLARE_NOTIFIER(PThread, Context, ThreadMain);
PCLI & m_cli;
PString m_commandLine;
bool m_ignoreNextEOL;
PStringList m_commandHistory;
PThread * m_thread;
enum State {
e_Username,
e_Password,
e_CommandEntry,
e_ProcessingCommand
} m_state;
PString m_enteredUsername;
};
class Arguments : public PArgList
{
public:
Arguments(
Context & context,
const PString & rawLine
);
Context & WriteUsage();
Context & WriteError(
const PString & error = PString::Empty()
);
Context & GetContext() const { return m_context; }
protected:
Context & m_context;
PString m_command;
PString m_usage;
friend class PCLI;
};
PCLI(
const char * prompt = NULL
);
virtual ~PCLI();
virtual bool Start(
bool runInBackground = true
);
virtual void Stop();
bool StartContext(
PChannel * channel,
bool autoDelete = true,
bool runInBackground = true
);
bool StartContext(
PChannel * readChannel,
PChannel * writeChannel,
bool autoDeleteRead = true,
bool autoDeleteWrite = true,
bool runInBackground = true
);
virtual Context * CreateContext();
virtual Context * AddContext(
Context * context = NULL
);
virtual void RemoveContext(
Context * context
);
virtual void GarbageCollection();
virtual void OnReceivedLine(
Arguments & line
);
virtual bool OnLogIn(
const PString & username,
const PString & password
);
void Broadcast(
const PString & message
) const;
bool SetCommand(
const char * command,
const PNotifier & notifier,
const char * help = NULL,
const char * usage = NULL
);
void ShowHelp(
Context & context
);
const PString & GetNewLine() const { return m_newLine; }
void SetNewLine(const PString & newLine) { m_newLine = newLine; }
bool GetRequireEcho() const { return m_requireEcho; }
void SetRequireEcho(bool requireEcho) { m_requireEcho = requireEcho; }
const PString & GetEditCharacters() const { return m_editCharacters; }
void SetEditCharacters(const PString & editCharacters) { m_editCharacters = editCharacters; }
const PString & GetPrompt() const { return m_prompt; }
void SetPrompt(const PString & prompt) { m_prompt = prompt; }
const PString & GetUsernamePrompt() const { return m_usernamePrompt; }
void SetUsernamePrompt(const PString & prompt) { m_usernamePrompt = prompt; }
const PString & GetPasswordPrompt() const { return m_passwordPrompt; }
void SetPasswordPrompt(const PString & prompt) { m_passwordPrompt = prompt; }
const PString & GetUsername() const { return m_username; }
void SetUsername(const PString & username) { m_username = username; }
const PString & GetPassword() const { return m_password; }
void SetPassword(const PString & password) { m_password = password; }
const PCaselessString & GetExitCommand() const { return m_exitCommand; }
void SetExitCommand(const PCaselessString & exitCommand) { m_exitCommand = exitCommand; }
const PCaselessString & GetHelpCommand() const { return m_helpCommand; }
void SetHelpCommand(const PCaselessString & helpCommand) { m_helpCommand = helpCommand; }
const PString & GetHelpOnHelp() const { return m_helpOnHelp; }
void SetHelpOnHelp(const PCaselessString & helpOnHelp) { m_helpOnHelp = helpOnHelp; }
const PCaselessString & GetRepeatCommand() const { return m_repeatCommand; }
void SetRepeatCommand(const PCaselessString & repeatCommand) { m_repeatCommand = repeatCommand; }
const PCaselessString & GetHistoryCommand() const { return m_historyCommand; }
void SetHistoryCommand(const PCaselessString & historyCommand) { m_historyCommand = historyCommand; }
const PString & GetNoHistoryError() const { return m_noHistoryError; }
void SetNoHistoryError(const PString & noHistoryError) { m_noHistoryError = noHistoryError; }
const PString & GetCommandUsagePrefix() const { return m_commandUsagePrefix; }
void SetCommandUsagePrefix(const PString & commandUsagePrefix) { m_commandUsagePrefix = commandUsagePrefix; }
const PString & GetCommandErrorPrefix() const { return m_commandErrorPrefix; }
void SetCommandErrorPrefix(const PString & commandErrorPrefix) { m_commandErrorPrefix = commandErrorPrefix; }
const PString & GetUnknownCommandError() const { return m_unknownCommandError; }
void SetUnknownCommandError(const PString & unknownCommandError) { m_unknownCommandError = unknownCommandError; }
virtual Context * StartForeground();
virtual bool RunContext(Context * context);
protected:
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;
struct InternalCommand {
PNotifier m_notifier;
PString m_help;
PString m_usage;
};
typedef std::map<PString, InternalCommand> CommandMap_t;
CommandMap_t m_commands;
typedef std::list<Context *> ContextList_t;
ContextList_t m_contextList;
PMutex m_contextMutex;
};
class PCLIStandard : public PCLI
{
public:
PCLIStandard(
const char * prompt = NULL
);
virtual bool Start(
bool runInBackground = true
);
PCLI::Context * StartForeground();
};
class PCLISocket : public PCLI
{
public:
PCLISocket(
WORD port = 0,
const char * prompt = NULL,
bool singleThreadForAll = false
);
~PCLISocket();
virtual bool Start(
bool runInBackground = true
);
virtual void Stop();
virtual Context * AddContext(
Context * context = NULL
);
virtual void RemoveContext(
Context * context
);
bool Listen(
WORD port = 0
);
WORD GetPort() const { return m_listenSocket.GetPort(); }
protected:
PDECLARE_NOTIFIER(PThread, PCLISocket, ThreadMain);
bool HandleSingleThreadForAll();
bool HandleIncoming();
virtual PTCPSocket * CreateSocket();
bool m_singleThreadForAll;
PTCPSocket m_listenSocket;
PThread * m_thread;
typedef std::map<PSocket *, Context *> ContextMap_t;
ContextMap_t m_contextBySocket;
};
class PCLITelnet : public PCLISocket
{
public:
PCLITelnet(
WORD port = 0,
const char * prompt = NULL,
bool singleThreadForAll = false
);
protected:
virtual PTCPSocket * CreateSocket();
};
#endif // PTLIB_CLI_H
// End Of File ///////////////////////////////////////////////////////////////
PCLISocket::m_listenSocket
PTCPSocket m_listenSocket
Definition: cli.h:671
PCLI::SetHelpOnHelp
void SetHelpOnHelp(const PCaselessString &helpOnHelp)
Set help on help.
Definition: cli.h:465
PCLI::Context::e_CommandEntry
Definition: cli.h:175
PCLI::ContextList_t
std::list< Context * > ContextList_t
Definition: cli.h:564
PCLI::SetUsername
void SetUsername(const PString &username)
Set username for log in validation.
Definition: cli.h:423
PCLI::SetHistoryCommand
void SetHistoryCommand(const PCaselessString &historyCommand)
Set command that will list/execute command history.
Definition: cli.h:485
PCLI::m_exitCommand
PCaselessString m_exitCommand
Definition: cli.h:546
PCLI::ShowHelp
void ShowHelp(Context &context)
Show help for registered commands to the context.
PCLI::~PCLI
virtual ~PCLI()
Destroy the command line interpreter.
PCLI::m_contextMutex
PMutex m_contextMutex
Definition: cli.h:566
PCLI::GetEditCharacters
const PString & GetEditCharacters() const
Get characters used for editing (backspace/delete) command lines.
Definition: cli.h:378
PCLISocket::Stop
virtual void Stop()
Stop and clean up command line interpreters.
PCLI::SetEditCharacters
void SetEditCharacters(const PString &editCharacters)
Set characters used for editing (backspace/delete) command lines.
Definition: cli.h:383
PCLI::m_passwordPrompt
PString m_passwordPrompt
Definition: cli.h:543
PCLI::m_newLine
PString m_newLine
Definition: cli.h:538
PCLI::m_helpOnHelp
PString m_helpOnHelp
Definition: cli.h:548
PCLI::Context::ReadAndProcessInput
virtual bool ReadAndProcessInput()
Read a character from the attached channel an process.
PNotifier
Class specialisation for PNotifierTemplate<INT>
PCLI::m_historyCommand
PCaselessString m_historyCommand
Definition: cli.h:550
PCLI::Arguments::GetContext
Context & GetContext() const
Get the CLI context supplying the command line arguments.
Definition: cli.h:211
PCLI::GetNewLine
const PString & GetNewLine() const
Get new line string output at the end of every line.
Definition: cli.h:358
PCLI::m_usernamePrompt
PString m_usernamePrompt
Definition: cli.h:542
PCLI::InternalCommand
Definition: cli.h:556
PCLISocket::m_thread
PThread * m_thread
Definition: cli.h:672
PCLI::Arguments
This class is an enhancement to PArgList to add context.
Definition: cli.h:183
PCLI::RunContext
virtual bool RunContext(Context *context)
Run a context.
PCLI::GetExitCommand
const PCaselessString & GetExitCommand() const
Get command to be used to exit session.
Definition: cli.h:438
PCLI::GetPrompt
const PString & GetPrompt() const
Get prompt used for command line interpreter.
Definition: cli.h:388
PCLI::AddContext
virtual Context * AddContext(Context *context=NULL)
Add a command line interpreter context to the system.
PCLI::Context::WritePrompt
virtual bool WritePrompt()
Write prompt (depending on state) to channel.
PCLI::GetHelpCommand
const PCaselessString & GetHelpCommand() const
Get command to be used to display help.
Definition: cli.h:448
PCLI::m_prompt
PString m_prompt
Definition: cli.h:541
PIndirectChannel
This is a channel that operates indirectly through another channel(s).
Definition: indchan.h:49
PCLI::Context::OnStop
virtual void OnStop()
Callback for when context is stopping.
PCaselessString
This class is a variation of a string that ignores case.
Definition: pstring.h:1708
PCLI::Context::m_commandHistory
PStringList m_commandHistory
Definition: cli.h:169
PCLI::OnReceivedLine
virtual void OnReceivedLine(Arguments &line)
Received a completed command line.
PCLIStandard::PCLIStandard
PCLIStandard(const char *prompt=NULL)
Create new command line interpreter for standard I/O.
PCLI::Context::Context
Context(PCLI &cli)
Construct new command line interpreter context.
PCLI::m_username
PString m_username
Definition: cli.h:544
PCLI::Context::IsProcessingCommand
bool IsProcessingCommand() const
Indicate is currently processing a command.
Definition: cli.h:160
PCLI::SetCommandErrorPrefix
void SetCommandErrorPrefix(const PString &commandErrorPrefix)
Set error prefix for if Arguments::WriteError() called.
Definition: cli.h:515
PCLI::InternalCommand::m_notifier
PNotifier m_notifier
Definition: cli.h:557
PCLI::GetUnknownCommandError
const PString & GetUnknownCommandError() const
Get error message for if unknown command is entered.
Definition: cli.h:520
PCLI::Start
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
PCLI::Context::Start
bool Start()
Start a command line interpreter thread.
PCLI::Context::~Context
virtual ~Context()
Destroy command line interpreter context.
PCLI::GetUsername
const PString & GetUsername() const
Get username for log in validation.
Definition: cli.h:418
PCLI::m_commands
CommandMap_t m_commands
Definition: cli.h:562
PBoolean
BOOL PBoolean
Definition: object.h:102
PCLISocket::RemoveContext
virtual void RemoveContext(Context *context)
Remove the command line interpreter context.
PCLI::m_requireEcho
bool m_requireEcho
Definition: cli.h:539
PCLI::GetHelpOnHelp
const PString & GetHelpOnHelp() const
Get help on help.
Definition: cli.h:459
PCLI::GetCommandUsagePrefix
const PString & GetCommandUsagePrefix() const
Get usage prefix for if Arguments::WriteUsage() called.
Definition: cli.h:500
PCLI::GarbageCollection
virtual void GarbageCollection()
Remove any closed command line interpreter contexts.
PCLI::Context
Context for command line interpreter.
Definition: cli.h:64
PCLI::SetUsernamePrompt
void SetUsernamePrompt(const PString &prompt)
Set prompt used for login (if enabled).
Definition: cli.h:403
PCLI::m_noHistoryError
PString m_noHistoryError
Definition: cli.h:551
PCLISocket::HandleSingleThreadForAll
bool HandleSingleThreadForAll()
PCLISocket::m_singleThreadForAll
bool m_singleThreadForAll
Definition: cli.h:669
PCLISocket::Start
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
PCLI::Context::State
State
Definition: cli.h:172
PCLI::SetCommandUsagePrefix
void SetCommandUsagePrefix(const PString &commandUsagePrefix)
Set usage prefix for if Arguments::WriteUsage() called.
Definition: cli.h:505
PCLI::StartContext
bool StartContext(PChannel *channel, bool autoDelete=true, bool runInBackground=true)
Open a command line interpreter context.
PCLISocket::ContextMap_t
std::map< PSocket *, Context * > ContextMap_t
Definition: cli.h:674
PCLI::SetNoHistoryError
void SetNoHistoryError(const PString &noHistoryError)
Set error message for if there is no history.
Definition: cli.h:495
PCLI::Arguments::m_usage
PString m_usage
Definition: cli.h:217
PCLISocket::PDECLARE_NOTIFIER
PDECLARE_NOTIFIER(PThread, PCLISocket, ThreadMain)
PCLITelnet::CreateSocket
virtual PTCPSocket * CreateSocket()
PCLI::GetPassword
const PString & GetPassword() const
Get password for log in validation.
Definition: cli.h:428
PChannel
Abstract class defining I/O channel semantics.
Definition: channel.h:107
PCLI::PCLI
PCLI(const char *prompt=NULL)
Contracut a new command line interpreter.
PCLI::SetPasswordPrompt
void SetPasswordPrompt(const PString &prompt)
Set prompt used for password (if enabled).
Definition: cli.h:413
PCLI::m_editCharacters
PString m_editCharacters
Definition: cli.h:540
PCLI::Broadcast
void Broadcast(const PString &message) const
Set a string to all command line interpreter contexts.
PCLI::m_unknownCommandError
PString m_unknownCommandError
Definition: cli.h:554
PCLI::GetNoHistoryError
const PString & GetNoHistoryError() const
Get error message for if there is no history.
Definition: cli.h:490
PCLIStandard
Command Line Interpreter over standard input/output.
Definition: cli.h:572
PCLI::Context::ProcessInput
virtual bool ProcessInput(int ch)
Process a character read from the channel.
PCLIStandard::Start
virtual bool Start(bool runInBackground=true)
Start a command line interpreter.
PCLI::SetNewLine
void SetNewLine(const PString &newLine)
Set new line string output at the end of every line.
Definition: cli.h:363
PCLI::Context::PDECLARE_NOTIFIER
PDECLARE_NOTIFIER(PThread, Context, ThreadMain)
PCLI::m_commandUsagePrefix
PString m_commandUsagePrefix
Definition: cli.h:552
PString
The character string class.
Definition: pstring.h:108
PCLI::GetRepeatCommand
const PCaselessString & GetRepeatCommand() const
Get the command to be used to repeat the last executed command.
Definition: cli.h:470
PCLI::InternalCommand::m_usage
PString m_usage
Definition: cli.h:559
PCLI::SetPassword
void SetPassword(const PString &password)
Set password for log in validation.
Definition: cli.h:433
PCLI::GetUsernamePrompt
const PString & GetUsernamePrompt() const
Get prompt used for login (if enabled).
Definition: cli.h:398
PCLI::Arguments::WriteError
Context & WriteError(const PString &error=PString::Empty())
Write an error to the CLI output channel.
PTCPSocket
A socket that uses the TCP transport on the Internet Protocol.
Definition: tcpsock.h:44
PCLI::Arguments::WriteUsage
Context & WriteUsage()
Write to the CLI output channel the usage for the current command.
PCLI::SetRepeatCommand
void SetRepeatCommand(const PCaselessString &repeatCommand)
Set the command to be used to repeat the last executed command.
Definition: cli.h:475
PCLI::Context::m_enteredUsername
PString m_enteredUsername
Definition: cli.h:178
PString::Empty
static PString Empty()
Return an empty string.
PCLISocket::m_contextBySocket
ContextMap_t m_contextBySocket
Definition: cli.h:675
PCLISocket::~PCLISocket
~PCLISocket()
PCLI::Arguments::m_context
Context & m_context
Definition: cli.h:215
PArgList
This class allows the parsing of a set of program arguments.
Definition: args.h:45
PCLIStandard::StartForeground
PCLI::Context * StartForeground()
Initialise a foreground context and return it.
PCLI::Context::m_state
enum PCLI::Context::State m_state
PCLI::GetHistoryCommand
const PCaselessString & GetHistoryCommand() const
Get command that will list/execute command history.
Definition: cli.h:480
PCLI::m_repeatCommand
PCaselessString m_repeatCommand
Definition: cli.h:549
PCLI::InternalCommand::m_help
PString m_help
Definition: cli.h:558
PCLISocket::GetPort
WORD GetPort() const
Get the port we are listing on.
Definition: cli.h:660
PCLI::Context::m_commandLine
PString m_commandLine
Definition: cli.h:167
PCLI::Context::Write
virtual PBoolean Write(const void *buf, PINDEX len)
Low level write to the channel.
PCLI::Context::m_ignoreNextEOL
bool m_ignoreNextEOL
Definition: cli.h:168
PCLI::SetUnknownCommandError
void SetUnknownCommandError(const PString &unknownCommandError)
Set error message for if unknown command is entered.
Definition: cli.h:525
PCLI::GetRequireEcho
bool GetRequireEcho() const
Get flag for echo is required for entered characters.
Definition: cli.h:368
PThread
This class defines a thread of execution in the system.
Definition: thread.h:66
PStringList
This is a list collection class of PString objects.
Definition: pstring.h:2184
PCLI::CommandMap_t
std::map< PString, InternalCommand > CommandMap_t
Definition: cli.h:561
PCLITelnet::PCLITelnet
PCLITelnet(WORD port=0, const char *prompt=NULL, bool singleThreadForAll=false)
PCLI::Context::e_ProcessingCommand
Definition: cli.h:176
PCLI::m_helpCommand
PCaselessString m_helpCommand
Definition: cli.h:547
PCLI::SetCommand
bool SetCommand(const char *command, const PNotifier &notifier, const char *help=NULL, const char *usage=NULL)
Register a new command to be interpreted.
PCLISocket::PCLISocket
PCLISocket(WORD port=0, const char *prompt=NULL, bool singleThreadForAll=false)
PCLI::m_contextList
ContextList_t m_contextList
Definition: cli.h:565
PCLI::Context::Stop
void Stop()
Stop command line interpreter context.
PCLISocket::HandleIncoming
bool HandleIncoming()
PCLI::CreateContext
virtual Context * CreateContext()
Create a new context.
PCLI::Stop
virtual void Stop()
Stop and clean up command line interpreters.
PCLI::Context::m_cli
PCLI & m_cli
Definition: cli.h:166
PCLISocket
Command Line Interpreter over TCP sockets.
Definition: cli.h:603
PCLI::Context::m_thread
PThread * m_thread
Definition: cli.h:170
PCLITelnet
Command Line Interpreter over Telnet sockets.
Definition: cli.h:683
PCLISocket::AddContext
virtual Context * AddContext(Context *context=NULL)
Add a command line interpreter context to the system.
sockets.h
PMutex
Synonym for PTimedMutex.
PCLI::Arguments::Arguments
Arguments(Context &context, const PString &rawLine)
PCLI::Context::OnStart
virtual void OnStart()
Call back frunction for when context is started.
PCLI::GetCommandErrorPrefix
const PString & GetCommandErrorPrefix() const
Get error prefix for if Arguments::WriteError() called.
Definition: cli.h:510
PCLI::m_password
PString m_password
Definition: cli.h:545
PCLI::SetPrompt
void SetPrompt(const PString &prompt)
Set prompt used for command line interpreter.
Definition: cli.h:393
PCLI::SetHelpCommand
void SetHelpCommand(const PCaselessString &helpCommand)
Set command to be used to display help.
Definition: cli.h:453
PCLI::m_commandErrorPrefix
PString m_commandErrorPrefix
Definition: cli.h:553
PCLI::Context::e_Username
Definition: cli.h:173
PCLI::SetExitCommand
void SetExitCommand(const PCaselessString &exitCommand)
Set command to be used to exit session.
Definition: cli.h:443
PCLISocket::CreateSocket
virtual PTCPSocket * CreateSocket()
PCLI::Context::e_Password
Definition: cli.h:174
PCLI::Arguments::m_command
PString m_command
Definition: cli.h:216
PObject
Ultimate parent class for all objects in the class library.
Definition: object.h:1118
PCLI
Command Line Interpreter class.
Definition: cli.h:56
PCLI::GetPasswordPrompt
const PString & GetPasswordPrompt() const
Get prompt used for password (if enabled).
Definition: cli.h:408
PCLI::StartForeground
virtual Context * StartForeground()
Initialise a foreground context and return it.
PCLI::Context::OnCompletedLine
virtual void OnCompletedLine()
Call back for a command line was completed and ENTER pressed.
PCLI::RemoveContext
virtual void RemoveContext(Context *context)
Remove the command line interpreter context.
PSocket::GetPort
WORD GetPort() const
Get the port the TCP socket channel object instance is using.
PCLI::SetRequireEcho
void SetRequireEcho(bool requireEcho)
Set flag for echo is required for entered characters.
Definition: cli.h:373
PCLISocket::Listen
bool Listen(WORD port=0)
Start listening socket.
PCLI::OnLogIn
virtual bool OnLogIn(const PString &username, const PString &password)
Received a login name/pasword to be verified.
PCLI::Context::GetCLI
PCLI & GetCLI() const
Get the CLI.
Definition: cli.h:156