OVERVIEW

This collection of files provides a general purpose algebraic expression
evaluation module, which has been expanded to supports variables and
variable assignments so you can set their values.  There's also a couple
of versions that handle values as fractions.  In addition, a routine to
allow you to examine the binary storage format for floating point values
used in PCs.  Plus some routines to put it all together.  I hope you find
them useful.

I've a web site that covers some of the details of the expression parser
at:
    http://users.easystreet.com/jkirwan/new/parsing.html

An earlier version of this ZIP file also included a few calculator programs,
but these can now be picked up separately at the above site.


TOOLS NEEDED

To get started, you will need access to the QBASIC v1.1 interpreter.  Since
Microsoft provides it free on most DOS and Windows systems, you should have
it handy.  Sometimes, the folks who installed the operating system didn't
bother to install QBASIC.  If that happened to you, find it and install it.

Much of the really useful code is written here for use with the QuickBASIC
v4.5 compiler.  However, you can easily convert the QuickBASIC compiler code
for use with the free version of QBASIC, v1.1, by following instructions I
provide later.  You will need an editor of some kind for this, but both DOS
and Windows provides them.  DOS provides EDIT and Windows provides NOTEPAD,
at a minimum.


GETTING STARTED

To see if there is anything you are curious about, try running the floating
point demonstration routine.  Even if you aren't interested in seeing the
binary data for floating point numbers, the code demonstrates one version of
the expression evaluation code and can be run from QBASIC.  You can test out
the expression handling that way.

So, just enter:

  QBASIC /RUN FLOATQB

This will start up the program, too, if you use the /RUN option.  In any
case, the program will accept expressions like (1+3)*7, as well as simple
numbers.

If you want to try out the expression programs that handle numbers in
fractional form, you can use:

  QBASIC /RUN FRACALC

or

  QBASIC /RUN FRACALCV

These programs do not use the same expression evaluation routines, but they
demonstrate keeping fractions in their lowest terms using a greatest common
divisor function.  The first of these two, FRACALC, does not support the
use of variables, while the second of the pair, FRACALCV, does.

Take note of FLOAT.MAK, CALC.MAK, and CALCV.MAK.  These are special files
used by the editor environment for the compilers, such as QuickBASIC v4.5.
When you start up the compiler's editor with:

  QB FLOAT

the QuickBASIC editor will first read the FLOAT.MAK file to find a list of
source code files that it should automatically preload for you.  This helps
simplify things.  Please notice that the command isn't "QB FLOAT.BAS" -- if
you say it that way, the QuickBASIC editor will only read FLOAT.BAS and not
all of the files listed in FLOAT.MAK.

So if you have one of the compiler tools, you can use those files included
here that are designed for them.  This includes all of the files with the
extension, .BI, as well as the .BAS files listed in FLOAT.MAK, CALC.MAK,
and CALCV.MAK.  If not, read on for some general instructions on how to
edit them together in order to make your own QBASIC-compatible packages.

Good luck!


FILE LISTING

Here's the list of files in the package:

    readme.txt      Short description of the package (this file.)
    floatqb.bas     QBASIC version of FLOAT, designed as a stand-alone.
    float.mak       List of files needed for the FLOAT program.
    float.bas       Main FLOAT program used to display FP number formats.
    parse.bas       Equation evaluator subroutine package.
    parse.bi        Include file for the equation evaluator subroutines.
    variable.bas    Equation evaluator subroutine package, with variables.
    variable.bi     Include file for variable evaluator subroutines.
    hash.bas        String-to-hash number routines.
    hash.bi         Include file for string-to-hash number routines.
    table.bas       Symbol table management using hash values.
    table.bi        Include file for hashtabl.bas.
    fracalc.bas     A calculator program that is a hodge-podge I threw
                        together to demonstrate how to handle fractions.
    fracalcv.bas    Like fracalc.bas, except it supports variable names.
                        You can use g=5*4 on one line, then g*3 on the next.


PROGRAMS

The following are short descriptions about each of the modules and programs.
Often, I've neglected to provide adequate documentation on routines, and I
apologize for that.  However, there is a great deal of useful information in
the files and you can usually find much of what you need by seeing how I've
used a routine, elsewhere in the code.

