============================== mzscript 0.8 ===============================
               An advanced script module for LiteStep/PureLS
                       by Marcus Westerlund (maze)
===========================================================================

First, the usual disclamer:
Use at your own risk (shouldn't be any trouble though)

===========================================================================
History:
===========================================================================

 version 0.8 (2001-09-24) / qwilk
	- Now works with PureLS! (thanks to jugg)
	- Added !Refresh support
	- Added !Pause (courtesy of Maduin's pause.dll)
	- Made changes to make mzscript compile with current LSAPI
	- Cleaned up the source code

 version 0.7.2 (2000-05-22) / maze
	- Added internal vars mousex and mousey
	- Fixed case sensitivity, is now not case sensitive (should fix new build problem)

 version 0.7 (2000-05-19) / maze
	- Added !scriptload 
	- Added !scriptremove
	- Added !varMul
	- Added !setlistsep
	- Added internal variables to return system properties

 version 0.6 (2000-03-07) / maze
	- Added !varAdd
	- Added support for saving variables
	- Added !ifEval
	- Added more syntax on if bangs
	- Added support for custom rc-file
	- Added list functionality
	- Added var substitution
	- Added goto,gotoif and label to script
	- Added some minor things

 version 0.5 (2000-02-24) / maze
	- First version out


===========================================================================
Installation:
===========================================================================

----- How to load the module:

LoadModule c:\path_to_dll\mzscript.dll

----- However, using e-variables is highly recommended:

ThemeDir $LitestepDir$themes\MyTheme\
LoadModule "$ThemeDir$modules\mzscript\mzscript.dll"

(please note that the e-variable LiteStepDir is defined automatically by LiteStep!)

===========================================================================
Usage:
===========================================================================

----- step.rc -----

mzScriptFile filename
- Uses filename as scriptfile instead of step.rc (default step.rc)

mzBangChar |
- What char to use instead of ! for bang commands. This is useful
 for nesting bangs. (defaults to |)

mzListSeparator :
- Char to separate parts of variables when they are used as lists (defaults to : )

mzAutosaveVars replace/save
- Automatically saves variables in the script file in use. "replace" means no new variables
 will be added to the file, but the others will be replaced. "save" also adds variables not
 present in the script file. (disabled by default)


----- bangs -----

----- Variable manipulation bangs:

!varSet name The string 
or !varSet name "The string"
- Sets variable "name" to "The string"

!varRemove name
- Removes variable "name"

!varShow name
- Show context of "name"

!varRun name
- executes the contents of variable "name", can be a bang or a command

!varAdd name number
- Adds number to variable "name". A non valid number vill be the same as 0

!varMul name number
- Multiplies number with "name". A non valid number vill be the same as 0.
 Number may be float but "name" is always integer.

!varSave name
- Saves the variable "name" to the script file.

!varReplace name
- Saves the variable "name" to the script file, but only if it already exists.

!varSaveAll replace/save
- Saves all variables to the script file, if replace is used then no new variable
 entries will be added.

----- If bangs...

!ifExist name [command]
!ifNExist name [command] 
- Executes [command] if variable exists (or not).

!ifEq name "string" [command]
!ifNEq name "string" [command]
- Executes [command] if variable is equal (or not) to string.

!ifEval ("hello" <= "wow") [command]
- Evaluates expression (quite useful with var substitutions)
 Valid comparisons are:
 "<" less than
 "<=" less or equal to
 ">" greater than
 "=>" greater or equal to
 "=" equal to
 "<>" not equal to

where [command] may be of the following syntaxes:
    command arg
    'command arg'
    'command arg' else '|bang'
    '|bang hello' '"c:\foo bar\command" world'
    {command arg}
    {command arg} else {bang arg}

The first string between the ' signs is executed if true, if false the second (if it exists).
Likewise, the first string between { and } is executed (a must with nested ifs) if true,
if false the second string (if it exists).

----- Other bangs...

!msgbox msg
- Displays msg in a message box.

!exec command
- Executes command, may be a bang or a program (useful when invoked from someware else,
 var substitution takes place)

!setlistsep s
- Sets list separator character to s

!scriptload filename
- Loads script definition file from filename

!scriptremove bang_name_without_!
- Removes scriptbang bang_name_without_!

!pause [n]
- Pauses for n milliseconds (courtesy of Maduin's pause.dll)


----- scriptfile.rc -----
(defaults to step.rc)

*Script start command
- Executes command on startup

*Script bang !thebang
- Start of a bangscript that will connected to !thebang

*Script exec command
- Part of a bangscript that executes command when the bang is invoked

*Script exit
- Exits a bangscript

*Script label labelname
- Used with goto and gotoif

*Script goto labelname
- Jumps to label labelname in bangscript. If this label is not found then the script is aborted.

*Script gotoif ("string1" <> "string2") labelname
- Jumps to label labelname in script if evaluation of expression is true. If the label is not
found then the bangscript is aborted. See !ifEval for valid comparisons.

*Script ~bang
- Declares the end of a bangscript.

*Script var name string
or *Script var name "string"
- Sets variable name to "string".


----- Substitutions -----

(This feature was implemented in version 0.6)
Substitutions are made in bangs and in scripts.

%[var]
- is substituted with the contents of variable var. 

%[var:] 
- is substituted with the first part of variable var's contents
 (before the first list separator).

%[var:_]  
- is substituted with the second part of variable var's contents
 (starting from the first list separator).

?["Questions" "subst on yes" "subst on no"]
- Pops up a message box with the message "Questions". If yes is clicked
 it is substituted with "subst on yes", if no is clicked it is substituted
 with "subst on no".

##### Examples:

Let's say variable hello is set to "c:\hi.txt:world.txt",
and that the separator is set to the default value of ":"

- notepad %[hello]
would execute as "notepad c:\hi.txt:world.txt"
- notepad %[hello:]
would execute as "notepad c"
- notepad %[hello:_]
would execute as "notepad \hi.txt:world.txt"


----- Internal variables -----

The internal variables are:

xresolution
yresolution
year
month
day
weekday
hour
minute
second
mousex
mousey

It should be quite obvious what they stand for. They are used as regular vars.

##### Example:

!msgbox %[hour]:%[minute]:%[second]

will show the current time in a message box.

Remember not to alter internal variables. It is possible, but you have to recycle 
to get them to act as functions again.

===========================================================================
Examples:
===========================================================================

----- Simple -----

;Start conditions
*Script var vwm shown
*Script var bar shown
*Script start notepad

;First bangscript
*Script bang !togglebar
*Script exec !ifeq bar "shown" '|varset bar hidden' else '|varset bar shown'
*Script exec !toggleslider [1]
*Script exec !ToggleShortcutGroup 1
*Script exec !ToggleCommand 
*Script exec !SystrayToggle 
*Script exec !ifeq vwm "shown" |VWMRollup
*Script ~bang

;Second bangscript
*Script bang !togglevwm
*Script exec !ifeq vwm "shown" '|varset vwm hidden' else '|varset vwm shown'
*Script exec !ifeq bar "hidden" |varset vwm shown
*Script exec !ifneq bar "hidden" |VWMRollup
*Script exec !ifeq bar "hidden" |togglebar
*Script ~bang


----- Advanced -----

;Not to be changed by varsave ... using start and !varset instead of var
;Contains turing program, makes three ones and terminates on two states
*Script start !varset t_program "one:one::1:r:two:two::1:l:one:one:1:1:l:one:two:1:1::exit"

;Bang used by turing to shift tape
*Script bang !turing_left
*Script exec !varset t_left "%[t_right:]:%[t_left]"
*Script exec !varset t_right "%[t_right:_]"
*Script ~bang

;Bang used by turing to shift tape
*Script bang !turing_right
*Script exec !varset t_right "%[t_left:]:%[t_right]"
*Script exec !varset t_left "%[t_left:_]"
*Script ~bang

;A turing bang. Using t_program as turing program
*Script bang !turing
*Script exec !varset t_left ""
*Script exec !varset t_right ""
*Script exec !varset state "%[t_program:]"
*Script label start
*Script exec !varset prog "%[t_program:_]"
*Script label loop
*Script gotoif ("%[prog:]" <> "%[state]") skipp
*Script exec !varset tmp %[prog:_]
*Script gotoif ("%[tmp:]" <> "%[t_right:]") skipp
*Script exec !varset tmp %[tmp:_]
*Script exec !varset t_right "%[tmp:]:%[t_right:_]"
*Script exec !varset tmp %[tmp:_]
*Script exec !ifeval ("%[tmp:]" = "r") |turing_right
*Script exec !ifeval ("%[tmp:]" = "l") |turing_left
*Script exec !varset tmp %[tmp:_]
*Script exec !varset state %[tmp:]
*Script goto start
*Script label skipp
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script exec !varset prog "%[prog:_]"
*Script gotoif ("%[prog]" <> "") loop
*Script exec !varremove tmp
*Script label loop2
*Script exec !turing_right 
*Script gotoif ("%[t_left]" <> "") loop2
*Script exec !msgbox Result - %[t_right]
*Script ~bang


(...and this short example shows that there is no limitations to
what can be done with this script according to A. Turing)

===========================================================================
Some things:
===========================================================================
version 0.5 (maze)
I hope this will be of some use, I know it has been for me (that's why I wrote it).
I don't know if there will be more versions to come (is there demand?), but eventually
I may add sending keystrokes to windows. (Suggestions?)

version 0.6 (maze)
Oh well. I did make some additions. But now I will probably leave this module alone for
a while. But you are welcome to send me your suggestions and bug reports.

version 0.7 (maze)
Not much to say. I'm thinking of doing plugin support, but I dont know what that would be 
good for. I may check out the case sensitivity problem some day.

version 0.8 (qwilk)
Well, what can I say? I am just proud to be part of the mzscript legacy! <vbg>
I hope you enjoy it, especially the users of PureLS who has been without this
awesome module for too long...

===========================================================================
Contact (authors in order of appearance):
===========================================================================

Marcus Westerlund (maze)
marcus@cs.umu.se
http://www.acc.umu.se/~macce

Karl-Henrik Henriksson (qwilk)
qwilk@desktopian.org
http://desktopian.org/