SparForte is written for GCC Ada (GNAT) and GCC C. Most of the
source files are Ada 95 but some are Ada 2005.
Ada source code is divided into modules called packages. Files with
an ".ads" suffix are package specifications: they contain the definitions
of the contents of the package which are visible to other modules.
Specifications are similar to C header files.
Files with ".adb" suffixes are Ada package bodies. They contain the
complete implementation of the package contents. These are somewhat like
".c" files in C.
Most of SparForte, except for the main program and C support files,
is all contained in Ada package files.
.orig Files
In order for configure to remove undesired feature, such as support for a
particular database engine, some files end with an ".orig" suffix. These
are the original files, the ones with full capability, before configure
removes any features. For example, parser.adb.orig is the complete version
of parser.adb.
When editing files that have a .orig version, make your changes to the
.orig version and then run configure to produce a new version of the file
to build SparForte. For example, to change parser.adb, edit parser.adb.orig
and then run configure to produce a new parser.adb.
Overall Project Structure
The SparForte package files can be divided up into 4 layers which build one
on top of another:
utilities - packages containing commonly used functions shared by
several packages
scanner - packages implement the lexical scanner. This part
of SparForte compiles the byte code, maintains the symbol table, and interprets
the script as a series of "tokens".
parser - packages that implement the SparForte features and check for
syntactic and semantic errors. This part of SparForte "runs" the script
and reports error messages.
main program - the procedure that runs when SparForte is started
(spar.adb)
Utility Packages
Loosely, utility packages contain commonly used functions shared by
other packages.
bush_os - the package containing a thin binding to your operating system.
For example, opening files, deleting files, creating pipes, operating system
error codes, etc.
When the configure script is run, these files are created by copying bush_linux,
or another bush_ file as appropriate for your operating system.
There are several child packages: support for the O/S terminal (bush_os.tty),
support for the SDL library (bush_os.sdl) and executing programs (bush_os.exec).
bush_alpha - bush_os for Linux on DEC Alpha computers
bush_cygwin - bush_os for the Cygwin system on Microsoft Windows computers
bush_freebsd - bush_os for FreeBSD operating system
bush_linux - bush_os for the Linux on i386/x86_64 systems
world - the symbol table and global type declarations
gen_list - a generic (template) package for single-direction linked
lists.
pen - the pen drawing package (uses SDL).
script_io - routines to read a script file
user_io - routines to read the keyboard and print to the screen.
Also implements the emacs and vi editing modes.
signal_flags - interface to the C signal handlers.
c_os - support functions written in the C language. In particular,
the signal handlers are written in C, and helper functions for graphics.
c_scanner - a function based on the GCC Ada source code dealing with the calendar, required by the SparForte calendar package.
Scanner Packages
jobs - runs an operating system command. That is, forks
off a separate process, sets up standard input, output and error, and starts
the command running. Also implements SparForte job control.
scanner - contains the main body of the scanner. Includes
identifier declarations, byte code compiler, tokenizing functions,
and error reproting.
scanner-arrays - the implementation of SparForte single-dimensional
arrays.
scanner-calendar - implementation of Ada.Calendar package.
(This is the GCC Ada calendar package with the time type as non-private
so it can be used from SparForte.)
scanner-calendar-latest.ads / scanner-calendar-pre441.ads /
scanner-calendar-pre431.ads / scan-cal-gnat314.ads - different
versions of the Ada.Calendar
package from different version of GCC Ada modified for use with SparForte.
"pre441", for example, means
the Calendar package prior to GCC 4.4.1. The configure script chooses
one and copies it to the name scanner-calendar
Parser Packages
builtins - implementation of built-in shell commands. That
is, "cd", "pwd", "history", "help" and so on.
parser - implements the core AdaScript language and any packages not
separated into another file (e.g. sound).
Handles syntax checking, running scripts and running commands at the SparForte
command prompt.
parser_arrays - implementation of the built-in arrays package.
parser_aux - utility functions soley for the parser. For example,
working with file_type variables, creating temp files and opening network
sockets.
parser_awk - implementation of the Gnat.Awk package (not implemented)
parser_cal - implementation of the built-in calendar package; interface
to scanner-calendar package.
parser_cgi - implementation of the built-in cgi package; interface
to the AdaCGI package
parser_cmd - implementation of the built-in command_line package,
interface to Ada.Command_Line
parser_db - implementation of the built-in db package; interface
to Warren Gay's APQ Postgres binding
parser_dirops - implementation of the directory_operations package;
interface to Gnat.Directory_Operations package
parser_enums - implementation of the built-in enums package,
interface to various Ada enumerated type features/packages
parser_files - implementation of the built-in files package
parser_lock - implementation of the built-in lock_files package,
interface to GNAT.Lock_Files
parser_mysql - implementation of the built-in mysql package; interface
to Warren Gay's APQ Postgres binding
parser_numerics - implementation of the built-in numerics package,
interface to various Ada numeric features/packages
parser_os - implementation of the built-in os package
parser_pen - implementation of the built-in pen package
parser_stats - implementation of the built-in stats package
parser_strings - implementation of the built-in strings package,
interface to various Ada string features/packages
parser_tio - implementation of the built-in Text_IO package,
interface to the Ada.Text_IO package.
parser_units - implementation of the built-in units package,
interface to various measurement conversion routines.
Main Program
spar - shows --help instrutions, interprets command line option
switches, invokes the SparForte parser
Third-Party Projects
SparForte has been built with some third-party source code included in the
release. Most of these projects are contained in subdirectories.