CMD/CMD_Manager.h

Go to the documentation of this file.

/*
 * PROPRIETARY INFORMATION.  This software is proprietary to
 * Side Effects Software Inc., and is not to be reproduced,
 * transmitted, or disclosed in any way without written permission.
 *
 * Produced by:
 *      Mark Elendt
 *      Side Effects Software Inc.
 *      20 Maud St.
 *      Toronto, Ontario,  M5V 2M5
 *      Canada
 *      416-366-4607
 *
 * NAME:        Command library (C++)
 *
 * COMMENTS:    Handle command parsing for expansion.
 *      The command manager class also contains the interface to the
 *      long operation interrupt mechanism.
 *
 */

#ifndef __CMD_Manager_H__
#define __CMD_Manager_H__

#include "CMD_API.h"
#include <iostream.h>
#include <UT/UT_Assert.h>
#include <UT/UT_String.h>
#include <UT/UT_StringArray.h>
#include <UT/UT_PtrArray.h>
#include <UT/UT_SymbolTable.h>
#include <CH/CH_Manager.h>
#if !defined(GAMEOS)
#include <UT/UT_Spawn.h>
#endif
#include <FS/FS_ServerSocketListener.h>
#include "CMD_Command.h"
#include "CMD_Source.h"
#include "CMD_Variable.h"

class UT_WorkArgs;
class CH_AutoEventHandler;
class CMD_Args;
class CMD_Loop;
class CMD_AliasTable;
class CMD_Manager;
class CMD_Command;

extern "C" {
   DLLEXPORT extern void CMDextendLibrary(CMD_Manager *theManager);
}

typedef void (*CMD_PostCmdCallback)(void *userdata);
typedef void (*CMD_CommandEchoCallback)(const char *echo_line,void *userdata);

typedef UT_PtrArray<CMD_Command *>      CMD_CommandList;
typedef UT_PtrArray<CMD_Source *>       CMD_SourceStack;
typedef UT_PtrArray<char *>             CMD_PromptStack;

#define CMD_STATUS_VARIABLE "status"

class CMD_API CMD_Manager : public CH_Manager {
public:
     CMD_Manager(const char *appname, int load_dsos = 1);
    virtual ~CMD_Manager();

    virtual void         setContext();
    // this command won't assert
    static bool          getContextExists() { return theManager != NULL; }
    static CMD_Manager  *getContext()
                         {
                            UT_ASSERT( theManager );
                            return theManager;
                         }

    //  Send input to the command manager.  If the command is complete,
    //  the command will be executed, otherwise there will be input pending
    //  with the remainder of the input sitting in a buffer until there's
    //  a full command...
    void                 sendInput(const char *input, bool create_block = true);
    // This version splits the input into lines and sends them to the single
    // line sendInput. We need a non-const char * so we can avoid copying the
    // data. The conents of the string are modified, and then restored, so
    // you don't actually have to worry about the string being modified.
    void                 sendMultiLineInput(char *input,
                                            bool create_block = true);

    //  Force execution of a command
    void                 execute(const char *cmd, int addToHistory = 0,
                                 ostream *out=0, ostream *err=0,
                                 int doAliasExpansion = 1,
                                 bool create_block = true);

    // Try to complete the given command to the longest common string.
    // If an exact match is found, append a " ".
    void                 completeCommand(const char *prefix, 
                                         UT_String &command) const;

    void                 matchCommands(const char *prefix,
                                       UT_StringArray &matches) const;

    //  Install a command into the command list, chaining will return
    //  a pointer to the previous command if it existed, nil if not
    void                 installCommand(const char *name, const char *options,
                                CMD_Callback cb, bool is_safe = true);

    //  Install a callback that gets executed after every command. 
    //  'userdata' is passed on each call to the callback.
    //  Returns the previous installed post command callback.
    CMD_PostCmdCallback  setPostCmdCallback(
                                CMD_PostCmdCallback callback, void *userdata);
    void *               getPostCmdCallbackData() const
                            { return myPostCmdCallbackData; }

    // Install a callback that gets run after every command is echoed,
    // if echoing is turned on.  Your callback may never keep a pointer to
    // the data that is passed in.
    void                 setCommandEchoCallback(
                                CMD_CommandEchoCallback callback,
                                void *userdata);
    void *               getCommandEchoCallbackData() const
                            { return myCommandEchoCallbackData; }

