=============================================================================
%% Iniquity Programming Language - (c)Copyright 1996 Mike Fricker
%% Preliminary IPL Documentation [v1.00 alpha]
=============================================================================
[ UNFINISHED !! ]
%[ Source Comments ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
Comments are just areas of source code that the compiler ignores. Commenting
your code is a good idea if you indend on anyone else working with it. It
can also be useful for 'blocking out' an area of source code temporarily for
debugging, etc. IPL has several ways of commenting code:
Enclose comments in "|" (pipe) characters. These types of comments can span
multiple lines of source. Any text in between pipes is ignored.
Any text after a "%" (percent sign) on that line is ignored by the compiler.
Any text after a "#" (number sign) on that line is ignored by the compiler,
but the # symbol MUST be the first character on the line (full line comment).
Some examples of commenting:
| This is an enclosed comment.
It can span multiple lines, and is useful
for blocking out source code for debugging. |
# here is an example of a line comment.
# the next line contains a partial line comment ..
@ int x = 10 % declare integer x and assign it 10 ..
IPL supports imbedded comments, that is, comments planted in the middle of
expressions. This isn't a very pretty way to comment source, but it works.
%[ Blocks ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
A block is a clause of statements grouped together. Each IPL block begins
with a "{" (open brace) character and ends with a "}" (close brace). It is
possible for a block to be empty and not contain any statements.
Each IPL program begins with a "{" character, which initializes the main
module block. Execution continues until the final "}" block terminator is
reached (if the module hasn't been prematurely terminated). An infinite
number of blocks may reside within the main block.
All procedures, functions, loops and conditional statements spawn blocks.
(Note that in some cases where there is only 1 statement, the open/close
brace characters are not necessary - as with the for/if/while commands.)
See also the @ reserved word for information on how variables are carried
through parent/child blocks.
%[ Data Types ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
These are the built-in IPL variable data types.
identifier size description
---------- ---- -----------
bool 1 true/false (1/0)
byte 1 ordinal number (0..255)
short 1 ordinal number (-128..127)
word 2 ordinal number (0..65535)
int 2 ordinal number (-32768..32767)
long 4 ordinal number (-2147483648..2147483647)
real 6 extended number (2.9^-39..1.7^38)
str 256 an array of characters (1-255), str#0 = length of str
file n/a used as a file handle reference only
%[ Reserved Words ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
These are the built in IPL commands. Each is explained below with full
syntax information. Note that although it is possible to create variables or
functions with reserved word names, the built in IPL reserved words will
always override existing identifiers. So be careful not to conflict.
@ (variable declaration)
~~~~~~~~~~~~~~~~~~~~~~~~
syntax: @ [ = ]
or: @ , [ = ], ...
Use the @ character to create new variables in the current block. Variables
created in parent blocks will exist in all child blocks (loops, ifs, etc) of
that block. When the block that the variable originated in is completed, the
variable is terminated (memory occupied by it is restored). IPL defalts to
initializing the variables contents to 0's (ascii0/null).
must be one of the built in IPL variable types. is the
identifier name for the variable. It must not conflict with the name of a
variable that may already exist at that point (the compiler will notify you
when duplicate identifiers are declared). You can specify many identifiers
in one declaration, and (for most types) an initial value for the variable.
The @ keyword is fairly flexible; here are some examples:
@ int x % declares an integer "x"
@ byte num = 10 % declares a byte "num" and sets it to 10
@ str filename = "this.txt" % declares a string "filename" and inits it
@ int a, b, c = 10 % creates vars a, b and c, and assigns them 10
@ file myfile % initializes file handle "myfile"
@ bool done = false % declares boolean variable "done" as false
You can actually use any expression applicible to that type after the =. In
many programming languages, you can only pre-init variables with constants or
built in operations. In IPL you can use any available routines in your var
declaration. Also, IPL allows you to declare variables ANYWHERE in your
module. You are not restricted to define them all at the top of each block,
although it is usually more organized that way.
proc (procedure/function declaration)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
syntax: proc [ : ] { ... }
or: proc "[" [+] [, ...] "]" [ : ] { ... }
This command creates a procedure or function in the current IPL module block.
The major difference between a procedure and a function is that a function
returns a value. The syntax for the proc reserved word seems complex, but
really its simple:
The first is the identifier name for the function. Next comes the
(optional) procedural parameters. After the parameter type an identifier is
required for that parameter. Multiple variables of the same type may be
created by separating the identifiers by commas (","). Multiple types can
be separated with colons (":").
Examples:
proc Hello { % procedure
outln["Hello world!"] % writes: Hello World!
}
proc IsSysOp : bool { % function
IsSysOp = userNum = 1 % returns true if user is the sysop
}
%[ Function Reference ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
This is a list of built-in IPL functions. Function identifier lists are in
order of subject. Detailed function information is below.
============================================================( output )=======
out - display a string of text
outln - display a string of text (w/ linefeed)
clrscr - clear the screen (or text window) with current attribute
clreol - clear from current column to end of line w/ current attr
beep - make an audiable 'beep' sound
cout - display a string of text; interprets color control codes
coutln - display a string of text w/ linefeed; interprets color codes
dnln - move down lines with linefeed
gotoxy - move cursor to specified screen position
posup - move cursor up specified number of rows
posdown - move cursor down specified number of rows
posleft - move cursor left specified number of columns
posright - move cursor right specified number of columns
posx - move cursor to the specified column, w/o changing rows
posy - move cursor to the specified row, w/o changing columns
setback - change background text color
setfore - change foreground text color
setblink - set blinking attribute on/off (or bright background)
============================================================( multinode )====
nodegetstatus - returns activity string for current node
nodestatus - set the activity string for the current node
%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
5.01 - output routines
~~~~~~~~~~~~~~~~~~~~~~
Note that (unless specified) ALL output functions operate on both the remote
AND local consoles simutaneously. The 'remoteout' variable can be used to
toggle remote display.
out - display a string of text
=============================================================================
syntax: proc out[str text]
params: text - String to display
notes: Displays text on both the remote and local end, with NO linefeed.
No control or MCI codes are processed.
example: out["Hi!!"]
see also: outln
-----------------------------------------------------------------------------
outln - display a string of text (w/ linefeed)
=============================================================================
syntax: proc out[str text]
params: text - String to display
notes: Displays text on both the remote and local end, with a CR/LF
appended to the end. The cursor will go down to the next line,
and the window will scroll is necessary. No control or MCI codes
are processed.
example: outln["Hello world!"]
see also: out
-----------------------------------------------------------------------------
clrscr - clear the screen (or text window) with current attribute
=============================================================================
syntax: proc clrscr
notes: Remember that this clears the screen with the current attribute,
so if you're expecting a black background color, make sure that
the current color attribute has a black background.
example: setback[1] % set background color to blue
clrscr % wow! now we have a blue screen background
see also: clreol
-----------------------------------------------------------------------------
clreol - clear from current column to end of line w/ current attr
=============================================================================
syntax: proc clreol
notes: This does NOT do any scrolling. See the clrscr function for notes
on color attributes.
example: gotoxy[1,10] % move cursor to 1, 10
clreol % erase the line
see also: clrscr
-----------------------------------------------------------------------------
beep - make an audiable 'beep' sound
=============================================================================
syntax: proc beep
notes: You won't hear this locally if the sysop-available flag is off and
sound restriction is enabled (Iniquity filters beeps).
example: beep % complicated, huh?
see also: ??
-----------------------------------------------------------------------------
cout - display a string of text; interprets color control codes
=============================================================================
syntax: proc cout[str text]
params: text - String to display
notes: Only color-related control codes are interpreted in the string (ie
|00-|23, |U0-|U9, |B0-|B7), all other control or MCI codes are
left alone.
example: cout["|01blue |02green |03cyan |04red"]
see also: coutln
-----------------------------------------------------------------------------
coutln - display a string of text w/ linefeed; interprets color codes
=============================================================================
syntax: proc coutln[str text]
params: text - String to display
notes: Appends a CR/LF to the end of text. See the out function for
scrolling rules. Only color-related control codes are interpreted
in the string (ie |00-|23, |U0-|U9, |B0-|B7), all other control or
MCI codes are left alone.
example: coutln["|u1 - user textcolor |u4 - user infocolor"]
see also: cout
-----------------------------------------------------------------------------
dnln - move down lines with linefeed
=============================================================================
syntax: proc dnln[byte lines]
params: lines - Number of linefeeds to output
example: outln["example of dnln routine"]
dnln[2] % skip 2 lines
outln["wow! we're down here now."]
see also: ??
-----------------------------------------------------------------------------
gotoxy - move cursor to specified screen position
=============================================================================
syntax: proc gotoxy[byte x, y]
params: x - Screen column to move cursor to
y - Screen row to move cursor to
notes: x and y are 1-based. 1 is the top row/column, 25/80 is the bottom
row/column.
example: gotoxy[40,12] % move cursor to middle of screen
see also: posup, posdown, posleft, posright, posx, posy
-----------------------------------------------------------------------------
posup - move cursor up specified number of rows
=============================================================================
syntax: proc posup[byte rows]
params: rows - Number of rows to move cursor up
example: posup[2] % move cursor 2 rows up, without changing columns
see also: posdown, posleft, posright, gotoxy, posx, posy
-----------------------------------------------------------------------------
posdown - move cursor down specified number of rows
=============================================================================
syntax: proc posdown[byte rows]
params: rows - Number of rows to move cursor down
example: posdown[4] % move cursor 4 rows down, without changing columns
see also: posup, posleft, posright, gotoxy, posx, posy
-----------------------------------------------------------------------------
posleft - move cursor left specified number of columns
=============================================================================
syntax: proc posleft[byte columns]
params: columns - Number of columns to move cursor left
example: posleft[10] % move cursor 10 spaces left, without changing rows
see also: posdown, posup, posright, gotoxy, posx, posy
-----------------------------------------------------------------------------
posright - move cursor right specified number of columns
=============================================================================
syntax: proc posright[byte columns]
params: columns - Number of columns to move cursor right
example: posright[8] % move cursor 8 columns right, without changing rows
see also: posdown, posup, posleft, gotoxy, posx, posy
-----------------------------------------------------------------------------
posx - move cursor to the specified column, w/o changing rows
=============================================================================
syntax: proc posx[byte x]
params: x - Column to move cursor to (1-80)
example: posx[40] % move cursor to the middle of the screen
see also: posdown, posup, posleft, posright, gotoxy, posy
-----------------------------------------------------------------------------
posy - move cursor to the specified row, w/o changing columns
=============================================================================
syntax: proc posy[byte y]
params: y - Row to move cursor to (1-25 or 1-50)
example: posy[2] % move cursor to 2nd row, same column
see also: posdown, posup, posleft, posright, gotoxy, posx
-----------------------------------------------------------------------------
setback - change background text color
=============================================================================
syntax: proc setback[byte bgcolor]
params: bgcolor - Background color (0-7 or 0-15)
notes: See Appendix A for more information on text color attributes.
example: setback[4] % change the background color to red
out["whoah, red!!"]
see also: setfore, setblink, setcolor
-----------------------------------------------------------------------------
setfore - change foreground text color
=============================================================================
syntax: proc setfore[byte fgcolor]
params: fgcolor - Foreground color (0-15)
notes: See Appendix A for more information on blinking with backgrounds
example: setfore[12] % change the foreground color to bright red
setblink[true] % enable blinking
out["WARNING !!"]
see also: setback, setblink, setcolor
-----------------------------------------------------------------------------
setblink - change foreground text color
=============================================================================
syntax: proc setblink[bool blink]
params: blink - Enable or disable blinking/hivideo backgrounds
notes: See Appendix A for more information on text color attributes.
example: setfore[14] % change the foreground color to yellow
out["yellow!"]
see also: setback, setfore, setcolor
-----------------------------------------------------------------------------
setcolor - change foreground and background color
=============================================================================
syntax: proc setcolor[byte fgcolor, bgcolor]
params: fgcolor - Foreground color (0-15)
bgcolor - Background color (0-7 or 0-15)
notes: See Appendix A for more information on text color attributes.
example: setfore[10] % change the foreground color to bright green
setback[2] % set background color to green
out["whoah."]
see also: setback, setfore, setblink
-----------------------------------------------------------------------------
5.05 - multinode routines
~~~~~~~~~~~~~~~~~~~~~~~~~
nodegetstatus - returns activity string for current node
=============================================================================
syntax: proc nodegetstatus : str
returns: Current status string or an empty string if the BBS is not in
multinode mode
example: @ str activity = nodegetstatus
see also: nodestatus
-----------------------------------------------------------------------------
nodestatus - set the activity string for the current node
=============================================================================
syntax: proc nodestatus[str status]
params: status - New node activity string (limited to 50 characters).
notes: Updates the NODEINFO.DAT file immediately with the new activity
string. Does nothing if the BBS is not in multinode mode.
example: nodestatus["Entering a oneliner"]
see also: nodegetstatus
-----------------------------------------------------------------------------
%[ Appendix A - Color attributes ]%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
=============================================================================
These are the default textmode colors. When blink mode is enabled, only the
first 8 (0-7) may be used for text background colors. Any color may be used
for a foreground attribute.
0 black 1 blue
2 green 3 cyan
4 red 5 magenta
6 brown 7 light grey
8 dark grey 9 light blue
10 light green 11 light cyan
12 light red 13 light magenta
14 yellow 15 white