CD Shell 2

CD Shell 2.0 Beta Test Guide

There are many differences between Boot Scriptor 1.2 and CD Shell 2.0. The following list of items are new or have changed from Boot Scriptor 1.2, and override the current documentation available at www.bootscriptor.org. As CD Shell 2.0 gets closer to final release, this information will be integrated into the web documentation.

Remember this is a beta release, so bugs are expected. If you encounter a bug (or any kind of unexpected result, for that matter), please report it to me. This way when I release the final version of CD Shell 2.0, it will be as stable and bug-free as possible. Thanks, and enjoy the new CD Shell!

Differences from Boot Scriptor 1.2 Web-based Documentation

1. Program name changed and version updated.

Boot Scriptor is now called CD Shell. At times I have disliked the name Boot Scriptor, and now that the more powerful features described below are in place, the program really is a lot like a *nix shell. It is still the same program, however, so I don't feel a need to restart the version numbering. This release will be version 2.0, partly because of the powerful new features available, but mainly because I've broken compatibility with 1.x series scripts.

As the name of the program changed, so have some other things as well. The CD Shell files should go in a folder called /cdsh in the root of your disk image. The startup script is now called cdshell.ini, and the splash screen is now called cdsh.bmp or cdsh.csi. The bitmap convert tool now takes the options -bmp2csi and -csi2bmp.

2. Comment character is now '#'.

The end-of-line comment character has been changed from the semicolon to the hash symbol. This is more in line with other scripting languages, and makes it possible for me to use the semicolon in a better way -- as a command separator.

3. Multiple commands per line are now supported.

You can now type more than one command on a single line, both in scripts and at the shell prompt. Commands are separated using the semicolon, and cannot span multiple lines. There is no need to use a semicolon after the last command on the line, but you can do so without penalty if you wish.

Example:

print "Message one.\n"; print "Message two.\n"

When errors are reported in scripts, you will see something like [Line:15.3]. This means that the error occured in the third command on the fifteenth line.

4. Variables are now supported.

A. Setting and creating variables (writing).

One of the most powerful new features is variable support. You can set the value of a variable using the set command. If the variable doesn't exist when you set it, then it will be created. Valid variable names contain only the characters a-z, A-Z, 0-9, and _.

There are two forms of the set command:
set <variable> = [string]
set <variable> = [expression]

The first form sets the variable to a string. The string must be delimited by quotes, but you can use the backslash to escape a character if needed.

Examples:

set variable_one = "Boot Scriptor is now"

						set variable_two = "called \"CD Shell\"."

The second form basically evaluates a mathmatical expression (I'll go into greater depth about expressions later in this file) and then stores the result into the variable. All variables are represented internally as strings, so this essentially just calculates the result of the expression and then converts the number into a string.

Example:

set myVar = 1 + 2

B. Using variables (reading).

When you want the value of a variable, you use the dollar sign.

Examples:

print "$variable_one $variable_two"

						set myVar = $myVar + 5

The dollar sign also has the ability to escape characters, so $$, $;, and $# can be used to get '$', ';', and '#' without CD Shell thinking you are ending a command or starting a comment, etc.. Also the special symbol $< can be used, which is sort of like a backspace, or a separator.

Example:

# This prints out "Baseball"

						set first = "Base"

						print "$first$<ball"

C. Built-in variables.

Modules can define their own variables as well. Some of these module-defined variables actually take the place of commands previously found in Boot Scriptor, such as the color command. Whereas all user-defined variables are both readable and writable, the built-in ones may be read-only or write-only. Also whereas all user-defined variable names are case-sensitive, most of the modules' variable names are not. Below is a list of all built-in variables.

Variable	Module	R/W	Description
$appName	Basic	R	Returns the program name
$dateYear	Basic	R	Returns the current year.
$dateMonth	Basic	R	Returns the current month.
$dateDay	Basic	R	Returns the current day.
$timeHour	Basic	R	Returns the current hour.
$timeMinute	Basic	R	Returns the current minute.
$timeSecond	Basic	R	Returns the current second.
$textColor	Basic	R,W	This variable can be used to check or set the default text color.
$boldColor	Basic	R,W	This variable can be used to check or set the text highlight color.
$overscanColor	Basic	R,W	This variable can be used to check or set the display's overscan color.
$version	Basic	R	Returns the program version.
$versionDebug	Basic	R	This variable lets you check to see if you're running a debug build of CD Shell.
$versionDOS	Basic	R	This variable lets you check to see if you're currently in the Script Debugger.
$vesa	Basic	R	This variable lets you check to see if CD Shell will be able to display CSI images.
$vga	Basic	R	This variable lets you check to see if a VGA is installed.
$lastKey	Script	R,W	This variable stores the keycode of the last key pressed.
$tabSize	Script	R,W	This variable controls the distance between tab stops when using the \t escape sequence with the print command.
$textCursorX	Script	R,W	This variable controls the horizontal location of the text cursor (0-79).
$textCursorY	Script	R,W	This variable controls the vertical location of the text cursor (0-24).

And more to come :)

