DP Tool Club 8/CDASC08.ISO/NEWS/2293/AML.DOC

Text File | 1993-10-07 | 159KB | 4,314 lines

  T h e   A u r o r a   M a c r o   L a n g u a g e   G u i d e
  ─────────────────────────────────────────────────────────────









  The Aurora Macro Language Guide

  Version 1.01, August 1993  (unregistered)

  Copyright (c) 1993 Aurora Terra, Inc.

  ALL RIGHTS RESERVED.






  Aurora Terra, Inc.
  P.O. Box 34275
  Bethesda, MD. 20827-0275  USA
  (301)-468-2255



  The Aurora Editor is Copyright (c) 1993 by Aurora Terra, Inc.
  The Aurora Editor/386 is Copyright (c) 1993 by Aurora Terra, Inc.
  The Aurora Macro Language is Copyright (c) 1993 by Aurora Terra, Inc.

  No parts of The Aurora Editor software or this document may be copied
  in part or in whole, except as provided by the License in the
  following pages.

  This version of The Aurora Editor is NOT public domain or free
  software, but is distributed as "shareware" for evaluation purposes
  only. Please refer to the license information in the following pages.

  The Aurora Editor is a trademark of Aurora Terra, Inc.
  The Aurora Editor/386 is a trademark of Aurora Terra, Inc.
  The Aurora Macro Language is a trademark of Aurora Terra, Inc.

  Other product names found throughout this document are trademarks of
  various companies.
                                                  Table of Contents   vi


  Table of Contents
  ─────────────────

  I-1  Introduction...................................................ii

  1-1  The Aurora Macro Language.......................................1
  1-2  Macro Language Sentences........................................2
  1-3  Comments........................................................3
  1-4  Evaluating Arguments............................................3
  1-5  Function Call Series............................................4
  1-6  Variables.......................................................5
  1-7  Native Functions................................................6
  1-8  Defining Functions..............................................8
  1-9  Control Functions..............................................10
  1-10  Logical Functions.............................................11
  1-11  Objects.......................................................12
  1-12  Handling Events...............................................14
  1-13  The Interpreter and Compiler..................................16

  2-1  Native Function List...........................................17

  3-1  Native Functions - In Detail...................................24
  3-2  Definition Functions...........................................25
  3-3  Conditional Functions..........................................26
  3-4  Logical Functions..............................................27
  3-5  Bitwise Logical Functions......................................27
  3-6  Control Functions..............................................28
  3-7  Arithmetic Functions...........................................28
  3-8  String Functions...............................................29
  3-9  Evaluation and Compilation Functions...........................32
  3-10  Miscellaneous Functions.......................................33
  3-12  Object Functions..............................................34
  3-13  Disk Functions................................................36
  3-14  System Functions..............................................39
  3-15  Timer Functions...............................................42
  3-16  Keyboard Functions............................................43
  3-17  Mouse Functions...............................................45
  3-18  Queue Functions...............................................46
  3-19  Video Functions...............................................48
  3-20  Text Buffer Functions.........................................51
  3-21  Mark Functions................................................59
  3-22  Window Functions..............................................68

  A-1  The Aurora Macro Language and The Aurora Editor................83

                                                       Introduction   ii


  Warranty Disclaimer
  ───────────────────

  Aurora Terra makes no warranty of any kind, either express or implied,
  including but not limited to implied warranties of merchantability and
  fitness for a particular purpose, with respect to this software and
  accompanying documentation.

  IN NO EVENT SHALL AURORA TERRA BE LIABLE FOR ANY DAMAGES RESULTING
  FROM THE USE OF THIS SOFTWARE, INCLUDING BUT NOT LIMITED TO, DAMAGES
  FOR LOSS OF BUSINESS PROFITS, BUSINESS INTERRUPTION, LOSS OF BUSINESS
  INFORMATION, INCIDENTAL OR CONSEQUENTIAL DAMAGES, OR OTHER FINANCIAL
  LOSS ARISING OUT OF THE USE OF OR INABILITY TO USE THIS PROGRAM, EVEN
  IF AURORA TERRA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.


  I-1  Introduction
  ─────────────────

  This is The Aurora Macro Language Guide. It describes all of the
  features and native functions of The Aurora Macro Language. Prior
  knowledge of another programming language such as C or Pascal may be
  helpful in understanding this document.

  For information on how to install, configure, and use The Aurora
  Editor, see "The Aurora Editor Users Guide".

  It is not necessary to understand all the details of the Aurora Macro
  Language to use The Aurora Editor. However, experienced users may find
  the macro language to be very useful for writing new editor functions,
  or in configuring detailed aspects of the editor. Knowledge of the
  macro language may also help you to better understand the keyboard
  definition (AKBD.A), menu definition (AMEN.A), and configuration
  (ACFG.A) files for The Aurora Editor.

  This document describes macro language "native" functions which are
  built in to The Aurora Macro Language. The Aurora Editor also uses
  many "library functions" which are built up from native functions and
  are contained in the file ALIB.X. Library functions are documented in
  the The Aurora Editor Users Guide (A.DOC), and summarized in the The
  Aurora Editor Quick Reference (AREF.DOC).
                                           The Aurora Macro Language   1


  1-1  The Aurora Macro Language
  ──────────────────────────────

  The Aurora Macro Language is a flexible, interpreted language, which
  is simple in syntax, yet rich in function. A primary design goal was
  to keep the macro language interpreter and compiler small enough so
  they would fit in the same .EXE file as the rest of the editor. This
  allows the editor to execute macro language expressions interactively
  within an editor session, and greatly enhances the overall flexibility
  of the editor. Both the interpreter and compiler are accessible as
  native functions within the macro language itself.

  The Aurora Macro Language may appear somewhat similar to LISP in
  syntax, but the resemblance ends there. The Aurora Macro Language is
  primarily a "string-oriented" language with "the string" as the only
  visible data type. All functions and data are viewed as character
  strings and can be manipulated as character strings. Since there is
  only one data type, no variable declarations are required.

  The Aurora Macro language is also "object-oriented". Functions and
  data can be encapsulated into "objects", and object hierarchies can be
  created with "inheritance" and "multiple inheritance". Inheritance
  hierarchies can also be dynamically altered.


  1-2  Macro Language Sentences
  ─────────────────────────────

  Each program in written in The Aurora Macro Language is really just a
  string composed of a series of macro language "sentences". Each
  sentence is composed of a series of "words" separated by spaces, and
  each sentence is usually terminated by a period. The first word in
  each sentence is the name of a function to execute, and any words that
  follow are arguments to the function. For example:

    abc 1 2 3.
    xyz "foo" "bar" x.

  In the above example, two sentences are evaluated. The arguments "1",
  "2", and "3" are passed to the function "abc", and the strings "foo",
  "bar", and the variable "x" are passed to the function "xyz".

  Function names can be up to 255 characters in length and may contain
  any characters. You can use "native" (built-in) functions, or define
  your own functions.
                                            Macro Language Sentences   2


  A function can have up to 100 arguments, or no arguments at all.
  Arguments to a function may be integers from -2147483647 to
  [phone], strings enclosed in double quotes, variables, or even
  other sentences.

  Hex integers can be specified by adding an "h" at the end of the
  integer. A leading zero is required if the hex integer begins with an
  alphabetic character. For example, "1h", "3CH", and "0FFFFh" are valid
  hex integers.

  Strings may be up to 16000 characters in length, and variable names
  may be up to 255 characters in length.

  If an argument to a function is another sentence, it must be enclosed
  in parentheses:

    abc 1 (xyz "foo" "bar" x) 3.

  In the above example, the arguments "foo", "bar", and the value of the
  variable "x" are passed to the function "xyz". The result of
  evaluating "xyz" becomes the second argument to the function "abc".
  Note that a terminating period is not required for the sentence
  beginning with "xyz" since it is already terminated by a right
  parenthesis.

  An argument may also be composed of more than one sentence. In this
  case, the value of the argument is the value of the last sentence:

    abc 1 (alpha "foo" "bar". beta. gamma 5 6) 3.

  In the above example, the value of the second argument to "abc" is the
  result of evaluating the sentence "gamma 5 6".

  A sentence may be spread out over more than one line and spaces may be
  inserted anywhere in the sentence, as long as the words in the
  sentence are not split. The above example could also be written as:

    abc 1 (
      alpha "foo" "bar".
      beta.
      gamma 5 6
    )  3.
                                                            Comments   3


  1-3  Comments
  ─────────────

  Single line and multi-line comments can be inserted anywhere within a
  macro language program. In a single line comment, any characters
  located between two slashes (//) and the end of the line are ignored
  (except if they are contained within a double quoted string). For
  example:

    abc 1 2 3.           // this is a single line comment
    xyz "foo" "bar" x.   // this is another single line comment

  Multi-line comments can span any number of lines. For multi-line
  comments, any characters located between the comment delimiters "/*"
  and "*/" are ignored. For example:

    abc 1 2 3.
       /* this is a
          multi-line comment */
    xyz "foo" "bar" x.


  1-4  Evaluating Arguments
  ─────────────────────────

  When the interpreter evaluates a macro language sentence, each
  argument in the sentence is evaluated from first to last. The
  resulting values for each argument are passed to the function (the
  first "word" in the sentence) and the function is evaluated. For
  example:

    abc 1 "foo" x (xyz 5 6).

  In the above macro language sentence, the first argument evaluates
  to "1", the second argument evaluates to "foo", the third argument
  evaluates to value of the variable "x", and the fourth argument
  evaluates to the value of the sentence "xyz 5 6".

  You can prevent the evaluation of an argument by prefixing it with
  the "literal" operator (%). For example:

    abc 1 "foo" %x (xyz 5 6).

  The difference between the above example and the previous example is
  that the third argument is now the string "x", not the variable "x" (x
  is not evaluated). As you can see from the above example, using the
  literal operator (%) can also be a convenient way to specify string
  arguments (that contain no blanks), without enclosing the string in
  double quotes.
                                                Evaluating Arguments   4


  If all of the function arguments are prefixed with the literal (%)
  operator, you can remove the literal operator from the arguments and
  attach it to the end of the function name. For example:

    xyz %foo %bar %x.

      is equivalent to:

    xyz% foo bar x.

  In both the examples above, the strings "foo", "bar", and "x" are
  passed to the function "xyz". Note that some native functions in the
  macro language (such as the "fun" function) do not normally evaluate
  their arguments. These functions automatically assume that all
  arguments are "literal", without having to use the literal operator.

  The inverse of the literal operator is the "evaluation" operator (@).
  This operator forces evaluation of an argument, even when the function
  name is suffixed with the literal operator (%). For example:

    xyz% foo bar @x.

  In the example above, the third argument evaluates to the value of the
  variable "x", not the string "x". The first and second arguments still
  evaluate to the strings "foo" and "bar".

  Both the literal operator (%) and the evaluation operator (@) can be
  used to specify "null" arguments (strings of zero length) when they
  are specified by themselves. For example:

    xyz @ % %foobar.

  In the example above, the first and second arguments are "null"
  strings, and the third argument is the string "foobar".


  1-5  Function Call Series
  ─────────────────────────

  In many programming languages, the situation often arises where the
  same function is called many times in series, each time with different
  arguments. The Aurora Macro Language provides a convenient way to
  handle this situation: just specify the function name once and then
  specify each set of arguments separated by commas. For example:

    abc 1 2 3.
    abc 4 5 6.
    abc 7 8 9.
                                                Function Call Series   5


      is equivalent to:

    abc 1 2 3, 4 5 6, 7 8 9.


  1-6  Variables
  ──────────────

  The Aurora Macro Language allows you to assign values to variables
  which are local to a function definition, or that reside in a macro
  language "object" (see the "Defining Functions" and "Objects" sections
  below for a description of function definitions and objects).

  Variables local to a function are referred to as "local" variables,
  whereas variables that reside in an object are referred to as "object"
  variables. There is no need to define either of these variables. Both
  variable types are defined the first time a variable assignment is
  made.

  The native function "=" is used to assign a value to a local variable.
  For example:

    = %x 3.    // local variable x is assigned a value of "3"

  Note that in the example above, the argument "x" must be preceded by
  the literal operator (%), otherwise the VALUE of the variable "x"
  (instead of the variable "x") would be assigned the value "3".
  The above example could also have been written as:

    = "x" 3.   // local variable x is assigned a value of "3"

  Local variable assignments exist until they are re-assigned or until
  the function in which they are contained returns.

  To assign a value to a "object" variable, use the "set" native
  function. The assignment will be made in the "default" object, unless
  an object name is explicitly specified between two slash (/)
  characters. For example:

    set %x 3.          // object variable x in the "default" object is
                       //   assigned the value "3"
    set %/aurora/x 3   // object variable x in the object "aurora" is
                       //   assigned the value "3"

  Object variable assignments exist until they are re-assigned or until
  the object in which they are located is destroyed. Since object
  variable assignments can remain in effect across function calls, they
  are considered to be "global" variables.
                                                           Variables   6


  These are more examples of variable assignments:

    =% x foobar.            // assigns "foobar" to local variable x
    = %i x.                 // assigns the value of x to local var i
    = %i (abc 3 x).         // assigns the value of the expression
                            //   "abc 3 x" to local variable i

    set% x foobar.          // assigns "foobar" to object variable x
                            //   (in the default object)
    set %x y.               // assigns the value of y to object var x
    set %x (xyz).           // assigns the value of the function
                            //   "xyz" to object variable x
    set (xyz) %x.           // assigns "x" to the variable name which
                            //   is the value of function "xyz"
    set %/aurora/x y.       // assigns the value of y to object var x
                            //   in the object "aurora"

  When a reference is made to a variable which has never been assigned a
  value (a "non-existent" variable), the value of that variable is
  always the "null" string (a string of length zero).

  Note that when variables are referenced, local variables have higher
  precedence than object variables. For example:

    = %x 4.
    set %x 5.
    abc x.

  In the example above, the value "4" will be passed to the function
  "abc". The argument "x" to function "abc" refers to the local variable
  "x", not the object variable "x".


  1-7  Native Functions
  ─────────────────────

  The Aurora Macro Language has hundreds "native" functions, which are
  pre-defined or "built-in". A few commonly used native functions may be
  used in later examples and are worth mentioning briefly here:


  Conditional:

    eq     returns "1" if all of it's arguments are equal, otherwise
           it returns the null string.

    ne     returns "1" if all of it's arguments are not equal,
           otherwise it returns the null string.
                                                    Native Functions   7


    >      returns "1" if each of it's arguments is numerically
           greater than the argument which follows, otherwise it
           returns the null string.

    <      returns "1" if each of it's arguments is numerically less
           than the argument which follows, otherwise it returns the
           null string.


  Arithmetic:

    +      returns the numeric sum of all of its arguments.

    -      if only one argument is specified, it returns the numeric
           negative of the argument, otherwise it returns the value of
           of the first argument minus all the arguments which follow.

    *      returns the numeric product of all of its arguments.

    /      returns the value of the first argument divided by all the
           arguments which follow.


  String:

    cat    concatenates all of its arguments and returns the result.

    sub    returns the substring of its first argument taken from the
           position of the second argument and extending for the
           length of the third argument.

    fin    searches for the second argument inside the first argument
           and returns the position if found, otherwise it returns
           null.


  Other:

    beep   beeps the PC speaker at the frequency of the first argument
           for the duration of the second argument.


  Library:

    say    displays a message on the window title bar (this function is
           documented in "The Aurora Editor Users Guide").
                                                  Defining Functions   8


  1-8  Defining Functions
  ───────────────────────

  The Aurora Macro Language has many native functions which are
  pre-defined when a macro language program is evaluated. No further
  definitions are required to use native functions.

  To create your own functions, you must first define them with the
  native function "fun". For example:

    fun  hello (
      say "hello".
      beep 300 300.
    ).

  In the example above, the function "hello" is defined. Note that the
  native function "fun" automatically assumes that both its arguments
  are literal. The literal operator (%) is not required. Also note that
  the definition of "hello" is a macro language "sentence", and
  therefore requires a terminating period.

  Arguments passed to user-defined functions can be accessed with the
  the "arg" and "qarg" native functions. The "arg" native function maps
  any arguments passed to the function to local variables within the
  function. For example:

    fun  hello (
      arg s f.
      say s.
      beep f 300.
    ).

  In the example above, the local variables "s" and "f" are mapped to
  the first two arguments passed to "hello". The variables "s" and "f"
  can then be used in any expression within the function. This does not
  mean that exactly two arguments must always be passed to "hello". Any
  number of arguments may be passed to any function. If only one
  argument were passed to the function "hello" in the example above, the
  value of the local variable "f" would be the null string. If three
  arguments were passed to "hello", the third argument would not be
  accessible as a local variable.

  The "qarg" native function allows you access function arguments by the
  order in which they where passed. The "qarg" function takes one
  argument: the relative position of the argument being passed to the
  function. The following example is equivalent to the previous example:
                                                  Defining Functions   9


    fun  hello (
      say (qarg 1).
      beep (qarg 2) 300.
    ).

  Note that "qarg 0" will return total number of arguments passed to the
  function.

  Remember that you can call any function with any number of arguments
  at any time. The number of arguments is always determined by the
  function call, not the function.

  It is also possible to call non-existent or undefined functions.
  Calling an undefined function will always return the value of the last
  argument passed to the undefined function. Calling a defined function
  returns the value of the last sentence in the function. For example:

    fun  abc (
      arg x y.
      dothis 1 x.
      dothat 2 y.
      hello x y.
    ).

    abc "hello world" 300.

  In the example above, the function "abc" is defined and then called
  with the arguments "hello world" and "300". The return value of the
  call to "abc" would be the result of evaluating the last sentence
  "hello x y". If the function "hello" is not defined, the return value
  of "abc" would be "300".

  It is also possible to call the "null" function by using the literal
  operator (%) or the evaluation operator (@) as the function name.
  Since the null function is not defined, it always returns the value of
  the last argument passed to it. This can be useful for returning
  variables or constant values from a function. For example:

    fun  xyz (
      = %x 3.
      % x.
    ).

    set %y (xyz).

  In the example above, the function "xyz" is defined and then called
  with no arguments. The function "xyz" assigns "3" to the local
  variable "x" and then returns the value of "x" (3). The object
  variable "y" is then assigned a value of "3".
                                                  Control Functions   10


  1-9  Control Functions
  ──────────────────────

  There are several native functions which can be used to control the
  flow of execution of a macro language program. Note that no special
  syntax is required to use control functions. They are treated just
  like any other function. The difference between control functions and
  other functions is that not all of the arguments to a control function
  are always evaluated.

  Perhaps the most commonly-used control function is the "if" function.
  The first argument of the "if" function is always evaluated. If the
  first argument does not evaluate to zero or null, then the second
  argument is evaluated, otherwise the third argument is evaluated. The
  return value of the "if" function is the value of the second or third
  argument, depending on which one is evaluated. For example:

    if x (abc) (xyz).

  In the example above, if the variable x is "0" or null, then the
  function "xyz" is evaluated, otherwise the function "abc" is
  evaluated.

  "Conditional" native functions such as "eq" are often used with the
  "if" function. For example:

    if (eq s "yes") (
      = %x 1.
      beep 700 200.
    )(
      = %x 2.
      beep 200 200.
    ).

  In the example above, if the variable "s" is equal to "yes", the value
  "1" is assigned to local variable "x" and a high-pitched beep is
  heard. If "s" is not equal to "yes", the value "2" is assigned to "x"
  and low-pitched beep is heard.

  The "if" function can be used anywhere that any other function can be
  used. For example:

    = %x (if (eq s "no") "nope" "yup").

  In the example above, if "s" is equal to "no", then the value "nope"
  is assigned to "x", otherwise the value "yup" is assigned to "x".
                                                  Control Functions   11


  The "while" and "dowhile" functions are control functions which can be
  used to perform looping operations. The "while" function will evaluate
  it's first and second arguments repeatedly while it's first argument
  is "true" (non-null and non-zero). For example:

    = %x 1000.
    while x (
      beep x 200.
      = %x (- x 100).
    ).

  In the example above, the PC speaker will beep 10 times, each time
  with decreasing frequency.

  The "dowhile" function is similar to the "while" function, except that
  the first and second arguments are evaluated repeatedly until the
  second argument evaluates to "false" (null or zero). The following
  example is equivalent to the previous example:

    = %x 1000.
    dowhile (
      beep x 200.
      = %x (- x 100).
    ) x.


  1-10  Logical Functions
  ───────────────────────

  The logical functions test the logical values of their arguments to
  return either "1" (true) or null (false). Like the control functions
  (see above), not all of the arguments to a logical function are always
  evaluated.

  The following logical functions are available:

    and    returns "1" if all it's arguments evaluate to "true"
           (non-null and non-zero). If an argument does not evaluate
           to "true", then no more arguments are evaluated.

    or     returns "1" if at least one of it's arguments evaluate to
           "true". No more arguments are evaluated after the first
           "true" argument is found.

    !      returns "1" if all of it's arguments evaluate to "false",
           otherwise it returns null. All arguments are evaluated.

  The following example demonstrates the use of logical functions:
                                                  Logical Functions   12


    if (and ((eq x 3) (or y z))) (beep 400 400).

  In the example above, a beep is heard only if the variable "x" is "3",
  and at least one of the variables "y" or "z" are true (non-null and
  non-zero).



  1-11  Objects
  ─────────────

  In The Aurora Macro Language, an object is a user-defined group of
  function definitions and variable assignments. Each object has a name
  (up to 255 characters). By default, all object variables and functions
  are placed in the pre-defined object "a". The object "a" is
  automatically created by the interpreter whenever a macro language
  program is evaluated.

  To create a new object, you must use the native function "objnew". For
  example:

    objnew% 17 aurora.

  In the example above, a new object called "aurora" will be created.
  The object "aurora" will have an estimated size of 17 function
  definitions and/or variable settings (this size estimate is used by
  the interpreter to create an optimized internal index).

  To add functions or variable assignments to the object you created,
  use the "obj" native function:

    obj  aurora  (

      set %x 1.        // assign 1 to variable x in object "aurora"
      set %y 2.        // assign 2 to variable y in object "aurora"

      fun  abc (       // define function "abc" in object "aurora"
        say "abc".
      ).

      fun  xyz (       // define function "xyz" in object "aurora"
        say "xyz".
      ).

    ).

  In the example above, any variable assignments or function definitions
  within the scope of the "obj" sentence will be added to the object
  "aurora" (the default object is "aurora" inside the obj sentence).
  Variable assignments or functions definitions made outside the scope
  of the "obj" sentence would be added to the default object "a".
                                                            Objects   13


  Like the "fun" native function, the "obj" native function assumes that
  all its arguments are literal. The literal operator (%) is not
  required.

  An object can "inherit" the functions and variable assignments of
  other objects by grouping them together in "inheritance paths". When a
  reference to function or variable is made, and it is not found in the
  current "default" object, then the object's inheritance path is
  searched until the reference is found. This mechanism works similar to
  the way the DOS "PATH" environment variable is searched when executing
  DOS programs, except that it is also possible to create hierarchal
  search paths.

  The searching of inheritance paths is performed automatically by the
  macro language interpreter and is transparent to any function call or
  variable reference. Note that "native" functions are always accessible
  from within any object.

  The inheritance path or "ancestry" of an object can be defined when
  the object is created with the "objnew" command. For example:

    objnew% 17 aurora obj1 obj2.

  In the example above, the object "aurora" is created and assigned the
  inheritance path "obj1 obj2". When a reference to a function or
  variable in the object "aurora" fails, the objects "obj1" and "obj2"
  are searched for the reference (in the order they are specified). In
  this way the object "aurora" is said to "inherit" the functions and
  object variables of "obj1" and "obj2". Using inheritance, the object
  "aurora" appears to contain all of the functions and variables of
  "obj1" and "obj2". Note that the objects "obj1" and "obj2" may also
  have inheritance paths. In this way, hierarchal inheritance paths can
  be established.

  Consider the following example:

    objnew% 1 obj1, 1 obj2.
    objnew% 3 aurora obj1 obj2.

    obj  obj1 (
      set% s hello.
    ).

    obj  obj2 (
      fun  hello (
        arg x y.
        say x.
        beep y 300.
      ).
    ).
                                                            Objects   14


    obj  aurora (
      hello s 400.
    ).

  In the example above, the function "hello" is called with the
  arguments "s" and "400". Since there is no function "hello" in the
  object "aurora", the inheritance path for "aurora" is searched and
  "hello" is found in "obj2". Also, since object "aurora" has no
  variable "s", the inheritance path is searched and "s" is found in
  "obj1".

  Object inheritance paths can also be changed dynamically via the
  "objpar" native function. For example:

    objpar% aurora obj3 obj4.

  In the example above, the inheritance path for the object "aurora" is
  changed to "obj3 obj4".


  Functions and variables in other objects can be referenced directly by
  specifying the object name between slash (/) characters immediately
  before the function name or variable name. For example:

    abc 1 2 /aurora/x.     // variable x in object "aurora"

    /obj2/xyz "foobar".    // function "xyz" in object "obj2"



  1-12  Handling Events
  ─────────────────────

  Event Handling is a built-in feature of The Aurora Macro Language.
  When an external event occurs (a keystroke, mouse event, or timer
  event), it is posted to the interpreter event queue. The next time the
  interpreter is idle, it will read the event from the event queue,
  translate it into a pre-defined function name (with arguments if
  applicable), and attempt to call the function. If the user has
  properly defined a function with the same pre-defined function name,
  the user's function will be called automatically by the interpreter.

  When the interpreter calls the user's function, it will always look
  for the function in the current "event object" (the event object is
  not the necessarily the same object as the default object). Only one
  object can be the event object at any given time. When a macro
  language program is initially evaluated, the event object is the
  default object "a", but that can be changed at any time by the program
  (see below).
                                                    Handling Events   15


  If the function is not found in the event object, the interpreter will
  search the event object's inheritance path for the event function. In
  this way, an object inherits the event-handling capabilities of it's
  ancestor objects.

  It is often useful to change the entire behavior of the keyboard and
  mouse simply by making another object the event object. For example,
  when you switch from a File Manager window to an Edit window, The
  Aurora Editor simply changes current event object, and a whole
  different set of keyboard functions and mouse functions become active.

  To change the current event object, use the native function "objeve":

    objeve %aurora2.

  In the example above, the object "aurora2" becomes the current event
  object.


  You can place your own user-generated events in the interpreter event
  queue using the native function "que". For example:

    que% xyz 1 3.

  In the example above, the function call "xyz 1 3" is placed on the
  interpreter event queue. The next time the interpreter is idle, it
  will read "xyz 1 3" from the event queue and evaluate it in the
  current event object, just like a keyboard or mouse event.

  User-generated events can also be directed to an explicitly specified
  object (other than the event object), by using the native function
  "queobj". For example:

    queobj% aurora xyz 1 3.

  In the example above, "xyz 1 3" is placed on the interpreter event
  queue. However, when the interpreter later reads "xyz 1 3" from the
  event queue, it will force the evaluation of "xyz 1 3" to occur in the
  object "aurora", not in the current event object.

  The native functions "send" and "sendobj" work just like "que" and
  "queobj" above, except that the interpreter event queue is bypassed.
  The functions specified in "send" and "sendobj" are always called
  immediately. For example:

    send% xyz 1 3.
    sendobj% aurora abc 5 7.
                                                    Handling Events   16


  In the examples above, "xyz 1 3" is evaluated immediately in the
  current event object, and "abc 5 7" is evaluated immediately in the
  object "aurora".


  1-13  The Interpreter and Compiler
  ──────────────────────────────────

  The Aurora Macro Language contains native functions for compiling and
  evaluating macro language code.

  To evaluate a string of macro language source code from within a macro
  language program, use the "evl" function. For example:

    = %x "+ 4 5 6".
    = %y (evl x).

  In the example above, the local variable "x" is assigned a string
  which is a macro language expression. In the next sentence, the "evl"
  function evaluates the value of "x" and assigns the result (15) to
  "y".

  Since there are many native functions for manipulating strings, you
  can actually construct code dynamically and execute it from within a
  running macro language program using the "evl" function.

  To evaluate macro language code in a file on disk, use the native
  function "objdsk". For example:

    objdsk %aurora "test.a" 3 4.

  In the example above, the contents of the file "test.a" are evaluated
  and passed the arguments "3" and "4", with "aurora" as the default
  object. The "objdsk" command will evaluate both macro language source
  and compiled files (compiled files will execute faster).

  To compile a macro language source file on disk, use the native
  function "comf". For example:

    comf "test.a" "test.x".

  In the example above, the file "test.a" is compiled and the result is
  placed in the file "test.x".

  You can use any filenames you wish for source and compiled files. The
  convention is to use the file extension ".A" for macro language source
  files, and ".X" for compiled macro language files.
                                               Native Function List   17


  2-1  Native Function List
  ─────────────────────────

  The following section summarizes all available native macro language
  functions by category. Each native function is followed by a brief one
  line description.


  Definition Functions:

    =     - assign a value to a local variable
    set   - assign a value to an object variable
    ren   - rename an object variable or function
    uns   - remove an object variable or function from an object

    fun   - define a function
    arg   - map function arguments to local variables
    qarg  - access function arguments by ordinal number


  Conditional Functions:

    eq   - test strings for equality
    eqi  - test strings for equality (ignoring case)
    ne   - test strings for inequality
    ==   - test integers for equality
    !=   - test integers for inequality
    <    - test if each argument is less than the next
    >    - test if each argument is greater than the next
    <=   - test if each argument is less than or equal to the next
    >=   - test if each argument is greater than or equal to the next


  Logical Functions:

    and  - test if all arguments are true
    or   - test if one argument is true
    !    - test if no arguments are true


  Bitwise Functions:

    &    - return the "bitwise and" of two strings
    |    - return the "bitwise or" of two strings
    ^    - return the "bitwise exclusive or" of two strings
                                               Native Function List   18


  Control Flow Functions:

    if       - if-then-else structure
    while    - loop while first argument is true
    dowhile  - loop while second argument is true


  Arithmetic Functions:

    +    - add all arguments together
    -    - subtract arguments from first argument
    *    - multiply all arguments together
    /    - divide first argument by other arguments
    mod  - return modulus of first argument divided by second argument


  String Functions:

    cat  - concatenates all arguments
    sub  - get a substring of the first argument
    fin  - search for a string in another string, with optional replace
    siz  - return the total size (in bytes) of arguments
    dup  - duplicate a string any number of times
    wrd  - set the character set to define a "word"
    idx  - search for the first of a group of characters in a string
    vfy  - verify that a string is composed of specified characters
    chc  - change the case of a string

    byte - convert an integer to a 1-byte string
    word - convert an integer to a 2-byte string
    long - convert an integer to a 4-byte string
    hex  - convert a hex string to a normal string
    toh  - convert a normal string to a hex string


  Evaluation and Compilation Functions:

    evl  - evaluate a string as macro language code
    evla - evaluate a string as if it were a function argument
    comf - compile a macro language source file
    #get - include a macro language source or compiled file
    var  - evaluate a string as if it were a variable
    prs  - parse a string for input to evl or evla.
                                               Native Function List   19


  Miscellaneous Functions:

    asc  - return the ascii integer value of a character
    pat  - expand a filename to fully qualified name
    exe  - execute a DOS program
    wait - delay for a specified number of milliseconds
    beep - beep the PC speaker


  Object Functions:

    obj     - add functions and variables to an object
    objnew  - create a new object and establish object ancestry
    objdes  - destroy an object
    objsav  - save an object
    objnam  - rename an object
    objeve  - change the current event object
    objpar  - change the ancestry of an object
    objdsk  - evaluate macro language source or compiled code in a file

    qobj    - test for the existence of an object
    qobjsiz - return the size of an object (variables and functions)
    qobjexe - return the current object
    qobjeve - return the current event object
    qobjanc - test for the ancestry of an object


  Disk and File Functions:

    dskdel  - delete a file
    dskren  - rename a file
    dskloc  - search for a file in multiple directories
    dskfin  - search for a string in a file
    dskcpy  - copy a file
    dskcur  - change the current disk drive and/or path
    dskdir  - create a directory
    dsktch  - touch a file
    dskatt  - change file attributes

    qdskpat - return the current drive/path or boot path
    qdskdrv - return available disk drives
    qdskcap - return disk drive capacity (total and used)


  System Functions:

    sysmem  - define maximum XMS/EMS memory
    sysswp  - define swap files
    sysprt  - define printer settings
    syssnd  - enable or disable sound
                                               Native Function List   20


    qsysver - return the current version of The Aurora Editor
    qsysos  - return the current version of the operating system (DOS)
    qsyspgm - return the name of The Aurora Editor .EXE file
    qsysvar - return the value of an environment variable


  Timer Functions:

    timdes  - destroy a timer
    timint  - create a interval timer
    timalm  - create an alarm timer

    qtim    - return the current time


  Keyboard Functions:

    kbdenh  - enable/disable enhanced keyboard
    kbdrpt  - define keyboard event reporting mode
    kbdclr  - clear keyboard buffer

    qkbdshf - return keyboard shift status
    qkbdchr - wait for a character to be entered and return it


  Mouse Functions:

    mouini  - open and initialize the mouse
    moutrm  - close the mouse
    mousen  - adjust mouse sensitivity
    mourpt  - define mouse event reporting mode
    moupos  - set the mouse position
    mouvis  - show/hide the mouse

    qmoupos - return the mouse x or y position


  Queue Functions:

    que       - post an event to the event queue
    send      - send event directly to the event object (bypass queue)
    queobj    - post an event to an object
    sendobj   - send an event directly to any object (bypass queue)
    quedis    - read and dispatch the next event from the event queue
    quesiz    - set the size of the event queue
    quequi    - force quedis to return null
                                               Native Function List   21


  Video Functions Functions:

    vidcsz    - set the visible cursor size
    vidbli    - set the video blink mode
    vidfon    - set the video mode
    vidorg    - set the mapping of the virtual to physical screen
    vidpri    - print a string on the screen
    vidbor    - set the color of the screen overscan border
    vidoff    - turn video off
    vidon     - turn video on

    qvidmon   - test for monochrome
    qvidp     - return video info (mapping, size, and blink mode)


  Text Buffer Functions:

    texdra   - redraw all windows displaying the specified text buffer
    texcre   - create a new text buffer
    texmen   - create a menu text buffer
    texdes   - destroy a text buffer
    texloa   - create a text buffer from a file or directory on disk
    texnam   - rename a text buffer
    textop   - make a text buffer the current default text buffer
    texdty   - set or clear the text buffer dirty flag
    texdlm   - set text buffer line delimiter or binary line length
    texusz   - set text buffer undo/redo stack size

    texovl   - overlay a string at an x y position in a text buffer
    texinsx  - insert a string at an x y position in a text buffer
    texdelx  - delete a string at an x y position in a text buffer
    texinsy  - insert one or more strings as lines in a text buffer
    texdely  - delete one or more lines in a text buffer

    qtex     - test for the existence of a text buffer
    qtexlin  - return a portion of a line in a text buffer
    qtexend  - return the number of lines in text buffer
    qtexpre  - return the previous text buffer in the text buffer list
    qtexdty  - return the value of the dirty flag
    qtextru  - return the value of the truncate flag
    qtexlen  - return the length of a line
    qtexbeg  - return the position of the first non-blank char in a line
    qtexfld  - return info about a text fold
    qtextop  - return the default text buffer
    qtexmrk  - return info about marks associated with a text buffer

    qtexbin  - return text buffer binary line length
    qtexmen  - return info about a menu text buffer
    qtexdir  - return info about a directory listing from texloa
                                               Native Function List   22


    undbeg   - start saving undo/redo information for text buffers
    undend   - stop saving undo/redo information for text buffer
    und      - undo or redo last text buffer change


  Mark Functions:

    mrkset  - create a new mark or modify an existing mark
    mrkdes  - destroy a mark
    mrknam  - rename a mark
    mrktop  - make a cursor mark the default mark
    mrkcol  - change the color of a mark

    mrkdel  - delete the text within a mark
    mrkins  - copy the text within a mark at a new location
    mrkmov  - move the text within a mark to a new location
    mrkovl  - overlay the text within a mark at a new location

    mrkshf  - shift the text within a mark left or right

    mrkfil  - fill a mark with a character
    mrkcas  - change the case of the text within a mark
    mrkjus  - justify the text within a mark (left, right, center)
    mrksrt  - sort the text within a mark
    mrktab  - expand the tab characters within a mark

    mrkrfl  - reflow the text within a mark
    mrksav  - save or print the text within a mark
    mrkfin  - search for and optionally replace text within a mark
    mrkrel  - relocate a mark to a new position or text buffer
    mrkfld  - create new text folds or remove existing text folds

    qmrk    - test for the existence of a mark
    qmrkpre - return the previous mark in the text buffer mark list
    qmrktex - return the text buffer name associated with a mark
    qmrkp   - return the mark coordinates, width, or height
    qmrkcol - return the column position of a mark (cursor marks)
    qmrklin - return the first line number of a mark (cursor marks)
    qmrkins - return the insert/overlay state of a mark (cursor marks)
    qmrktyp - return the type of mark
    qmrkbuf - return the contents of a column mark
    qmrkwin - return the window associated with a mark (cursor marks)


  Window Functions:

    windra  - redraw specified portion of a window
    winset  - create, hide, or show a window
                                               Native Function List   23


    windes  - destroy a window
    winnam  - rename a window
    winttl  - change a window title
    wineot  - change the window end-of-text line
    winmen  - set the menubar for a window
    winmeh  - highlight a menubar item for a window
    wintic  - set the title bar controls for a window
    winmrk  - set the cursor mark for a window
    winpar  - set the window parent
    winnex  - alter the placement of the window in the window list
    winpre  - alter the placement of the window in the window list
    winvib  - create a local video buffer for a window

    wincol  - set the window colors
    winbor  - set the window borders
    winfra  - set the window frame components
    winshd  - set the window shadow
    winsh2  - set the window shadow for dialog controls

    winscr  - scroll the contents of a window
    winadj  - scroll the contents of a window without moving cursor
    winbar  - set a window scroll bar thumb position
    winsiz  - resize a window
    winmov  - move a window
    wintil  - tile windows on the screen

    qwin    - test for the existence of a window
    qwinmrk - return the cursor mark name associated with a window
    qwintex - return the name of the text buffer displayed in a window
    qwinx   - return the left-most column number displayed in a window
    qwiny   - return the top-most column number displayed in a window
    qwintop - return the top window
    qwinbot - return the bottom window
    qwinpre - return the previous window in the window list
    qwinnex - return the next window in the window list
    qwinchi - return the first/last child window of a specified window
    qwinttl - return a window title string
    qwinpar - return the parent window of a specified window
    qwintit - return a window title or title highlight position
    qwincol - return the color of a window component
    qwinbor - return window border info
    qwinp   - return the window coordinates, height, or width
    qwinfra - return info about the window frame components
    qwinrgn - return the window regions at specified virtual coordinates
    qwinbar - return the position of a scrollbar thumb
    qwincnt - return the number of windows or child windows
    qwinmen - return window menubar info
    qwintic - return window title bar control info
                                          Native Functions - Detail   24


  3-1  Native Functions - In Detail
  ─────────────────────────────────

  The following sections describe each of the macro language native
  functions in detail. The functions are listed in the following format:

    functionname  [arg 1]  [arg 2]  [arg 3] ...

  The function name is listed first, followed by it's arguments in
  brackets. The argument and return value "types" are not given, since
  they always character strings.

  The "..." indicates that a variable number of arguments (similar to
  the previous arguments) may follow. Note that function arguments are
  always optional in The Aurora Macro Language. In many cases, the
  function will supply a default value if an argument is not specified,
  or a null value is specified.

  Many functions take an [options] character string as an argument. An
  option is just a one character code that tells the function to do
  something in a specific way. Each function may have it's own set of
  options, each with their own meaning. In many cases, multiple options
  can be specified in the [options] character string. For example:

    fin s "b" %ir.   // the options "i" and "r" are passed to the
                     // function "fin"

  Some native function names may include a 3-character prefix (such as
  "obj", "tex", mrk", etc.) which indicates the "group" of related
  functions that the function belongs to. For example, "objnew" is an
  "object" function, "mrkset" is "mark" function, and "texcre" is a
  "text buffer" function. Within these function groups, functions whose
  only purpose is to return information are also prefixed by a "q"
  (query). For example, "qtexend" returns the number of lines in a text
  buffer.

  In functions which test for "true" or "false" (such as "if" or "and"),
  a value of null or "0" is false. Any other value is true.

  Remember, the following section describes "low-level" native
  functions. Many other "library" functions are available in The Aurora
  Editor (see "The Aurora Editor User's Guide"). Library functions are
  "built up" from native functions in The Aurora Macro Language, and are
  easier to use for most "high-level" editing operations.
                                               Definition Functions   25


  3-2  Definition Functions
  ─────────────────────────

  =  [var name]  [value].

    Assigns the value [value] to the local variable [var name]. The
    local variable is defined only within the current function
    definition. Returns 1 if success or null if failure.


  set  [obj var name]  [value].

    Assigns the value [value] to the object variable [obj var name]. The
    assignment remains in effect until another assignment is made to the
    same variable name, or the variable is destroyed or renamed with the
    "uns" or "ren" functions (see below). The variable will also be
    destroyed if the object containing the variable is destroyed.
    Returns 1 if success or null if failure.


  ren  [obj var name]  [new obj var name].

    Renames the object variable [obj var name] to [new obj var name].
    Only the name of the variable changes, not the value. Returns 1 if
    success or null if failure.


  uns  [obj var name].

    Destroys or "un-sets" the object variable [obj var name]. Both the
    variable name and value are removed from the object in which they
    are contained. Returns 1 if success or null if failure.


  fun  [function name]  [function body]  [arg 1]  [arg 2] ...

    Defines the function [function name] by assigning the macro language
    expression [function body] to the function [function name].

    [arg 1], [arg 2], etc. arg seldom used. They tell the macro language
    compiler which arguments are to be compiled whenever they are
    encountered in a call to [function name]. This can speed up
    performance when an argument to a [function name] is a string
    containing a macro language expression which is to be evaluated
    within [function name]. [arg 1], [arg 2], etc. are integers
    specifying the relative position of the argument to be compiled.

    This function returns 1 if success or null if failure.
                                               Definition Functions   26


  arg  [var name 1]  [var name 2] ...

    Names the arguments passed to the function in which it is contained.
    After this call, the arguments can be accessed by name.


  qarg  [argument number n].

    Returns the "nth" argument passed to the function in which it is
    contained. If n is zero or null, the number of arguments passed to
    the function is returned.



  3-3  Conditional Functions
  ──────────────────────────

  eq  [string 1]  [string 2] ...

    Returns 1 if [string 1] is equal to any one of the arguments which
    follow it, otherwise it returns null.


  eqi  [string 1]  [string 2] ...

    Returns 1 if [string 1] is equal (ignoring case) to any one of the
    arguments which follow it, otherwise it returns null.


  ne  [string 1]  [string 2] ...

    Returns 1 if [string 1] is not equal to any of the arguments which
    follow it, otherwise it returns null.


  ==  [string 1]  [string 2] ...

    Returns 1 if [string 1] is numerically equal to any one of the
    arguments which follow it, otherwise it returns null.


  !=  [string 1]  [string 2] ...

    Returns 1 if [string 1] is not numerically equal to any one of the
    arguments which follow it, otherwise it returns null.


  <  [string 1]  [string 2] ...

    Returns 1 if each argument is numerically less than the next
    argument, otherwise it returns null.
                                              Conditional Functions   27


  >  [string 1]  [string 2] ...

    Returns 1 if each argument is numerically greater than the next
    argument, otherwise it returns null.


  <=  [string 1]  [string 2] ...

    Returns 1 if each argument is numerically less than or equal to the
    next argument, otherwise it returns null.


  >=  [string 1]  [string 2] ...

    Returns 1 if each argument is numerically greater than or equal to
    the next argument, otherwise it returns null.



  3-4  Logical Functions
  ──────────────────────

  and  [string 1]  [string 2] ...

    Evaluates all arguments until an argument returns "0" or null, in
    which case it returns null, otherwise it returns 1.


  or  [string 1]  [string 2] ...

    Evaluates all arguments until an argument does not return "0" or
    null, in which case it returns 1, otherwise it returns null.


  !  [string 1]  [string 2] ...

    Returns 1 if all arguments are either "0" or null, otherwise it
    returns null.



  3-5  Bitwise Logical Functions
  ──────────────────────────────

  &  [string 1]  [string 2].

    Returns [string 1] "and-ed bitwise" with [string 2].
                                          Bitwise Logical Functions   28


  |  [string 1]  [string 2].

    Returns [string 1] "or-ed bitwise" with [string 2].


  ^  [string 1]  [string 2].

    Returns [string 1] "xor-ed bitwise" with [string 2].



  3-6  Control Functions
  ──────────────────────

  if  [condition]  [then body]  [else body].

    Evaluates the expression [condition]. If it is not "0" or null, then
    the expression [then body] is evaluated, otherwise the expression
    [else body] is evaluated. Returns the result of the last evaluated
    sentence.


  while  [condition]  [while body].

    Evaluates the expression [while body] while the expression
    [condition] does not evaluate to "0" or null. [condition] is
    evaluated before the first evaluation of [while body]. Returns null.


  dowhile  [while body]  [condition].

    Evaluates the expression [while body] while the expression
    [condition] does not evaluate to "0" or null. [condition] is
    evaluated after the first evaluation of [while body]. Returns null.



  3-7  Arithmetic Functions
  ─────────────────────────

  +  [integer 1]  [integer 2] ...

    Returns the numeric sum of all arguments.


  -  [integer 1]  [integer 2] ...

    If only one argument is specified, this function returns the numeric
    negative of the argument, otherwise it returns the result of
    subtracting all arguments after the first argument, from the first
    argument.
                                               Arithmetic Functions   29


  *  [integer 1]  [integer 2] ...

    Returns the numeric product of all arguments.


  /  [integer 1]  [integer 2] ...

    Returns the result of dividing the first argument by all arguments
    after the first argument.


  mod  [integer 1]  [integer 2]

    Returns the modulus of dividing the first argument by the second
    argument.


  3-8  String Functions
  ─────────────────────

  cat  [string 1]  [string 2] ...

    Returns the concatenated string of all arguments.


  sub  [string]  [position]  [length].

    Returns the substring of [string] starting at character position
    [position] and extending for a length of [length] characters. If
    [length] is zero or not specified, then the length used is the
    length from position to the end of [string].


  fin  [string]  [search string]  [options]  [replace string].

    Searches for [search string] within [string]. Any combination of the
    following [options] may specified:

      i - case insensitive search
      r - search in "reverse", starting from the end of the string
      w - search for "whole words" only

    If [replace string] is not specified, this function returns the
    character position where [search string] was found in [string]
    (returns "0" if not found).

    If [replace string] is specified, this function returns a string
    where every occurrence of [search string] has been replaced with
    [replace string].
                                                   String Functions   30


  siz  [string 1]  [string 2] ...

    Returns the sum of the string lengths of all of its arguments.


  dup  [size]  [fill string].

    Returns a string of length [size]. If [fill string] is specified,
    the string is filled by duplicating [fill string] enough times to
    fill the string:

      ex.  dup 10 "abc".    returns "abcabcabca"

    If [fill string] is not specified, the contents of the return string
    are undefined. Returns null if failure.


  wrd  [char set].

    Sets the default character set for defining a "word" for the "whole
    words" only search option. The "whole words" search option is used
    by the "fin" and "mrkfin" functions. [char set] is a string composed
    of all the characters in the character set. Character ranges can be
    indicated with a hyphen (-). For example:

      wrd "abcA-Z0".

    The example above sets the default character set to the characters
    a, b, c, 0, and the characters A through Z.


  idx  [string 1]  [string 2].

    Returns the position in [string 1] of the first character contained
    in [string 2]. Returns null if none are found.


  vfy  [string 1]  [string 2].

    Returns the position in [string 1] of the first character not
    contained in [string 2]. Character ranges such as "a-zA-Z0-9" can be
    specified for [string 2]. Returns null if all characters in [string
    1] are contained in [string 2].


  chc  [string]  [options].

    Changes the case of [string] and returns the result. The following
    [options] may be specified:
                                                   String Functions   31


      l - change all characters to lower case
      u - change all characters to upper case

    If options "u" and "l" are both specified, the case of each
    character in the string is toggled or "flipped".


  byte  [integer 1]  [integer 2] ...

    Converts each integer argument to a string of length 1 (a 1-byte
    binary number) and returns the concatenated result. For example:

      byte 32 32 20h.

    The example above returns a string of 3 blanks.


  word  [integer 1]  [integer 2] ...

    Converts each integer argument to a string of length 2 (a 2-byte
    binary number) and returns the concatenated result.


  long  [integer 1]  [integer 2] ...

    Converts each integer argument to a string of length 4 (a 4-byte
    binary number) and returns the concatenated result.


  hex  [string 1]  [string 2] ...

    Converts every two hex characters in each argument string to 1
    character and returns the concatenated result. For example:

      hex "202020" "2020".

    The example above returns a string of 5 blanks.


  toh  [string 1]  [string 2] ...

    Converts every character in each argument string to 2 hex characters
    and returns the concatenated result. For example:

      toh "ABC" "12".

    The example above returns the string "4142433132".
                               Evaluation and Compilation Functions   32


  3-9  Evaluation and Compilation Functions
  ─────────────────────────────────────────


  evl   [expression]  [reps].
  evla  [expression]  [reps].

    These functions evaluate [expression] for [reps] number of times.
    [reps] defaults to "1" if not specified. These functions return the
    result of the last evaluation of [expression].

    The function "evla" evaluates [expression] as if it were an argument
    to a function, whereas "evl" evaluates [expression] as a macro
    language sentence.

    Note that [expression] is not "parsed" before it is evaluated. If
    [expression] must be parsed, use the "prs" function first. For
    example:

      evl (prs evalstring).

    The example above parses the value of the variable "evalstring" and
    then evaluates it as a macro language sentence.


  comf  [source file]  [compiled file].

    Compiles the macro language source code in the file [source file]
    and places the compiled code in the file [compiled file]. If
    [compiled file] already exists, then it is overwritten. Returns 1 if
    success, or null if failure.


  #get  [source or compiled file].

    Includes the specified macro language source or compiled file into
    the current macro source code when it is evaluated or compiled.


  var  [string].

    Evaluates [string] as a variable and returns the value of the
    variable. For example:

      var (cat "xy" "z").

    The example above returns the value of the variable "xyz".
                               Evaluation and Compilation Functions   33


  prs  [expression].

    Parses the macro language expression [expression] and returns the
    result. Parsing will remove comments and insignificant spaces from
    the expression.

    Parsing is normally done automatically by the "objdsk" function when
    source code is loaded and executed, or by the "comf" function when
    source code is compiled. However, if a string is constructed and
    evaluated while a macro language program is executing, it should
    first be parsed before being evaluated by the "evl" function. For
    example:

      prs "beep  100     100. // beep the speaker".

    The example above returns the string "beep 100 100", which can be
    then be evaluated by the "evl" function.


  3-10  Miscellaneous Functions
  ─────────────────────────────

  asc  [string].

    Returns the integer ascii value of the first character in [string].


  pat  [filename]  [filename2/path].

    Expands [filename] to a fully qualified filename if it is not fully
    qualified or ambiguous. The second argument [filename2/path] is used
    as the "template" to construct the fully qualified name. If
    [filename2/path] is not specified, then the current drive and
    directory are used as the template. For example:

      pat "foobar.c" "d:\misc\*.*".    // returns "d:\misc\foobar.c".


  exe  [command]  [options]  [memory].

    Executes the DOS command [command]. The string [command] is the DOS
    program name (.EXE or .COM file) and parameters exactly as you would
    type them on the DOS command line. The following [options] may be
    specified:

      k  - prompts the user to return when the command is completed
      c  - clears the screen before the command begins and restores
           the screen after the command is completed
                                            Miscellaneous Functions   34


    [memory] specifies the amount of memory (in k) to request from DOS
    for the program. If [memory] is -1, then the maximum available
    memory will be used. The interpreter may swap to XMS memory, EMS
    memory, or disk to satisfy this request.

    Note: If option "k" is specified, then option "c" is used
    internally, whether or not it is specified in the function call.


  wait  [milliseconds].

    Delays execution for the time period specified by [milliseconds].


  beep  [frequency]  [duration].

    "Beeps" the PC speaker for the specified frequency and duration.
    Frequency is in herz and duration is in milliseconds.


  3-12  Object Functions
  ──────────────────────

  Object functions are used to manipulate and return information about
  macro language objects. Objects can be used to logically group
  together related functions and variables. There are functions for
  creating and destroying objects, setting and querying an object's
  ancestry, and changing the current "event" handling object. Also, the
  "objdsk" function can evaluate macro code in a file on disk. Object
  function names use the prefix "obj".


  objnew  [obj name]  [estimated size]  [obj 1]  [obj 2] ...

    Creates a new object [obj name], and optionally establishes the
    ancestry of the object. [estimated size] is the estimated number of
    variables and functions which you believe the object may contain,
    and is used to optimize internal tables. [obj 1], [obj 2], etc are
    optional "ancestor" objects from which [obj name] may "inherit"
    functions and variable assignments. Returns 1 if success or null if
    failure.


  obj  [obj name]  [obj body].

    Adds functions and variables to the object [obj name]. When [obj
    body] is evaluated, any function definitions or object variable
    assignments within [obj body] are added to the object [obj name].
                                                   Object Functions   35


  objdes  [obj name].

    Destroys the object [obj name]. The object [obj name] is also
    removed from the inheritance path of other objects, if applicable.


  objsav  [obj name]  [filename]  [options].

    Saves the object [obj name] in the file [filename] as a compiled
    sequence of "set" function calls. The "objdsk" function can be used
    to reload the object from disk. The following options may be
    specified:

      a - append to the end of [filename]

    Returns 1 if success or null if failure.


  objnam  [obj name]  [new obj name].

    Renames the object [obj name] to [new obj name]. Returns 1 if
    success or null if failure.


  objeve  [obj name].

    Makes the object [obj name] the current "event" object. The event
    object is where the interpreter looks for event handler functions
    when dispatching events from the internal event queue.


  objpar  [obj name]  [obj 1]  [obj 2] ...

    Changes the "inheritance path" or ancestry of the object [obj name]
    to [obj 1], [obj 2], etc.


  objdsk  [obj name]  [filename]  [arg 1]  [arg 2] ...

    Evaluates the macro language source or compiled code in [filename],
    with the object [obj name] as the default object. [arg 1], [arg 2],
    etc. are arguments passed to the macro code in [filename]. This
    function returns the value of the last sentence evaluated in
    [filename].


  qobj  [obj name].

    Returns 1 if the object [obj name] exists, otherwise it returns
    null.
                                                   Object Functions   36


  qobjsiz  [obj name].

    Returns the number of functions and variables in the object [obj
    name].


  qobjexe.

    Returns the name of the currently executing or "default" object.


  qobjeve.

    Returns the name of the current "event" object.


  qobjanc  [obj name]  [obj 2].

    Returns 1 if the object [obj name] has the object [obj 2] as an
    ancestor object in it's inheritance path, or if [obj name] equals
    [obj 2], otherwise it returns null.


  3-13  Disk Functions
  ────────────────────

  Disk functions are used to manipulate files on disk, and to return
  path and drive information. Disk function names use the prefix "dsk".


  dskdel  [filename]  [options].

    Deletes the file [filename] and returns 1 if success, or null if
    failure. Empty directories can also be deleted if option "d" is
    specified.


  dskren  [filename]  [new filename].

    Renames the file [filename] to [new filename]. Returns 1 if success,
    or null if failure.


  dskloc  [filename]  [path].

    Searches the path string [path] for the file [filename]. [path] can
    be a sequence of paths separated by semicolons (;) (as in the DOS
    "PATH" environment string). This function returns the fully
    qualified filename if found, otherwise it returns null.
                                                     Disk Functions   37


  dskfin  [filename]  [string]  [options].

    Searches for the string [string] in the file [filename]. The
    following search [options] can be specified:

      i - case insensitive search
      w - search for "whole words" only

    This function returns non-zero if the string is found, otherwise it
    returns null.


  dskcpy  [source filename]  [dest filename]  [options].

    Copies the file [source filename] to [dest filename]. The following
    [options] may be specified:

      a - append the source file to the destination file

    This function returns non-zero if successful, otherwise it returns
    null.


  dskcur  [path]  [options].

    Sets the current drive or the current path for the specified drive.
    The following [options] can be specified:

      d - set the current drive
      p - set the current path

    Returns 1 if success or null if failure.

    For example:

      dskcur "d:" %d.       // set current drive to "d:"
      dskcur "c:\xyz" %p    // set current directory for "c:" to "xyz"
      dskcur "c:\xyz" %dp   // set current drive and directory


  dskdir  [path].

    Creates the new directory specified by [path]. All elements of the
    path must exist (except the last element). Returns 1 if success or
    null if failure.


  dsktch  [filename].

    "Touches" the file [filename] by setting the file's date and time to
    the current date and time. Returns 1 if success or null if failure.
                                                     Disk Functions   38


  dskatt  [filename]  [attributes].

    Changes the attributes of the file [filename] to [attributes]. The
    attributes of a directory can also be changed. [attributes] may be
    any combination of the following:

      r - read only
      h - hidden
      s - system
      a - archive

    Returns 1 if success or null if failure.


  qdskpat  [options].

    Returns the fully qualified boot path or the current path. The
    following [options] may be specified:

      b - return the boot path where the interpreter was invoked
      c - return the current path

    If no options are specified, the default is "c".


  qdskdrv  [options].

    Returns a string consisting of all available disk drive letters.
    The following [options] may be specified:

      t - include network information. "1" after the drive letter
          indicates a local drive, "2" indicates a network drive.

    For example, for a computer system with 3 logical hard drives, 2
    floppies, and network drives F and G:

      qdskdrv.      // returns "ABCDEFG"
      qdskdrv %t.   // returns "A1B1C1D1E1F2G2"


  qdskcap  [drive]  [options].

    Returns the total or free amount of disk space available on disk
    drive [drive], in bytes. The following options may be specified.

      c - return the total capacity of the drive
      f - return the free space on the drive

    If no drive is specified, the current drive is assumed. If no
    options are specified, the default is "c".
                                                   System Functions   39


  3-14  System Functions
  ──────────────────────

  System functions are used to control and provide information about the
  interpreter's operating environment. There are functions to control
  the interpreter's use of memory and printer devices, and functions to
  return information such as environment strings and version numbers.
  System function names use the prefix "sys".


  sysmem  [options]  [limit].

    Allows the use of EMS or XMS memory. [limit] is the maximum amount
    of EMS or XMS to use, in k (a value 0 or -1 indicates that the
    maximum available amount should be used). One of the following
    [options] may be specified:

      e - use EMS memory
      x - use XMS memory

    To use both EMS and XMS memory, this function must be called twice.
    Note that an EMS or XMS driver must be installed before this
    function can be called successfully. This function returns a
    non-zero value if success, otherwise it returns null.

  sysswp  [swap file 1]  [swap file 2]  [swap file 3].

    Sets the swap files names for the interpreter to use in low memory
    situations. The interpreter will use [swap file 2] only when there
    is no more room on the drive containing [swap file 1], and [swap
    file 3] only when there is no more room on the drive containing
    [swap file 3]. All swap files should be on different drives. Returns
    non-zero if success or null if failure.

    EMS and XMS memory (if available) will be used before the swap
    files.


  sysprt  [id]  [options]  [page size]  [left margin]  [top margin]
          [right margin]  [bottom margin]  [line spacing]  [copies].

    Sets the current printer settings. The following printer settings
    can be specified:

    - [id]

      not used (reserved for future use).
                                                   System Functions   40


    - [page size]

      Specifies the "Lines per Page" of printed output. This includes
      the [top margin] and [bottom margin]. After the specified lines
      per page have been printed, a formfeed character (ascii 12) will
      be sent to the printer and a new page will be started.

      If PrtPag is zero, printing will be continuous (no formfeed
      characters will be sent to the printer). [top margin], [bottom
      margin], and the "page number" option will be ignored.

    - [line spacing]

      Specifies the number of lines to advance after printing each line
      of output. A value of 1 generates single-spaced output, 2
      generates double-spaced output, and so on.

    - [copies]

      Specifies the number of copies to print.

    - [top margin]

      Specifies the number of blank lines to precede the printed output
      at the top of each page. This value is included in [page size].
      [top margin] is ignored if [page size] is set to zero.

    - [bottom margin]

      Specifies the number of blank lines to follow the printed output
      at the bottom of each page. This value is included in [page size].
      [bottom margin] is ignored if [page size] is set to zero.

    - [left margin]

      Specifies the number of blank columns to precede the printed
      output on each line.

    - [right margin]

      Specifies the column position at which to truncate each printed
      line. This column position is relative to column zero of the
      printed output, NOT the file being printed. If zero is specified,
      lines are not truncated.

    - [options]

      The following [options] can be specified:
                                                   System Functions   41


      h - prints a "header" at the top of each page. The header is
          specified in the "mrksav" function when printing. This option
          is ignored if [page size] is zero.

      f - prints a "footer" at the top of each page. The footer is
          specified in the "mrksav" function when printing. This option
          is ignored if [page size] is zero.

      s - adds a separator line after the header line and before the
          footer line.

      p - prints a right-justified page number on the header and footer
          lines. If neither a header or footer was specified, a blank
          header line is assumed. This option is ignored if [page size]
          is zero.

      l - prints a line number at the beginning of each line.

      e - sends a formfeed character to the printer when printing is
          completed.


  syssnd  [0/1].

    Enables (1) or disables (0) sound from the PC speaker.


  qsysver.

    Returns the current version of The Aurora Editor.


  qsysos  [options].

    Returns the operating system name or the operating system version.
    The following [options] may be specified:

      v - return major OS version
      m - return minor OS version

    If no options are specified, the operation system name ("DOS") is
    returned.


  qsyspgm.

    Returns the name of The Aurora Editor .EXE file you that is
    currently executing, without path information or the .EXE extension.
                                                   System Functions   42


  qsysvar  [var name].

    Returns the environment string for the specified environment
    variable [var name]. [var name] must be in upper case. For example:

      qsysvar "PATH".

    This function returns null if the environment variable is not found.


  3-15  Timer Functions
  ─────────────────────

  Timer functions are used to create and destroy system "timers". Timers
  are used to automatically call user-defined functions at a specified
  time and date, or at periodic intervals. The "qtim" function also
  returns date and time information. Timer function names use the prefix
  "tim".


  timint  [timerid]  [interval]  [obj]  [fun]  [arg 1]  [arg 2] ...

    Sets an interval timer to call the function [fun] in the object
    [obj] with arguments [arg 1], [arg 2], etc. The function is called
    for every time interval (in milliseconds) specified by [interval].

    If [obj] is null, then the current "event" object is used. The
    [timerid] can be 0-9, and uniquely identifies the timer. Note that
    the first call to [fun] will occur after the specified time
    interval, not after the call.

    This function returns 1 if success or null if failure.


  timalm  [timerid]  [year(YYYY)]  [month(MM)]  [day(DD)]
          [dayofweek (0-6)]  [hour(HH)]  [min(mm)]  [sec(ss)]
          [obj]  [fun]  [arg 1]  [arg 2] ...

    Sets an "alarm" timer to call the function [fun] in the object [obj]
    with arguments [arg 1], [arg 2], etc. The function is called at the
    specified time and date.

    If [obj] is null, then the current "event" object is used. The
    [timerid] can be 0-9, and uniquely identifies the timer.

    "-1" may be specified as a "wildcard" for any of the date or time
    parameters. For example:

      timalm  2 -1 3 -1 -1 11 0 0 @ "march".
                                                    Timer Functions   43


    The example above sets timer 2 to call the function "march" in the
    current event object at 11 o'clock for every day in the month of
    march.

    This function returns 1 if success or null if failure.


  timdes  [timerid].

    Stops and destroys the timer [timerid]. This function destroys both
    interval and alarm timers. Returns 1 if success or null if failure.


  qtim.

    Returns the date and time as a character string of length 17, with
    the following format:

      "YYYYMMDDWhhmmssuu"

      YYYY - year
      MM   - month (1-12)
      DD   - day (1-31)
      W    - day of the week (0-6, 0=sunday)
      hh   - hour (0-23)
      mm   - minutes (0-59)
      ss   - seconds (0-59)
      uu   - hundredths of a second (0-99)



  3-16  Keyboard Functions
  ────────────────────────

  Keyboard functions are used to control and return information about
  the keyboard. Keyboard function names use the prefix "kbd".


  kbdenh  [0/1].

    Turns checking for the enhanced keyboard ON (1) or OFF (0). "kbdenh
    1" enables the enhanced keyboard keys if the enhanced keyboard is
    detected. "kbdenh 0" disables the enhanced keyboard keys.


  kbdrpt  [report mode].

    Determines how the interpreter calls keyboard event handler
    functions.
                                                 Keyboard Functions   44


    If [report mode] is "1" and a key is typed in, the interpreter
    attempts to attempts call the user function "key" in the current
    event object with the following arguments:

      key name - name of the key ("k_s_f1", "k_a_y", etc.)
      key code - a 2 byte code identifying the key
      key char - the character typed in (if not a function key)

    If [report mode] is "2" and a key is typed in, the interpreter
    attempts to call a user function in the current event object with
    the same name as the "key name" argument above, with the following
    arguments:

      key code - a 2 byte code identifying the key
      key char - the character typed in (if not a function key)

    The default keyboard reporting mode is "2". This function returns 1
    if successful or null if failure.


  kbdclr.

    Removes all keystrokes from the keyboard buffer.


  qkbdshf  [mask].

     Returns the current shift key state of the keyboard "and-ed
     bitwise" with the integer specified by [mask]. The following table
     lists each bit position and it's corresponding shift key:

       01h - right shift key is down
       02h - left shift key is down
       04h - ctrl key is down
       08h - alt key is down
       10h - scroll lock is on
       20h - num lock is on
       40h - caps lock is on
       80h - insert state is on

     For example, the value of "qkbdshf 3" is non-zero if either shift
     key is currently pressed down.


  qkbdchr  [options].

    If [option] "h" is specified, this function returns "1" if a key has
    been pressed, otherwise it returns null. The key remains in the
    keyboard buffer.
                                                 Keyboard Functions   45


    If [option] "h" is not specified, this function waits for a
    character to be entered from the keyboard and returns the character
    as a string of length one.



  3-17  Mouse Functions
  ─────────────────────

  Mouse functions are used to control and return information about the
  mouse. Mouse function names use the prefix "mou".


  mouini.

    Initializes the mouse and returns the mouse driver version (or null
    if failure). This function also displays the mouse pointer at the
    center of the screen, and enables the interpreter event queue to
    receive mouse events.

    In order for this function to return successfully, a DOS mouse
    driver (such as "mouse.com" or "mouse.sys") must be installed before
    the interpreter is invoked.


  moutrm.

    Deactivates the mouse driver and removes the mouse pointer from the
    screen. No more mouse events will be received by the interpreter
    event queue. Returns 1 if success or null if failure.


  mousen  [horz]  [vert]  [double speed].

    Sets the mouse sensitivity by setting the horizontal mickey-to-pixel
    [horz] and vertical mickey-to-pixel [horz] ratios, and by setting
    the double speed threshold [double speed]. The default value of
    these settings after calling "mouini" are:

      Horz mickey-to-pixel ratio:   8
      Vert mickey-to-pixel ratio:  16
      Double speed threshold:      64

    Returns 1 if success or null if failure.


  mourpt  [report mode].

    Determines how the interpreter calls mouse event handler functions.
                                                 Keyboard Functions   46


    If [report mode] is "1" and a mouse event is read from the event
    queue, the interpreter attempts to call the user function "mouse" in
    the current event object with the following arguments:

      mouse event name - name of the mouse event ("m_l_down", etc)
      mouse x position - x position of mouse (virtual coordinates)
      mouse y position - y position of mouse (virtual coordinates)

    If [report mode] is "2" and a mouse event is read from the event
    queue, the interpreter attempts to call a user function in the
    current event object with the same name as the "mouse event name"
    above, with the following arguments:

      mouse x position - x position of mouse (virtual coordinates)
      mouse y position - y position of mouse (virtual coordinates)

    The default mouse reporting mode is "2". This function returns 1 if
    successful or null if failure.


  moupos  [x position]  [y position].

    Sets the position of the mouse cursor on the physical screen (0,0 is
    the upper left corner). Returns 1 if success or null if failure.


  mouvis  [0/1].

    Shows (1) or hides (0) the mouse cursor.


  qmoupos  [options].

    Returns the current mouse position on the physical screen (0,0 is
    the upper left corner). The following options may be specified:

      x - return the x position of the mouse
      y - return the y position of the mouse

    If no options are specified, the default is "x".



  3-18  Queue Functions
  ─────────────────────

  Queue functions are used to control and return information about the
  interpreter event queue. Queue function names generally use the prefix
  "que".
                                                    Queue Functions   47


  que  [fun]  [arg 1]  [arg 2] ...

    Places the function [fun] and it's arguments [arg 1], [arg 2],
    etc. on the interpreter event queue. The next time the interpreter
    is idle, it will read the event queue and attempt to call [fun] in
    the current event object. Returns 1 if success or null if failure.


  send  [fun]  [arg 1]  [arg 2] ...

    This function is similar to the "que" function above, except that
    the interpreter event queue is bypassed. The function [fun] in the
    current event object is called immediately. This function returns
    the result of evaluating [fun].


  queobj  [obj]  [fun]  [arg 1]  [arg 2] ...

    This function works similar to the "que" function above, except that
    the interpreter attempts to call the function [fun] in the object
    [obj], not in the current event object.


  sendobj  [obj]  [fun]  [arg 1]  [arg 2] ...

    This function is similar to the "queobj" function above, except that
    the interpreter event queue is bypassed. The function [fun] in the
    object [obj] is called immediately. This function returns the result
    of executing the function [fun].


  quedis.

    This function reads the next event from the queue and "dispatches"
    it by calling the user event handler function associated with the
    event. If there is no event on the event queue, it will wait for an
    event to appear in the queue. This function returns when the user
    event handler function returns.

    If the function "quequi" (see below) is called in the user event
    handler, this function returns "0", otherwise it returns "1". This
    feature can be used to implement a dispatch loop which is not
    terminated until the "quequi" function is called. For example:

      while (quedis).

    The loop above will continue to dispatch events from the event queue
    until a user function calls "quequi".
                                                    Queue Functions   48


  quequi.

    Forces the "quedis" (see above) function to return null.


  quesiz  [size].

    Sets the interpreter event queue size to [size] events. The default
    size is 20 when the interpreter is invoked. Returns 1 if successful
    or null if failure.



  3-19  Video Functions
  ─────────────────────

  Video functions are used to control and return information about the
  video device. Video function names use the prefix "vid".


  vidcsz  [start]  [end].

    Sets the physical cursor size on the screen. [start] and [end]
    indicate the distance of the top and bottom of the cursor from the
    top of the character cell, on a scale of 0 to 100. For example,
    "vidcsz 0 100" sets the cursor size to the entire character cell.

    Specifying -1 for both [start] and [end] hides the cursor.


  vidbli  [0/1].

    Turns the video blink mode ON (1), or OFF (0). The video blink mode
    determines whether or not color attributes above 127 blink on and
    off. The video blink mode is OFF by default.


  vidfon  [columns]  [rows]  [back attr]  [back fill].

    Changes the video mode and/or sets the background color attribute
    and background fill string. You can do either operation separately
    or together.

    When changing the video mode, both [columns] and [rows] must be
    non-zero. [columns] may be 40 or 80 and [rows] may be 12, 14, 21,
    25, 28, 43, or 50. If [columns] or [rows] are zero or null, the
    video mode is not changed.
                                                    Video Functions   49


    To change the background attribute or fill string, specify the
    background color attribute [back attr] and fill string [back fill].
    If [back attr] is not specified, a value of 0 (black) is used. If
    [back fill] is not specified, a blank (ascii 32) is used. If neither
    are specified, the current background remains unchanged.

    Note: the string [back fill] can be a maximum of 50 chars long.

    This function returns 1 if successful or null if failure.


  vidorg  [x]  [y]  [options].

    Changes the mapping of the physical video device (the screen) to the
    virtual video device (the virtual screen is 64k x 64k characters).
    [x] and [y] specify the left and top positions of the physical
    device within the virtual device. The following options may be
    specified:

      r - [x] and [y] specify a mapping relative to the current mapping
      a - [x] and [y] specify an absolute mapping. [x] and [y] are
          referred to as "virtual coordinates".

    For example, "vidorg 12000 17896 %a" maps the top left of the
    screen to (12000, 17896) of the virtual screen.

    If no [options] are specified, the default option is "r".

    When the editor is invoked, the default mapping is (16000,16000).
    This function returns 1 if success or null if failure.


  vidpri  [string]  [x]  [y]  [attr]  [options]

    Prints the string [string] on the screen background at position [x],
    [y] using the color attribute [attr]. The following [options] may be
    specified:

      a - [x] and [y] are in absolute virtual screen coordinates.
      d - [x] and [y] are in physical device coordinates, with (0,0)
          as the left and top.

    If no [options] are specified, the default is "d". This function
    returns 1 if successful or null if failure.


  vidbor  [attr].

    Sets the screen overscan border color to [attr].
                                                    Video Functions   50


  vidoff.

    Turns off the video device. All screen updates are deferred until
    the function "vidon" is called.


  vidon.

    Turns on the video device.


  qvidmon.

    Returns 1 if the video device is in monochrome mode, otherwise it
    returns null.


  qvidp  [options].

    Returns the video parameter specified in [options]. One of the
    following [options] may be specified:

      l - returns the left virtual coordinate of the physical screen
      t - returns the top virtual coordinate of the physical screen
      r - returns the right virtual coordinate of the physical screen
      b - returns the bottom virtual coordinate of the physical screen
      x - returns the width of the screen
      y - returns the height of the screen
      k - returns the video blink mode (0=off, 1=on)
                                              Text Buffer Functions   51


  3-20  Text Buffer Functions
  ───────────────────────────

  Text buffer functions are used to control and return information about
  text buffers. A text buffer is a group of one or more lines of text
  and is used for editing files. There are many functions for creating,
  modifying, and destroying text buffers. Text buffer function names
  generally use the prefix "tex".

  Any number of text buffers can be created. Text buffers are organized
  into a global "text buffer list". The "default" text buffer is always
  at the top of the list.

  Text buffers are identified by a "text buffer name". Specifying a null
  text buffer name for any of the text buffer functions indicates that
  the "default" text buffer should be used.

  Note that changes made to a text buffer with these functions are not
  automatically displayed in any windows which might be associated with
  the text buffer. You must use the "windra" or "texdra" functions to
  update the window (see "Window Functions").


  texcre  [text buffer]  [line 1]  [line 2] ...

    Creates a new text buffer with the name [text buffer]. The new text
    buffer becomes the default text buffer. The arguments [line 1],
    [line 2], etc are the initial lines to be placed in the text buffer.
    If no initial lines are specified, the text buffer is created with
    one blank line.

    Returns 1 if successful or 0 if failure.


  texmen  [text buffer]  [line 1]  [line 2] ...

    Creates a new menu text buffer with the name [text buffer]. The new
    text buffer becomes the default text buffer. The arguments [line 1],
    [line 2], etc are the initial lines to place on the menu (see the
    section "Defining Menus" in The Aurora Editor Users Guide).

    Returns 1 if successful or 0 if failure.


  texdes  [text buffer].

    Destroys [text buffer] and all marks and windows associated with
    [text buffer]. The previous text buffer becomes the default text
    buffer. Returns 1 if successful or 0 if failure.
                                              Text Buffer Functions   52


  texloa  [text buffer]  [filename]  [options]  [line number]
          [delimiter]  [trunc length].

    Creates a new text buffer from the file [filename], or inserts the
    file [filename] into an existing text buffer. If [filename] contains
    wildcards or specifies a directory, then a directory listing is
    loaded. The "qtexdir" function can be used to return information
    about the directory listing.

    If [text buffer] does not exist, then the a new text buffer with the
    name [text buffer] is created, and the file [filename] is loaded
    into it. The new text buffer becomes the default text buffer.

    If [text buffer] is an existing text buffer, then the file
    [filename] is inserted into [text buffer] after the line [line
    number]. If [line number] is 0 then it is inserted before the first
    line. if [line number] is -1 then it is inserted after the last
    line.

    The following [options] may be specified:

      b - the [delimiter] argument specifies a 1-byte line delimiter
      w - the [delimiter] argument specifies a 2-byte line delimiter
      h - include hidden files when loading a directory listing
      d - include subdirectories when loading a directory listing
      k - convert file sizes to 1k increments when loading a directory
          listing
      a - ignore the argument [filename] and load an internal ascii
          chart

    If options "b" or "w" are specified then [delimiter] specifies a
    byte or word line delimiter used to define the end of each line
    loading the file.

    If options "b" or "w" are not specified and [delimiter] is zero,
    then the line delimiter defaults to "0D0Ah" (carriage return -
    linefeed).

    If options "b" or "w" are not specified and [delimiter] is greater
    than zero, then [delimiter] specifies the binary line length, and
    the file is loaded in "binary mode".

    [trunc length] specifies the maximum line length that can be loaded
    before wrapping to the next line. The maximum line length can not
    exceed 16000. If [trunclength] is zero or not specified, then a
    maximum line length of 16000 is assumed.

    This function returns 1 if a file was loaded, 2 if a directory
    listing was loaded, or null if failure.
                                              Text Buffer Functions   53


  texnam  [text buffer]  [new text buffer].

    Renames the text buffer [text buffer] to [new text buffer]. Returns
    1 if success or null if failure.


  texdra  [text buffer]  [line number].

    Draws the client area of all windows which currently display the
    text buffer [text buffer].

    If [line number] is specified, only the specified line number is
    drawn (this is faster than drawing all lines of the text buffer). If
    [line number] is -1, the line drawn is the line at the default
    cursor mark for the text buffer.

    Returns 1 if successful or 0 if failure.


  textop  [text buffer].

    Makes the text buffer [text buffer] the default text buffer by
    moving it to the top of the text buffer list. The default text
    buffer can be easily referenced in any text buffer function by
    specifying "null" for the [text buffer] argument.


  texdty  [text buffer]  [options].

    Sets or clears the dirty flag for the text buffer [text buffer]. The
    dirty flag is set automatically by any function which modifies the
    text buffer, and can be retrieved with the "qtexdty" function (see
    below). The following options can be specified:

      c - clear the dirty flag
      s - set the dirty flag

    If no options are specified, the default is "s".


  texdlm  [text buffer]  [delimiter]  [options].

    Sets the default byte or word line delimiter associated with the
    text buffer [text buffer]. The following options can be specified:

      b - [delimiter] is a 1-byte delimiter.
      w - [delimiter] is a 2-byte delimiter.

    If no [options] are specified and [delimiter] is non-zero, then
    [text buffer] will have no delimiter.
                                              Text Buffer Functions   54


  texusz  [text buffer]  [size].

    Sets the size of the undo/redo stack associated with the text buffer
    [text buffer]. The default size is zero.


  texovl  [text buffer]  [x]  [y]  [string].

    Overlays the string [string] at column [x], line [y] of the text
    buffer [text buffer]. If [x] or [y] are null, then the column and
    line of the default cursor mark are assumed. Returns 1 if success or
    null if failure.


  texinsx  [text buffer]  [x]  [y]  [string].

    Inserts the string [string] horizontally at column [x], line [y] of
    the text buffer [text buffer]. If [x] or [y] are null, then the
    column and line of the default cursor mark are assumed. Returns 1 if
    success or null if failure.


  texinsy  [text buffer]  [x]  [y]  [string]  [reps].

    Inserts the string [string] vertically at column [x] after line [y]
    of the text buffer [text buffer]. If [x] or [y] are null, then the
    column and line of the default cursor mark are assumed. [reps]
    indicates the number of lines to be inserted (if 0 or null is
    specified, one line is inserted). Returns 1 if success or null
    if failure.


  texdelx   [text buffer]  [x]  [y]  [length].

    Deletes the 1-line segment of text of length [length] at column [x],
    line [y] of the text buffer [text buffer]. If [x] or [y] are null,
    then the column and line of the default cursor mark are assumed.
    Returns 1 if success or null if failure.


  texdely  [text buffer]  [y]  [reps].

    Deletes [reps] number of lines starting with line [y] in the text
    buffer [text buffer]. If [reps] is null or zero, then one line is
    deleted. If [y] is null then the line number of the default cursor
    mark is assumed. Returns 1 if success or null if failure.
                                              Text Buffer Functions   55


  qtex  [text buffer].

    Returns 1 if the text buffer [text buffer] exists, or null if it
    does not exist.


  qtexlin  [text buffer]  [line number]  [a]  [b].

    Returns a copy of the line [line number] from column [a] through
    column [b] text buffer [text buffer]. If [line number] is null or
    zero, then the line number of the default cursor mark is assumed. If
    [a] is null or zero, then "1" is used for [a]. If [b] is null or
    zero, then the line length used for [b]. This function returns null
    if failure.


  qtexend  [text buffer].

    Returns the number of lines in the text buffer [text buffer].


  qtexpre  [text buffer].

    Returns the previous text buffer before [text buffer] in the text
    buffer list. Returns null if [text buffer] is the last text buffer
    in the list.


  qtexdty  [text buffer].

    Returns 1 if the text buffer [text buffer] has been modified, or
    null if it has not been modified.


  qtextru  [text buffer].

    Returns 1 if the text buffer [text buffer] has been truncated during
    execution of the function "texloa". This can occur by interrupting
    "texloa" with <Ctrl-Break>, or when the system is out of space. This
    function returns null if [text buffer] has not been truncated.


  qtexbeg  [text buffer]  [line number].

    Returns the column position of the first non-blank character of line
    [line number] in the text buffer [text buffer]. If [line number] is
    zero or null, the line number of the default cursor mark is assumed.
                                              Text Buffer Functions   56


  qtexlen  [text buffer]  [line number].

    Returns the length of line [line number] in the text buffer [text
    buffer]. If [line number] is zero or null, the line number of the
    default cursor mark is assumed.


  qtexfld  [text buffer]  [line number]  [rel]  [options].

    If [rel] is not specified, this function returns the number of lines
    in the text fold beginning or ending at the line [line number].

    If [rel] is specified, the value of [rel] may be a positive or
    negative integer. The following [options] may also be specified:

      a - returns the line number that is the "apparent" distance of
          [rel] lines away from [line number]. The "apparent" distance
          is the visible distance on the screen (text folds count as one
          line).
      v - returns the "apparent" line number that is the actual distance
          of [rel] lines away from [line number].
      r - this option can be specified with options "a" or "v". It
          indicates the relative distance away from [line number] is to
          be returned, not a line number.

    If no [options] are specified, the default is "a".

    If [line number] is zero or null, the line number of the default
    cursor mark is assumed.


  qtextop.

    Returns the default text buffer at the "top" of the text buffer
    list.


  qtexmrk  [text buffer]  [options].

    Returns the default mark or cursor mark at the "top" of the mark
    list associated with the text buffer [text buffer]. The following
    [options] may be specified:

      c - returns the first cursor mark on the mark list
      m - returns the first non-cursor mark on the mark list

    If no options are specified, then the first mark on the mark list is
    returned (cursor mark or non-cursor mark).
                                              Text Buffer Functions   57


    Note: if there are any cursor marks associated with the text buffer,
    the interpreter always places them "ahead" of non-cursor marks on
    the mark list, so that calling this function with no [options] will
    always return a cursor mark.


  qtexbin  [text buffer].

    Returns the binary line length associated with the text buffer [text
    buffer]. If [text buffer] was not loaded in "binary mode", then this
    function returns null.


  qtexmen  [text buffer]  [line number]  [options].

    Returns information about the menu text buffer [text buffer] created
    with the "texmen" function. If [line number] is null or zero, the
    line number of the default cursor mark is assumed. The following
    [options] may be specified:

      c - return the position of the highlight character at [line
          number]
      w - return the menu width
      n - return the menu item description at [line number]
      f - return the macro code for the menu item at [line number]
      y - return last cursor position on the menu text buffer

    (see also "Defining Menus" in The Aurora Editor Users Guide).


  qtexdir  [options].

    Returns information about the most recently loaded directory listing
    loaded with the "texloa" function. The following options may be
    specified:

      d - return the number of subdirectories in the directory listing
      f - return the number of files in the directory listing
      s - return the sum of all the file sizes in the directory listing


  undbeg.

    Marks the beginning of a series of "tex" and "mrk" function calls
    which are considered to be one "undoable/redoable" operation. The
    current cursor mark position, and window size and position (if
    applicable) will be saved with the "undoable" operation.
                                              Text Buffer Functions   58


    The "undend" function (see below) marks the end of the "undoable"
    series of function calls.


  undend.

    Marks the end of a series of "tex" and "mrk" function calls started
    by the "undbeg" function (see above) which are to be considered as
    one "undoable" operation. All of the information required to "undo"
    the function calls between "undbeg" and "undend" is pushed onto an
    internal undo/redo stack.


  und  [text buffer]  [options].

    Restores the most recent changes made to the text buffer [text
    buffer] that were recorded with the "undbeg" and "undend" functions
    (see above). The following options may be specified:

      u - restores the most recent modification to the text buffer
      r - reverses the effects of the last "und %u" function call

    If no [options] are specified, the default is "u". This function
    returns 1 if success or null if failure.
                                                     Mark Functions   59


  3-21  Mark Functions
  ────────────────────

  Mark functions are used to control and return information about
  "marks". A mark defines an area of text within a specific text buffer,
  or specifies a "cursor" position in a text buffer. There are many
  functions for creating, modifying, and destroying marks. Mark function
  names use the prefix "mrk".

  Any number of marks can be associated with a text buffer. Marks are
  organized into a "mark list" attached to the text buffer. The
  "default" mark is at the top of the list.

  Marks are identified by a "mark name". Specifying a null mark name for
  any of the mark functions indicates that the default mark should be
  used.

  Using the mark functions, operations on text buffers can be restricted
  to the areas of text defined by the marks. "Cursor marks" are a
  special type of mark used to specify movable cursor positions within a
  text buffer. A Window can be attached to a text buffer via cursor
  marks (see "Window Functions").

  Note that changes made to a text buffer with these functions are not
  automatically displayed in any windows associated with the text
  buffer. You must use the "windra" or "texdra" functions to update the
  window (see "Text Buffer Functions" and "Window Functions").


  mrkset  [mark]  [options]  [text buffer]  [l]  [t]  [r]  [b]
          [s]  [e].

    Creates a new mark with the name [mark] for the text buffer [text
    buffer], or modifies the mark if it already exists. If a new
    "cursor" mark is created, it becomes the default mark for the text
    buffer. Cursor marks are always placed ahead of non-cursor marks on
    text buffer's mark list.

    [l], [t], [r], [b] are the left, top, right, and bottom coordinates
    of the mark, relative to the top-left corner of the text buffer. [s]
    and [e] are the start and end positions on the first and last lines
    of the mark. [s] and [e] are currently used only by the "mrkfin"
    function.

    If [l] or [t] are null or zero, then the column and line of the
    default cursor mark in the text buffer are used. If [r] or [b] are
    null or zero, then [l] and [t] are used. If [s] or [e] are null or
    zero, then the left and right boundaries of the resulting mark are
    used.
                                                     Mark Functions   60


    The following [options] can be specified:

      c - the mark is a "cursor" mark, used to mark a movable position
          in a text buffer. The cursor mark becomes the default mark for
          the text buffer
      i - places the mark in "insert" mode if it is a cursor mark. If
          this option is not specified, the cursor mark is placed in
          "overlay" mode.
      r - the mark is a rectangular or "column" mark. If this option is
          not specified, the mark is a "line" mark.
      h - the mark is "hidden"

    This function returns 1 if success or null if failure.


  mrkdes  [mark].

    Destroys the mark [mark]. If [mark] was the default mark, then the
    previous mark in the mark list becomes the default mark. Returns 1
    if success or null if failure.


  mrknam  [mark]  [new mark].

    Renames the mark [mark] to [new mark]. Returns 1 if success or null
    if failure.


  mrktop  [mark].

    Makes the cursor mark [mark] the default mark by moving it to the
    top of the mark list. A non-cursor mark can only be made the default
    mark if no cursor mark exists for the text buffer.


  mrkcol  [mark]  [attr].

    Changes the display color for the mark [mark] to [attr]. If this
    function is not called, then the mark color is determined by the
    "wincol" function (see "Window Functions"). This call allows marks
    to have different colors. Returns 1 if success or null if failure.


  mrkdel  [mark].

    Deletes the text inside the mark [mark], and the mark itself. For
    "line" marks, this function deletes all lines in the mark. For
    rectangular or "column" marks, this function deletes all columns in
    the mark and shifts all columns to the right into the vacated area.

    Returns 1 if success or null if failure.
                                                     Mark Functions   61


  mrkins  [mark]  [text buffer]  [x]  [y].

    Copies the text inside the mark [mark] to column [x] line [y] in the
    text buffer [text buffer].

    If [text buffer] is not specified, then the text buffer associated
    with [mark] is assumed. If [x] or [y] is not specified, then the
    column and line of the default cursor mark for the text buffer are
    assumed.

    For "line" marks, the new text is inserted vertically into [text
    buffer] after line [y]. For rectangular or "column" marks the new
    text is inserted horizontally into [text buffer] at column [x], line
    [y].

    Returns 1 if success or null if failure.


  mrkmov  [mark]  [text buffer]  [x]  [y].

    Moves the text inside the mark [mark] to column [x] line [y] in the
    text buffer [text buffer]. The mark itself is moved along with the
    text.

    If [text buffer] is not specified, then the text buffer associated
    with [mark] is assumed. If [x] or [y] is not specified, then the
    column and line of the default cursor mark for the text buffer are
    assumed.

    For "line" marks, the text is moved vertically into [text buffer]
    after line [y]. For rectangular or "column" marks the text is moved
    horizontally into [text buffer] at column [x], line [y].

    Returns 1 if success or null if failure.


  mrkovl  [mark]  [text buffer]  [x]  [y].

    Overlays the text inside the mark [mark] at column [x] line [y] in
    the text buffer [text buffer].

    If [text buffer] is not specified, then the text buffer associated
    with [mark] is assumed. If [x] or [y] is not specified, then the
    column and line of the default cursor mark for the text buffer are
    assumed.

    Returns 1 if success or null if failure.
                                                     Mark Functions   62


  mrkshf  [mark]  [shift]  [fill character].

    Shifts the text in the mark [mark] left or right by [shift] columns
    and fills the vacated columns with [fill character]. If the value of
    [shift] is negative, then the text if shifted left, otherwise the
    text is shifted right. If [fill character] is null then blanks are
    used. Returns 1 if success or null if failure.


  mrkfil  [mark]  [fillchar]  [a]  [b].

    Fills the text within the mark [mark] with the character [fill
    character]. If the mark is a "line" mark, then [a] and [b] are used
    as the left and right columns for the fill. [a] and [b] are ignored
    for "column" marks.

    Returns 1 if success or null if failure.


  mrkcas  [mark]  [options]  [a]  [b].

    Changes the case of the text within the mark [mark]. If the mark is
    a "line" mark, then [a] and [b] are used as the left and right
    columns for the case change. [a] and [b] are ignored for "column"
    marks. The following [options] can be specified:

      l - change the text to lower case
      u - change the text to upper case

    Specifying both options "l" and "u" will toggle the case of each
    character in the text. If no [options] are specified, the default is
    "u".

    This function returns 1 if success or null if failure.


  mrkjus  [mark]  [options]  [a]  [b].

    Right justifies, centers, or left justifies the text within the mark
    [mark]. If the mark is a "line" mark, then [a] and [b] are used as
    the left and right columns for the justification. [a] and [b] are
    ignored for "column" marks. The following [options] can be
    specified:

      l - left justifies the text in the mark
      c - centers the text in the mark
      r - right justifies the text in the mark

    If no [options] are specified, the default is "l". This function
    returns 1 if success or null if failure.
                                                     Mark Functions   63


  mrksrt  [mark]  [options].

    Sorts the lines in the mark [mark]. All portions of each line are
    included in the sort, even if the mark is a "column" mark. The
    portion of each line within the mark is the sort key. The following
    options may be specified:

      a - ascending sort
      d - descending sort

    If no [options] are specified, then the default is "a". This
    function returns 1 if success or null if failure.


  mrktab  [mark]  [tab width].

    Expands any tab characters (ascii 9) in the mark [mark]. If the mark
    is a "column" mark, the left and right edges the mark are ignored.
    [tab width] determines how much each tab character is expanded. [tab
    width] may be 2, 4 or 8.

    Returns 1 if success or null if failure.


  mrkrfl  [mark]  [text buffer]  [l]  [t]  [r]  [options]  [indent].

    Reflows the lines in the mark [mark]. All the text within each line
    is reflowed, even if the mark is a "column" mark. The reflowed text
    is inserted into the text buffer [text buffer] after line [t]. The
    original text within the mark remains unchanged. The reflowed text
    is formatted to fit between columns [l] and [r] in [text buffer].
    [indent] specifies the number of columns to indent the first line of
    the reflowed text.

    If [text buffer] has been loaded in "binary mode", it cannot be
    reflowed.

    If [text buffer] is not specified, then the text buffer of the
    default cursor mark is assumed. If [l], [t], or [r] are not
    specified, then the column and line of the default cursor mark are
    assumed.

    The following [options] may be specified:

      b - blank lines are preserved.
      r - justifies the reflowed text on both the left and right
          boundaries.

    This function returns the number of lines inserted in [text buffer],
    or null if failure.
                                                     Mark Functions   64


  mrksav  [mark]  [filename]  [options]  [delimiter]  [header]  [prtini].

    Saves the text within mark [mark] to the file [filename]. Specifying
    a filename such as PRN, LPT1, LPT2, etc. prints the text within the
    mark. following [options] may be specified:

      a - the text is appended to [filename]
      b - the argument [delimiter] specifies a byte delimiter to be
          saved after each line.
      w - the argument [delimiter] specifies a word delimiter to be
          saved after each line.
      f - each line is saved without a delimiter.
      p - specifies that the saved file is to be formatted for printing
          using the print settings specified with the "sysprt" function,
          called before this function.
      i - specifies that only the string [prtini] is to be saved. The
          text within the mark is ignored. This can be used to send an
          initialization string the printer.
      z - saves an end-of-file (ascii 26) character at the end of
          [filename]. If option "p" is specified, then a formfeed
          character (ascii 12) is sent to the printer when printing is
          completed.

    If [delimiter] is not specified, the delimiter associated with the
    mark's text buffer is used (text buffers loaded in binary mode have
    no delimiter).

    When option "p" is specified, the argument [header] can be used to
    print a header and/or footer string. The "sysprt" function must be
    called before this function and must specify the header or footer
    options.

    This function returns 1 if success or null if failure.


  mrkfin  [mark]  [search string]  [replace string]  [options]
          [cursor mark].

    Searches the text within the mark [mark] for [search string]. If
    [replace string] is specified, then [search string] is replaced with
    [replace string]. If the cursor mark [cursor mark] is specified and
    the search string is found, then the cursor mark is moved to the
    location where the search string was found.

    The following [options] may be specified:

      i - ignore case during the search
      r - search in "reverse" from the bottom to the top of the mark
                                                     Mark Functions   65


      a - replace all occurrences of [search string] with [replace
          string]
      w - search for "whole words" only
      x - search for the first character which also occurs in the search
          string
      y - search for the first character which does not occur in the
          search string
      z - force replace, even if the replace string is null

    If [replace string] or option "z" was specified, the number of
    replacements is returned, otherwise the column where the search
    string was found is returned. If nothing was found then null is
    returned.


  mrkrel  [mark]  [x]  [y]  [options]  [text buffer].

    Relocates the mark [mark] to a new location in the text buffer [text
    buffer]. If no text buffer is specified, then the text buffer
    associated with [mark] is assumed. The following [options] may be
    specified:

      a - [x] and [y] specify an absolute column and line position in
          the text buffer
      r - [x] and [y] specify an offset from the current left and top
          coordinates of [mark].

    If no [options] are specified, then "r" is assumed. This function
    returns 1 if success or null if failure.


  mrkfld  [mark]  [options].

    Folds or unfolds the lines of text contained within the mark [mark].
    The following [options] may be specified:

      f - creates a new text fold containing all lines within the mark.
      u - removes text folds contained within the mark. If option "a" is
          not specified, only "top-level" text folds are removed.
      a - removes all text folds contained within the mark when
          specified with the option "u".

    If options "u" and "f" are both specified, existing text folds are
    removed before the new text fold is created.

    If no [options] are specified, then "f" is assumed. This function
    returns 1 if success or null if failure.
                                                     Mark Functions   66


  qmrk  [mark].

    Returns 1 if the mark [mark] exists, or null if it does not exist.


  qmrkpre  [mark]  [options].

    Returns a previous mark before [mark] in the mark list. The
    following [options] may be specified:

      c - return the previous cursor mark before [mark]
      m - return the previous non-cursor mark before [mark]

    If no [options] are specified, then the previous mark (cursor or
    non-cursor) is returned. This function returns null if no previous
    mark is found.


  qmrktex  [mark].

    Returns the text buffer in which the mark [mark] is located.


  qmrkp    [mark]  [options].

    Returns a coordinate of the mark [mark], or the width or height of
    the mark [mark]. The following [options] may be specified:

      l - returns the left-most column of the mark
      t - returns the top line number of the mark
      r - returns the right-most column of the mark
      b - returns the bottom line number of the mark

      x - returns the width of the mark
      y - returns the height of the mark


  qmrkcol  [mark].

    Returns the column position of the cursor mark [mark].


  qmrklin  [mark].

    Returns the line number of the cursor mark [mark].
                                                     Mark Functions   67


  qmrkins  [mark].

    Returns the "insert mode" of the cursor mark [mark]. Returns "i" if
    the cursor mark is in insert mode, or "o" if the cursor mark is in
    overlay mode.


  qmrktyp  [mark].

    Returns "l" if [mark] is a "line" mark, or "r" if [mark] is a
    rectangular or "column" mark.


  qmrkbuf  [mark].

    Returns a string composed of the text within the "column" mark
    [mark]. This function is ignored for "line" marks.

    This function will return null if the area of the column mark
    exceeds 16000.


  qmrkwin  [mark].

    Returns the window name associated with the cursor mark [mark].
                                                   Window Functions   68


  3-22  Window Functions
  ──────────────────────

  Window functions are used to control and return information about
  windows. A window is a rectangular area of the screen which can used
  to display text buffers and marks, or to display other "child"
  windows. Window function names use the prefix "win".

  Any number of windows can be created. Windows are organized into a
  global "window list". The "default" window is at the top of the list.

  Windows are identified by a "window name". Specifying a null window
  name for any of the window functions indicates that the default window
  should be used.

  To display a text buffer in a window, the window must be attached to a
  cursor mark associated with the text buffer. Since a text buffer may
  have any number of cursor marks, any number of windows can used to
  display different areas of the same text buffer.

  Note that most window functions will not actually update windows on
  the screen, unless the function description explicitly specifies that
  they do. In this case, you must use the "windra" or "texdra" functions
  to update the window (see also "Text Buffer Functions").


  winset  [window]  [options].

    Creates a new window with the name [window], or hides/shows an
    existing window. The following [options] may be specified:

      h - hide the window
      d - show the window

    Windows can be created as "hidden". For example:

      winset "abc" %h.   // creates the hidden window "abc"

    If no [options] are specified, the default is "d". This function
    returns 1 if success of null if failure.


  windes  [window].

    Destroys the window [window] and removes it from the screen. Returns
    1 if success or null if failure.
                                                   Window Functions   69


  winnam  [window]  [new window].

    Renames the window [window] to [new window]. Returns 1 if successful
    or null if failure.


  winttl  [window]  [title]  [options]  [title id].

    Sets a window title to the string [title] for the window [window].
    Each window can have up to 5 titles. The argument [title id]
    specifies which title is being set. [title id] can be 1 - 5 (if the
    title id is zero, null, or not specified, then "1" is assumed). Any
    combination of the following [options] can be specified:

      n - sets the title on north title bar.
      s - sets the title on south title bar.
      e - sets the title on east title bar.
      w - sets the title on west title bar.

      l - the title is left-justified in the title bar.
      c - the title is centered in the title bar.
      r - the title is right-justified in the title bar.

      d - draws the window title bar containing the title immediately
          after setting the title.

      x - sets the title to the "default status line". The default
          status line has the following format:

             [HH]  C XXXXX L YYYYY of TTTTT

          The status line displays information about the text buffer
          associated with the window (if any). [HH] is the hex value of
          the character at the cursor, XXXXX and YYYYY are the column
          and line positions of the cursor mark, and TTTTT is the total
          number of lines in the text buffer.

      h - checks for the highlight character "&". Specifying "&" before
          a character in the title indicates that it is to be
          highlighted when displayed. The "&" character itself is not
          displayed.

      1 - the title is not padded with any spaces (left or right).
          Normally the title is padded with one space if it is left of
          right justified.

      z - hides the title. This can be used to specify a title for the
          end-of-text line (see the "wineot" function).

    This function returns 1 if success or null if failure.
                                                   Window Functions   70


  wineot  [window]  [title id].

    Sets the "end-of-text" line for the window [window] to the window
    title [title id] which was previously set with the "winttl" function
    (see above). The title should be hidden with option "z" when calling
    the winttl function.

    If [title id] is -1, then the following default end-of-text line is
    used: "≡≡≡≡≡≡ End of Text ≡≡≡≡≡≡".


  winmen  [window]  [menu bar id]  [item 1]  [item 2] ...

    Defines a menu bar for the window [window]. Up to five menu bars can
    be defined for one window. [item 1], [item 2], etc. are the items to
    be placed on the menu bar. [menu bar id] specifies which of the five
    menu bars is being defined, and can be any of the following values:

      0 - the primary menu bar at the top of the window, under the
          north title bar (if any)
      1 - menu bar 1 underneath the primary menu bar
      2 - menu bar 2 underneath menu bar 1
      3 - menu bar 3 at the bottom of the window, above the south
          south title bar (if any)
      4 - vertical menu bar 4 at the left edge of the client area

    Each menu bar item may contain one ampersand character (&) which is
    not displayed, but indicates that the character following it is to
    be highlighted when displayed.

    This function returns 1 if success or null if failure.


  winmeh  [window]  [menu bar id]  [item number].

    Highlights or un-highlights the menu bar item [item number] on
    menubar [menu bar id] on the window [window]. There can only be one
    highlighted item per menu bar. [item number] is the relative
    position of the menu bar item from the beginning of the menu bar (1
    for first item, 2 for the second, and so on).

    If [item number] is null or zero, then the highlight is removed from
    any currently highlighted item in the menu bar.

    This function returns the offset (in character positions) of the
    specified menu item from the beginning of the menu bar, or null if
    failure.
                                                   Window Functions   71


  wintic  [window]  [char]  [attr]  [char]  [attr] ...

    Defines one-character title bar icon controls for the window
    [window]. [char] specifies the character to be displayed for each
    control and [attr] specifies the color attribute of each control. If
    [attr] is null, then the default window control color is used.

    Controls are normally left-justified on the title bar. If any
    control is preceded by an (@) character, then that control and any
    controls following it will be right justified on the title bar. For
    example:

      wintic @ "≡" @ "@" @ "".

    In the example above, title bar controls are defined for the default
    window using the default control colors. The control "≡" is left
    justified, while the controls "" and "" are right justified.

    This function returns 1 if success or null if failure.


  windra  [window]  [options]  [line number].

    Draws the window components specified by [options]. [line number] is
    ignored for all options except the "l" and "a" options. Any
    combination of the following [options] may be specified:

      b - draws the window border
      p - draws the primary menu bar only
      m - draws all window menu bars
      w - draws the west title bar
      n - draws the north title bar
      e - draws the east title bar
      s - draws the south title bar
      h - draws the horizontal scroll bar
      v - draws the vertical scroll bar
      l - draws the line [line number] in the window. If this option is
          specified and [line number] is null or zero, then the line
          number of the default cursor mark is assumed.
      t - draws the client area of the window
      a - draws the client area of all windows with the same text buffer
          as [window]. If [line number] is specified, then only
          the specified line is drawn.
      c - draws the cursor
      u - draws the cursor and updates the client area if needed
      f - draws the frame (every part of the window except the client
          area)
                                                   Window Functions   72


    This function returns 1 if success or null if failure. If option "c"
    is specified, and the client area needs updating, then 2 is
    returned.


  winmrk  [window]  [mark].

    Associates the cursor mark [mark] with the window [window]. Only one
    cursor mark may be associated with a window at one time. The window
    will display the text buffer associated with the cursor mark.
    Windows that are not associated with a text buffer (such as message
    boxes or dialog box windows) do not need to use this call. This
    function returns 1 if success or null if failure.


  winpar  [parent]  [child].

    Makes the window [parent] the "parent" window of the window [child].


  winnex  [window 1]  [window 2].

    Changes the order of the windows on the screen by placing [window 2]
    on top of [window 1].


  winpre  [window 1]  [window 2].

    Changes the order of the windows on the screen by placing [window 1]
    on top of [window 2].


  winvib  [window].

    Creates a local video buffer for the window [window]. This is only
    needed for windows that have child windows (such as dialog boxes).
    Creating a local video buffer for the parent window will eliminate
    screen flicker when moving the window. Returns 1 if success or null
    if failure.


  wincol  [window]  [element]  [attr]  [element]  [attr] ...

    Sets the colors of specific window elements for the window [window].
    [element] is a one character code specifying a part of the window,
    and can be one of the following:
                                                   Window Functions   73


      b - border
      e - border corner
      0 - north title bar
      1 - south title bar
      c - window title bar controls (default color)
      m - menus
      i - menu character highlight
      x - menu bar item highlight
      d - menu disable
      s - scroll bars
      z - end-of-text line
      t - text or client area
      h - mark (default color)
      f - text folds

    [attr] is the color attribute (0-255). Using negative values from -1
    to -6 for [attr] have a special meaning:

      -1 - do not change the current value of this attribute
      -2 - use the default value for this attribute
      -3 - increment the value of this attribute
      -4 - decrement the value of this attribute
      -5 - increment the background color for this attribute
      -6 - decrement the background color for this attribute


  winbor  [window]  [x]  [y]  [xo]  [yo]  [options].

    Sets the border for the window [window]. [x] is the thickness for
    the left and right borders. [y] is the thickness for the top and
    bottom borders. [xo] and [yo] are the amount of horizontal and
    vertical overlap on the border corners. The following [options] are
    available:

      s - changes the size of other parts of the window to accommodate
          the new border sizes. If this option is not specified, the
          entire window may grow or shrink.

    For the following [options], the borders are drawn using the text
    graphics characters. [x], [y], [xo], and [yo] are ignored, the
    horizontal and vertical border thickness is always 1, and there is
    no overlap on the border corners:

      1 - single line
      2 - double horizontal
      3 - double vertical
      4 - double line
      5 - blank
                                                   Window Functions   74


  winfra  [window]  [options]  [west title width]  [east title width]
          [west menu width]  [control location].

    Defines the window frame components to be displayed for the window
    [window]. [options] determine which window frame components are
    displayed. You can choose any combination of the following options:

      b - borders
      m - primary menu
      w - west title bar
      n - north title bar
      e - east title bar
      s - south title bar
      h - horizontal scroll bar
      v - vertical scroll bar
      1 - menu bar 1
      2 - menu bar 2
      3 - menu bar 3 (south)
      4 - menu bar 4 (west)
      z - south title controls
      > - place north title bar in the window border

      + - add specified options to existing window
      - - remove specified options from existing window


    The following arguments to "winfra" can also be specified:

      [west title width] - the width of the west title (if present)
      [east title width] - the width of the east title (if present)
      [west menu width]  - the width of the west menu bar (if present)
      [control location] - the location of the window title bar controls
                           (n=north title bar, s=south title bar)


  winshd  [window]  [bot]  [right]  [bot indent]  [right indent].

    Adds or removes the shadow on the right and bottom sides of the
    window [window]. [bot] and [right] specify the shadow thickness on
    the bottom and right borders. If [bot] and [right] are zero or null,
    the shadow is removed. [bot lead] and [right lead] specify the
    amount of indentation for the bottom and right shadows. Returns 1 if
    success or null if failure.


  winsh2  [window]  [attr]  [bot indent]  [right indent]

    Adds or removes a one-half width shadow on the right and bottom
    sides of the window [window]. This function is intended for use with
                                                   Window Functions   75


    stationary windows on a blank background (such as dialog box
    controls). [attr] is the shadow color. [bot lead] and [right lead]
    specify the amount of indentation for the bottom and right shadows.
    Returns 1 if success or null if failure.


  winscr  [window]  [x]  [y]  [options]  [reps].

    Scrolls the text buffer displayed in the window [window] to the
    position [x], [y]. The following [options] can be specified:

      r - [x] and [y] are relative to the current position (default)
      a - [x] and [y] designate the absolute column and line number
          to scroll to.
      d - the window contents are redrawn immediately after each scroll.
          There is no need to call "windra" or "texdra".
      c - the window cursor mark (if any) is moved to same extent that
          the window is scrolled.
      p - [y] is ignored and the window is scrolled up or down by the
          window height minus one line. If [y] is less than zero, the
          window is scrolled up. If [y] is greater than zero, the window
          is scrolled down.

    Note that this function will only redraw the window contents if the
    "d" option is specified. If the "d" option is not specified, use the
    the "windra" and "texdra" functions to redraw.

    [reps] specifies the amount of scroll "repetitions" to occur (the
    default is 1). A value of [reps] greater than 1 used with the "d"
    option can provide for a "smooth scroll" effect.

    This function returns 1 if success or null if failure.


  winadj  [window]  [x]  [y].

    Scrolls the window [window] relative to the position of the cursor
    mark associated with the window. The cursor mark is not moved. The
    window is scrolled so that the cursor is [x] columns away from the
    left edge of the client area and [y] lines away from the top edge of
    the client area.

    If zero is specified for [x] or [y], the window is not scrolled in
    that dimension. If -1 is specified for [x] or [y], the window view
    is adjusted so that the cursor is placed in the center of the window
    for the specified dimension.

    Note that this call will not automatically redraw the text buffer in
    the window. Use the "windra" or "texdra" function to redraw the
    window.
                                                   Window Functions   76


    This function returns 1 if success or null if failure.


  winbar  [window]  [value]  [limit]  [options].

    Sets the thumb position on the horizontal or vertical scroll bars
    for the window [window]. If option "v" is not specified, then
    [limit] specifies the scroll bar range and [value] is the thumb
    position to set within that range. The following options may be
    specified:

      x - sets the thumb position on the horizontal scroll bar
      y - sets the thumb position on the vertical scroll bar
      d - draws the scroll bar immediately after setting the thumb.
          If this option is not specified, then "windra" must be used.
      v - [value] and [limit] specify the virtual x and y coordinates
          on the screen where the thumb should be set. The coordinates
          must be inside the scroll bar thumb ranges. This option can be
          used to allow the mouse to drag the scroll bar thumb.

    This function returns 1 if success or null if failure.


  winsiz  [window]  [l]  [t]  [r]  [b]  [reps]  [options]  [rel window].

    Changes the size and position of the window [window]. [l], [t], [r],
    and [t] specify the new window coordinates. The following [options]
    can be specified:

      r - coordinates are relative to the current window position
      a - coordinates are absolute (relative the "origin" - see below)
      c - coordinates specify the size of the client area, not the
          whole area of the window
      s - scrolls the window to keep the cursor mark visible, if
          necessary

    If option "a" is specified, the following options may also be
    specified:

      d - origin is at the top left corner of the screen
      w - origin is at the top left corner of the window [rel window]
      1 - origin is at the top left corner of the client area of the
          window [rel window]
      z - origin is at the virtual coordinates 0, 0

    If option "r" is specified, [reps] specifies the number of sizing
    repetitions (the default is 1).
                                                   Window Functions   77


    When a window is resized, all parts of the window are automatically
    redrawn ("windra" or "texdra" are not required). This function
    returns 1 if successful or null if failure.


  winmov  [window]  [l]  [t]  [reps]  [options]  [rel window].

    Moves the window [window] to the coordinates [l], [t]. This call is
    nearly identical to the function "winsiz" (see above), except that
    only the position of the window can be changed, not its relative
    size.


  wintil  [window]  [options]  [split thresh]  [limit].

    Tiles all windows on the screen, or "splits" the window [window]
    into tiles. [limit] specifies the maximum number of tiles. If
    [limit] is null or zero, then all windows will be tiled.

    [split thresh] specifies the number of splits that can occur in one
    direction before the next split occurs in a perpendicular direction.
    If [split thresh] is null or zero, then the default is 2.

    The following [options] may be specified:

      h - favor horizontal splits
      v - favor vertical splits
      l - tile only the window [window], and any windows which display
          the same text buffer as [window].
      b - reverse the tiling order by starting with the window on the
          bottom

    This function returns 1 if success or null if failure.


  qwin  [window].

    Returns 1 if the window [window] exists or null if it does not
    exist.


  qwinmrk  [window].

    Returns the cursor mark associated with the window [window], or null
    if failure.


  qwintex  [window].

    Returns the text buffer associated with the window [window], or null
    if failure.
                                                   Window Functions   78


  qwinx  [window]  [virtual x-coordinate].

    If [virtual x-coordinate] is specified:
      Returns the visible column number in the window [window] at the
      specified virtual x-coordinate, or null if failure.

    otherwise:
      Returns the left-most column number shown in the window [window].


  qwiny  [window]  [virtual y-coordinate].

    If [virtual y-coordinate] is specified:
      Returns the visible line number in the window [window] at the
      specified virtual y-coordinate, or null if failure.

    otherwise:
      Returns the topmost line number shown in the window [window].


  qwinbot.

    Returns the bottom-most window on the screen.


  qwintop  [options].

    Returns the top-most window on the screen. If no options are
    specified, the top-most "parent-less" window is returned. If option
    "z" is specified, the top-most window is returned, whether or not
    the window has a parent window (this is the "default" window at the
    top of the window list).


  qwinpre  [window]  [options].

    Returns the previous window in the window list before the window
    [window]. If option "z" is specified, then a child window may be
    returned, otherwise the closest window before [window] at the same
    level as [window] is returned. Returns null if failure.


  qwinnex  [window]  [options].

    Returns the next window in the window list after the window
    [window]. If option "z" is specified, then a child window may be
    returned, otherwise the closest window after [window] at the same
    level as [window] is returned. Returns null if failure.
                                                   Window Functions   79


  qwinpar  [window].

    Returns the parent window of [window] or null if failure.


  qwinchi  [window]  [options].

    Returns a child window of the window [window]. The following
    [options] may be specified:

      b - returns the bottom-most child window
      t - returns the top-most child window

    This function returns null if [window] has no child windows.


  qwinttl  [window]  [title id]  [options].

    Returns the title string specified by [title id] for the window
    [window]. if option "h" is specified, then this function returns the
    highlighted position within the title string (if any).


  qwincol  [window]  [element].

    Returns the numeric color attribute of the element [element] for the
    window [window]. See the function "wincol" for a list of one
    character element codes.


  qwinbor  [window]  [options].

    Returns the border thickness or border type for the window [window].
    One of the following [options] can be specified:

      x - returns the width of the left and right borders
      y - returns the height of the top and bottom borders
      t - returns the border type (see the "winbor" function)


  qwinp  [window]  [options].

    Returns the virtual coordinate, width, or height of [window]
    specified by [options]. [options] can be any of the following:

      0 - returns a main window coordinate
      1 - returns a client window coordinate
                                                   Window Functions   80


      l - returns the left coordinate of the window
      t - returns the top coordinate of the window
      r - returns the right coordinate of the window
      b - returns the bottom coordinate of the window

      x - returns the width of the window (the width of the client area
          if option "1" is specified)
      y - returns the height of the window (the height of the client
          area if option "1" is specified)
      d - returns the height or width of the "visible" portion of the
          the window on the screen, when used with the "x" or "y"
          options above


  qwinfra  [window]  [component].

    Tests for the presence of the frame component [component] in the
    window [window]. See the function "winfra" for a list of one
    character component codes. This function returns a non-zero value if
    the specified [component] is present, otherwise null is returned.


  qwinrgn  [window]  [x]  [y].

    Returns an integer code identifying the region of the window
    [window] containing the virtual coordinates [x] and [y]. This
    function is useful for determining the window region on which a
    mouse click occurred. The following table shows the integer codes
    and the corresponding window regions.
                                                   Window Functions   81


      code         region
      ────         ──────

        0          [x], [y] are not in the window
        1          client area

        2          north border
        3          east border

        4          south border
        5          west border
        6          northwest border corner
        7          northeast border corner
        8          southeast border corner
        9          southwest border corner

       11          north title bar
       12          south title bar
       13          west title
       14          east title

       19          vertical & horizontal scroll bar intersection

       21          vert scroll bar up arrow
       22          vert scroll bar down arrow
       23          vert scroll bar page-up bar
       24          vert scroll bar page-down bar
       25          vert scroll bar thumb

       31          horz scroll bar left arrow
       32          horz scroll bar right arrow
       33          horz scroll bar page-left bar
       34          horz scroll bar page-right bar
       35          horz scroll bar thumb

       51 - 100    window title bar controls from left to right

       101- 200    primary menu bar items from left to right
       201- 300    menu bar 1 items from left to right
       301- 400    menu bar 2 items from left to right
       401- 500    menu bar 3 items from left to right
       501- 600    menu bar 4 items from top to bottom


  qwinbar  [window]  [limit]  [options].

    Returns the current position of the scroll bar thumb in the range
    0 - [limit] for the window [window]. The following [options] can be
    specified:
                                                   Window Functions   82


      x - horizontal scroll bar
      y - vertical scroll bar

    If no [options] are specified, the default is "y".


  qwincnt  [window].

    Returns the number of child windows for the parent window [window].
    If [window] is null, this function returns the total number of
    "parent-less" windows in the window list.


  qwinmen  [window]  [menu bar id]  [options]  [item].

    Returns information about the menu bar [menu bar id] on the window
    [window]. [item] is an integer specifying the relative position of a
    menu bar item from the beginning of the menu bar. If [item] is not
    specified, the currently highlighted menu bar item (if any) is
    assumed. The following [options] may be specified:

      s - returns the menu bar item string for [item]
      o - returns the offset (in columns) of [item] from the beginning
          of the menu bar
      c - returns the highlighted character for [item]
      n - returns the total number of menu bar items


  qwintic  [window]  [n].

    This function returns the "[n]th" one-character title bar control
    that was specified with the "wintic" function. For the left-most
    title bar control, n is "1".
                    The Aurora Macro Language and The Aurora Editor   83


  A-1  The Aurora Macro Language and The Aurora Editor
  ────────────────────────────────────────────────────

  This section describes some aspects of The Aurora Editor from the
  point of view of The Aurora Macro Language.


  The Aurora Editor is itself a compiled macro language program
  contained in the file A.X. The programs A.EXE and A3.EXE are macro
  language interpreters which execute A.X.

  The main macro source file for A.X is the file A.A. The file A.A does
  very little except to include ACFG.A (configuration settings), AMEN.A
  (menu definitions), ALIB.X, (compiled editor library functions), and
  AKBD.A (keyboard and mouse definitions). When A.A is compiled, all of
  the above files are combined and A.X is generated.

  When The Aurora Editor is initially started from the DOS command line,
  A.X is executed and the following things happen:

  - The configuration settings (in ACFG.A) are placed in the object
    "prf" via the "set" native function.

  - The editor menus (in AMEN.A) are created via the "winmen" and
    "texmen" native functions.

  - All editor library functions are included from the file ALIB.X.
    Library functions are the editor commands described in The Aurora
    Editor Users Guide.

  - The keyboard and mouse definition functions (in AKBD.A) are added to
    event handler objects such as "edit", "fmgr", "prompt", etc.

  - The history file (A.HIS) and saved key macros are loaded (if
    configured).

  - Edit windows and/or File Manager windows are created, depending
    on what was entered on the DOS command line or remembered from
    a previous edit session.


  It is important to keep the following things in mind when writing your
  own macro commands for The Aurora Editor:

  1) The top-most window displayed on the screen is always the "default"
     window, and can be referenced with a null window name in any of the
     "win" native functions.
                    The Aurora Macro Language and The Aurora Editor   84


     Likewise, the text buffer and cursor mark displayed in the top-most
     window are the "default" text buffer and the "default" mark. They
     can also be referenced with null text buffer and null mark names in
     the "tex" and "mrk" native functions.

  2) When the user creates a marked block for use the "block" functions
     (such as copy, move, delete, etc.), that mark can be referenced
     with the mark name "*". This mark cannot be referenced with a null
     mark name, since that would refer to the cursor mark.

  3) The Aurora Editor uses timer id's 6, 7, 8, and 9. This leaves timer
     id's 0 through 5 available.

  4) The Aurora Editor creates the following "event" objects:

       "edit"   - edit windows
       "fmgr"   - file manager windows
       "menu"   - menu windows
       "prompt" - prompt windows and edit fields

     The Aurora Editor sets the current event object based on the window
     type of the top-most window. For example, if the top-most window is
     a File Manager window, then the current event object is "fmgr".

     Other "ancestor" objects used by The Aurora Editor are:

       "a"          - all windows
       "mon"        - all windows
       "win"        - movable or sizable windows
       "edit-fmgr"  - edit and file manger windows
       "dlg"        - dialog boxes