Telegard Bulletin Board Software, v3.10
REFERENCE: Scripting Language
Copyright (C) 1998 by Tim Strike
All Rights Reserved.
The following is the script language defintion for Telegard 3.0. The
script language replaces the infoform questionaires with a more powerful,
customizable format that allows people to use a primitive "programming"
language to do things (like create custom drop files, prompted user help,
and many other things...)
Command Options Description
---------- ---------------------- ------------------------------------
:label - Defines script label <for jump>
ACS acs script_cmd Check <acs>
CALL label Save position, jump to label
(see RETURN)
CLS - Clear screen
COMMANDLINE "text" Update command line
COMMENT "text" Update users' SysOp comment
"text" to replace with text
"~VU text" to add old text after
"text ~VU" to add old text before
(i.e. use the ~VU for old comment)
DECREMENT variable <value> Decrease variable
type INTEGER
if no <value>, uses 1
ENDSCRIPT - End script execution
FILECLOSE - Close open textfile
FILECREATE filename Opens textfile (destructive)
FILEDISPLAY filename Display file
FILEERASE filename Erase file <filename>
FILEEXIST filename script_cmd Test if file exists, execute command
FILEOPEN filename Opens textfile (append)
FILEPUT "text" Adds text to textfile
FLUSH - Flush keyboard/inbound buffers
GET variable "text" <options>
if type STRING "text" length upper_YES/NO <"mask">
<"mask">: ? - Any Character
@ - Alpha Character
# - Number
Other - Forced Add
i.e. "###-###-####" ; phone #'s
"@#@ #@#" ; Canadaian postal
INTEGER "text"
CHAR "text" <valid_chars>
other keys: ^M : ENTER
^_ : SPACE
^[ : ESC
^^ : Caret
HANGUP - Hangup user
IF "text" "text" If
IFNOT "text" "text" If not
<statement> :
<statements...> :
ELSE Else
<statement> :
<statements...> :
ENDIF Endif
INCREMENT variable <value> Increase variable
type INTEGER
if no <value>, uses 1
JE "text1" "text2" label Jump to label if "text1" = "text2"
JNE "text1" "text2" label Jump to label if "text1" != "text2"
JUMP label Jump to label
KEYPRESSED script_cmd Execute script_cmd if keypressed
MCI variable Process MCI on string variable
MENU command "text" Execute Menu command w/options
NL - Send CR/LF
NOYES variable "text" Yes/No Question, Default NO
if type STRING "text"
BOOLEAN "text"
PAGEUSER - Page User
PUT "text" Send "text" to display
PUTNL "text" Send "text" w CR/LF to display
RANDOM variable max_value Generate random number
variable -> must be INTEGER type
range: 0..max_value-1
RETURN Return to saved position (last CALL)
SCRIPT <name-of-script> Execute another script
TRANSLATE variable "text" "c1" "c2" Translate characters
variable -> must be STRING type
"text" variable to translate
"c1" characters to translate
"c2" characters to replace with
i.e. TRANSLATE TIM_STR "unix/path/here/" "/" "\"
TIM_STR contains "unix\path\here\" after command
TRAMSLATE TIM_STR "Testing 123" "312" "987"
TIM_STR contains "Testing 879" after command
VALIDATE level Validate user to -> level
VARIABLE variable type <"text"> Declare variable, optional value
STRING { string type, 70 chars max }
INTEGER { long integer }
CHAR { single character }
BOOLEAN { boolean - YES/NO }
YESNO variable "text" Yes/No Question, Default YES
if type STRING "text"
BOOLEAN "text"
var_name "text" Set variable contents
VARIABLES
To access a variable contents, use $variable_name$ in any "text"
string. This allows you to use the contents of a variable for input
or output.
To change a variables contents after it has already been defined,
simply put the variable name followed by the new contents - for
example:
VARIABLE TIM STRING "First Contents"
TIM "Second Contents"
PASSED PARAMETERS
To access a script option contents (options/MCI sent to script on
script command line), use @token_num@ to get the option. @1@ will
return the first token (ie, the first string inbetween spaces). @2@
will return the second, @*@ will return all the option contents. For
example, if the script were executed as:
-E
TSCRIPT ~UN ~CN ~CP ~CB
@1@ would return ~UN, @2@ would return ~CN, @5@ would return blank,
@*@ would return ~UN ~CN ~CP ~CB -- all of the options. The script
options are available in any "text" field.
IF STATEMENTS
If statement blocks are self-contained;
IFNOT "~TR" "0" IFNOT "~TR" "0"
PUTNL "Illegal Logons!" PUTNL "Illegal Logons!"
ENDIF ENDIF
The statement (1) is functionally equivalent to (2):
IF "~TR" "0" JE "~TR" "0" ILLEGAL
GOTO ILLEGAL
ENDIF
but executes slower (use option 2!) . . .
LABELS
Labels can be a maximum of 12 characters in length.
Of note; labels must be first level commands, meaning they can *not*
be imbedded within IF/IFNOT..ELSE..ENDIF statements. If you bury
your label within these statements, you *will* get into the
statement, but you'll get an error coming out. Do *not* construct
scripts with labels inside goto statements. YOU HAVE BEEN WARNED!
CALL/RETURN
The call/return subset is a very handy way of creating procedures.
Take for instance, the following script:
CALL LINE
PUTNL "This is my very own header, it'll allow the creation of of"
PUTNL "of a couple of nifty functions which I need not worry about"
PUTNL "duplicating. This example is simple, imagine complex functions!"
CALL LINE
PUTNL "This is after my second CALL statement.
; this is important -- this way, the script will never run into the
; "functions" by accident
ENDSCRIPT
:LINE
PUTNL "`09<`0B*`01--------------------------------------------------------`0B*`09>"
RETURN
In this example, when CALL is first encountered, it'll skip down and
process after :LINE, then when it comes to RETURN, return to the line
after the first CALL. When the second CALL is encountered, it'll
return back to the line after the second CALL. This allows for
dynamic jumps to and from a procedure/function type reference without
worrying about where you're returning too (it just returns to the
next logical statement).
ILLEGAL CONSTRUCTS
The following statements are illegal (for parsing reasons):
ACS <acs> IF "test1" "test2"
KEYPRESSED IF "test1" "test2"
FILEEXIST <path:file> IF "test1" "test2"
Because of how Telegard parses the script language, the above
construct is not permitted -- it just creates too many problems.