VSInterp Scripting Documentation - Versus
Jesse McGrew

From a scripter's perspective, the Versus language can be divided into four
parts: evaluating variable and function references in text; evaluating
numerical expressions; running commands; and processing loops and statements.

Evaluating Variable and Function References (ParseVars)
=======================================================

Strings of text are often evaluated to expand embedded references and
substitutions. This process has two parts. First, backslash substitutions are
performed, which map a backslash followed by a letter into a single ASCII
character:

  \A       CTCP delimiter (^A, ASCII 1)
  \L       newline or BIRC hyperlink character (^J, ASCII 10)
  \S       carriage return or BIRC script link character (^M, ASCII 13)
  \b       bold (^B, ASCII 2)
  \k       color (^C, ASCII 3)
  \t       tab (^I, ASCII 9)
  \o       normal (^O, ASCII 15)
  \r       reverse (^R, ASCII 18)
  \i       italic (^V, ASCII 22)
  \u       underline (^_, ASCII 31)

Next, dollar sign references (functions and variables) are expanded. These
references are possible:

  $$
    changes to a single dollar sign.
  $0 through $9
    changes to the value of the named pseudovariable.
  $0- through $9-
    changes to the value of the named pseudovariable list. $5- is the same
    as $5 $6-, or $5 $6 $7-, etc. $9- contains $9 and any words following it.
  $varname
    changes to the value of the named variable. variable names are
    case-sensitive. if there is no variable by that name, it will remain
    unchanged. the parser picks the longest matching variable name: for
    example, if there is a variable named $foo but none named $food, "$food"
    will evaluate to the value of $foo followed by the letter "d".
  $'$varname'
    changes to the value of the variable whose name is in the named variable.
    for example, if $varname contains "foo", $'$varname' will return the
    value of $foo.
  ${text}
    recursively evaluates the text, then changes to the value of the variable
    with that name. for example, if $varname contains "5", ${foo$varname}
    will return the value of $foo5.
  $arrayname.text
    recursively evaluates the text, then changes to the value of the variable
    whose name is arrayname followed by a dot and the result of the
    evaluation. for example, if $varname contains "5", $foo.$varname will
    return the value of $foo.5.
  $funcname(text)
    recursively evaluates the text, runs the named function (giving the text
    as parameters), and changes to the function's return value. if there is
    no function by that name, or if the function is an alias that returns no
    value, the return value will be "<no value>".
  $(text)
    interprets the text as a numerical expression (see the next section).
  $?="message|default value"
    this is the input box pseudofunction. it displays a dialog box with the
    message in the window and an input line where the user can type text. if
    the vertical bar and default value are omitted, the input line will be
    empty; otherwise, it will contain the default value. the pseufunction
    reference is then changed into the text typed on the input line, or the
    string "INPUT_CANCELLED" if the user cancelled by pushing Escape or Cancel.
    if the same pseudofunction reference appears more than once in the text
    (with the same message and default value), the box will only be displayed
    once.

The variable $null is predefined to equal an empty string. In addition,
$scriptdialect is predefined to the string "Versus", and $scripthost is a
string describing the application running the script.

Evaluating Numerical Expressions
================================

Numerical expressions are used as conditions in loops and by the $() construct.
These are standard algebraic expressions, with the following operators in order
from lowest to highest precedence (operators on the same line have equal
precedence):

  !! &&                boolean or, and
  == != <= >= < >      equals, does-not-equal, less-or-equal, 
                       greater-or-equal, less-than, greater-than
  + -                  add, subtract
  * / %                multiply, divide, remainder
  | & ^                bitwise or, and, xor
  << >>                bitwise shift left, shift right
  ^^                   exponent
  ~ - !  [unary]       bitwise not, arithmetic negation, boolean not

For example, -5*4+2 will be evaluated as ((-5)*4)+2, or -18. Boolean and
comparison operators return 0 (false) or 1 (true). All binary operators are
left-associative: 1-2-3 is evaluated as (1-2)-3.

