home *** CD-ROM | disk | FTP | other *** search
Text File | 1993-08-18 | 155.0 KB | 4,311 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.0, 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 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 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
- +2147483647, 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 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].
-
- Deletes the file [filename] and returns 1 if success, or null if
- failure. Empty directories can also be deleted with this function.
-
-
- 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
-
-
-