    //  Remove a command from the command list
    void                 commandDump(ostream &os, const char *pattern=0,
                                    const char *prefix=0) const;
    void                 commandHelp(ostream &os, const char *cmd) const;
    void                 searchHelp(CMD_CommandList &list,
                                    const char *filename,
                                    const char *pattern) const;
    // Note this only prints exact matches to the help.
    void                 printHelp(ostream &os, const char *filename,
                                   const char *pattern = 0) const;
    void                 saveAliases(ostream &os);
    void                 saveVariables(ostream &os);

    int                  setHistoryCapture(int onOff)
                         {
                             int        prev = myHistoryCapture;
                             myHistoryCapture = onOff;
                             return prev;
                         }
    CMD_Source          *pushSource(const char *filename, int verbose=0);
    CMD_Source          *popSource(int checkLoop = 1);
    CMD_Source          *getSource()
                         {
                            UT_ASSERT(mySourceStack.entries());
                            return mySourceStack(mySourceStack.entries()-1);
                         }
    int                  getSourceLevel() { return mySourceStack.entries()-1; }

    void                 pushOutputStreams(ostream &out, ostream &err);
    void                 popOutputStreams();

    void                 unsetVariable(const char *name);
    void                 resetVariables();
    void                 setVariable(const char *name, const char *value,
                                        int local, int uplevel=0);

    bool                 hasVariable(const char *name) const;
    bool                 getVariable(const char *name, UT_String &value)
                            { return getVariableValueByName(name, value); }
    bool                 getVariable(const char *name, float &value)
                            { return getVariableValueByName(name, value); }
    bool                 getVariable(const char *name, int &value)
                            { return getVariableValueByName(name, value); }

    bool                 hasEnv(const char *name) const;
    bool                 getEnv(const char *name, UT_String &value);
    void                 getVariableNames(UT_StringArray &names, int dirty=0);
    int                  clearDirtyVariables();
    int                  isVariableNameOk(const char *name);

    void                 setMotName(const char *path);
    void                 setJob(const char *path);

    // Return the number of commands run.  It's possible for this to overflow
    unsigned             getCommandsRun() const { return myCommandCount; }

    ostream             &getError(int printMessage = 1);

    //  These two return pointers to their previous streams so that
    //  you can restore them if you need to:
    ostream             *setStandardOut(ostream &os);
    ostream             *setStandardErr(ostream &os);
    // Call this if you are deleting a stream that was previously used
    // in a call to setStandard[Out|Err].
    void                 streamDeleted(ostream &os);

    void                 setPrompt(const char *prompt);
    const char          *getPrompt(int level = -1) const
                         {
                             if (level < 0 || level >= myPromptStack.entries())
                                 level = myPromptStack.entries()-1;
                            return myPromptStack(level);
                         }
    void                 pushPrompt(const char *prompt);
    void                 popPrompt();

    int                  isLoopCommand(const char *str);

    int                  evaluateCondition(const char *expr);
    int                  evaluateCondition(int argc, const char *argv[]);

    // These two functions are inverses of each other. If the string is
    // written out using saveProtectedString(), then you MUST use
    // expandControlSequences() when loading the string back in.
    static void          saveProtectedString(ostream &os, const char *s);
    static void          expandControlSequences(UT_String &str);

    void                 dumpHistory(ostream &os) const;
    void                 clearHistory();

    // Index 0 is most recent command:
    const char          *getHistoryCommand(int n) const;
    unsigned int         getHistoryCount() const;

    CMD_VariableTable   *getGlobalVariables() { return myGlobals; }
    CMD_AliasTable      *getAliases() { return myAliases; }
    bool                 getAlias(const char *name, UT_String &value);
    void                 setAlias(const char *name, const char *value);
    void                 destroyAlias(const char *name);
    void                 destroyAliases();


    /// Specify whether a global hscript variable may be overwritten by an
    /// environment variable's value when loading the hip file, instead of
    /// just using the value saved in the hip file.
    void                 allowEnvironmentToOverwriteVariable(
                            const char *name, bool onoff);
    /// Should we use the environment variable value when loading this variable
    /// from the hip file?
    bool                 isEnvironmentAllowedToOverwriteVariable(
                            const char *name);
    /// Say that we're loading the global variables from a hip file or that
    /// we're done loading them.
    void                 setIsLoadingGlobalVariables(bool onoff)
                         { myIsLoadingGlobalVariables = onoff; }
    /// Are we loading global variables from the hip file?
    bool                 isLoadingGlobalVariables()
                         { return myIsLoadingGlobalVariables; }

    void                 saveCommandString(ostream &os, const UT_String &str);

    // Now, here, we provide some nice functions to handle getting arguments
    void                 getFrameRange(CMD_Args &args,
                                        int &fstart, int &fend, int &finc,
                                        char oframe = 'f', char ofinc = 'i');

