opl2java v1.20 README
=====================

Last updated: 13/12/2000


Copyright and Copyleft
~~~~~~~~~~~~~~~~~~~~~~
The opl2java translator and its sources are covered by the GNU Public Licence.
Please read Copying.txt for more information.  opl2java has been produced using
Bison and Flex.

The psion.opl Java library and opllib C library are (C) Copyright Taurus
Software, 2000.  You may not modify these in any way without prior permission
from the author.  Sources are available on request, for those intending to
help develop the library further.


Author
~~~~~~
Robert Thornburrow, Taurus Software, robert@tsac.co.uk


Purpose
~~~~~~~
To allow OPL programs to be moved to or tested on other platforms.


Platforms
~~~~~~~~~
Linux-i386, Cygwin32, WIN32 (Note: No makefile is given for MSVC++).


How it works
~~~~~~~~~~~~
OPL source code is parsed and then the resulting parse tree is dumped in
another programming language.  Built-in OPL functions and procedures are
translated into library calls and a runtime library emulates this
functionality.


Installation
~~~~~~~~~~~~
Go into the src directory and type:

    make -f Makefile.linux install
    
This will build the opl2java binary and install it in opl2java's bin
directory.  Subsititute cygwin32 for linux to compile under Cygwin.
Drop the .c files into a project with MSVC++.

Note: You don't need flex/bison to compile the sources.  The .l and .y
files are provided in case you wish to modify them.


Operation
~~~~~~~~~
Copy your OPL sources to your development platform (using 3Link or similar).
In this example, the source file is "example.opl".  At the command line type:

   opl2java -Mj -V -x example.opl
   
This will produce a file called example.java, containing a single Java class
called "example".  To compile this, you will need "javac" in you path and
the opl2java directory in your classpath (the directory above the psion
directory for the psion.opl library).  You can now javac the file in the
normal way, or do a one step translate and compile:

   opl2java -Mj -V example.opl
   
opl2java will invoke the Java compiler for you.

Note: You will need to put opl2java/lib in your classpath for opl2java to
drive the compiler for you.  To perform translation only, use -x.

The resulting class file can then be executed.

A similar process is used to create applets, but instead specify -MJ.  The
applet can be run by creating a HTML file with an <applet> tag.  This can
then be tested with "appletviewer".

If your application uses any resource files (e.g. PIC files), then these can
be placed in a ZIP file and downloaded in one go when the applet starts up.
You need to specify the ZIP file in your applet tag:

  <applet code="patience.class" width=480 height=160>
    <param name="ResourceZIPFile" value="patience.zip">
  </applet>

This will speed up the running of the application over the Internet.  Another
use for this technique is for websites that only allow certain file extensions
to be uploaded (.PIC not being one of them).


What's Supported
~~~~~~~~~~~~~~~~
The 1.10 translator supports the following keywords:

APP AND BUSY CHR$ DEFAULTWIN DO ELSE ELSEIF ENDA ENDP ENDIF ENDWH EXIT FONT gAT
gBOX gCLOSE gCLS gCOPY gCREATE GETEVENT GIPRINT gLINEBY gLOADBIT GLOBAL gFILL
gFONT gGREY gMOVE gPRINT gSTYLE gTMODE gUSE IF LOCAL mCARD MENU mINIT NUM$ OFF
ON OR PRINT PROC RANDOMIZE RETURN RND SECOND STATUSWIN UNTIL WHILE

The 1.20 translator also supports:

ASC AT CURSOR dBUTTONS dCHOICE dEDIT dFLOAT DIALOG dINIT dTEXT GETCMD$ gBORDER
GET gLINETO gPATT gSETWIN LEFT$ LOCK PAUSE SQR

The OPL language syntax (IFs, WHILEs etc) is pretty much complete and most of
the simple OPL functions (e.g. gCREATE) and procedures (e.g. gUSE) are
implemented in some form or other.  The latter are implemented in a separate
library, so can be upgraded independantly of the translator.  Further keywords
can be added to the translator by simple modification of the lexer.

Currently the translator supports the following language options:

  j - Java applications for use with JDK 1.1.x upwards
  J - Java applets for use with JDK 1.1.x upwards
  c - RISCOS C for use with the Acorn Archimedes range of machines
  
The runtime library "psion.opl" supports several key features:

  * Emulation of OPL graphics windows and bitmaps.
  * Emulation of the Psion keyboard (Ctrl = Psion key).
  * Loading of native Series 3 files (a filter provides correct endian'ness).
  * Loading and conversion of Series 3a .pic files (black and grey only).
  * Loading of resources as a ZIP file (applets only).
  
  
What's Not Supported
~~~~~~~~~~~~~~~~~~~~
Currently the translator and runtime library do not support:

  * Keywords other than those listed above
  * Textual functions (PRINT etc), only the graphical versions of these (gPRINT)
  * Functions with variadic arguments (PRINT etc), common variants are supported
  * Menus (use hotkeys instead)
  * Dialogs
  * Fonts
  * OS Calls
  
Series 5 OPL32 has not been attempted.


Files
~~~~~
bin/        Directory where the opl2java binary will reside.
examples/   A sample OPL program which can be made into an applet or an
            application.
lib/        The psion.opl Java library (binaries only).
src/        Source code for opl2java translator.


History
~~~~~~~
v1.20 - Added support for more OPL keywords.  Upgraded OPL library to handle
        new keywords and blinking cursors, and to allow multiple applet
        instnaces.  Ported to CygWin32.
v1.10 - Simultaneous C and Java generation from the same binary.  Added support
        for Java Applet generation.  NT version can now take parameters.  Added
        type checking for correct expression generation.  Added ZIP file
        support.
v1.00 - Switched to NT Development and added Java generation.
v0.10 - Acorn Archimedes version which produced RISCOS C code.

