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
 */

#ifndef PTLIB_CLI_H
#define PTLIB_CLI_H

#include <ptlib.h>

#if P_CLI

#include <ptlib/sockets.h>
#include <ptclib/vartype.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 EchoInput(char ch);

        virtual void OnCompletedLine();

        virtual bool GetTerminalSize(
          unsigned & rows,
          unsigned & columns
        );

        virtual void Broadcast(
          const PString & message  
        );

        PCLI & GetCLI() const { return m_cli; }

        bool IsProcessingCommand() const { return m_state == e_ProcessingCommand; }

      protected:
        PDECLARE_NOTIFIER(PThread, Context, ThreadMain);
        bool InternalMoveCursor(bool left, PINDEX count);
        bool InternalEchoCommandLine(PINDEX echoPosition, PINDEX moveLeftCount);
        bool InternalMoveHistoryCommand(int direction);
        bool InternalWrite(const char * str, PINDEX len, PINDEX & written);

        PCLI      & m_cli;
        PString     m_commandLine;
        PINDEX      m_editPosition;
        bool        m_ignoreNextEOL;
        PStringList m_commandHistory;
        PINDEX      m_historyPosition;
        PThread   * m_thread;
        int         m_pagedLines;

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

    bool SetCommand(
      const char * command,       
      bool & value,               
      const char * name,          
      const char * help = NULL,   
      const PNotifier & notifier = PNotifier() 
    );

    bool SetCommand(
      const char * command,       
      const PVarType & value,     
      const char * name,          
      const PVarType & minValue,  
      const PVarType & maxValue,  
      const char * help = NULL,   
      const PNotifier & notifier = PNotifier() 
    );

    template <typename TYPE>
    bool SetCommand(
      const char * command,        
      TYPE & value,                
      const char * name,           
      TYPE minValue,               
      TYPE maxValue = INT_MAX,     
      const char * help = NULL,    
      const PNotifier & notifier = PNotifier() 
    )
    {
      return SetCommand(command, PRefVar<TYPE>(value), name, minValue, maxValue, help, notifier);
    }

    virtual void ShowHelp(
      Context & context,        
      const PArgList & partial  
    );

    const PString & GetNewLine() const { return m_newLine; }

    void SetNewLine(const PString & newLine);

    bool GetRequireEcho() const { return m_requireEcho; }

    void SetRequireEcho(bool requireEcho) { m_requireEcho = requireEcho; }

    const PIntArray & GetEditCodes() const { return m_editCodes; }

    void SetEditCodes(const PIntArray & editCodes) { m_editCodes = editCodes; }

    const PIntArray & GetEraseCodes() const { return m_eraseCodes; }

    void SetEraseCodes(const PIntArray & eraseCodes) { m_eraseCodes = eraseCodes; }

    const PIntArray & GetLeftCodes() const { return m_leftCodes; }

    void SetLeftCodes(const PIntArray & leftCodes) { m_leftCodes = leftCodes; }

    const PIntArray & GetRightCodes() const { return m_rightCodes; }

    void SetRightCodes(const PIntArray & rightCodes) { m_rightCodes = rightCodes; }

    const PIntArray & GetBeginCodes() const { return m_beginCodes; }

    void SetBeginCodes(const PIntArray & beginCodes) { m_beginCodes = beginCodes; }

    const PIntArray & GetEndCodes() const { return m_endCodes; }

    void SetEndCodes(const PIntArray & endCodes) { m_endCodes = endCodes; }

    const PIntArray & GetPrevCmdCodes() const { return m_prevCmdCodes; }

    void SetPrevCmdCodes(const PIntArray & prevCmdCodes) { m_prevCmdCodes = prevCmdCodes; }

    const PIntArray & GetNextCmdCodes() const { return m_nextCmdCodes; }

    void SetNextCmdCodes(const PIntArray & nextCmdCodes) { m_nextCmdCodes = nextCmdCodes; }

    void SetAutoFillCodes(const PIntArray & autoFillCodes) { m_autoFillCodes = autoFillCodes; }

    const PIntArray & GetAutoFillCodes() const { return m_autoFillCodes; }

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

    const PString & GetAmbiguousCommandError() const { return m_ambiguousCommandError; }

    void SetAmbiguousCommandError(const PString & ambiguousCommandError) { m_ambiguousCommandError = ambiguousCommandError; }

    const PCaselessString & GetScriptCommand() const { return m_scriptCommand; }

    void SetScriptCommand(const PCaselessString & scriptCommand) { m_scriptCommand = scriptCommand; }

    const PString & GetNoScriptError() const { return m_noScriptError; }

    void SetNoScriptError(const PString & noScriptError) { m_noScriptError = noScriptError; }

    int GetPagerLines() const { return m_pagerLines; }

    void SetPagerLines(int lines) { m_pagerLines = lines; }

    const PString & GetPageWaitPrompt() const { return m_pagerWaitPrompt; }

    void SetPageWaitPrompt(const PString & prompt) { m_pagerWaitPrompt = prompt; }

    const PString & GetPagerCommand() const { return m_pagerCommand; }

    void SetPagerCommand(const PString & cmd) { m_pagerCommand = cmd; }


  protected:
    PString         m_newLine;
    bool            m_requireEcho;
    PIntArray       m_editCodes;
    PIntArray       m_eraseCodes;
    PIntArray       m_leftCodes;
    PIntArray       m_rightCodes;
    PIntArray       m_beginCodes;
    PIntArray       m_endCodes;
    PIntArray       m_prevCmdCodes;
    PIntArray       m_nextCmdCodes;
    PIntArray       m_autoFillCodes;
    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;
    PString         m_ambiguousCommandError;
    PCaselessString m_scriptCommand;
    PString         m_noScriptError;
    int             m_pagerLines;
    PString         m_pagerWaitPrompt;
    PCaselessString m_pagerCommand;

    virtual bool InternalPageWait(Context & context);

    struct InternalCommand
    {
      InternalCommand(const PNotifier & notifier, const char * help, const char * usage, const char * argSpec, const char * varName);
      InternalCommand(const InternalCommand & other);
      ~InternalCommand();
      bool IsMatch(const PArgList & args, bool partial = false) const;
      bool operator<(const InternalCommand & other) const;

      PStringArray m_words;
      PString      m_command;
      PNotifier    m_notifier;
      PString      m_help;
      PString      m_usage;
      PString      m_argSpec;
      PString      m_varName;
      PVarType   * m_variable;
      PVarType   * m_minimum;
      PVarType   * m_maximum;
    };
    typedef std::set<InternalCommand> Commands_t;
    Commands_t m_commands;
    bool InternalSetCommand(const char * commands, const InternalCommand & info);

    virtual void OnSetBooleanCommand(Arguments & args, const InternalCommand & cmd);
    virtual void OnSetIntegerCommand(Arguments & args, const InternalCommand & cmd);

    typedef std::list<Context *> ContextList_t;
    ContextList_t  m_contextList;
    PDECLARE_MUTEX(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


#if P_CURSES

class PCLICurses : public PCLI
{
  public:
    PCLICurses();
    ~PCLICurses();

    virtual Context * StartForeground();

    virtual Context * CreateContext();

    void GetScreenSize(
      unsigned & rows,
      unsigned & cols
    ) { rows = m_maxRows; cols = m_maxCols; }

    P_DECLARE_ENUM(Borders,
      NoBorder,
      FullBorder,
      BorderAbove,
      BorderBelow,
      BorderLeft,
      BorderRight
    );

    class Window : public PChannel
    {
    protected:
      PCLICurses & m_owner;
      Borders      m_border;
      bool         m_focus;

      Window(PCLICurses & owner, Borders border);

    public:
      // Overrides from PChannel
      virtual PString GetName() const { return "CursesWindow"; }
      virtual PBoolean Write(const void * data, PINDEX length);

      // New functions
      virtual bool FillChar(
        unsigned row,
        unsigned col,
        char ch,
        unsigned count
      ) = 0;

      virtual void SetPosition(
        unsigned row,
        unsigned col
      ) = 0;
      virtual void GetPosition(
        unsigned & row,
        unsigned & col
      ) = 0;

      virtual void SetSize(
        unsigned rows,
        unsigned cols,
        Borders border = NumBorders
      ) = 0;
      virtual void GetSize(
        unsigned & rows,
        unsigned & cols,
        bool includeBorder
      ) = 0;

      virtual void SetCursor(
        unsigned row,
        unsigned col
      ) = 0;
      virtual void GetCursor(
        unsigned & row,
        unsigned & col
      ) = 0;

      virtual void Refresh() = 0;
      virtual void Clear() = 0;
      virtual void Scroll(int n = 1) = 0;

      virtual void SetFocus();
      bool HasFocus() const { return m_focus; }
    };

    Window & NewWindow(
      unsigned row,
      unsigned col,
      unsigned rows,
      unsigned cols,
      Borders border = NoBorder
    );

    void RemoveWindow(
      Window & wnd
    );

    void RemoveWindow(
      PINDEX idx
    );

    PINDEX GetWindowCount() const { return m_windows.GetSize(); }

    Window * GetWindow(
      PINDEX idx
    ) { return dynamic_cast<Window *>(m_windows.GetAt(idx)); }

    Window & operator[](PINDEX idx) const { return m_windows[idx]; }

    Window * GetFocusWindow() const;

    virtual void Refresh();

  protected:
    void Construct();

    virtual bool InternalPageWait(Context & context);

    PArray<Window> m_windows;
    unsigned       m_maxRows;
    unsigned       m_maxCols;
};
#endif // P_CURSES

#endif // P_CLI

#endif // PTLIB_CLI_H


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