menusys.h File Reference

menusys public interface More...

#include <vector>

Go to the source code of this file.

Data Structures

struct  MSYS_Thread
 Thread definition. More...
struct  MSYS_DispatchEntry
 Menu command definition. More...

Defines

#define TCHAR   char
 Character type that depends on the _UNICODE definition. Defined as char for non-Unicode builds and wchar_t (Windows) or UChar (Unix) for Unicode builds. The use of ICU as the backing implementation can be forced on Windows by defining USING_ICU.

Typedefs

typedef std::vector< TCHAR * > MSYS_Args
 Menu command handler arguments.
typedef void(*) MSYS_Handler (MSYS_Thread *aThread, MSYS_Args &aArgs)
 Menu command handler function.

Functions

bool MSYS_Process (const TCHAR *aInputFile, bool aEnableThreads)
 Start the menu system.
void MSYS_ThreadUserCreate (MSYS_Thread *aNewThread, const MSYS_Thread *aParentThread)
 Initialization of thread-specific data structures callback.
void MSYS_ThreadUserDestroy (MSYS_Thread *aThread)
 Uninitialization of thread-specific data structures callback.
void MSYS_GetPrompt (MSYS_Thread *aThread, TCHAR *aBuf, size_t aBufSiz)
 Request for current prompt callback.
void MSYS_DisplayOption (MSYS_Thread *aThread, const TCHAR *aOption, const TCHAR *aValue)
 Display an option to the user in the standard way.
bool MSYS_NeedHelp (MSYS_Thread *aThread, MSYS_Handler aHandler, MSYS_Args &aArgs, bool aShowHelp=true)
 Returns if detailed help has been requested in the arguments.
void MSYS_ShowHelp (MSYS_Thread *aThread, MSYS_Handler aHandler)
 Display summary help or detailed command help.
void MSYS_Display (MSYS_Thread *aThread, const TCHAR *aFormat,...)
 Display a string.
void MSYS_DisplayWrapped (MSYS_Thread *aThread, const TCHAR *aText)
 Display a string word-wrapped for 80 column display.

Variables

const TCHAR * MSYS_HEADER
 Create a header entry in the short help.
const MSYS_DispatchEntry MSYS_Commands []
 User supplied function table.
const TCHAR MSYS_DefaultOptionsFile []
 User supplied default configuration file.

Detailed Description

menusys public interface

Version:
1.2

Definition in file menusys.h.

Define Documentation

#define TCHAR   char

Character type that depends on the _UNICODE definition. Defined as char for non-Unicode builds and wchar_t (Windows) or UChar (Unix) for Unicode builds. The use of ICU as the backing implementation can be forced on Windows by defining USING_ICU.

On Windows the Unicode is supported natively and works interchangeably with ICU (as on Windows UChar == wchar_t). Unicode interfaces are supported on Unix only through the use of ICU.

Definition at line 127 of file menusys.h.

Typedef Documentation

typedef std::vector<TCHAR*> MSYS_Args

Menu command handler arguments.

Arguments to every command handler will be parsed out of the command line and supplied to the command handler in this array.

Definition at line 136 of file menusys.h.

typedef void(*) MSYS_Handler(MSYS_Thread *aThread, MSYS_Args &aArgs)

Menu command handler function.

Every menu command is implemented using one of these handlers. The command is looked up in the dispatch table (see MSYS_Commands) and called passing it the supplied parameters. Errors should be notified to the user via display text.

Handlers should be implemented similar to:

extern void
ThisHandlerFunction(
    MSYS_Thread *   aThread,
    MSYS_Args &     aArgs
    )
{
    if (MSYS_NeedHelp(aThread, ThisHandlerFunction, aArgs)) {
        Display extra detailed help that is not included in the longHelp entry
        return;
    }

    if (aArgs are invalid) {
        MSYS_Display(aThread, _T("Invalid arguments. See help for details.\n"));
        return;
    }

    general implementation
}

For more powerful command argument parsing, SimpleOpt can be used with the aArgs array. This allows simple parsing of complex command lines into options, arguments and files. See the SimpleOpt documentation for details.

CSimpleOpt args(aArgs.size(), &*aArgs.begin(), rgOptions, SO_O_USEALL);
while (args.Next()) {
    ...
}

Parameters:
aThread Thread requesting the prompt. If threads have not been enabled, this will always be the main thread.
aArgs Arguments supplied to the command.

Definition at line 213 of file menusys.h.

Function Documentation

void MSYS_Display ( MSYS_Thread *  aThread,
const TCHAR *  aFormat,
  ... 
)

Display a string.

Thread-safe display of text to the console and writing to the tee file when it is enabled. Additionally, this function will replace thread keywords with the actual thread details when thread handling is enabled.

The thread keywords that are replaced are:
{{THREADID}} Numeric thread ID.
{{THREADNAME}} Thread name as assigned at thread creation.

