HHL and VL
----------
This is a preliminary release of HHL and VL, a development environment
primarily aimed at small handheld computers. It consists of two parts: a
compiler and a bytecode interpreter called VL. The compiler runs under Unix,
but the bytecode machine is meant to be very portable. Currently it runs
under Unix and PalmOS, but getting it to run under other systems should be
simple.

The programming language is HHL. If you've worked with PHP, you know the
basic programming model; you embed language segments in an HTML-like
markup language. The idea is that most handheld applications actually don't
do a whole lot, and they look and feel like web pages. However, it's
important to note that this language is not HTML; it's different because
it has a different purpose, and size is a big issue (we don't want huge
bytecode).

Installing
----------
There are four components to the source. There is the hhlc compiler
(compiles to a program called hhlc), the platform-independent VL source
code, the platform-dependent VL front ends, and install-vlo.c, a little
utility to transfer bytecode to the Palm.

To get anything interesting to work on the Palm, you need the pilot-link
package (libraries and include files). You also need lex and yacc for the
compiler.

This package doesn't use GNU configure yet because you really ought to know
what you're doing if you mess with this (I'll switch it to autoconf later).
Just edit the Makefile; the only thing you should need to change to get the
compiler to work is PILOTLINK; change this to your pilot-link includes.

Then do a

 $ make

to build the compiler and Unix version of VL--you should get two programs
called hhlc and vl.

 $ make install-vlo

for the palm transfer utility. You'll find a precompiled Palm executable in
the directory precompiled/.

If you'd like to build the Palm executable, edit the Makefile and change
the PCC line to the location of your m68k cross compiler, and PILRC to
whatever your pilrc executable is. Then do a

 $ make all

This version compiles with the Palm SDK 3.5. Unfortunately, the pilrc
program has a little bug that prevents this it working on RISC
architectures; you might want to stick with Linux/x86 for this. (I'm working
on that.)

Getting Started
---------------
There are some simple examples in the examples/ directory. Try a simple test
with

 $ ./hhlc examples/rowsamp

This creates an object file called out.vlo. Run it with the Unix vl:

 $ ./vl out.vlo

You should get a weird-looking list of numbers. That's because the Unix vl
is a text-only interface mostly meant for debugging. To get it to the Palm:

1. Install vl_palm.prc with pilot-xfer -i or whatever.
2. Run the VLPalm app. It tells you to install a VL program file. (This
   step is necessary to create the database on the Palm and will eventually
   go away.)
3. Do a "./install-vlo out.vlo" on your Unix machine.
4. Run the VLPalm app again, and press the Go button. The display should
   make more sense now.

The HHL Language
----------------
This release supports most basic language features, but does not have two
things in particular: floating-point numbers and lists. (Those still have a
few bugs, but I'll include them in the next release.)

The markup language is entirely based on tables and has two basic tags:
<table> (for starting a table) and <c> (for a cell). They're lower-case (for
the moment; I may make this permanent). The attributes for these tags are:

<table>:
 c=x            Number of columns is x.
 fsize=x	Default font size. x can be small, medium, or large.
 fjust=x	Default cell justification. x is one of left, right, center.

<c>:
 name=x		Gives the cell a name. Required for functions like cellp(),
		and for actions.
 action=x	Gives the cell an action. When you tap on the cell, VL
		calls the function x with the cell name as an argument.
 fsize=x	Overrides default font size.
 fjust=x	Overrides default font justification.

There aren't many builtin functions in this release, but here they are:

All:
print(x)	Sends the expression x to the display processor.
rows_left()	Returns number of rows left on display using current font.
cellp(name, x)	Changes cell display named by "name" to the expression x.
atoi(x)		Converts x to an integer and returns the result.
trim(x)		Strips whitespace off the end of a string, returns result.

Palm only:
openpdb(x)	Opens a Palm database "x". Returns dbhandle.
closepdb(x)	Closes the dbhandle x.
getpdbrec(x)	Get the next record from dbhandle x. 

Bugs/Incapabilities
-------------------
Plenty. Probably the biggest bug in this release is that vl_init() doesn't
actually verify the header, so if you point VL at a bogus file, it's almost
definitely going to crash. Sorry 'bout that; I'll fix it soon.

hhlc Options
------------
-o <file>	output file
-d <num>	set debug level
-p		output parse tree (to "parse_tree"; PostScript file)

License/Author
--------------
This package is distributed under your choice of the "Artistic" or
GNU GPL.

Brian Ward
bri@cs.uchicago.edu

