@c -*-texinfo-*-
@node Overview, Builtin Predicates, Top, Top
@comment  node-name,  next,  previous,  up
@chapter Overview 

@menu
* Introduction::                Introduction 
* CommandLine::                 Command line Options 
* Startup::                     Startup 
* Syntax::                      Syntax 
* Notation::                    Notation 
@end menu

@node Introduction, CommandLine,  , Overview
@comment  node-name,  next,  previous,  up
@section Introduction 
ICP is an Edinburgh style prolog based on the 
WAM. In addition it includes the following special features.

@table @code
@item threads
ICP allows multiple threads in a single process. This allows the solving
of multiple goals in pseudo parallel, achieved through the use of
pre-emptive time-slicing.
@item parlog
ICP includes a parlog engine. A parlog thread can be started and
facilities are provided for parlog to call prolog and vice versa.
@item Logic & Objects
Logic & Objects is a object-oriented layer on top of Prolog.
@item TCP
A TCP interface allows for the communication between processes over a
communication network.
@item Mailboxes
Mailbox is a high-level communication model that is simple and yet has
many more features than TCP.
@item user-defined error handling
Users may define their own procedures for handling and recovering
from errors.
@item user-defined file types
Users may define their own file types and then supply hooks for reading
and transforming terms in those files.  This is a generalisation of
term expansion.
@end table

Source files are assumed to have the
suffix `@file{.pl}' while compiled files have the extension
`@file{.icp}'. Built in predicates dealing with these files will
automatically append these extensions to files if they are not present.

@node CommandLine, Startup, Introduction, Overview
@comment  node-name,  next,  previous,  up
@section Command line Options 

@cindex command line
@table @file
@item -s Stack
The initial size of the stack can be specified.  The unit is K-cells, with
the default being 16 (K-cells); e.g. to double the size of the stack,
specify `-s 32'.
@item -h Heap
The initial size of the heap can be specified.  The unit is K-cells, with
the default being 48 (K-cells); e.g. to double the size of the heap,
specify `-h 96'.
@item -f File
Uses file @code{File} (instead of default ~/icp.pl) as the startup file
for Prolog component of ICP.
@item -ff File
Uses file @code{File} (instead of default ~/icp.par) as the initialisation
file for Parlog component of ICP.
@item -n
Skips Prolog startup file processing; i.e. does not read ~/.icp.pl.
@item -nn
Skips Parlog startup file processing; i.e. does not read ~/.icp.par.
@item -z String
@code{String} is executed by Prolog at startup time.
@item -zz String
@code{String} is executed by Parlog at startup time.
@item -F Charset
@code{Charset} may be one of `latin1' (default), `greek' or `mac'.  This
defines the character encoding which categorizes characters into upper case,
lower case or graphic characters.  This is used to determine variable names
(beginning with upper case) and unquoted atoms (all lower case).
@item -b File
Allows the selection of an alternative boot file. The boot file
determines which system files are loaded at start up time and initialises
the system.  This option is rarely used.
@end table

@node Startup, Syntax, CommandLine, Overview
@comment  node-name,  next,  previous,  up
@section Startup 

