---
title: "Portable Oberon-07"
series: "Mostly Oberon"
number: 11
author: "rsdoiel@gmail.com (R. S. Doiel)"
date: "2020-08-15"
keywords: [ "Oberon", "portable", "stdin" ]
copyright: "copyright (c) 2020, R. S. Doiel"
license: "https://creativecommons.org/licenses/by-sa/4.0/"
---
# Portable Oberon-07
## using OBNC modules
This is the eleventh post in the [Mostly Oberon](../../04/11/Mostly-Oberon.html) series.
Mostly Oberon documents my exploration of the Oberon Language, Oberon System and the
various rabbit holes I will inevitably fall into.
## Working with standard input
By R. S. Doiel, 2020-08-15 (updated: 2020-09-05)
Karl Landström's [OBNC](https://miasap.se/obnc/), Oberon-07 compiler,
comes with an Oberon-2 inspired set of modules
described in the Oakwood Guidelines as well as
several very useful additions making Oberon-07 suitable for
writing programs in a POSIX environment. We're going to
explore three of the Oakwood modules and two of Karl's own additions
in this post as we create a program called [SlowCat](SlowCat.Mod).
I am using the term "portable" to mean the code can be compiled
using OBNC on macOS, Linux, and Raspberry Pi OS and Windows 10
(i.e. wherever OBNC is available). The Oakwood Guideline modules
focus on portability between an Oberon System and other systems.
I'll leave that discussion along with
[POW!](http://www.fim.uni-linz.ac.at/pow/pow.htm)
to the end of this post.
### SlowCat
Recently while I was reviewing logs at work using [cat](https://en.wikipedia.org/wiki/Cat_(Unix)), [grep](https://en.wikipedia.org/wiki/Grep)
and [more](https://en.wikipedia.org/wiki/More_(command)) it
struck me that it would have been nice if **cat**
or **more** came with a time delay so you could use them like a
teleprompter. This would let you casually watch the file scroll
by while still being able to read the lines. The program we'll build
in this post is "SlowCat" which accepts a command line parameter
indicating the delay in seconds between display each line read from
standard input.
## Working with Standard Input and Output
The Oakwood guides for Oberon-2 describe two modules
particularly useful for working with standard input and output.
They are appropriately called `In` and `Out`. On many Oberon Systems
these have been implemented such that your code could run under Unix
or Oberon System with a simple re-compile. We've used `Out` in our
first program of this series, "Hello World". It provides a means to
write Oberon system base types to standard out. We've used `In`
a few times too. But `In` is worth diving into a bit more.
### In
The [In](http://miasap.se/obnc/obncdoc/basic/In.def.html) module provides
a mirror of inputs to those of [Out](http://miasap.se/obnc/obncdoc/basic/Out.def.html). In Karl's implementation we are interested in one procedure
and module status variable.
+ `In.Line(VAR line: ARRAY OF CHAR)` : Read a sequence of characters from standard input from the current position in the file to the end of line.
+ `In.Done` : Is a status Boolean variable, if the last call to an procedure in `In` was successful then it is set TRUE, otherwise FALSE (e.g. we're at the end of a file)
We use Karl's `In.Line()` extension to the standard `In` implementation
before and will do so again as it simplifies our code and keeps things
easily readable.
There is one nuance with `In.Done` that is easy to get tripped up on.
`In.Done` indicates if the last operation was successful.
So if you're using `In.Line()` then `In.Done`
should be true if reading the line was successful. If you hit the end of
the file then `In.Done` should be false. When you write your loop
this can be counter intuitive. Here is a example of testing `In.Done`
with a repeat until loop.
~~~
REPEAT
In.Line(text);
IF In.Done THEN
Out.String(text);Out.Ln();
END;
UNTIL In.Done = FALSE;
~~~
So when you read this it is easy to think of `In.Done` as you're
done reading from standard input but actually we need to check for `FALSE`.
The value of `In.Done` was indicating the success of reading our line.
An unsuccessful line read, meaning we're at the end of the file, sets
`In.Done` to false!
### Out
As mention `Out` provides our output functions. We'll be using
two procedure from `Out`, namely `Out.String()` and `Out.Ln()`.
We've seen both before.
### Input
"SlowCat" needs to calculate how often to write a line of
text to standard output with the `Out` module. To do that
I need access to the system's current time. There isn't an
Oakwood module for time. There is a module called
`Input` which provides a "Time" procedure. As a result
I need to import `Input` as well as `In` even though
I am using `In` to manage reading the file I am processing
with "SlowCat".
A note about Karl's implementation. `Input` is an Oakwood
module that provides access to three system resources --
mouse, keyboard and system time. Karl
provides two versions `Input` and `Input0`, the first is
intended to be used with the `XYPlane` module for graphical
applications the second for POSIX shell based application.
In the case of "SlowCat" I've stuck with `Input` as I am
only accessing time I've stuck with `Input` to make my source
code more portable if you're using another Oberon compiler.
## Working with Karl's extensions
This is the part of my code which is not portable
between compiler implementations and with Oberon Systems.
Karl provides a number of extension module wrapping various
POSIX calls. We are going to use two,
[extArgs](http://miasap.se/obnc/obncdoc/ext/extArgs.def.html)
which provides access to command line arguments and
[extConvert](http://miasap.se/obnc/obncdoc/ext/extConvert.def.html)
which provides a means of converting strings to integers.
If you are using another Oberon compiler you'll need to
find their equivalents and change my code example. I
use `extArgs` to access the command line parameters
included in my POSIX shell invocation and I've used
`extConvert` to convert the string presentation of the
delay to an integer value for my delay.
## Our Approach
To create "SlowCat" we need four procedures and one
global variable.
`Usage()`
: display a help text if parameters don't make sense
`ProcessArgs()`
: to get our delay time from the command line
`Delay(count : INTEGER)`
: a busy wait procedure
`SlowCat(count : INTEGER)`
: take standard input and display like a teleprompter
`count`
: is an integer holding our delay value (seconds of waiting) which is set by ProcessArgs()
### Usage
Usage just wraps helpful text and display it to standard out.
## ProcessArgs()
This a functional procedure. It uses two of Karl's extension
modules. It uses `extArgs` to retrieve the command line parameters
and `extConvert` the string value retrieved into an integer.
`ProcessArgs()` returns TRUE if we can successful convert the
command line parameter and set the value of count otherwise return
FALSE.
## Delay(VAR count : INTEGER)
This procedure uses `Input0` to fetch the current epoch time
and counts the number of seconds until we've reached our delay
value. It's a busy loop which isn't ideal but does keep the
program simple.
## SlowCat(VAR count: INTEGER);
This is the heart of our command line program. It reads
a line of text from standard input, if successful writes it
to standard out and then waits using delay before repeating
this process. The delay is only invoked when a reading a
line was successful.
## Putting it all together
Here's a "SlowCat" program.
~~~
MODULE SlowCat;
IMPORT In, Out, Input, Args := extArgs, Convert := extConvert;
CONST
MAXLINE = 1024;
VAR
count: INTEGER;
PROCEDURE Usage();
BEGIN
Out.String("USAGE:");Out.Ln();
Out.Ln();
Out.String("SlowCat outputs lines of text delayed by");Out.Ln();
Out.String("a number of seconds. It takes one parameter,");Out.Ln();
Out.String("an integer, which is the number of seconds to");Out.Ln();
Out.String("delay a line of output.");Out.Ln();
Out.String("SlowCat works on standard input and output.");Out.Ln();
Out.Ln();
Out.String("EXAMPLE:");
Out.Ln();
Out.String(" SlowCat 15 < README.md");Out.Ln();
Out.Ln();
END Usage;
PROCEDURE ProcessArgs() : BOOLEAN;
VAR i : INTEGER; ok : BOOLEAN; arg : ARRAY MAXLINE OF CHAR;
res : BOOLEAN;
BEGIN
res := FALSE;
IF Args.count = 1 THEN
Args.Get(0, arg, i);
Convert.StringToInt(arg, i, ok);
IF ok THEN
(* convert seconds to microseconds of clock *)
count := (i * 1000);
res := TRUE;
END;
END;
RETURN res
END ProcessArgs;
PROCEDURE Delay*(count : INTEGER);
VAR start, current, delay : INTEGER;
BEGIN
start := Input.Time();
REPEAT
current := Input.Time();
delay := (current - start);
UNTIL delay >= count;
END Delay;
PROCEDURE SlowCat(count : INTEGER);
VAR text : ARRAY MAXLINE OF CHAR;
BEGIN
REPEAT
In.Line(text);
IF In.Done THEN
Out.String(text);Out.Ln();
(* Delay by count *)
Delay(count);
END;
UNTIL In.Done = FALSE;
END SlowCat;
BEGIN
count := 0;
IF ProcessArgs() THEN
SlowCat(count);
ELSE
Usage();
END;
END SlowCat.
~~~
## Compiling and trying it out
To compile our program and try it out reading
our source code do the following.
~~~
obnc SlowCat.Mod
# If successful
./SlowCat 2 < SlowCat.Mod
~~~
## Oakwood Guidelines and POW!
Oberon and Oberon-2 were both used in creating and enhancing the
Oberon System(s) as well as for writing programs on other operating
systems (e.g. Apple's Mac and Microsoft Windows).
Implementing Oberon compilers on non Oberon Systems required clarification
beyond the specification. The Oakwood Guidelines were an agreement
between some of the important Oberon-2 compiler implementers which
attempted to fill in that gap while encouraging portability in
source code between operating systems. Portability was desirable
because it allowed programmers (e.g. students) to compile
and run their Oberon programs with minimal modification in any
environment where an Oakwood compliant compiler was available.
Citation for Oakwood can be found in [Oberon-2 Programming with Windows](https://archive.org/details/oberonprogrammin00mhlb/page/n363/mode/2up?q=Oakwood+Guidlines).
> Kirk B.(ed): The Oakwood Guidelines for Oberon-2 Compiler Developers. Available via FTP from ftp.fim.uni-linz.ac.at, /pub/soft/pow-oberon/oakwood
The FTP machine doesn't exist any more and does not appear to have been included in JKU's preservation plans. Fortunately the POW! website has been preserved.
[POW!](http://www.fim.uni-linz.ac.at/pow/pow.htm) was a
different approach. It was a compiler and IDE targeting
other than Oberon Systems (e.g. Windows and later Java). It was
intended to be used in a hybrid development environment and to
facilitate leveraging non-Oberon resources (e.g. Java classes,
native Windows API). POW project proposed "Opal" which was a
super set of modules that went beyond Oakwood. Having skimmed
"Oberon-2 Programming with Windows" some may seem reasonable to
port to Oberon-07, others less so.
Why Oakwood and POW? These efforts are of interest to Oberon-07
developers as a well worn path to write code that is easy to
compile on POSIX systems and on systems that are based on the
more recent [Project Oberon 2013](http://www.projectoberon.com/).
It enhances the opportunity to bring forward well written modules
from prior systems like [A2](https://en.wikibooks.org/wiki/Oberon/A2)
but implemented for the next generation of Oberon Systems
like [Integrated Oberon](https://github.com/io-core/io).
### Oakwood PDF
Finding a PDF of the original Oakwood guidelines is going to become
tricky in the future. It was created by Robinson Associates and the
copy I've read from 1995 includes a page saying not for distribution.
Which sorta makes sense in the era of closed source software
development. It is problematic for those of us who want to explore
how systems evolved. The term "Oakwood Guidelines" is bandied about
after 1993 and several of the modules have had influence on the language
use via book publications. I was able to find a PDF of the 1995
version of the guidelines at
[http://www.math.bas.bg/bantchev/place/oberon/oakwood-guidelines.pdf](http://www.math.bas.bg/bantchev/place/oberon/oakwood-guidelines.pdf).
Here's a typical explanation of Oakwood from
[http://www.edm2.com/index.php/The_Oakwood_Guidelines_for_Oberon-2_Compiler_Developers#The_Oakwood_Guidelines](http://www.edm2.com/index.php/The_Oakwood_Guidelines_for_Oberon-2_Compiler_Developers#The_Oakwood_Guidelines)
for a description of Oakwood.
> __The Oakwood Guidelines for the Oberon-2 Compiler Developers /These guidelines have been produced by a group of Oberon-2 compiler developers, including ETH developers, after a meeting at the Oakwood Hotel in Croydon, UK in June 1993__
[http://www.edm2.com/index.php/The_Oakwood_Guidelines_for_Oberon-2_Compiler_Developers#The_Oakwood_Guidelines](http://www.edm2.com/index.php/The_Oakwood_Guidelines_for_Oberon-2_Compiler_Developers#The_Oakwood_Guidelines)
(an OS/2 developer website) was helpful for providing details about Oakwood.
It would have been nice if the Oakwood document had made its way
into either ETH's or JKU's research libraries.
Leveraging prior art opens doors to the past and future. Karl has
done with this with the modules he provides with his OBNC compiler
project.
### Next and Previous
+ Next [Oberon to Markdown](../../10/03/Oberon-to-markdown.html)
+ Previous [Procedures in records](../..//07/07/Procedures-in-records.html)