Documentation

===================================================

DOS the Butler RPD Documentation

===================================================

Index:

Quick Overview
Customizing the DOScript
Modifying the DOSInterpreter source (Advanced)

Quick Overview

Original Programmer: Stephen Akiki

Objective:

Allow for the Rapid Prototype and Development of a personal "butler"

with the complete power of a hand-coded "butler".

Initial Language: Custom (DOScript)

Processing Language: D (www.digitalmars.com/d/)

Target Language: D - DMD Compiler 2.014 alpha

DMC Linker and Util. 8.50

Compiling:

To compile the DOScript, run the Build.pl or Build.bat script (depending on your OS).

To compile the DOSInterpreter, run the appropriate "DOSInterpreter" script

Recovering:

If for some reason the Build script doesn't move the executable and/or source back from

./dmd/bin, use the Recover.pl (or Recover.bat) to retrieve your code automatically.

Licensing:

There is none, you may use this code and/or program for whatever you want. Although I

must ask that if you distribute the source that you leave this header alone.

Other than that, enjoy!

Bugs or Comments:

theangrybaby@gmail.com

Make sure to include "DOS the Butler" somewhere in the subject field.

Customizing the DOScript

#OS directive: #OS <Name of Operating System>

NOTE: Only windows OS supported at this tim

#TITLE directive: #TITLE <Title you want your console window to have>

#PROCESS directive: #PROCESS <1 or 0>

Process directive (when set to 1) is responsible for showing the "Starting (application)..." message where application is designated by the 4th parameter in Single Function. When set to 0, you do not need to designate a 4th parameter in the Single Function.

#COLOR directive: #COLOR <background color> <foreground color>

Available colors - (Name of color - color code you write):

Bright White - btwhite
Light Yellow - ltyellow
Light Purple - ltpurple
Light Red - ltred
Light Aqua - ltaqua
Light Green - ltgreen
Light Blue - ltblue
Gray - gray
White - white
Yellow - yellow
Purple - purple
Red - red
Aqua - aqua
Green - green
Blue - blue
Black - black

#SYMBOL directive: #SYMBOL <Symbol Key> <Actual Key>

The symbol directive is used so that a special character key <Actual Key> may be recognized when pressed, while still providing an aesthetically pleasing symbol key on the menu when displayed.

e.g.

Because the Enter (Return) key is recognized as the special character, \r , when pressed, you must put '\r' in the 1st parameter in the Single Function or Submenu. Although you may do this, it may be confusing to some to remember all special characters. Using the #SYMBOL directive, you are allowed to substitute the '\r' in the menu with the <Symbol Key> while still retaining the <Actual Key> for recognizing what key you press. For instance, in the emptytemplate.txt you have one symbol: #SYMBOL <<TAB>> \t. This means that you can enter <<TAB>> in any first parameter of either a Single Function or Submenu (as shown in the picture) and it will be displayed in the console window. However, when you press the tab key on your keyboard, the '\t' key is sent and recognized by the program because you specified that the <<TAB>> symbol means '\t'.

#START directive: #START

Signifies the start of the main function in the program. If your not a programmer, this won't mean much, just know that the only things that can come before this directive is the #OS, #TITLE, #PROCESS, #COLOR and #SYMBOL directives.

#CLRSCR directive: #CLRSCR

Inserts the clear screen command into the program window. i.e. it will clear whatever was on the screen before the directive.

#TEXT directive: #TEXT <text you want displayed>

Inserts the text you supply into the program window.

Single Function: -> <Character Key> - <Title> - <Command> - <Process> or -> <Character Key> - <Title> - <Command>

<Character Key> is the key that is used to recognize what key has been pressed. If that key is pressed the appropriate <Command> is excecuted. The use of the #SYMBOLdirective is the only way to change what is displayed on the screen (the symbol) and what is actually recognized (the character key).
<Title> is the title that will be displayed on the console window.
<Command> is what will be executed when <Character Key> is pressed. WHATEVER IS IN THIS FIELD WILL BE INJECTED RAW INTO THE RESULTING SOURCE CODE. Thus it is possible to string together a series of commands. For instance: -> 1 - Test - writefln("Hello, this is a test"); writefln("I'm afraid you can't do that"); system("pause"); - NONE will print out "Hello, this is a test", "I'm afraid you can't do that" and then pause after the 1 key is pressed.
<Process> if the #PROCESS directive is set to 1, then this field is required, otherwise you do not need it. Whatever is entered into this field will result in a message: "Starting <Process> ..." If #PROCESS is set to 1, but you do not want a message to appear, type into this field NONE.

Submenu: => <Character Key> - <Title> - <Name of SubMenu> ... ... ... <=

See Single Function <Character Key> definition
See Single Function <Title> definition
<Name of SubMenu> is the identifier for the particular submenu. These must be unique, no two names of submenus can be the same.
The <= arrow signifies the end of a submenu, EVERY => MUST BE MATCHED BY A <= BEFORE ANOTHER => IS SHOWN. In other words, there can't be nested submenus (yet).

Nested Single Function - <4 spaces> -> <Character Key> - <Title> - <Command> - <Process> or -> <Character Key> - <Title> - <Command>

All definitions are the same as Single Function except for the fact that there must be 4 spaces before the -> to signify that this single function belongs in the appropriate submenu

#END directive

Signifies the end of the main program, this must go at the end.

Modifying the DOSInterpreter source (Advanced Usage)

The DOSInterpreter can be split up into 8 sections:

Configuration

General names of the target file, DOScript, and DOS executable

Preprocessor

Gets general info from directives such as:

Operating system
Title of program
Whether or not to include Process Status
Color of program
Any symbol substitutions
Single Function Count
Sub Menu Count

General Functions

General functions for the program such as:

Handle #TEXT directives
Handle #CLRSCR directives
Reading the DOScript into memory
Clearing the target file before writing to it
An abstraction for appending to the target file
A function for writing the symbols picked up by the preprocessor

Make Menu Functions

This makes the functions that appear in the target file and that are called to display the appropriate submenu

Validator

Validates the DOScript. Currently checks the following things:

Incorrect spacing on single functions
Incorrect spacing on sub menus

Main

Holds the color hash that translates the directive found by the preprocessor
Reads DOScript into memory
Validates
Preprocesses the file
Clears the Target File

Make Switch Statements

Actually builds the switch hierarchy and puts the appropriate submenu function calls in place (in can do this because of uniform menu declarations)

Build

Deletes any previous instance of a DOS.exe
Builds using the Build.bat file