Parameters:
aThread Thread as supplied to the command handler.
aFormat Format string the same as used by printf(). Note that the string character format uses the Windows style of:
TCHAR argument format spec
char char s
wchar_t wchar_t s
char wchar_t S
wchar_t char S

Definition at line 1138 of file menusys.cpp.

References DISPLAY_OUTPUT, OutputToConsole(), OutputToTeeFile(), and StringReplacements().

Referenced by Dispatch(), DoChdir(), DoEcho(), DoExit(), DoHelp(), DoLoop(), DoProc(), DoPwd(), DoRead(), DoSetOpt(), DoSleep(), DoThreads(), DoTimer(), InputLoop(), MSYS_DisplayOption(), MSYS_DisplayWrapped(), MSYS_ShowHelp(), OptConsole(), OptThreads(), ThreadCreate(), ThreadJoin(), ThreadStop(), and TimerTell().

void MSYS_DisplayOption ( MSYS_Thread *  aThread,
const TCHAR *  aOption,
const TCHAR *  aValue 
)

Display an option to the user in the standard way.

Parameters:
aThread Thread requesting the prompt. If threads have not been enabled, this will always be the main thread.
aOption Option name
aValue Option value. This value will be automatically quoted as necessary such that the value will be a valid setopt statement.

Definition at line 1687 of file menusys.cpp.

References MSYS_Display().

Referenced by DoSetOpt(), OptConsole(), OptThreads(), and OptUtf8().

void MSYS_DisplayWrapped ( MSYS_Thread *  aThread,
const TCHAR *  aText 
)

Display a string word-wrapped for 80 column display.

This function will word-wrap text and output it using MSYS_Display.

Parameters:
aThread Thread as supplied to the command handler.
aText Text to be displayed.

Definition at line 1160 of file menusys.cpp.

References MSYS_Display().

Referenced by MSYS_ShowHelp().

void MSYS_GetPrompt ( MSYS_Thread *  aThread,
TCHAR *  aBuf,
size_t  aBufSiz 
)

Request for current prompt callback.

This function is called from MSYS immediately prior to accepting input from the user. It will be called even when input is being read from a file.

Note:
Do not use call any MSYS_* function calls from this callback.
Parameters:
aThread Thread requesting the prompt. If threads have not been enabled, this will always be the main thread.
aBuf Buffer to write the prompt text that will be displayed to the user.
aBufSiz Size of the buffer in characters.

Referenced by InputLoop().

bool MSYS_NeedHelp ( MSYS_Thread *  aThread,
MSYS_Handler  aHandler,
MSYS_Args &  aArgs,
bool  aShowHelp = true 
)

Returns if detailed help has been requested in the arguments.

This function examines the arguments for any instances of "-?" or "/?" to determine if detailed help has been requested for this command. It will ignore those arguments if they have been suppressed with a command prefix.

Parameters:
aThread Thread as supplied to the command handler.
aHandler Command handler function pointer.
aArgs Arguments as supplied to the command handler.
aShowHelp If true and help has been requested, ShowHelp will be automatically called for this handler before it returns.
Return values:
true User has requested detailed help for this command.
false User has not requested detailed help for this command.

Definition at line 1202 of file menusys.cpp.

References MSYS_ShowHelp().

Referenced by DoChdir(), DoEcho(), DoExit(), DoHelp(), DoLoop(), DoProc(), DoPwd(), DoRead(), DoSetOpt(), DoSleep(), DoTee(), DoThreads(), DoTimer(), OptConsole(), OptThreads(), and OptUtf8().

bool MSYS_Process ( const TCHAR *  aInputFile,
bool  aEnableThreads 
)

Start the menu system.

Calling this function starts processing of the console or file input and exits only when the input file has been completed, or the exit command has been encountered.

Note:
The locale should be set correctly before displaying the menu. It is recommended that setlocale(LC_ALL, ""); be executed before calling this function.
Parameters:
aInputFile Input file that should be processed. MSYS will return immediately following processing the end of this file (no console input). If NULL, the input will be taken from the console.
aEnableThreads Should multiple threads be permitted?
Return values:
true Successful completion
false aInputFile could not be executed

Definition at line 737 of file menusys.cpp.

References DoRead(), DoThreads(), FileExists(), g_pRootThread, g_rgDispatch, InitInternal(), InputLoop(), MSYS_DefaultOptionsFile, MSYS_ThreadUserCreate(), and MSYS_Thread::ROOT_THREAD.

void MSYS_ShowHelp ( MSYS_Thread *  aThread,
MSYS_Handler  aHandler 
)

Display summary help or detailed command help.

Parameters:
aThread Thread as supplied to the command handler.
aHandler Command handler function pointer to display the help for. If this is NULL then summary help will be displayed. Otherwise the detailed help for that command will be displayed.

