menusys Documentation

Library	menusys
Author	Brodie Thiesfield [code at jellycan dot com]
Source	http://code.jellycan.com/menusys/

An interactive cross-platform command-line shell. Menusys facilitates the creation of programs that provide a scriptable command-line for user interaction. Standard command line functionality is provided by this library, for instance, command help, options, file handling, scripting, timing, and loops. Only the commands for your own functionality (e.g. stress test clients, C or C++ API testing) needs to be implemented.

FEATURES

• MIT Licence allows free use in all software (including GPL and commercial)
• multi-platform (Windows 95/98/ME/NT/2K/XP, Linux, Unix)
• full command line parsing into commands and arguments
• summary and extended help for internal and user commands
• MBCS and UNICODE input/output (current locale and UTF-8)
• generic file system commands (e.g. cd, pwd, shell)
• timing and timing analysis (multiple timers, lap timers)
• multiple threads (start, stop, join)
• simple procedures and loops
• supports both MBCS and UNICODE build types on Windows
• compiles cleanly at warning level 4 (Windows/VC.NET 2003) and -Wall (Linux/gcc)

USAGE

The following steps are required to use menusys. The file main.cpp included with the menusys distribution implements the minimal menusys-based program.

1. Include the menusys.h header file. It is recommended to also include the <locale.h> header and call setlocale() in main().

   #include <locale.h>
   #include "menusys.h"

2. Provide implementations for the functions MSYS_ThreadUserCreate(), MSYS_ThreadUserDestroy(), and MSYS_GetPrompt().

3. Define an array of MSYS_DispatchEntry entries as MSYS_Commands This is the command definition and help text for each command implemented by you. The internal menusys commands will be automatically added to this list.

4. Implement the main() function and call MSYS_Process().

   int
   _tmain(
       int     argc,
       TCHAR * argv[] )
   {
       setlocale(LC_ALL, "");
       fprintf(stdout, "MENUSYS\n\n");
       const TCHAR * pInputFile = (argc > 1) ? argv[1] : NULL;
       return MSYS_Process(pInputFile, true) ? 0 : 1;
   }

NOTES

Menusys compiles with thread support by default (native threads on Windows, pthreads on all other platforms). This can be enabled or disabled by the client in the call to MSYS_Process() however the thread libraries are still required. To disable all threads so that the thread library doesn't need to be linked, define MSYS_NOTHREADS when compiling the library.

MIT LICENCE

The licence text below is the boilerplate "MIT Licence" used from: http://www.opensource.org/licenses/mit-license.php

Copyright (c) 2007, Brodie Thiesfield

Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:

The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.

THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.

---