Strings can also be compared by enclosing them in [square brackets]:

  [a] == [b]           check for equality, ignoring case
  [a] === [b]          check for equality, matching case
  [a] != [b]           check for inequality, ignoring case
  [a] !== [b]          check for inequality, matching case
  [a] < [b]            does "a" come before "b", ignoring case?
  [a] <= [b]           does "a" come at or before "b", ignoring case?
  [a] > [b]            does "a" come after "b", ignoring case?
  [a] >= [b]           does "a" come at or after "b", ignoring case?

When a numerical expression is used as a condition, any nonzero value is true
and zero is false.

Numbers can be specified as either signed decimal integers (123, -500, etc.)
or unsigned hexadecimal numbers prefixed with a dollar sign ($FF, $20, etc.).
Since the dollar sign also introduces a variable reference, the dollar sign
before a hex number should be doubled to prevent unwanted evaluations:
  $$FF + $$1

Running Commands
================

A command is a line of text that describes an action to be performed without
altering the flow of execution. Commands can be prefixed with the characters
^ and/or * (in that order), which suppress text output and alias matching
respectively. Command names are case-insensitive. Commands are described in
the reference table at the end of this document.

Normally a command is evaluated before it is run. In addition to commands
described in the table, these special forms are also available, and are not
evaluated before they are run:

  $varname++
    increments the value of $varname by 1.
  $varname--
    decrements the value of $varname by 1.
  $varname += num
    increments the value of $varname by <num>, which must be an integer
    constant.
  $varname -= num
    decrements the value of $varname by <num>.
  @ $varname = text
    evaluates the text, then assigns it to the global variable $varname.
    this value of $varname will be available in every alias, event, and menu
    item. $varname can also be of the form $arrayname.text as described in
    the first section.
  @s $varname = text
    same as above, but this value will be stored so that it's still available
    the next time the program is run.
  -@ $varname
    deletes the global variable $varname.
  -@s $varname
    deletes the global variable $varname and removes it from storage so that
    it won't be back next time the program is run.
  @l $varname = text
    (that's the letter L as in Local)
    evaluates the text, then assigns it to the local variable $varname. this
    value of $varname will only be available in the current alias, event, or
    menu item, and it will mask out any global variable by that name as long
    as it exists. There is no -@l because local variables are automatically
    deleted when their enclosing routine exits.

Processing Loops and Statements
===============================

Loops and statements are constructs that span more than one line or alter the
flow of execution. They may contain commands, and a command is always permitted
wherever a loop or statement is, but a loop or statement isn't permitted
everywhere that a command is.

The first line of a loop or statement can always be prefixed with 'Eval' to
cause it to be evaluated.

Break [if <condition>]

  Exits the innermost loop. If a condition is specified, the loop is only
  exited when the condition is true.

Continue [if <condition>]

  Skips the rest of the code in the innermost loop and runs through the loop
  again. If the loop has an increment part ('for' and 'foreach'), it will be
  run before the next iteration of the loop. If a condition is specified,
  the loop is only exited when the condition is true.

Halt [if <condition>]

  Exits immediately from the current alias, event, or menu item. If a
  condition is specified, the routine is only exited when the condition is
  true.

Alias <name> [<hotkey>]
<code>
EndAlias

  Creates an alias with the given name, hotkey, and code (the host
  application may not support hotkeys). The alias can be called just like
  a command or function: parameters will be broken into words and passed
  in as $1 through $9. $1- contains $1 and all the words after it, and so on.
  $0 contains the name of the alias as it was called; the first character of $0
  will be % if it was called as a function.
  
  If the alias is a function, it can return a value by assigning it to the
  global variable $fresult. The variable's value will not be overwritten by
  intervening function calls; it will be saved before a function call and
  restored afterward.


Event <name> "<mask>"
<code>
EndEvent

  Creates an event with the given name, mask, and code. The event will be
  called by the host application when it sees fit (typically when some kind
  of application-specific event happens that is described by <mask>). The
  host application may not support events.

Parse [extended] <text>
<code>
EndParse

  Breaks <text> up into words, assigns them to the pseudovariables $0 through
  $9 (and $0- through $9-), and runs <code> with the modified
  pseudovariables. If the 'extended' keyword is specified, the text will be
  split up like list elements instead of simple words (see the section later
  about list functions).

If <condition>
<code>
[ElseIf <condition>
<code>]
[Else
<code>]
EndIf

  Executes <code> if the condition is true. If one or more ElseIf sections
  are given and the condition is false, flow of execution will proceed to
  the first section whose condition is true, skipping the rest of the
  sections. If none of the conditions are true and an Else section is
  specified, it will be run.

While [optimized] <condition>
<code>
EndWhile

  Executes <code> repeatedly as long as the condition is true. If the
  condition is initially false, the code will never be run. If the
  'optimized' keyword is specified and <code> is a single line, it will be
  run as a command without evaluation (instead of a block of commands and
  statements), which is faster. If the command needs to be evaluated, prefix
  it with 'Eval'.

For [optimized] (<init-command>; <condition>; <increment-command>)
<code>
EndFor

  Runs <init-command>, then executed <code> repeatedly as long as the
  condition is true, running <increment-command> after each iteration. If
  'Continue' is executed in the code, <increment-command> will still be
  run before the next iteration. If the condition is initially false, the
  code will never be run. The 'optimized' keyword works just like in 'While'.

ForEach (<vars>; <list>)
<code>
EndForEach

  Breaks <list> up into list elements, then locally assigns them in turn to
  each member of <vars> (which must be a comma-separated list of one or more
  variable names) and runs <code>, repeating until all the list elements have
  been used. Some of the variables will be empty during the last iteration if
  there are not enough list elements to fill them.

Switch <text>
[case <text>:
<code>]
[case multi <values>
<code>]
[case range <low>..<high>
<code>]
[case is <relation> <number>
<code>]
[case matches <pattern>
<code>]
[case expr <expression>
<code>]
[case else
<code>]
EndSwitch

  Evaluates <text>, locally assigns the result to $@, then executes the code
  for the first case clause that matches. A case clause of the first type
  matches if its text is the same as $@, ignoring case. A 'case multi'
  matches if any one of the <values> (which must be a comma-separated list)
  is the same as $@, ignoring case. A 'case range' matches if $@ is a number
  between <low> and <high>, inclusive. A 'case is' matches if $@ is a number
  that obeys the given relation (for example, 'case is < 100' would match
  when $@ is a number less than 100). A 'case matches' matches when $@ is
  matched by the given wildcard pattern (see $WildMatch() in the function
  reference). A 'case expr' matches when the expression evaluates to true. A
  'case else' matches when no other cases have matched.
  
  There may be only one 'case else', but the other case clauses can occur
  any number of times in any order.

MenuTree <tree name>
<tree description>
EndMenuTree

  Creates a menu tree with the given name and description. The interpretation
  of <tree name> and <tree description> is up to the host application, which
  might not support menus at all.

MenuItem <item name> on <tree name>
<code>
EndMenuTree

  Assigns code to a menu item that was previously created by MenuTree. The
  host application may not support menus.

Language <name>
<foreign code>
EndLanguage

  Runs <foreign code> through the ActiveScripting engine specified by <name>.
  The foreign code has access to an object called 'Versus' with the following
  methods:
    Parse(Text: string): string
      Evaluates Text and returns the result.
    GetVar(Name: string): string
      Returns the value of the variable with the given name.
    Execute(Command: string)
      Evaluates the command, then runs it.
    ExecuteNoEval(Command: string)
      Runs the command without evaluating it.
    SetVar(Name, Value: string)
      Sets the named global variable to the given value.
    SetVarLocal(Name, Value: string)
      Sets the named local variable to the given value. The variable is
      local to the alias/event/menuitem containing the Language statement.
    IncVar(Name: string; Amount: integer)
      Adds the given amount to the value of the named variable.
  ... and the following property:
    State: integer (read-only)
      Contains an integer made by adding together 1 if the enclosing alias,
      event, or menu item was called as a function, and 2 if text output is
      being suppressed.

With <text>
<code>
EndWith

  Prefixes <text> to each line of <code> (without an intervening space), then
  runs the code.

Function Reference
==================

TVSInterp's commands are divided into separate groups, which can be
individually enabled or disabled by the host application:

Set Functions
-------------

A set is a comma-separated list of words surrounded by square brackets:
[alpha,beta,zappa]. Whitespace, case, and duplicate elements are ignored;
that set is equivalent to [Alpha, Beta  ,ZapPa]. The empty set is [].

$AddToSet(<set> <items>)

  Returns <set> after cleaning it up and adding all the items from <items>
  (which can be a set or a comma-separated list of items). The list returned
  has no space between items, no duplicate items, and is all lowercase.

$RemoveFromSet(<set> <items>)

  Returns <set> after cleaning it up and removing all the <items> from it.

$IsInSet(<items> <set>)

  Returns 1 (true) if all the items from <items> appear in <set>, or 0
  (false) otherwise. <items> can be a set or a comma-separated list of one
  or more items.

List Functions
--------------

A list is a group of list elements separated by spaces. Each item can take one
of three forms:
1. A single word, e.g.: foo
2. One or more words enclosed in double quotes, e.g.: "foo bar"
3. Any text enclosed in balanced angle brackets, e.g.: <foo <bar baz>>

Elements of type 1 and 2 may contain other characters escaped inside them
using backslashes: "\"Hello,\" he said." Functions that return a single element
strip the quoting before returning it.

Each list element has a numerical index, starting with zero for the first
element.

When a list function expects a pattern or delimiter as a parameter, the
parameter can be quoted into a list item (see $ListQuote()) if it contains
spaces or quote marks.

$ListClean(<list>)

  Returns the list with multiple spaces between items condensed into a single
  space.

$ListDelete(<idx> <list>)

  Returns the list after removing the <idx>th element.

$ListElementCount(<list>)

  Returns the number of elements in the list.

$ListFromWords(<words>)

  Creates a list that contains each word in <words> as an element in order
  and returns it. This is equivalent to $ListSplit(" " <words>). Use this
  before attempting to use list functions or ForEach on a list of words that
  have not been quoted as list elements but might contain special list
  characters such as backslash.

$ListIndex(<idx> <list>)

  Extracts the <idx>th element from the list and returns it. The return value
  is empty if there is no element with that number.

$ListIndexOf(<pattern> <list>)

  Returns the index of the first element in the list that matches the
  pattern.

$ListInsert(<idx> <element> <list>)

  Returns the list after inserting <element> at the <idx>th position. If
  <idx> is greater than the number of elements in the list, blank elements
  will be inserted at the end before <element>.

$ListJoin(<delimiter> <list>)

  Concatenates the list's elements by adding <delimiter> in between.
  Any list quoting around the elements will be stripped, so joining the
  elements with a space will not necessarily produce the same list.

$ListQuote(<text>)

  Returns <text> quoted into a suitable list item. Valid type 3 (angle
  bracket) list items are simply surrounded with another pair of angle
  brackets; other types are scanned through to escape list markers with
  backslashes, then surrounded with double quotes if they contain spaces.

$ListRand(<list>)

  Returns a random element from the list.

$ListRange(<start> <end> <list>)

  Returns the list created by extracting elements numbered <start> through
  <end> (inclusive) from <list>.

$ListRemove(<pattern> <list>)

  Returns the list after removing all elements that match <pattern>.

$ListReplace(<start> <end> <element> <list>)

  Returns the list after removing all elements from <start> to <end>
  (inclusive) and replacing them with the single element <element>.

$ListSearch(<pattern> <list>)

  Returns the list created by extracting all the elements that match
  <pattern> from <list>

$ListSearchReplace(<pattern> <element> <list>)

  Returns the list after replacing all elements that match <pattern> with
  <element>.

$ListShuffle(<list>)

  Returns the list with the elements rearranged in a random order.

$ListSort(<list>)

  Returns the list after sorting the elements in ASCII order.

$ListSplit(<delimiter> <text>)

  Returns the list created by splitting <text> into elements separated by
  <delimiter>.

Miscellaneous Functions
-----------------------

Functions that deal with character positions number the characters starting at
1 for the first character.

$Asc(<text>)

  Returns the ASCII code of the first character of the text.

$Char(<num>)

  Returns the character with the given ASCII number.

$CTime()

  Returns the number of seconds Windows has been running.

$Date()

  Returns the current date in a short format.

$DecodeInterval(<seconds>)

  Returns the number of seconds as a human-readable string. For example,
  $DecodeInterval(3680) returns "1 hour 1 minute 20 seconds".

$DecodeMInterval(<milliseconds>)

  Returns the number of milliseconds as a human-readable string. For example,
  $DecodeMInterval(3680711) returns "1 hour 1 minute 20.711 seconds".

$Eval(<text>)

  Evaluates <text> an additional time, then returns it.

$GlobMatch(<string> <pattern>)

  Attempts to match <string> against <pattern>, using only classic wildcards,
  and returns true if it succeeds. <string> may contain spaces, but <pattern>
  may not. Classic wildcard patterns can contain the following special
  characters:

    ?           matches exactly one character of any value
    *           matches zero or more characters of any value

  All other characters are compared directly against the text, ignoring case.
  For example, the pattern "f?o" would match "foo" or "f o" or "flo" but not
  "floo".

$GlobMatchCase(<string> <pattern>)

  Same as $GlobMatch(), but case-sensitive.

$IsNumeric(<text>)

  Returns true if the text is an integer. Note that this will return true
  even for numbers that are out of range.

$Length(<text>)

  Returns the number of characters in the text.

$Lower(<text>)

  Returns the text converted to lowercase.

$MTime()

  Returns the number of milliseconds Windows has been running.

$NoAttribs(<text>)

  Returns <text> after changing all characters produced by backslash
  substitutions back to the original text. For example, $NoAttribs(c:\temp)
  returns "c:\temp", even though the \t is originally interpreted as a tab.

$Rand(<range>)

  Returns a random number greater than or equal to zero, and less than <range>.
  If <range> is omitted, it is assumed to be 2. 

$RStrPos(<needle> <haystack>)

  Returns the position of the beginning of the rightmost occurrence of
  <needle> in <haystack>, or 0 if it doesn't appear.

$RStrTokL(<token> <text>)

  Searches for the rightmost occurrence of <token> in <text> and returns
  everything to the left. If <token> does not appear in <text>, this function
  (and all StrTok functions) pretend that it appears after the end of the text.
  In that case, this function returns the entire string. 

$RStrTokR(<token> <text>)

  Searches for the rightmost occurrence of <token> and <text> and returns
  everything to the right. If <token> does not appear in <text>, this function
  returns an empty string.

$StrPos(<needle> <haystack>)

  Returns the position of the beginning of the first occurrence of <needle> in
  <haystack>, or 0 if it doesn't appear.

$StrPosFrom(<start> <needle> <haystack>)

  Returns the position of the beginning of the first occurrence of <needle>
  in <haystack>, starting the search at the <start>th character. If <needle>
  does not appear, the function returns 0.

$StrTokL(<token> <text>)

  Searches for the first occurrence of <token> in <text> and returns everything
  to the left. If <token> does not appear in <text>, this function returns the
  entire string.

$StrTokR(<token> <text>)

  Searches for the first occurrence of <token> in <text> and returns everything
  to the right. If <token> does not apepar in <text>, this function returns an
  empty string.

$SubStr(<text> <start> <length>)

  Copies and returns up to <length> characters from <text> starting at position
  <start>. If <start> is less than 1 or if <length> is greater than the number
  of characters in the string, fewer characters than specified will be copied.

$Time(<format>)

  Returns the current time in a format specified by <format>. If <format> is
  omitted, a default short format will be used. The format string may contain
  the following specifiers:

    c           displays the date and time in the same default format used by
                $Date() and $Time() without parameters
    d           displays the day of the month without a leading zero (1-31)
    dd          displays the day of the month with a leading zero (01-31)
    ddd         displays the day of the week as an abbreviation (Sun-Sat)
    dddd        displays the day of the week as a full word (Sunday-Saturday)
    ddddd       displays the date in the same default format used by $Date()
    dddddd      displays the date in a default long format
    m           displays the month number without a leading zero (1-12)
    mm          displays the month number with a leading zero (01-12)
                (if m or mm follow an h or hh, they display the minute instead
                of the month, as if n or nn were used instead.)
    mmm         displays the month name as an abbreviation (Jan-Dec)
    mmmm        displays the month name as a full word (January-December)
    yy          displays the year as a two-digit number (00-99)
    yyyy        displays the year as a four-digit number (0000-9999)
    h           displays the hour without a leading zero (0-23)
    hh          displays the hour with a leading zero (00-23)
    n           displays the minute without a leading zero (0-59)
    nn          displays the minute with a leading zero (00-59)
    s           displays the second without a leading zero (0-59)
    ss          displays the second with a leading zero (00-59)
    t           displays the time using the same default format as $Time()
                without parameters
    tt          displays the time using a default long format
    am/pm       displays "am" if it's before noon or "pm" if it's after
    a/p         displays "a" if it's before noon or "p" if it's after
                (am/pm and a/p can be written in lower, upper, or mixed case,
                and the displayed string will change accordingly.)
    ampm        displays a language-specific AM or PM specifier
                (am/pm, a/p, and ampm all force the preceding h or hh specifier
                to use a 12-hour clock instead of the default 24-hour clock.)
    /           displays a language-specific date separator
    :           displays a language-specific time separator
    'x' or "x"  text in quotes is displayed as-is, without being formatted
                as a time string

$UnixTime()

  Returns the current Unix time (number of seconds since midnight, January 1st,
  1970 GMT).

$UnixTime(<unixtime>)

  Returns the given Unix time formatted in the same format as $Time(c).

$UnixTime(<unixtime> <format>)

  Returns the given Unix time formatted using the format string, which is
  interpreted the same way as for $Time(<format>).

$Upper(<text>)

  Returns the text converted to uppercase.

$WildMatch(<string> <pattern>)

  Attempts to match <string> against <pattern> and returns true if it succeeds.
  <string> may contain spaces, but <pattern> may not. Wildcard patterns can
  contain the following special characters:

    ?           matches exactly one character of any value
    *           matches zero or more characters of any value
    %           matches zero or more of any character except a space
               (ASCII 172) matches either the end of the string, or a space
                followed by zero or more characters of any value
    \           escapes the next character so it will not be treated specially

  All other characters are compared directly against the text, ignoring case.
  For example, the pattern "f?o" would match "foo" or "f o" or "flo" but not
  "floo". The pattern "f%o" would match "foo" or "fido" but not "f o". The
  pattern "foo" would match "foo" or "foo " or "foo bar" but not "food".
  The pattern "how\?" would match "how?" but not "howz".

$WildMatch(<string> <pattern>)

  Same as $WildMatch(), but case-sensitive.

$WordCount(<text>)

  Returns the number of space-separated words that appear in <text>.

Miscellaneous Commands
----------------------

Eval <command>

  Evaluates <command> an additional time, then runs it.

NoAttribs <command>

  Runs the command after changing all characters produced by backslash
  substitutions back to the original text (as in $NoAttribs()). Note that this
  will not affect parameters to functions, since the functions have already
  been called by the time NoAttribs sees the text. To protect function
  parameters, use $NoAttribs().

Yield

  Causes the host application to process messages and respond to user input.
  This command is typically used to prevent a loop from locking up the
  application.

Alias Commands/Functions
------------------------

$AliasExists(<name>)

  Returns true if an alias exists with the given name.

UnAlias <name>

  Removes any alias with the given name.

File Commands/Functions
-----------------------

IMPORTANT NOTE: Commands and functions that take a filename followed by another
parameter expect the filename to be quoted as a list element to preserve
spaces. This means that backslashes will be treated specially, and not as path
separators. Use $ListQuote() to get around this, e.g.:
  AppendText $ListQuote($filename) $text

Commands and functions that only take a filename do not expect the parameter to
be quoted.

AppendText <file> <text>

  Appends <text> as a new line at the end of <file>. Nothing happens if the
  file does not already exist.

ChDir <path>

  Attempts to change the current directory to the given path.

CreateFile <file>

  Creates an empty file with the given name, or empties the file if it already
  exists.

$DirExists(<name>)

  Returns true if a directory exists with the given name. If no path is given,
  the current directory is searched.

$FileExists(<name>)

  Returns true if a file exists with the given name. If no path is given,
  the current directory is searched.

$GetCurrentDir()

  Returns the path to the currect directory.

$GetFileDateTime(<file> <format>)

  Returns the modification time and date of the given file, formatted according
  to the format string. If <format> is omitted, a default format will be used.
  If the file does not exist, the result is an empty string.
 
$GetFileSize(<file>)

  Returns the size in bytes of the file, or an empty string if the file does
  not exist.

$GetLinesInFile(<file>)

  Returns the number of lines in the given file, or -1 if the file does not
  exist.

MkDir <path>

  Attempts to create a directory with the given name.

$PathExists(<name>)

  Equivalent to $DirExists(<name>).

$RandomRead(<file>)

  Reads a random line from the file and returns it, or returns an empty string
  if the file does not exist.

$ReadLine(<number> <file>)

  Returns line number <number> (where the first line is 1) from <file>, or
  an empty string if the file does not exist or there is no line with that
  number.

RmDir <path>

  Attempts to delete the named directory.

RmFile <file>

  Attempts to remove the named file.

File Dialog Functions
---------------------

These functions are only available if both file commands/functions and dialog
commands/functions are enabled. The <filter> string should be a
vertical-bar-separated list of the format:
  Text files (*.txt)|*.txt|All files (*.*)|*.*
where the first segment is a human-readable description of the first file type,
the second segment is a file mask for the first type, the third segment is a
description of the second file type, and so on. Keep in mind that the filter
is only a suggestion, and the dialog will still allow filenames that don't
match it.

$OpenDialog(<title>|<filter>)

  Displays a standard Windows file open dialog with <title> in the title bar
  and <filter> in the drop-down box. Returns the path to the selected file, or
  an empty string if the user aborts the box by pressing Escape or Cancel. The
  returned file name is not guaranteed to exist.

$OpenPictureDialog(<title>|<filter>)

  The same as $OpenDialog(), except the dialog will show previews of image
  files as they are selected.

$SaveDialog(<title>|<filter>)

  Displays a standard Windows file save dialog with <title> in the title bar
  and <filter> in the drop-down box. Returns the path to the chosen file, or
  an empty string if the user aborts the box by pressing Escape or Cancel. The
  dialog will not ask for confirmation if the user selects a file that already
  exists.

$SavePictureDialog(<title>|<filter>)

  The same as $SaveDialog(), except the dialog will show previews of image
  files as they are selected.

Dialog Commands/Functions
-------------------------

MessageBox <text>

  Displays a message box with an OK button, the application's name in the title
  bar, and <text> inside the window.

$MessageDlg(<format> <text>)

  Displays a message dialog according to <format> with <text> inside the
  window, and returns a number describing the user's choice. <format> is a
  number made by adding these values, at most one from each group:

  Buttons shown:
    0     only show OK button
    1     show OK and Cancel
    2     show Abort, Retry, and Ignore
    3     show Yes, No, and Cancel
    4     show Yes and No
    5     show Retry and Cancel
  Icon shown:
    16    show STOP icon
    32    show question mark icon
    48    show exclamation point icon
    64    show "i" icon
  Default button:
    0     first button is default
    256   second button is default
    512   third button is default

  The return value is a number describing which button was chosen:
    1     OK
    2     Cancel
    3     Abort
    4     Retry
    5     Ignore
    6     Yes
    7     No

MessageDlg <format> <text>

  The same as $MessageDlg(<format> <text>) but discards the return value.

Sound commands
--------------

Beep

  Plays the default system sound.

MCI <command>

  Sends <command> to Windows's Media Control Interface system. The format of
  these strings is described in the Win32 API specification. Here are a few
  more common commands:

  play <filename>
    Plays a media file (WAV, MID, AVI).
  stop <filename>
    Stops playback and rewinds the file.
  pause <filename>
    Pauses playback.
  resume <filename>
    Resumes from where the file was paused.
  record <filename>
    Begins recording a media file.
  stop <filename>
    Stops recording.
  play cdaudio from <num>
    Plays track number <num>.
  stop cdaudio
    Stops CD playback.

Clipboard Command/Function
--------------------------

$GetClipboard()

  Returns the text on the clipboard, or an empty string if there is no text on
  the clipboard.

SetClipboard <text>

  Sets the clipboard to contain <text>.

DDE Command/Function
--------------------

$DDE(<service> <topic> <item> <text>)

  Attempts to send <text> to the specified DDE server using ExecuteMacro, then
  returns any text that results from it. <item> is treated as a list element,
  so it may contain spaces.

DDE <service> <topic> <item> <text>

  The same as $DDE(<service> <topic> <item> <text>), but discards any result.