Definition at line 2610 of file menusys.cpp.

References MSYS_DispatchEntry::cmd, g_rgDispatch, g_rgInternal, HelpAll(), HelpExternal(), HelpInternal(), MSYS_DispatchEntry::longHelp, MSYS_Commands, MSYS_Display(), MSYS_DisplayWrapped(), MSYS_DispatchEntry::oneHelp, OPTION_PREFIX, and OPTION_PREFIX_LEN.

Referenced by DoHelp(), DoSetOpt(), DoShell(), and MSYS_NeedHelp().

void MSYS_ThreadUserCreate ( MSYS_Thread *  aNewThread,
const MSYS_Thread *  aParentThread 
)

Initialization of thread-specific data structures callback.

This function is called from MSYS into the user library. It will be called once per thread at creation time so that the user can do any per-thread initialization required. If per-thread data is required, it should be stored in the mUserData data structure. Even if threads have not been enabled it will be called once for the main thread.

Note:
Do not use call any MSYS_* function calls from this callback.
A minimal implementation of this function for a program that does not use any thread-locale storage is:

extern void
MSYS_ThreadUserCreate(
    MSYS_Thread *       aNewThread,
    const MSYS_Thread * aParentThread
    )
{
    (void)aNewThread;
    (void)aParentThread;
}

Parameters:
aNewThread Thread to be initialized.
aParentThread Parent thread data. This data should be used to copy all thread-local properties into the new thread properties.

Referenced by MSYS_Process(), and ThreadCreate().

void MSYS_ThreadUserDestroy ( MSYS_Thread *  aThread  ) 

Uninitialization of thread-specific data structures callback.

This function is called from MSYS into the user library. It will be called once per thread at destruction time so that the user can do any per-thread uninitialization required. If per-thread data is required, it should be stored in the mUserData data structure. Even if threads have not been enabled it will be called once for the main thread.

Note:
Do not use call any MSYS_* function calls from this callback.
A minimal implementation of this function for a program that does not use any thread-locale storage is:

extern void
MSYS_ThreadUserDestroy(
    MSYS_Thread * aThread
    )
{
    (void)aThread;
}

Parameters:
aThread Thread to be uninitialized.

Variable Documentation

const MSYS_DispatchEntry MSYS_Commands[]

User supplied function table.

This table defines the functions that are being exported from the user library. Command names and command help will be displayed in the same order as they appear in this table. Help will always be supplied for internal command first, and then the user commands as defined in this table.

Multiple entries may use the same command handler function, however they should be grouped together in the table, with oneHelp and longHelp provided for the last entry only. All other entries must have the help set to NULL. For example:

{ _T("x"),    Exit, false, NULL, NULL },
{ _T("exit"), Exit, false, _T("Exit the application."), NULL },

Options that can be accessed via the internal "setopt" command should be created as a command with "_setopt_" prefixing the name of the option. For example:

{ _T("_setopt_OptionName"), ThisOptionHandler, false, _T("option help"), NULL },

An option command handler will always be called with the following arguments:

Index Value
0 "getopt" or "setopt"
1 option name (the name following the _setopt_ prefix)
2 value to be set (only with setopt)

An example implementation of an option handler:

extern void
ThisOptionHandler(
    MSYS_Thread *   aThread,
    MSYS_Args &     aArgs
    )
{
    if (MSYS_NeedHelp(aThread, ThisOptionHandler, aArgs)) return;

    const TCHAR * pAction = aArgs[0];
    const TCHAR * pOption = aArgs[1];
    const TCHAR * pValue  = aArgs.size() > 2 ? aArgs[2] : NULL;

    if (*pAction == _T('s')) {
        set "pOption" to "pValue"
    }
    else {
        MSYS_DisplayOption(aThread, pOption, "current value");
    }
}

The table MUST end with a NULL entry like:

{ NULL, NULL, false, NULL, NULL }

Referenced by DoSetOpt(), InitInternal(), and MSYS_ShowHelp().

const TCHAR MSYS_DefaultOptionsFile[]

User supplied default configuration file.

This is the filename used to load and save options by default when "setopt -load" or "setopt -save" is used without specifying a filename. This file will also be loaded by default if it exists when when MSYS_Process() is first called.

An example definition would be:

#ifdef _WIN32
extern const TCHAR  MSYS_DefaultOptionsFile[] = _T("menusys.cfg");
#else
extern const TCHAR  MSYS_DefaultOptionsFile[] = _T(".menusys");
#endif

Referenced by DoSetOpt(), and MSYS_Process().

const TCHAR* MSYS_HEADER

Create a header entry in the short help.

Use this as the command name of an entry which should be a header in the short help display. The entry must look like:

{ MSYS_HEADER, NULL, false, _T("Header Text"), NULL },

Generated on Wed Jun 20 09:28:35 2007 for menusys by  doxygen 1.5.2