This text file offers a line-by-line explanation of the code found in uCalc.uc,
which is the default file that is loaded when you run uCalc.Exe for interactive
use of the interpreter.

Each line explanation is separated from the next with a ========= . . .
 

==============================================================================

uCalc Echo Error

uCalc Language Builder has no hard-coded keywords.  The uCalc Interpreter
has one hard-coded keyword, which is the word "uCalc" (not case sensitive).
And it is a keyword only if it appears as the left-most word on a new line
followed by a space.  Regardless of the language you have constructed, there
is a list of interpreter commands at your disposal, which you can invoke by
preceding the command with "uCalc".  This particular command causes the
interpreter to visibly display an error message if an error within the code
being loaded is found.


==============================================================================

uCalc LineContinue " _"

Here, we use the LineContinue command to set " _" as the line continuation term.
Throughout other files, you will find lines of code with " _" at the end, which
signifies that the next line should be interpreted as part of the same line.


==============================================================================

uCalc Syntax {CPP_Comment:"//.*"} ::=

This uses the Syntax command to define the "//" term as a comment delimiter.
This syntax consists of a pattern with a regular expression for "//" followed
by all the rest of characters up to the end of the line.  such a section of
code will be replaced with nothing, and will hence be ignored when parsed.
See Basic.Txt for more details on Syntax definitions.


==============================================================================

// In order for the interpreter to perform its first bootstrapping steps, the
// following keywords were defined in the .EXE itself, but can be undefined
// or re-defined as necessary (but with special care): Extended, String, Stack,
// ucAddr, uc_Push, InputBuffer, + (Infix), - (Unary). The only permanent
// keyword is uCalc when it's the left-most word followed by a space and data.
//
// Patterns, such as brackets, parenthesis, curly braces, quotes (single and
// double), etc... are also predefined.  Rather than undefine patterns, simply
// define a new set of patterns that match the needs of your language.  A new
// definition for a given pattern will have precedence over the older one.

These lines represent a comment that is ignored by the interpreter, based on the
definition from the previous section.  The comment itself is self-explanatory.


==============================================================================

uCalc define Rank: -1 ~~ syntax: {BASIC_Comment:"[\x27].*"} ::=

This line might not be here in the future.  But, it does the same thing for the
single quote character ' (which as a hex ASCII value of 27), as what we did for
// in order to make it represent a comment.  Instead of the more specific Syntax
command, here we used the more general Define command, which can include other
properties other than just a Syntax.  In this case we gave this syntax a rank
of -1, which is the lowest possible rank (1 is the highest).  The reason for
this is that, as mentioned in the previous section, the single quote character
is already defined as quote character, just like the double quote.  When
multiple items share the same name, the must have a priority rank.  All
patterns are ranked as well (separately from named items).  In general newly
defined items implicitly have a higher ranking the previously defined ones,
unless you explicitly supply a rank.  If we defined this line with the default
rank, the single quote as a comment character would overshadow the single quote
as a quoting delimiter.  With the way it's defined here, uCalc will first check
if a given single quote has a matching quote, in which case it will be
considered a quoted string, otherwise it will be considered a comment.

This line of code is not of much importance; only the concept behind it is. It
can be used in other kinds of situations.  Comment patterns are defined in
Basic.Txt in a cleaner way.


==============================================================================

uCalc syntax %{Const:"[^=]+"}={Val} ::= _
   uc_Push(InputBuffer, "ucalc define variable ~~ name:{Const} ~~ Value:{Val}")

This line defines a syntax that will allow the interpreter to read and define
the constants that are found in the ucalcpb.bas file.  These are PowerBASIC
style equates, which begin with the "%" character.  Each line consists of an
equate (constant) name, such as %MyConstant, followed by an equal sign, and
then a numeric value.  The % character is stripped from the constant name.

==============================================================================

uCalc Load "ucalcpb.bas" "" "' End Of Constants"

The load command opens a file and runs the code that is included there.  The
second and third parameters are optional.  However, if included, the second
parameter represents text found in the first line that the interpreter should
consider.  All lines prior to that one are ignored by the interpreter.  If
blank, as in this case, it simply starts at the beginning.  The third parameter
is the text of the last line the interpreter should consider.  When it reaches
a line that matches that text, it closes the file and stops retrieving code from
it at that point.  So everything after that line is ignored.


==============================================================================

uCalc Load "Errors.uc"

This loads the contents of the Errors.uc file.  Here, and in the subsequent
lines, the optional starting and ending parameters are omitted.  So the entire
file is executed.

This file sets the text for error messages.  Should you wish to translate these
error messages to a different language, or to append your own list of error
messages, you can simply modify that file with any text editor.


==============================================================================

uCalc Load "Types.uc"

This loads a default set of data types.  You are free to rename or delete them,
modify their properties, or to add your own types to the list.  Fundamental
types, such as Single, Double, or Extended precision, and the various integer
types, are associated with callback routines.  These are included in a default
library that is part of the uCalc DLL.  You can construct your own data type
handlers in the same manner, and compile them into a DLL for use with uCalc.
See the help file for more details.

==============================================================================

uCalc Load "Define.uc"

As mentioned earlier, uCalc Language Builder has no built-in keywords.  It has
no syntax, functions, operators, or special symbols that it recognizes.  It has
no constructs for defining such things either.  What it does have is a small
bootstrapping language, with which you can build a language with all of the
functions, operators, and constructs you need.  There is a separation between
the bootstrapping language, and your language, so that the keywords used in
the bootstrapping language will not interfere with your language (on the other
hand, you can add things that will be recognized by the bootstrapping language).

Define.uc contains early-stage bootstrapping constructs for defining primitive
functions, operators, and variables, with which files listed further down can
define such items, on top of which you can later define more sophistacated
constructs.


==============================================================================

uCalc Load "WinAPI.uc"

This file contains a small number of Windows API routines, with which the
interpreter can define key items like print and message box statements, console
input, Cls, and things of that nature.


==============================================================================

uCalc Load "Library.uc"

Although uCalc Language Builder starts with no functions, operators, or
constructs, the uCalc DLL does come with a library of ready-made fundamental
functions, operators, data type handlers, and the like, which you can pick from
so that you don't have to build everything from scratch.  The Library.uc file
picks items that are deemed useful as a general starting point useful for
various kinds of languages one may want to construct.  You are free to remove,
modify, or add to the library.


==============================================================================

uCalc Load "Interp.uc"

This file loads things relating to the interactive use of the interpreter.


==============================================================================


uCalc Load "Help.uc"

This file creates a table of help messages, so that you can type the word HELP
followed by a keyword to get more information on that item.  [+++ Incomplete.
Though you can add items manually, ideally a construct would automatically add
definitions to the table whenever an item is defined].


==============================================================================

// End of file

This comment line is not required.  It is simply a visual place marker.