    void                 setContinueLevel(int level) { myContinueLevel=level; }
    int                  getContinueLevel() const { return myContinueLevel; }
    void                 bumpBreakLevel(int dir) { myBreakLevel += dir; }
    int                  getBreakLevel() const { return myBreakLevel; }
    void                 bumpLoopNestLevel(int dir)
                         {
                             myLoopNestLevel += dir;
                             if (!myLoopNestLevel)
                             {
                                myBreakLevel = 0;
                             }
                         }
    int                  getLoopNestLevel() const { return myLoopNestLevel; }
    CMD_Loop            *buildLoop(const char *text);
    void                 doPrompt();
    void                 getPrompt(UT_String &str);

    void                 setVerbose(int on_off);
    int                  getVerbose() const;

    void                 setCommandEcho(bool on_off)
                                                { myCommandEchoFlag = on_off; }
    bool                 getCommandEcho() const { return myCommandEchoFlag; }

    void                 setIORedirection(int on_off);
    int                  getIORedirection() const;

    const char          *getOptions(const char *cmdName); 

    int                  isCommandDefined(const char *name)
                         {
                             return findCommand(name, 1) >= 0;
                         }
    void                 getDSOCommands(CMD_CommandList &list);

    bool                 isLoading() const { return (myInLoadCount > 0); }
    void                 beginLoading() { myInLoadCount++; }
    void                 endLoading()   { myInLoadCount--; }

    void                 setSafeMode(int safe_mode);
    int                  isInSafeMode() const;
    void                 setBrowserMode(int browser_mode);
    int                  isInBrowserMode() const;

    void                 setStatusCode( int status_code )
                         { myStatusCode = status_code; }
    int                  getStatusCode() const
                         { return myStatusCode; }

    // The following versions of openPort vary slightly from one another.
    // Some versions take CMD_Args for error output while some take
    // an ostream.  Some versions take a const char * for the command to
    // execute, while others take a "const char *const*" array of arguments
    // for the command.
    //
    // Note that if we're told to execute a program, the port will be closed
    // when the program exits.
    bool                 openPort(int port, bool safe, bool quiet,
                                  bool wait, CMD_Args &args,
                                  const char *execute, pid_t *pid,
                                  bool separateerrors, bool suppress = true,
                                  const char *ip_mask = 0,
                                  FS_ServerSocketListener::ChildExitedCallback
                                                child_exited_callback = 0,
                                  bool detach_console_for_execute=false,
                                  bool drain_queue_when_waiting_for_exec=true);
    bool                 openPort(int port, bool safe, bool quiet,
                                  bool wait, ostream &error_output,
                                  const char *execute, pid_t *pid,
                                  bool separateerrors, bool suppress = true,
                                  const char *ip_mask = 0,
                                  FS_ServerSocketListener::ChildExitedCallback
                                                child_exited_callback = 0,
                                  bool detach_console_for_execute=false,
                                  bool drain_queue_when_waiting_for_exec=true);
    bool                 openPort(int port, bool safe, bool quiet,
                                  bool wait, CMD_Args &args,
                                  const char *const*execute_argv, pid_t *pid,
                                  bool separateerrors, bool suppress = true,
                                  const char *ip_mask = 0,
                                  FS_ServerSocketListener::ChildExitedCallback
                                                child_exited_callback = 0,
                                  bool detach_console_for_execute=false,
                                  bool drain_queue_when_waiting_for_exec=true);
    bool                 openPort(int port, bool safe, bool quiet,
                                  bool wait, ostream &error_output,
                                  const char *const*execute_argv, pid_t *pid,
                                  bool separateerrors, bool suppress = true,
                                  const char *ip_mask = 0,
                                  FS_ServerSocketListener::ChildExitedCallback
                                                child_exited_callback = 0,
                                  bool detach_console_for_execute=false,
                                  bool drain_queue_when_waiting_for_exec=true);

    void                 closePort(int port);
    void                 closeAutoPort();

    bool                 beginChannelBlock();
    bool                 endChannelBlock();

    void                 echoOff();
    void                 echoOn();

    // Retrieve an automatically-generated port via openport -a
    // Will be the same from call to call unless the port is closed
    static int           getHScriptPort();

    // Command for handling python command. This is a static public function
    // so that the overridden version can call this default
    // implementation depending on the command format.
    static void          cmd_python(CMD_Args &args);

protected:
    virtual bool         getVariableString(const char *name, UT_String &value,
                                           int &timeDepend, int thread);

private:
    template <typename T> bool
                         getVariableValueByName(const char *name, T &value);

