OASIS macro syntax
OASIS macros are written in plain text. Valid characters are:
abcdefghijklmnopqrstuwvxyz
ABCDEFGHIJKLMNOPQRSTUVWXYZ
`1234567890-=\[];',./
~!@#$%^&*()_+|{}:"[]?
any other character will almost always generate an error.
Basically, an OASIS macro consists of pools of droplets. A pool starts with a '(' and ends with a ')'. All the droplets of a pool are written between these two parentheses and the individual droplets are always separated by spaces. Two pools of two droplets would, for instance, look like:
(Droplet1 Droplet2)(Droplet3 Droplet4)
Pools can also be nested. A pool with two droplets of which the second droplet is again a pool of two droplets would look like:
(Droplet1 (Droplet2 Droplet3))
A droplet can be one of many things. It can be a number, a switch, a piece of text, an action, a variable, a complex, or it can, as we have seen, be a pool of droplets. There also is a droplet that does not represent anything, it is called an empty droplet. All these types of droplets will now be discussed.
A number droplet can be an integer droplet or a real droplet. An integer is a whole number without a fractional part. Examples are:
1 4 -90 505 -9999 -0 1000000
The range of an integer is [-2147483648 ... 2147483647]. A real is a number with a fractional part. Normal and scientific notations are allowed:
1.0 4.4 -9999.9999 -3.4563E-9 1.e1 etc.
Only the point is obligatory, but you should always add numbers for clarity. Don't use spaces in the scientific notations since the OASIS interpreter will read such notations as consisting of several droplets, remember that droplets are by definition separated by spaces. The range of a real is [5.0e-324 ... 1.7e+308] either positive or negative. The accuracy of a real is fifteen to sixteen digits.
A switch is a droplet that has only two states, like a computer bit, it can be switched ON or OFF. The two states of the switch can also be described with TRUE and FALSE. Note that ON is equal to TRUE and OFF to FALSE.
A piece of text is written in double quotes and can have a maximum length of 4095 characters. Some short examples are:
"Peter" "0.12" "Have a nice day."
Any valid character may be used inside a text, even if it has a special meaning for OASIS. Invalid characters inside a text are also allowed, but you should try to avoid using them. A text should preferably be typed on one line. The "|" character therefore has a special meaning inside a text; it causes the rest of the text to be written on the next line when a text is printed. For example
"The first line.|And the second line."
will be written by OASIS as:
The first line.
And the second line.
You are, however, not obliged to provide this 'next line' character since OASIS will always try to find the optimal layout for your texts.
An action is the basic tool to get your macro to do something. Some actions consist of a single droplet, others consist of a pool with one or more droplets following the action droplet which is always placed first in such an action pool. The meaning of the successor droplets depends entirely on the action. A simple example will illustrate this concept. The action droplet for dividing integers is called 'Div', it is always used in an action pool. When, for instance, the action (Div 9 2) is evaluated, it will result in the integer 4. Exchanging the two integers will give a zero integer as the result. It is also evident that the division action requires two extra droplets, one for the numerator and one for the enumerator of the division. All other actions work in an analogue fashion.
A variable is, most of the time, a reference to another droplet. The names of variables should always be distinct from numbers and texts. Variables are very useful for storing droplets that are needed more than once. Since variables are references to droplets, they can be many different things, even a reference to a variable which is a reference to another droplet (which may again be a variable). The action 'Set' assigns droplets to variables. An example:
(Set Distance 9 Time 2)
here the variable Distance is set to the integer droplet 9, and the variable Time is set to the integer 2.
A variable can also refer to a complex droplet. A complex is a compound droplet like a file, a signal, or a part of the display. Complexes can only be created during the execution of a OASIS macro.
It is important to know what the scope of a variable is. In the current implementation of OASIS all variables have a global scope. This means that the droplet to which they refer can be reached as long as the macro in which they were mentioned for the first time is being executed. You should realize right from the start what the consequence of this complete global scope is; you should never use the same variable name for two variables which should not be the same variable.
|
A single quote is a tool to guide macro evaluation. To understand what this means you should keep in mind that OASIS almost always evaluates a droplet first and then manipulates the result of that evaluation. Remember that (Div 9 2) was evaluated to 4. The next example will show a more complex cascade of evaluations (each line is one step in the process):
(Div (Div 16 2) (Div 8 4))
(Div 8 (Div 8 4))
(Div 8 2)
4
This cascade also shows that the evaluation proceeds from left to right. A quote directly in front of droplet will prevent evaluation. The next example will show the use of a quote in the 'Set' action
(Set Speed '(Div Distance Time))
when this action is evaluated the variable Speed refers to the pool droplet (Div Distance Time) which is an action pool. Note that the action pool (Div Distance Time) is not evaluated when the 'Set' action evaluates its successor droplet, it is only referred to, due to its quote. This constitutes the major difference from a normal action droplet, without a single quote in front of it, which would have been evaluated. When a quote is used, as shown in the previous example, the result of evaluating the 'Speed' variable will change when the 'Distance' and 'Time' variables change. So, evaluating Speed, with the given values for Distance and Time (see above), would result in '4' whereas, evaluating:
(Set Time 3)
(Eval Speed)
would result in '3'. Note that the 'Eval' action is used to force the evaluation of the Speed variable.
Debugging macros
Whenever you try to write your own macros in OASIS you will make mistakes. There are, in
a fact, an infinite number of mistakes you can make. Do not get frustrated by the continuous
flow of error messages you will see; it is a normal part of macro development and learning to
write macros in OASIS. Most of the time the error messages themselves will point you in the
right direction to correct the errors. You will find that with practice you will see fewer error
messages and when they do occur you will be able to find their causes more quickly. The
most often made mistake in OASIS, and a hard one to debug, relates to the parenthesis,
forgetting, adding, or misplacing one can make a mess of any good macro. A good second come those errors which relate to the proper use of the OASIS actions, you will find
that either the successor droplets are wrong, or that the context in which the action should be
performed is invalid for that particular action.
Normal debugging is done by checking the macro text and the programmers manual. There are
however circumstances in which you would like to be able to debug the evaluation process of
a macro to see exactly where something goes wrong. OASIS provides you with two different
ways to do this. The first is called tracing and the second is called assertion.
Trace Control
During tracing the result of each step in the evaluation process is shown along with the
source code of the macro that is being evaluated. Debugging your macro in this way will give
you a very good insight into what your macro is actually doing and where bugs are hidden.
During tracing you can also look up the syntax and meaning of all OASIS actions and look at
the values of all variables. There are two actions with which you can switch the tracing
option of OASIS on and off from within a macro:
TraceOn
TraceOff
You can also use the [Esc] key which will pop up a requester that asks you whether you want
to trace the current macro:
It is possible to trace a macro while recording a pen-tip trajectory with the digitizer. The
recording will continue until the serial buffer is full and restart again when the buffer has been completely read. There will be special requesters that warn you about these changes
during the recording. You will also see these warnings in any other situation where OASIS is
unable to keep up with the data flow from the digitizer.
Assertion
When you have some experience with debugging a macro, you will know that it is useful to
have some assertion actions built into it that will catch exceptions for you. An exception is a
state in which a macro should never find itself. For instance; a variable that you are about to
access should not be empty:
(Assert (NOT (IsEmpty MyVariable)) "The variable is still empty")
With these types of actions you can check suspicious macro code without having to trace
through it. It might be clear that this can save a lot of time and checking of results. If you
have inserted many assertions into your macro then they should be removed in the final
version of your macro because they will slow down macro execution somewhat.
|