5. If/then/else conditional commands added.

Three new commands have been added: if, then, and else. The 'if' command simply takes an expression as its only parameter. The 'then' command takes a command as its parameter, and executes it if the result of the last 'if' command was true (nonzero). The 'else' command will execute its parameter if the result of the previous 'if' command was false (zero). You can execute multiple then or else commands following an if command, but you can't nest if commands.

Examples:

if $textColor == 14

						then print "The text color is yellow.\n"

						then print "Aren't you happy?"

						else print "The text color is not yellow.\n"

						else print "But that's ok."

						

						if $vesa; then goto graphicMenu; else goto textMenu

6. Expressions

Mathmatical expressions in CD Shell are very much like those in C. Most of the standard C operators are available, and you can even use functions to return a value in the middle of an expression. Below is a list of supported operators, grouped according to precedence. All operations are carried out with a precision of 32-bits. Oh yeah, and it's all integer math -- no floats allowed. :)

Operator	Description

`(`	Open parenthesis
`)`	Close parenthesis

`-`	Negate
`!`	Logical not
`~`	One's complement (not)

`*`	Multiply
`/`	Divide
`%`	Modulo

`+`	Add
`-`	Subtract

`<<`	Left shift
`>>`	Right shift

`<`	Less than
`>`	Greater than
`<=`	Less than or equal
`>=`	Greater than or equal

`==`	Equal
`!=`	Not equal

`&`	Bitwise and

`^`	Bitwise xor

`\|`	Bitwise or

`&&`	Logical and

`^^`	Logical xor

`\|\|`	Logical or

7. Functions

Anywhere you would normally use a value in an expression, you can also use a function. Functions take the form 'name[parameters]'. Below is a list of supported functions.

1. Boot Check

The bootCheck function checks a drive to see if it appears bootable. If this function returns 0, then the device doesn't appear bootable. If it returns 1, then the device has a bootable boot-sector. If it returns 2, then the Master Boot Record contains a bootable partition. If it returns 3, then the bootable partition has a bootable boot-sector.

Examples:

if bootCheck[0]; then boot 0 # Boot from floppy.

						if bootCheck[0x80] == 3; then boot 0x80 # Boot HDD 0.

						if !bootCheck[0x81]; then print "hd1 is not bootable!"

2. Compare/iCompare

The compare function compares two strings to see if they are the same. It returns 1 if they are the same, and 0 if they are different. The icompare function is exactly the same, only it is case-insensitive.

Examples:

if compare["$myVar" "abc"]; then print "myVar is 
						set to 'abc'"

						if icompare["apple" "Apple"]

						then print "Apples are delicious."

						else print "You should not see this."

3. Defined

The defined function checks to see if a given variable exists. It returns 1 if the variable exists, and 0 if it does not.

Examples:

Examples:

						if defined[appName]; then print "You are using $appName."

						if !defined[myVar]; then print "myVar is not defined!"

4. Key

The key function returns the keycode of its parameter. The given paramter can be either a single-character key, or a one-word description of the key (for special keys). These descriptions are the same ones used for the onkey/setkey commands from Boot Scriptor, with the following changes: there is no 'semi' key (just use '$;'), and there is now a 'bracket' key, which is the close bracket ']'.

Examples:

if $lastKey == key[a]; then print "You pressed the
						letter 'a'."

						if $lastKey == key[enter]; then goto selectCurrentItem

5. File

The file function check for the existence of the file specified by its parameter. If the file is present, then the function returns 1. If the file is not found, then the function returns 0. Files are checked for in the current directory.

Examples:

if file[/cdsh/cdsh.bin]; then print "The file was
						found."

						if !file[cdsh.ini]; then print "The file was not found."