VERSION

  pcode-lite 0.1, released 2004-09-02

ABOUT

  pcode is a C program for executing pcode programs.  pcode-lite is a less
  featureful variant of pcode.

  It is derived from pcode2.c by Agnieszka Szczurowska, available at
  <URL:http://trethard.uta.edu./cse3302/CSE3302/pcode2.c>, which in turn is an
  implementation of the language described by Bruce J. MacLennan.

  pcode2.c may work perfectly well, but its source code is difficult to read
  and maintain.  As understanding how an interpreter works may be very useful
  knowledge in a programming languages course, I decided to create a less
  obtuse version of same, one students could read, understand, expand, and
  reuse in their own projects.  I admit my own source is not consistently easy
  to read, but it is a step in the right direction.

PREREQUISITES

- C compiler and Make utility    - For compilation, of course.
- Decent terminal emulator       - This is a text-only program at the moment.
- GNU Multiple Precision Library - Required for ten-digit integer mathematics.

  pcode also depends on the vec library contained in Paul Jarc's prjlibs, but
  since vec is bundled with pcode, you need not need to worry about this.

INSTALLATION

  First check your prerequisites.  Next edit the Makefile, following the
  instructions contained therein.  Run "make" to build the executable.
  Optionally copy it to a location in your $PATH.

SYNTAX

  pcode supports a syntax similar to that described in "Principles of
  Programming Languages", Third Edition, by Bruce J. MacLennan (ISBN 0-19-
  511306-3).  For the sake of readability, several enhancements are supported:

  - `.' in the input is converted to `0'.  Use this to mark ignored operands.
  - Everything following a `#' character is ignored.  This is for comments.
  - Spaces within numbers are ignored.  Use spaces for thousands' separators.
  - Extra space at line start is allowed.  I recomment indenting +9999999999's.
  - Blank lines and lines consisting solely of a comment are allowed.

  Of course, the strict style given in the book is also supported.

  I may in the future remove this extra syntax candy from pcode-lite.

COMMAND LINE ARGUMENTS

  -iFILE   Read input data from FILE.
  -oFILE   Write output data to FILE.
  -h       Print this message.
  -V       Display version and copyright information.

  If FILE is `-' or not specified, stdin or stdout is used.

SAMPLE USAGE

  Here pcode's debug mode is used to execute a program for calculating squares. 

  $ pcode-lite -i test/squares.pc
  +0000000001
  +0000000004
  [...]
  +0000010000

URLS

- http://ioioio.net./school/pcode/                  - Project web site.
- http://trethard.uta.edu./cse3302/CSE3302/pcode2.c - Original version.
- http://ioioio.net./misc/getline.c                 - My version of getline().
- http://multivac.cwru.edu./prjlibs/                - Source of vec library.
- http://www.swox.com./gmp/                         - GMP web site.
- http://ioioio.net./school/cse3322/                - Similar project to pcode.

TODO

- More testing and sample code.
- Comment describing the purpose of every function.
- Source cleanups and additional commenting.
- Ask Paul to add BSRCH to vec library, or do it myself.

WISHLIST

- GCC backend to produce pcode.  
  + This would require adding function pointer support to pcode.
- Graphical frontend.
- Profiling.

CHANGELOG

- 1 September 2004 - version 0.1
  + Initial release of pcode. 
- 2 September 2004 - version 0.1-lite
  + Initial release of pcode-lite. 

COPYRIGHT

- Andy Goth <unununium@openverse.com.>

LICENSE

  This program is available under the GPL.  See LICENSE for full details.

  I must place pcode therefore pcode-lite under the GPL because it incorporates
  Paul Jarc's vec library (part of prjlibs) and my getline.c (which derives
  from the GNU C Library), both of which are available only under the GPL.

vim: set ft=man tw=80 et:
