Copyright © 1997
From version 2.3a onwards, the Opal compilation system provides an
alternative to the ocs
command for developing Opal
applications: the oasys
tool. Oasys supports
functionality similar to ocs
, but extends the latter's possibilities by incorporating an interpreter-debugger which allows
expressions to be evaluated `on the fly', and the execution
of functions to be monitored.
Oasys was developed by Wolfgang Grieskamp and Eckard Lehmann and the latter programmed the interpreter-debugger as part of his master's thesis. Further improvements were added by Klaus Didrich.
Note: This manual is still incomplete as regards the debugger functionality.
The global configuration normally need not be edited by the user.
The global configuration is a Tcl script which is read when Oasys is invoked. It is looked for at the following locations:
A user may customize Oasys. The user configuration is a Tcl script which is read after the global configuration has been read. It is read from one of the following locations:
The user configuration may contain any Oasys or Tcl commands.
After having read the global and the user configuration, Oasys tries to read the project configuration from the file `config.oasys' in the current directory.
Whenever a directory is added to the search path of Oasys (see oasys-path), the `config.oasys' file of that directory will be loaded if present.
The Oasys command-line interpreter is a Tcl interpreter, so the user can use any feature of Tcl when writing global or local configuration files.
For defining new procedures, however, the Oasys command oasys-proc
(see oasys-proc) should be used. This has two advantages: input of
unit names or file names is supported by completion and the procedure is
registered with the Oasys help system.
As a short example, we present the definition of a command A
, which
registers all units in the current directory (see a for the simple
variant).
oasys-proc {A} \ {Add all units in current directory.} \ {CMD} \ { foreach s [glob *.sign] {a $s} }
Every unit which is to be used in Oasys must be registered before the first use.
Expressions are always evaluated in a so-called current context. This context is one of the registered units. It is called the focus. (See also oasys-additional-context.)
Before evaluating expressions, any units whose source code have been changed are checked and compiled.
All expressions are stored. The history can be retrieved
(see oasys-values). Element I can be referred to by the identifier
RES
I, e.g. RES2
for expression number 2. The last
expression can always be referred to with RES
.
The evaluation of expressions of the built-in monadic type com[data]
yields a constant, but does not execute the command.
Every unit can have one of three states:
The r
and c
commands
without arguments refer to all structures whose source code has been
changed.
In order to print the result of an evaluation, Oasys must know how to
transform a given data type into textual representation. The Opal
library contains two data types for texts: denotation
and
fmt
, the latter being a structured text which supports pretty
printing.
A print function for type data is a function of type
data -> denotation
or data -> fmt
. If the type is
parameterized, the print function must have one additional higher-order
parameter for the print functions of the parameter types. For example, a
print function for type map[dom, <, codom]
must have either
functionality (dom -> denotation) ** (codom -> denotation) -> map[dom,
<, codom] -> denotation
or (dom -> fmt) ** (codom -> fmt) -> map[dom,
<, codom] -> fmt
(you may not mix denotation
and fmt
).
The user may define print functions explicitly (see oasys-print-method).
If no print function is defined for type type in structure
struct, Oasys tries to find one. If one of the structures
struct, Fmt
struct, structConv
(in this order)
contains possible candidates for print functions, one of these candidates is
chosen. Selector functions are not considered.
If no print function can be found, Oasys prints <some>
to indicate
that `some' result has been obtained, but cannot be represented.
Functions, i.e. expressions with function functionality, are represented by their internal representation. For known functions their (internally unique) name is used, otherwise a lambda expression is printed.
Example:
Denotation.sign>e {+/+(",")} -| +/+'Denotation,1(,)
Names are annotated with their origin. In this example, there is also an additional number to distinguish overloaded functions.
Local variables of lambda expressions are renamed, and infix applications are converted into prefix applictions.
Example:
Denotation.sign>e {IF false THEN \\a, b. a ++ b ELSE \\a, b. a ++ "::" ++ b FI} -| \\ a0, a1. ++'Denotation(a0, ++'Denotation("::", a1))
In some cases local variables are not treated properly.
Commands starting with the letter `d' are used for debugging. Note that the debugging features are experimental and not stable yet.
Add structure STRUCTURE and all imported structures to the set of registered structures. STRUCTURE may contain a directory path or a file suffix; both will be removed. STRUCTURE and its imported structures must be found in the Oasys search path (see oasys-path).
Example:
> a Rational. -| loading Rational.sign -| loading Rational.impl
See also l, ll, oasys-register.
Reload, then create object archive for folderFOLDER to be used with
the ocs
command.
Reload all registered structures whose source has changed, then check these structures.
This command is rarely needed, because all actions are also part of the
e
command (see e).
Example:
> c -| loading Rational.impl -| checking Rational.impl -| ERROR [Rational.impl at 43.5]: -| improperly named function definition target or parameter foo -| ERROR [check]: language error
See also oasys-check, oasys-verbosity.
Set breakpoint for function NAME with optional guard EXPR.
Continue after interrupted evaluation.
Select frame NUMBER.
Introduction to oasys debugging commands.
Enable monitoring of execution of function NAME.
Reload all registered structures whose source has changed, check these structures and compile them, then evaluate EXPR in current focus (see f) and print the result. If EXPR contains spaces or quotes, it should be surrounded by curly brackets. Errors in the expressions are reported with line number 0.
Note that monadic expressions (expressions of type com[data]
)
are evaluated but not executed.
Example:
Rational.impl>e 24 / 8 -| [3/1] Rational.impl>e 34 / 8 -| ERROR [at 0.1]: no matching operation for 34 -| ERROR [check]: language error -| aborted
See also ex, f, t, x, oasys-eval, oasys-print-method, oasys-show-type, oasys-values.
Reload all registered
structures whose source has changed, check these structures
and compile them, then evaluate EXPR in current focus (see f),
execute the resulting command and print the result.
The expression must be of type com[data]
.
If EXPR contains spaces or quotes, it should be surrounded by curly brackets. Errors in the expressions are reported with line number 0.
Example:
BasicIO.sign>ex writeLine("abc") -| abc -| nil
Note that abc
is the side effect of the execution of the command, and
nil
is the value returned by the command.
See also e, f, t, x, oasys-exec, oasys-print-method, oasys-show-type, oasys-values.
Set focus to UNIT (structure name + `.sign' or `.impl'). UNIT is the context in which the following expressions are evaluated. The current focus is included in the oasys prompt.
The focus can not be set to implementation parts of library structures (see oasys-path).
Example:
> f Nat.sign
See also e, ex, x, oasys-focus.
Example:
> h a -| Add STRUCTURE to known units. -| A possible directory path and .sign or .impl suffix will be stripped -| from STRUCTURE.
See also oasys-help.
Example:
> l ... String.sign String.impl OptionConv.sign OptionConv.impl Com.sign Com.impl ComConv.sign ComConv.impl
See also ll, oasys-units.
Reload all registered
structures whose source has changed, check these structures
and compile them, then create an executable file which will execute COM.
COM must be a constant of type com[void]
. The executable file
will have the name COM as well.
Example:
HelloWorld.sign> ld hello -| linking hello'HelloWorld.sign
Example:
HelloWorld.sign>ll -| ... -| HelloWorld.impl, (#43), checked -| BasicIO.sign , (#44), checked, library -| BasicIO.impl , (#45), checked, compiled, library -| Pair.sign , (#46), checked, library -| Pair.impl , (#47), checked, compiled, library
See also l, oasys-units.
This command is rarely needed, because it is part of the c and the e and ex commands.
Example:
Rational.sign>r -| loading Rational.sign
See also oasys-reload.
Control whether the result type of expressions is printed. The command toggles between on and off.
Example:
Rational.sign>t -| show types is on Rational.sign>e + -| +'Rational -| rat'Rational ** rat'Rational -> rat'Rational
See also e, ex, oasys-show-type.
Reload all known structures whose source has changed, then
execute COM which must be a constant of type com[void]
.
This is faster than ex.
Example:
HelloWorld.sign>x hello -| Hello, World!
Oasys manages a set of units which are always added to the current context when evaluating expressions.
add UNITS
rm UNITS
clear
show
The smaller the set of imported units, the faster expressions will be evaluated. Additional imported units may cause ambiguities and even cyclic dependency errors.
See also oasys-focus, oasys-eval, oasys-exec.
Commands from this section are not available for completion on the command line and are hidden from the help command by default. This command makes them available.
See also oasys-really-all-commands
Create object archive for use with the ocs-command for the given FOLDER-NAME. FOLDER-NAME is the base name of the source path. If FOLDER-NAME is omitted, archives are created for all folders.
See also ar.
Set arguments for next invocation of the evaluator process. This is for debugging purposes only.
See also oasys-args-show.
Print arguments set with last call of oasys-args.
Imported units are checked first.
See also c, oasys-reload.
Note that monadic expressions (expressions of type com[data]
)
are evaluated but not executed.
See also e, oasys-exec, oasys-focus, oasys-run, oasys-print-method, oasys-show-type, oasys-additional-context.
com[data]
.
If EXPR contains spaces, quotes or square brackets, it should be surrounded by curly brackets. Errors in the expressions are reported with line number 0.
See also ex, oasys-eval, oasys-focus, oasys-run, oasys-print-method, oasys-show-type.
Set focus to UNIT (structure name + `.sign' or `.impl'). UNIT is the context in which the following expressions are evaluated. (See oasys-additional-context for extending this context.) The current focus is included in the oasys prompt.
The focus can not be set to implementation parts of library structures (see oasys-path).
If no UNIT is given, the command returns the current focus.
See also oasys-additional-context.
See also h
com[void]
.
See also ld.
oasys-path
just returns the current search path as a sequence
of pairs. The first element of each pair is the path to the sources, the
second element is the path to compiler results.
oasys-path add ocs
PATH adds PATH to the search
path. If PATH contains a file `config.oasys', it will be read and
executed.
oasys-path add library
PATH adds PATH to the search
path. Structures in this path are considered to be library structures.
If PATH contains a file `config.oasys', it will be read and
executed.
Difference between library and ordinary structures is that library structures are never checked for reloading (library structures are never outdated), and that compiler results are located in a different place.
-> fmt
or SORT -> denotation
.
In case SORT is parameterized, FUN must have a higher-order
parameter of type data -> fmt
or data ->
denotation
for every parameter sort data.
Take care in chosing a total function as print function.
See also Printing Results.
ARGSPEC specifies the syntax (including the name of the new command). Elements of ARGSPEC are
STRING | literal |
@VAR | variable |
@#UNIT | variable with unit completion |
@^FILE | variable with filename completion. |
?
to indicate optional
elements or *
to indicate repeatitions.
HELP contains the help text printed by the commands h and oasys-help.
ARGS is a list of Tcl variables for each of the elements of ARGSPEC (including literals).
BODY is a sequence of Tcl commands which may refer to the variables in ARGS. Optional elements and repetitions are represented as Tcl lists.
See Defining New Oasys Commands for an example.
See also q.
There is a set of commands with prefix oasys-intern
which are hidden
unless this command is given.
See also oasys-all-commands.
Register the given structures and load them into the repository unless they are already loaded.
STRUCTURE may contain a directory path or a file suffix; both will be removed. STRUCTURE and its imported structures must be found in the Oasys search path (see oasys-path).
See also a, oasys-path.
direct
(default) or transitive
and
modifies the RELATION.
imports | gives the imported basic units. If UNIT is an implementation, its signature part is regarded as an import. |
importers | is the reversed relation of imports , and
gives the basic units which import UNIT. If UNIT is a signature,
its implementation part is regarded as an importer.
|
implImports | is the set of implementation units which are used to realize UNIT. If UNIT is a signature, then it will be treated identical to the implementation of this signature. |
implImporters | is the reversed relation of
implImports , and delivers all units which use UNIT (or its
implementation part, if UNIT is a signature) for their implementation.
|
imports
.
See also r.
com[void]
.
This is faster than oasys-exec.
See also x, oasys-exec.
If PATHNAME is given to Oasys as argument when it is called, it will read the saved repository.
Select an item in evaluation stack (see oasys-bt).
on | result type is printed |
off | result type is not printed |
toggle | current state is toggled |
show | current state is printed |
See also t, oasys-eval, oasys-exec.
The printed representation is the user input. The stored value is the result of the evaluation in the environment which was current at the time the expression was evaluated for the first time.
The expressions can be accessed by the identifiers RES0
, RES1
,
... The last evaluated expression can also be accessed as RES
.
See also Evaluating Expressions.
Control the verbosity of Oasys.
diag hint | Show all diagnostics from checking Opal code. |
diag warn | Show warnings and errors from checking Opal code. |
diag error | Show only errors from checking Opal code. |
message LEVEL | Show messages of level LEVEL and below. (Currently levels 0 and 3 are used.) |
66 entries
[ $ ] [ . ] [ < ] [ a ] [ c ] [ d ] [ e ] [ f ] [ g ] [ h ] [ i ] [ k ] [ l ] [ m ] [ n ] [ o ] [ p ] [ q ] [ r ] [ s ] [ u ] [ v ]$HOME |
$OASYSGLOBALRC |
$OASYSLIB |
$OASYSRC |
$OCSDIR |
.oasysrc |
<some> |
abstract syntax |
additional context |
checked unit : [1], [2] |
checking structures |
com[data] : [1], [2], [3], [4] |
com[void] : [1], [2], [3], [4] |
compiled unit : [1], [2] |
completion : [1], [2] |
config.oasys : [1], [2] |
current context : [1], [2] |
default.repo |
diagnostics |
evaluation : [1], [2], [3], [4], [5] |
executable : [1], [2] |
execution : [1], [2], [3], [4], [5] |
expression history : [1], [2] |
finding print functions |
focus : [1], [2], [3], [4], [5], [6] |
global configuration |
help : [1], [2] |
import relation |
imported structures |
imported units : [1], [2], [3] |
infix application |
introduction |
known structures |
lambda expressions |
library structure : [1], [2], [3], [4] |
link |
list of evaluated expressions |
list of units : [1], [2], [3] |
loaded unit |
local variables |
messages |
monad |
monadic expression |
new Oasys command |
new Oasys commands |
oasys search path : [1], [2], [3], [4] |
object code |
Opal errors, warnings, hints |
overloading |
print function : [1], [2] |
print functions, finding |
project configuration |
quit : [1], [2] |
registered structures : [1], [2], [3], [4], [5], [6] |
registered units : [1], [2], [3], [4], [5], [6] |
relation |
reloading units : [1], [2] |
RES : [1], [2] |
result type : [1], [2] |
save repository |
side effect |
startup.oasys |
state : [1], [2], [3] |
unit information |
user configuration |
verbosity |
This document was generated 5 June 2001 (14:13:57) using the texi2html translator version 1.51-kd-pl15.