Oasys Manual

Klaus Didrich


Copyright © 1997


Introduction

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.


Configuring Oasys

Global Configuration

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:

  1. `$OASYSGLOBALRC'
  2. `$OASYSLIB/startup.oasys'
  3. `$OCSDIR/lib/oasys/startup.oasys'
  4. `/usr/ocs/lib/oasys/startup.oasys'

User Configuration

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:

  1. `$OASYSRC'
  2. `$HOME/.oasysrc'

The user configuration may contain any Oasys or Tcl commands.

Project Configuration

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.

Defining New Oasys Commands

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} }

Basic Usage of Oasys

Basic Commands

Managing Units

Every unit which is to be used in Oasys must be registered before the first use.

a UNIT
Add UNIT to the set of registered units. UNIT must be found in the current search path (see oasys-path).
l
ll
List the set of known units in short or in long format.

Evaluating Expressions

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 RESI, 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.

f UNIT
Set focus to UNIT.
e EXPR
Evaluate expression in current focus.
ex EXPR
Evaluate expression in current focus. Execute the resulting command.
x NAME
Execute command.
t
Switch printing of result type on or off.

Information

h [ CMD ]
Print information on CMD or all commands.
i
Print brief information on Oasys commands.

Compiler Functionality

Every unit can have one of three states:

loaded
The source code has been loaded.
checked
Abstract syntax of the unit is available.
compiled
Object code of the unit is available. (Signature units can never have this state.)

The r and c commands without arguments refer to all structures whose source code has been changed.

r
Reload structures.
c
Reload structures, then check structures.
ld COM
Reload structures, then create executable named COM which executes the command COM.
ar FOLDER
Reload structures, then archive structures in FOLDER

Printing Results

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, Fmtstruct, 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.

Printing Functions

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.

Debugging

Commands starting with the letter `d' are used for debugging. Note that the debugging features are experimental and not stable yet.

dm NAME
Enable monitoring of execution of function NAME. A monitored function execution can be interrupted by hitting C-C. Technically, a monitored function is going to be interpreted.
db NAME [EXPR]
Set a breakpoint for function NAME. Whenever this function is entered, execution is interrupted. The actual arguments of the function can be inspected by using the formal parameter names in expression evaluation. If EXPR is given, it must denote a boolean expression over the formal parameters of the function; execution is only interrupted if the guard expression is true.
do NAME
Disable debugging for function NAME (cancelling a previous monitor or break-point command).
ds
Show which functions are monitored or which have a breakpoint
dt
Show backtrace.
dc
Continue an interrupted execution
dn NUMBER
Perform a number of steps after interrupted evaluation
df NUMBER
Select frame

Alphabetic Listing of Oasys Shortcut Commands


a

synopsis: a STRUCTURE

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.


ar

DRAFT

synopsis: ar FOLDER

Reload, then create object archive for folderFOLDER to be used with the ocs command.


c

synopsis: c

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.


db

DRAFT

synopsis: db NAME [ EXPR ]

Set breakpoint for function NAME with optional guard EXPR.


dc

DRAFT

synopsis: dc

Continue after interrupted evaluation.


df

DRAFT

synopsis: df NUMBER

Select frame NUMBER.


di

DRAFT

synopsis: di

Introduction to oasys debugging commands.


dm

DRAFT

synopsis: dm NAME

Enable monitoring of execution of function NAME.


dn

DRAFT

synopsis: dn [ STEPS ]
Perform STEPS steps after interrupted evaluation.


do

DRAFT

synopsis: do NAME
Disable debugging for function NAME.


ds

DRAFT

synopsis: ds
Show debugged functions.


dt

DRAFT

synopsis: dt
Print back-trace.


e

synopsis: e EXPR

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.


ex

synopsis: ex EXPR

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.


f

synopsis: f UNIT

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.


h

synopsis: h [ CMD ]

Print short help on all commands (default) or the specified CMD.

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.


i

synopsis: i

Print a short summary (introduction) of the most important Oasys commands.


l

synopsis: l

List all registered units.

Example:

> l
...
String.sign String.impl OptionConv.sign OptionConv.impl Com.sign 
Com.impl ComConv.sign ComConv.impl

See also ll, oasys-units.


ld

synopsis: ld COM

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

ll

synopsis: ll

List all registered units, together with their internal number and state.

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.


q

synopsis: q

Quit Oasys.


r

synopsis: r

Reload all registered units whose source has changed.

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.


t

synopsis: t

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.


x

synopsis: x COM

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!

See also ex, oasys-run.


Alphabetic Listing of Ordinary Oasys Commands


oasys-additional-context

synopsis: oasys-additional-context ( add UNIT* | rm UNIT* | clear |show )

Oasys manages a set of units which are always added to the current context when evaluating expressions.

add UNITS
Add units to the additional context. Implementation units will be replaced by their corresponding signature parts.
rm UNITS
Remove units from the additional context. Implementation units will be replaced by their corresponding signature parts.
clear
Make the additional context the empty set.
show
Print the additional context.

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.


oasys-all-commands

synopsis: oasys-all-commands

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


oasys-archive

DRAFT

synopsis: oasys-archive [ FOLDER-NAME ]

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.


oasys-args

synopsis: oasys-args { ARG }

Set arguments for next invocation of the evaluator process. This is for debugging purposes only.

See also oasys-args-show.


oasys-args-show

synopsis: oasys-args-show

Print arguments set with last call of oasys-args.


oasys-bt

DRAFT

synopsis: oasys-bt
Print back trace.


oasys-check

synopsis: oasys-check { UNITS }
Check the given UNITS (if no units are given, all registered units are checked). It is not checked, whether the source code of UNITS has changed.

Imported units are checked first.

See also c, oasys-reload.


oasys-compile

synopsis: oasys-compile { UNITS }
Compile the given UNITS (if no units are given, all registered units are checked). Imported units are checked and compiled if necessary.


oasys-continue

DRAFT

synopsis: oasys-continue
Continue the last broken evaluation.


oasys-debug

DRAFT

synopsis: oasys-debug [ monitor NAME | off NAME | break NAME { EXPR } | update ]
Maintain debugging state.


oasys-eval

synopsis: oasys-eval EXPR
Evaluate EXPR in current focus (see oasys-focus and oasys-additional-context) and print the result. 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.

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.


oasys-exec

synopsis: oasys-exec EXPR
Evaluate EXPR in current focus (see oasys-focus and oasys-additional-context), execute the resulting command and print the result. The expression must be of type 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.


oasys-focus

synopsis: oasys-focus [ UNIT ]

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.


oasys-help

synopsis: oasys-help [ CMD ]

Print short help on all commands (default) or the specified CMD.

See also h


oasys-link

DRAFT

synopsis: oasys-link OBJECTNAME> [ EXEC-NAME ]
Link top-level command to executable EXEC-NAME. If EXEC-NAME is omitted, use name of top-level command. OBJECTNAME must be a constant of type com[void].

See also ld.


oasys-new

DRAFT

synopsis: oasys-new STRUCTNAME
Create a new structure with name STRUCTNAME.


oasys-path

synopsis: oasys-path [ add ( ocs | library ) PATH ]

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.


oasys-print-method

synopsis: oasys-print-method SORT FUN
Define FUN to be the print function for SORT. Any evaluated Opal expression of type SORT is passed to this function to obtain a printable representation. FUN must have the type SORT -> 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.


oasys-proc

synopsis: oasys-proc ARGSPEC HELP ARGS BODY
Define a new oasys command. As all of the above arguments consist of several words, they should be enclosed in curly brackets.

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.
Each of the elements may be prefixed with ? 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.


oasys-quit

synopsis: oasys-quit

Quit Oasys

See also q.


oasys-really-all-commands

synopsis: oasys-really-all-commands

There is a set of commands with prefix oasys-intern which are hidden unless this command is given.

See also oasys-all-commands.


oasys-register

synopsis: oasys-register { STRUCTURE }

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.


oasys-related

synopsis: oasys-related [ MODE ] [ RELATION ] { UNIT }
Print all units which related by RELATION with a unit from UNIT. MODE is either direct (default) or transitive and modifies the RELATION.

RELATION is one of
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.

The default RELATION is imports.


oasys-reload

synopsis: oasys-reload { UNIT }
Reload UNIT if its source has changed.

See also r.


oasys-run

synopsis: oasys-run
Execute COM which must be a constant of type com[void]. This is faster than oasys-exec.

See also x, oasys-exec.


oasys-save

synopsis: oasys-save [ PATHNAME ]
Save current state of the repository to PATHNAME (default is `default.repo').

