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: 28621 $
 * $Author: rjongbloed $
 * $Date: 2012-12-03 13:33:10 +1100 (Mon, 03 Dec 2012) $
 */

#ifndef PTLIB_CLI_H
#define PTLIB_CLI_H

#include <ptbuildopts.h>

#if P_CLI

#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();

        bool Run();

        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_usage;

      friend class PCLI;
    };


    PCLI(
      const char * prompt = NULL
    );

    virtual ~PCLI();

    virtual bool Start(
      bool runInBackground = true   
    );

    virtual void Stop();

    Context * StartContext(
      PChannel * channel,           
      bool autoDelete = true,       
      bool runInBackground = true   
    ) { return StartContext(channel, channel, autoDelete, autoDelete, runInBackground); }
    Context * StartContext(
      PChannel * readChannel,      
      PChannel * writeChannel,     
      bool autoDeleteRead = true,  
      bool autoDeleteWrite = true, 
      bool runInBackground = true   
    );

    virtual Context * StartForeground();

    bool Run(
      PChannel & channel            
    ) { return Run(&channel, &channel, false, false); }
    bool Run(
      PChannel * channel,           
      bool autoDelete = true        
    ) { return Run(channel, channel, autoDelete, autoDelete); }
    bool Run(
      PChannel * readChannel,      
      PChannel * writeChannel,     
      bool autoDeleteRead = true,  
      bool autoDeleteWrite = true  
    );

    bool RunContext(
      Context * context
    ) { return context != NULL && context->Run(); }

    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,  
      const char * argSpec = 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 & GetCommentCommand() const { return m_commentCommand; }

    void SetCommentCommand(const PCaselessString & commentCommand) { m_commentCommand = commentCommand; }

    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; }


  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_commentCommand;
    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;
      PString   m_argSpec;
    };
    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 Context * StartForeground();

    bool RunScript(
      PChannel & channel            
    ) { return RunScript(&channel, false); }
    bool RunScript(
      PChannel * channel,           
      bool autoDelete = true        
    );
};


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;
};


#if P_TELNET

class PCLITelnet : public PCLISocket
{
  public:
    PCLITelnet(
      WORD port = 0,
      const char * prompt = NULL,
      bool singleThreadForAll = false
    );

  protected:
    virtual PTCPSocket * CreateSocket();
};
#endif // P_TELNET

#endif // P_CLI

#endif // PTLIB_CLI_H


// End Of File ///////////////////////////////////////////////////////////////