@cindex startup
@cindex :- commands
@cindex ?- commands
When ICP is started it looks for the file @file{$HOME/.icp.pl} which
if found is consulted.  This is commonly used to declare operators,
load specific foreign code or prolog libraries.  Lines of commands to
be executed at startup time should be preceded by `:-' or `?-'.  `:-'
and `?-' commands may be scattered throughout the file, but the
behaviour is as if all the `:-' commands (in the same order) are at
the start of the file and all the `?-' commands (in the same order)
are at the end of the file.  The clauses in the body of the file are
asserted into the dynamic database.  Commands that write output
should specify the stream explicitly and not to rely on the default
current output stream.

After the startup file has been processed, the commands passed from the
command line through -z options are executed.

When the parlog sub-system is started up, it goes through
a similar process using the
startup file @file{$HOME/.icp.par} and the -zz options.  Parlog may
be started up in many ways - in the @file{$HOME/.icp.pl}, as a -z command
line option, or as a Prolog query.

@node Syntax, Notation, Startup, Overview
@comment  node-name,  next,  previous,  up
@section Syntax 

@cindex syntax
The syntax of ICP is compatible with Quintus Prolog
@footnote{Quintus is a trademark of Quintus Computer Systems Inc., USA}
@cite{Quintus Prolog Development Environment}, Quintus Computer Systems,
Inc., Mountain View, California, USA.

@menu
* Integers::                    Integers 
* FloatingPoint::               Floating Point Numbers 
* Atoms::                       Atoms 
* Variables::                   Variables 
* Tuples::                      Tuples 
* Lists::                       Lists 
* CharacterEscaping::           Character Escaping 
@end menu

@node Integers, FloatingPoint,  , Syntax
@comment  node-name,  next,  previous,  up
@subsection Integers 

An integer consists of a sequence of digits optionally preceded by a
minus sign @samp{-}.  These are normally interpreted as base 10
integers.  It is possible to enter integers in other bases (2 through
36).  To enter an integer
in a base other than 10, first enter the base in decimal, followed by an
apostrophe (@samp{'}) and then the string of digits.  If a base greater
than 10 is used, the characters @samp{a}-@samp{z} or @samp{A}-@samp{Z}
are used to stand for digits 10 through 35.  For example:
@example
	8'21	= 17 decimal
	16'FF	= 255 decimal
	36'Z	= 35 decimal
@end example

As a special case, base 0 allows characters to represent their ASCII
codes.  Examples:
@example
	0'A	= 65
	0'[	= 91
@end example

@node FloatingPoint, Atoms, Integers, Syntax
@comment  node-name,  next,  previous,  up
@subsection Floating Point Numbers 

A floating point number consists of a sequence of digits with an
embedded decimal point (@samp{.}), optionally preceded by a minus sign
(@samp{-}) and optionally followed by an exponent consisting of an upper
or lower case @samp{e} and a signed base 10 integer.  Note that there
must be at least one digit before, and one digit after, the decimal
point.

@node Atoms, Variables, FloatingPoint, Syntax
@comment  node-name,  next,  previous,  up
@subsection Atoms 

An atom may take any of the following forms:

@enumerate
@item
A sequence of alphanumeric characters (including underscore), starting
with a lower case letter
@item
A sequence of one or more characters from the set: @kbd{# $ & * + - . /
: < = > ? @ \ ^ ` ~}
@item
A sequence of characters delimited by single quotes (@samp{'}).  If the
single quote character is included it must be written twice.
@item
the special atoms @code{!} @code{;} or @code{@{@}}
@end enumerate

@node Variables, Tuples, Atoms, Syntax
@comment  node-name,  next,  previous,  up
@subsection Variables 

A variable is a sequence of alphanumeric characters (including
underscore) starting with a capital letter or an underscore (@samp{_}).
Variables which only occur once in the clause are called anonymous
variables and may be written as an underscore on its own.

@node Tuples, Lists, Variables, Syntax
@comment  node-name,  next,  previous,  up
@subsection Tuples 

A tuple is written as functor (which may be any term), followed by a
left bracket @samp{(}, followed by 0 or more comma separated terms,
and ending with a right bracket @samp{)}.  Note that the functor is
not limited to being an atom as in the case of Quintus Prolog.  There
must be no whitespace characters between the functor and the left
bracket.  The following are valid ICP tuples:
@example
        foo(X)
        bar()
        3(a,b,c)
        Var(foo,bar)
        person(john,33)(X,Y,Z)
@end example

Note that a tuple with 0 arity is not the same as the functor by itself i.e.
@code{X() = X} fails.

Atomic functors may be declared as operators which would allow the tuple
to be written without the brackets.  Operators may be declared to be
prefix, postfix or infix.  Infix operators can be further defined as
none, left or right associative.

@node Lists, CharacterEscaping, Tuples, Syntax
@comment  node-name,  next,  previous,  up
@subsection Lists 

A list is just a shorthand notation for `@code{./2}' tuples.  A list is
written as a left square-bracket @samp{[} followed by 0 or more comma
separated terms and ending with a right-square bracket @samp{]}.  The
list may also be written in `@code{./2}' notation.  e.g. @code{[1,2,3]}
unifies with @code{.(1,.(2,.(3,[])))}.  For convenience, a list of ASCII
codes may be written as a string delimited by double-quotes (@samp{"}).
e.g.  @code{"ABC" = [65,66,67]}.  To include the double-quote character
in the string, it must be written twice.

@node CharacterEscaping,  , Lists, Syntax
@comment  node-name,  next,  previous,  up
@subsection Character Escaping 

In quoted atoms, double-quote delimited lists or base 0 notation, escape
sequences can be used to denote characters.  This is used to avoid
ambiguity and to enter unusual characters.  ICP has the
following escape sequences:

@table @code
@item \a
alarm/bell (ASCII 7)
@item \b
backspace (ASCII 8)
@item \t
tab (ASCII 9)
@item \n
newline (ASCII 10)
@item \v
vertical tab (ASCII 11)
@item \f
formfeed (ASCII 12)
@item \r
carriage return (ASCII 13)
@item \e
escape (ASCII 27)
@item \s
space (ASCII 32)
@item \d
delete (ASCII 127)
@item \<octal string>
the character with ASCII code @kbd{<octal string>}
base 8.  e.g. @code{\007} is the
bell character and @code{\040} is the space character (ASCII 32).
@item \^<control char>
the character whose ASCII code is the @kbd{<control char>} mod 32.
e.g. @code{\^P} is @kbd{@key{CTL}-P}.
@item \<layout char>
no character, where @code{<layout char>}
is a character with ASCII code
=< 32 or >= 127.  This is most useful when
splitting atoms over two
lines where the ignored newline character is preceded by a backslash.
@item \c
no character, also all characters up to, but not including,
the next
non-layout character are ignored.
@item \<other>
the character @kbd{<other>}, where @code{<other>} is
any character not defined above.
@end table

@node Notation,  , Syntax, Overview
@comment  node-name,  next,  previous,  up
@section Notation
@cindex notation

@cindex predicate specification
Built-in predicates are introduced with a template such as
@strong{bag_of}(@var{?X}, @var{+Goal}, @var{-Set}) where @var{X},
@var{Goal} and @var{Set} are the arguments. The significance of the
leading characters is as follows.

@table @kbd
@item +
The argument is a (non variable) input.
@item -
The argument is an output. The output value is unified with the original
value.
@item ?
The argument is neither of the above. This might be because the argument
can be used both as an input and as an output argument, or because while
the argument is an input, it can be an uninstantiated variable.
@end table

Often, a tuple or predicate is represented by the term @var{Name/Arity},
where @var{Name} is the function symbol and @var{Arity} is the number of
arguments of the term.
@example
        Term            Representation
        ----            --------------
        foo(X,Y)        foo/2
        bar             bar/0
        not Goal        not/1
        1+2             +/2
@end example