If PATHNAME is given to Oasys as argument when it is called, it will read the saved repository.


oasys-select

DRAFT

synopsis: oasys-select NUMBER

Select an item in evaluation stack (see oasys-bt).


oasys-show-type

synopsis: oasys-show-type [ on | off | toggle | show ]
Control whether the result type of expressions is printed.
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.


oasys-source

DRAFT

synopsis: oasys-source [ UNIT ]
This command is not implemented.


oasys-step

DRAFT

synopsis: oasys-step [ STEPS ]
Evaluate a STEPS steps in current evaluation.


oasys-unit-compiled

DRAFT

synopsis: oasys-unit-compiled { UNIT }
Declare units to be compiled.


oasys-unit-interpreted

DRAFT

synopsis: oasys-unit-interpreted { UNIT }
Declare units to be interpreted.


oasys-units

synopsis: oasys-units [ full | name | file ]
Print information about the registered units. For every unit are printed:

See also l, ll.


oasys-values

synopsis: oasys-values
Show a list of expressions which have been evaluated.

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.


oasys-verbosity

synopsis: oasys-verbosity ( diag ( hint | warn | error ) | message LEVEL )

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.)


Index

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>

a

abstract syntax
additional context

c

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]

d

default.repo
diagnostics

e

evaluation : [1], [2], [3], [4], [5]
executable : [1], [2]
execution : [1], [2], [3], [4], [5]
expression history : [1], [2]

f

finding print functions
focus : [1], [2], [3], [4], [5], [6]

g

global configuration

h

help : [1], [2]

i

import relation
imported structures
imported units : [1], [2], [3]
infix application
introduction

k

known structures

l

lambda expressions
library structure : [1], [2], [3], [4]
link
list of evaluated expressions
list of units : [1], [2], [3]
loaded unit
local variables

m

messages
monad
monadic expression

n

new Oasys command
new Oasys commands

o

oasys search path : [1], [2], [3], [4]
object code
Opal errors, warnings, hints
overloading

p

print function : [1], [2]
print functions, finding
project configuration

q

quit : [1], [2]

r

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]

s

save repository
side effect
startup.oasys
state : [1], [2], [3]

u

unit information
user configuration

v

verbosity


This document was generated 5 June 2001 (14:13:57) using the texi2html translator version 1.51-kd-pl15.