For example, there is almost no documentation in HASHTABL.BAS.  Yet, it is
pretty important in handling fast look-up of variable names.  One of the
routines is called HTBL.Init.  It accepts three parameters and you can see
an example of its use in EVALVARS.BAS, where two numbers and an array are
specified in the call.  If you look closely, you'll see that the call looks
like:

  HTBL.Init MAXVARS, MAXHEAD, vartbl()

where MAXVARS = 1000 and MAXHEAD = 210.  With a little imagination, you may
realize that this means that the vartbl() should be initialized to handle a
maximum of 1000 variables (or symbol names.)

MAXHEAD is a little more complicated and requires a bit of understanding of
hash tables.  But if you set MAXHEAD to something about 2*SQR(MAXVARS) or
more, you'll be fine.  Of course, you don't know all this because I didn't
document it that much.  However, you can glean a bit from how I use it and
that will get you by.

Once again, I apologize.  But I hope you'll not find things too complicated
to follow with a little effort.  And you can always email me your questions.


  FLOAT PROGRAM

  You'll need a compiler tool to run it.  The command is:

    QB FLOAT

  The float program lets you try out and experiment with different
  floating point values.  It displays the internal storage in binary
  form and supports both IEEE and Microsoft's early binary format,
  in either 32-bit or 64-bit modes.  The program allows the use of
  algebraic expressions, too.

  The float program also helps demonstrate how the evaluate package
  might be used in a real application.


  HASH

  The HASH module simply converts an arbitrarily long string
  into a 32-bit hash code.  This module includes a "stirring
  table" to help make it more effective while still very fast.

  This is a library module.  So you'll need to write code that
  accesses the functions in order to use it.

  It is self-contained and doesn't depend on any other modules.


  TABLE

  The TABLE module provides generic support for managing hash
  tables.  It handles the addition of new entries and the
  searching for existing ones.

  This is a library module.  So you'll need to write code that
  accesses the functions in order to use it.

  It requires the use of the HASH module to operate.


  MISC

  The fracalc*.bas programs are not very cleanly designed --
  they use a state machine for parsing numbers and a recursive
  descent method for the rest of the expression, and another
  block of code to handle the fractional values.  The programs
  will handle 1/0 in fractional mode but will generate a fatal
  error in decimal mode from the same expression.  In short,
  the fracalc*.bas programs are less "professional" and more of
  a demonstration.


QBASIC INSTRUCTIONS

The programs, FLOATQB, FLOATV2, FRACALC, and FRACALCV can all be run from
QBASIC, without the need for a compiler tool to run them.  To run them,
just use:

  QBASIC /RUN FLOATQB
  QBASIC /RUN FLOATV2
  QBASIC /RUN FRACALC
  QBASIC /RUN FRACALCV

or the equivalent statements without the /RUN command line option.  The
other program systems, FLOAT, CALC, and CALCV can be used with QBASIC, but
not without changes.  That's because they use the $INCLUDE command which
isn't supported by QBASIC, but which is supported in the compiler tools.

If you want to try and make the compiler versions of these programs run
with QBASIC, you may.  I've already performed this trick for you, with
the FLOAT program system (defined in FLOAT.MAK).  It's been converted to
FLOATQB.BAS, which works under QBASIC and doesn't use $INCLUDE.

Just type out the contents of the .MAK file you are interested, for example,
the FLOAT.MAK file, which looks like:

  FLOAT.BAS
  PARSE.BAS
  VARIABLE.BAS
  TABLE.BAS
  HASH.BAS

This tells you that there are five BASIC source code files to merge.  Then
you need to copy FLOAT.BAS to a new filename, then append all of the sub-
routines and functions you find in the other modules into that new file.  You
should also take a look at the two source code files for $INCLUDE
statements.  Then test out the result.





Jon Kirwan
New World Computing Services
jkirwan@easystreet.com

    Creation Date:  Thu 22-Apr-1999 16:28:47
    Last Modified:  Thu 12-Aug-2004 18:21:53
