This directory contains the entire source to LEAP. Please bear in mind
that LEAP is now distributed under the terms of the GNU General Public
License, and you MUST read this.

You should have received a copy of the GNU General Public License
along with this program; if not, write to the Free Software
Foundation, Inc., 675 Mass Ave, Cambridge, MA 02139, USA.

A copy is provided in the file COPYING.

INTRODUCTION
After much deliberation, I have finally decided to release the source code under the terms of the GNU General Public License. This license gives you full access to the source code, and gives me the copyright that I need. Please make sure you have read the license to make sure you understand what is implied. It's written in a very clear fashion.

OK. Some explanation is needed about the release, but some more general information first.

The source code contained here is in version 7.0 Borland Pascal. I have recently undertaken to rewrite from the ground up, in 'C' (using the GNU C compiler), so development of this Pascal version is not going to be particularly active.

That's not to say I will not modify and improve the system. Pascal is a far better language for learning programming than 'C', it's just that I want LEAP to run on more systems, and Borland Pascal is tied to DOS/Windows. GNU 'C' however, is on practically every OS you care to name...

See the section on development and passing changes back for more information.

DEVELOPMENT
So you want to develop (Pascal) LEAP in some way. Great! Please feel free to do so. Several things though:

+ Make sure you comment well, others may use your code.
+ Pass changes back to me, so I can incorporate it in official releases.
+ Make sure you fully understand the GNU GPL, as by modifying it, you are agreeing to its terms.
+ Make sure you're not duplicating effort - Drop me an e-mail with your plans and ideas, and I'll let you know if anybody else is planning this. There will be a LEAP development mailing list soon, so drop a note to that as well. Check out the LEAP home page as well.

I'm particularly interested in the following fixes:

+ Bug fixes - Fixed problems.
+ Feature revisions - Reliability, performance etc. - Changes to the existing code that doesn't change functionality.
+ Feature additions - New features!

This release of the source code is the first - to get the code "out there". There is a fair bit of mess in the code, a fair few unused procedures and functions (especially in the tuples module).

STYLE
Programming style - Look at the existing code to get an idea for the general approach I use. Try to adopt the same approach - It'll make everybody's task easier.

+ I comment heavily, BEFORE the code it applies to. At least I try to. I aim for the following: Remove the CODE, and you're left with comments. You should be able to reconstruct the program from the comments. The commenting shouldn't be over the top, a line or two should suffice at each significant point. 

+ Look at the indentation. BEGIN...END blocks should match up in terms of indentation. I break out brackets where possible, and complex conditions, so it is easier to work out what is going on.

+ Naming convention:
Constants - Are generally CAPITALISED
Variables - Lower case, with underscores separating "words", or capitalisation of the first word, e.g. this_is_a_variable or thisIsAVariable - Don't use capitals in the first word.

COMMUNICATING MODIFICATIONS
Several means:
+ You can drop me a copy of the modified unit, and the version it was modified from (i.e. Beta 0.10.1 dated 22nd May)
+ Preferably though, a context diff of the change. A context diff is produced by the "diff" program in Unix machines. See diff(1) for information. If you don't have access to diff on Unix, don't worry.

When sending the changes, I will expect you to inform me what the change is. Imagine if I get a unit, "with changes", and don't know what has changed. I could find out eventually, but it's much better if you write a short summary that explains what you have done.

Please test the changes you make thoroughly. I will set up a regression testing suite at some point so that changes can be tested automatically.

PRE-HISTORY
LEAP was originally written as a final year undergraduate project. I took it from my submitted work, and made it more stable. Just so you know, a number of universities around the world, from France, England, New Zealand, and the US, are using LEAP as a tool for teaching databases.

I've received so many comments and requests for the source, that I've finally decided to make it freely available.

STRUCTURE
I won't go into too much detail about the structure of LEAP. I have written documentation, but need to spend a bit of time addressing it to bring it up to date. If you'd like a copy of the out of date (although still valid) documentation, drop me a note.

In the meantime however, here's a quick summary of LEAP structure. This is the Pascal structure. The 'C' version is different in some fundamental ways, but the main structure is similar.

LEAP revolves around the leap.pas unit. The main block is contained in the do_cli module, which takes a string, breaks it down into a few key sections, and calls operations. (The 'C' version parsers everything in the same place, in a two-stage manner, the Pascal version is uglier and less efficient, primarily because there are three parsing approaches).

Most of the operations are called from do_cli, but relational operators, which can contain nested expressions, are dealt with in one of three ways.

The best approach is the iterative approach, which builds a parse tree, and then "executes" it (the 'C' version builds on this substantially). The other approaches use recursion, and run into problems running natively under Windows 3.1 with its limited stack space.

There are a number of modules which abstract the implementation away from the specifics. "rtional" is the highest level, and implements the relational operators. This calls the various operations to access tuples, attributes and relations.

Note that I use the term "attributes", but the module is called "fields", I made this mistake early in the program development, and never got around to rectifying it. Its fixed in the 'C' version...

There is a hierarchy:

leap
rtional
tuples/fields/relations/dbase
dtypes

Utils sits off on the side and is called by all modules to perform various useful operations.

Tuples provides the conceptual "tuple", and allows data to be extracted from a relation. The principal operations are the readfirst and readnext tuple.

Fields and relations are accessed in a similair way, and provides an abstracted view of the relation's definition. 

Dbase is the hold all structure - Each "open" database has a structure in memory which points to the linked list that are the relations.

You probably get the picture - Walk through the program to see where things are happening.

The master database is always open, to facilitate access to the tiny data dictionary. The "use" command uses the relational operators, as it should do.

I'd like to go into more detail, but don't have the time at this stage. The LEAP documentation is very extensive, and will soon be available. 

If you have ANY questions AT ALL regarding the system, why I've done certain things, and so on, please drop me an e-mail, I'm only too happy to help! I'll incorporate question and answers into this document, until I release the program documentation.