    void                 internalSendInput(const char *input,
                                           bool run_pushed_source=false);
    // Commands for handling if statements
    static void          cmd_if   (CMD_Args &args);
    static void          cmd_else (CMD_Args &args);
    static void          cmd_endif(CMD_Args &args);
    static void          cmd_read (CMD_Args &args);

    // This version of openPort() is called by the public versions.
    bool                 openPort(int port, bool safe, bool quiet,
                                  bool wait, CMD_Args *args,
                                  ostream *error_output,
                                  const char *const*execute_argv, pid_t *pid,
                                  bool separateerrors, bool suppress,
                                  const char *ip_mask,
                                  FS_ServerSocketListener::ChildExitedCallback
                                                child_exited_callback,
                                  bool detach_console_for_execute,
                                  bool drain_queue_when_waiting_for_exec=true);
    // Find a cmd for me, if exact is specified, the command has to match
    // exactly.
    void                 processInput(CMD_Source *top, const char *line);
    void                 internalExecute(const char *str);
    void                 runCommand(char *str);
    void                 initLibraryGlue(void);
    void                 setGlueContext();
    void                 setPortContext();
    int                  findCommand(const char *name, int exact = 0);
    void                 sortCommands(void);
    void                 installBaseCommands(void);
    void                 addPortExtension();
    CMD_CommandList     *getCommandList(const char *list_name);
    void                 installBuiltIn();
    int                  aliasExpand(UT_String &str);
    void                 setReadVariables(const char *str);
    void                 breakAllSources();
    void                 updateNoAliasVariable();
    void                 pushStandardOut(ostream *os);
    void                 popStandardOut();
    void                 pushStandardErr(ostream *os);
    void                 popStandardErr();
    void                 updateStatusVariable();

    // Process the options for the command, stripping them out and returning
    // the new argc.
    void         stripOptions(const CMD_Command *cmd, CMD_Args &args);

    CMD_CommandList             *myCmdList;
    CMD_PromptStack              myPromptStack;
    UT_String                    myPendingCommands;
    UT_String                    myReadVariables;
    int                          myReadVariablesLocal;
    UT_SymbolTable              *myExactList;
    CMD_SourceStack              mySourceStack;
    CMD_VariableTable           *myGlobals;
    UT_SymbolTable               myEnvironmentOverridableGlobals;
    bool                         myIsLoadingGlobalVariables;
    CMD_AliasTable              *myAliases;
    UT_PtrArray<ostream *>       myStandardOuts;
    UT_PtrArray<ostream *>       myStandardErrs;
    unsigned                     myCommandCount;
    int                          myAliasProtect;        // No alias expansion
    int                          myFlags;
    int                          myBreakLevel;
    int                          myContinueLevel;
    int                          myLoopNestLevel;
    int                          myLocalSetLevel;
    int                          myExecuteCommandStack;
    int                          myStatusCode;
    unsigned                     myAliasExpand:1,
                                 myHistoryExpand:1,
                                 myHistoryCapture:1,
                                 myIsInSafeMode:1,
                                 myIsInBrowserMode:1;
    UT_String                    myAppName;
    UT_String                    myUnfinishedInput;

    int                          myInLoadCount;
    int                          myEchoOff;

    CMD_PostCmdCallback          myPostCmdCallback;
    void                        *myPostCmdCallbackData;

    // Support for command echoing
    CMD_CommandEchoCallback      myCommandEchoCallback;
    void                        *myCommandEchoCallbackData;

    // The command echo flag tells us whether or not to echo every command
    // back out to the stdout.  The myOldCommandEchoFlag is used to remember
    // our state so that we can turn off command echoing during a source.
    bool                         myCommandEchoFlag;

    static CH_AutoEventHandler  *theCHEventHandler;
    static int                   theChannelBlockCount;
    static CMD_Manager          *theManager;
};

inline
CMD_Manager *CMDgetManager()
{
    return CMD_Manager::getContext();
}

//////////////////////////////////////////////////////////////////////////////
//
// Inline definitions
//

template <typename T> bool
CMD_Manager::getVariableValueByName(const char *name, T &value)
{
    CMD_Source          *src;
    CMD_VariableTable   *table;
    int                  i;

    for (i = mySourceStack.entries()-1; i >= 0; i--)
    {
        src = mySourceStack(i);
        table = src->getLocalVariables();
        if (table->getVariable(name, value))
            return true;
    }
    return myGlobals->getVariable(name, value);
}

#endif

---