Oforth Tutorial 2 : Writing oforth programs

I - Oforth is a dynamic language

Oforth is a dynamic language : there is no compilation phase to run before executing Oforth source.

By convention, Oforth sources are stored into .of files, but you can use any file name.

Performing an oforth program is just sending an oforth source file to the interpreter as if it was entered manually.

The first way to do this is to add file to perform to oforth command line. Let's say you have written this file :

"Hello" println
System sleep(2000)
"Goodbye" println

If the file is named sleep.of, oforth interpreter can be launched using this file :

/oforth/oforth sleep.of


Intepreter has performed all oforth instructions included into this file.

II - Redirections

Redirections can be used to send instructions to oforth interpreter, using cat, type, ...

Pipe can be used, as input or output redirections.

/oforth/type sleep.of | oforth


Finally, Oforth can be used as a script interpreter. For instance, if oforth executable is located into /home/bin directory, this script, if executed, will print the sum of all numbers between 1 and 10000.


10000 seq sum println

III - File load

Interpreter can also load files using #load. If interpreter is launched, you can enter :

>"sleep.of" load


IV - Packages

Oforth packages allow to regroup a list of oforth sources under an unique name.

An oforth package is described into a file package. For instance "tcp" package is defined into packs/tcp.pkg and looks like :

// ****************************************************************************
// TCP package signature
// ****************************************************************************
[ $name, "tcp" ],
[ $version, "V0.9.0" ],
[ $state, $NotStable ],
[ $directory, "tcp" ],
[ $dependencies, [ ] ],
[ $author, "Franck Bensusan" ],
[ $contributors, [ ] ],
[ $url, "www.oforth.com" ],
[ $license, "BSD" ]

// *****************************************************************************
// TCP files
// *****************************************************************************
[ "TcpConnection.of", "TcpRequest.of", "TcpServer.of" ]

// *****************************************************************************

An oforth package file pushes 2 objects on the stack : a list corresponding to package signature and a list corresponding to packages files.

To load a package, #import: is used. For instance, to load package "node" :

>import: node

#import: performs the following steps :

  1. If the package is already loaded, #import: stops.
  2. It searches for package file name and stores the directory where the package file has been found.
  3. When the file is found, it loads it and retrieves the 2 objects generated.
  4. It searchs for all dependencies and loads corresponding packages using #import:
  5. It retrieves $directory value into package signature.
  6. For each file name into the second object, it loads corresponding file (using #load) into package_directory/directory_value.

For step 2. (package file search), search order is :

  • The current directory and, if file is not found, into /packs of the current directory.
  • If not found, searches into all directories listed into OFORTH_PATH variable and into /packs of each.

The first package file name found this way is loaded.

V - Debugging

The first debug option is ... #.s to print the stack. #.s can be added into functions or methods body to print stack when required.

The second debug option is to use --Dn command line parameter.

When --D1 is used, the execution stack is printed after each exception not catched.

When --D2 is used, break points can be set into functions or methods body using #.bp . When a break point is reached, execution stops and it is possible to go to (n)ext instruction, (i)nto next function, print the (s)tack or (r)un again until a new break oint is reached.

Oforth Documentation

Current available documentation :

I - Tutorials

  • Oforth basics : here
  • Oforth syntax : here
  • Writing Oforth programs : here
  • Oforth classes : here
  • Oforth parallelism : here
  • Oforth node : Work in progress...

II - Reference

  • Lang package reference : here