GEMini Atari/GEMini_Atari_CD-ROM_Walnut_Creek_December_1993.iso/files/language/xprolog/xprolog.doc

Text File | 1987-10-12 | 24.9 KB | 806 lines

            X Prolog Vers. 2.0

    This software is copyrighted by Andreas Toenne.
    It may be copied free of charge iff this copyright notice
    is left at it's place.

    Andreas Toenne
    Computer Science Department
    University of Dortmund, W-Germany

    E-mail :
        [e-mail]
        [e-mail]
        ...!seismo!unido!atoenne


    ***********************************************************

    Note ! This manual is just a quick hack to make Xprolog
    available as fast as possible.
    Sections that are missing are stated in '<' and '>'
    Xprolog follows mostly the Cprolog standard, thus the
    Cprolog manual could be of some help to the novice user

    ***********************************************************


    1. Getting started.

    This program was developed with the Mark Williams C-Compiler Vers. 2.0
    It was designed to live on a hard disk!
    To start Xprolog simply double click xprolog.ttp without arguments.
    Xprolog will try to read it's default image as : C:\BIN\PBOOT
    If you don't have this directory or wish to start with another
    image, enter the name as an argument for Xprolog.
    You may set the enviroment variable BOOTFILE as well.

    1.1 Booting XProlog

    If you start Xprolog for the very first time, you must create
    your own image.
    This is done by calling Xprolog with the option -b.
    Make sure that the bootfile _boot is present in the current directory.
    You may save the image with 'save(Imagename).' then.

    1.2 Options

    You can specify the sizes of the various data areas with the
    following options. The new size must be given in bytes.

    -p<size>     prototype space
    -f<size>    functor space
    -r<size>    number of rules (not bytes!)
    -c<size>    copystack
    -s<size>    THE STACK
    -t<size>    trailstack

    The builtin predicate 'statistics' shows the current sizes of
    all data areas.

    1.3 General

    The enviroment variable SHELL may be set if you don't have
    msh.prg    or want to specify another shell.  (cf.  'system', 'sh')
    <Control>C may be pressed anytime during computation.
    Xprolog performs an abort then. (cf. 'abort')

    1.4 Explanation of Data Areas

    Prototype: a term in a prolog program
    Prototype space: contains all prototypes. Forms a heap.
    Rule space: contains descriptors for prolog rules. (clause space)
        The rule's terms are kept in the prototype space.
    Functor: general descriptor for prolog terms. Contains the name, arity
        optional operator definitions and a link to it's rules.
        Functors are kept in an avl-tree.
    Copystack: keeps copies of prototypes. Grows during unification and
        shrinks only upon backtracking.
    THE STACK: keeps the computation data that makes up the resolution
        tree. Highly dynamic !!
    Trailstack: keeps trails (references) for variables that must be
        preserved for backtracking. Usually very small.

    1.5 Limitations and Default Values

    - max. 20 arguments in a term
    - max. 50 variables (without anonymous) in a prototype term
    - max. 15 open streams
    - the reader can read terms upto 8000 bytes
    - max. 256 characters in a name
    - the cpu stack is 32000 bytes wide

    - default shell is 'c:\bin\msh.prg'
    - default bootimage is 'c:\bin\pboot'
    - default prototype space size is 30000 bytes
    - default copystack size if 50000 bytes
    - default STACK size is 50000 bytes
    - default trailstack size is 800 trail entries
    - default number of clauses is 1000
    - default functor space is 30000 bytes

    2.0 Error Handling and Debugging

    2.0.1 Fatal Errors

    Fatal errors are :
    - not enough memory
    - prototype space overflow
    - missing main goal to start the machine
    - main goal has stopped
    - clause space overflow
    - missing error goal, iff an recoverable error happens
    - functor space overflow
    - bad data during boot phase
    - invalid prolog image

    Fatal errors print an message and terminate Xprolog.

    2.0.2 Lesser Errors

    These are :
    - STACK overflow
    - Trailstack overflow
    - Copystack overflow

    These errors cause an abort of the current goal. (cf. 'abort')
    They are usually caused by an loop or by generally insuffient memory.

    2.0.3 Recoverable Errors

    Recoverable Errors are counted as :
    1. Unknown clause.
    2. IO failure.
    3. Read past EOF.
    4. Bad syntax.
    5. Too many args/vars.
    6. Bad arguments.
    7. No valid expression.
    8. User break. (control)C

    Except error 1 these error are caused by builtin predicates.
    They have the following meanings :

    1. The current goal refers to an unknown clause. This is normaly due
       to a typo or an incomplete program.
    2. Some sort of general nastiness. Watch out !!
    3. If a read, get, etc. hits the end of the current input stream,
       it's argument will be unified with 'end_of_file'.
       Note ! This differs from other prolog implementations.
       If the programs attemps to read from this stream again, error 3
       is the result.
    4. This error is due to bad syntax in an prolog term.
       Look at the detailed error description of the reader.
    5. Xprolog has hard coded limitations for the number of arguments
       of a term and the number of variables in a prototype term.
       See section 1.5 'Limitations and Default Values'
    6. The arguments failed the parameter check for builtins.
    7. The user typed <control>C

    When an recoverable error occurs, a new goal is set up.
    This is 'error(NumberOfTheError, GoalThatCausedTheError)'.
    The clause error should normally print a message on the screen and
    fail. However it is possible to correct the error and succeed then.
    (Note that error 1 should always lead to a failure)

    2.1 Debugging Predicates

    There are few of them right now.
    'debug' switches tracing on.
    'nodebug' switches tracing off.
    'leash(Value)' sets the amount of tracing data.
    The initial value after debug is switched on is 'half'.
    The following leash modes exists :
    - full    trace on call, retry, exit and fail
    - tight    trace on call, retry and fail
    - half    trace on call and retry
    - loose    trace on call
    - off    no trace

    < it is assumed that the reader is familiar with the procedure >
    < box control flow model. cf. the prolog primer by Clocksin and >
    < Mellish >

    3. Reader and Syntax

    <far too short>

    Generally the reader expects every goal and every program term
    to be finished by a dot and a new line!

    To read a prolog program (not an image), you should type
    'consult(filenameinsinglequotes).'
    If you want to read several files you can shorten the command to
    '[filename, filename, ...].'. (cf. list syntax)
    The goal 'reconsult(filenameinsinglequotes)' rereads clauses.
    That means it abolishes the old clauses before asserting them
    from the file. (cf. 'abolish' and 'assert')
    The same effect is achieved by preceeding the filename in the
    short notation by a '-'.
    A special file (cf. IO predicates) is 'user'. This stands for
    the terminal.

    When Xprolog is in the top level loop, it reads goals from
    the terminal and tries to satisfy them.
    When Xprolog consultes a file, it reads terms and tries to assert
    them. You can execute goals by preceeding them by ?- or :- .
    The only difference between ?- and :- is, that :- generates no
    answer (ie. 'no' or 'yes') and no alternatives are tried.

    3.1 Prolog Syntax

    3.1.1 Terms

    Terms are
    - constants
    - variables
    - structures (generally known as compound terms)

    Constants are
    - integers    (all natural numbers that fit in two machine words)
    - atoms        (actual atoms are structures without arguments)
    The name for an atom must start with a lowercase letter and may
    contain any letter, digit and the '_'.
    If you want to use any character, you should enclose the name in
    single quotes.
    < there are some special 'standalone' character which form a >
    < valid name. cf. CM 'Programming in Prolog' >

    Variables must start with an uppercase letter or with an '_'.
    If you need a variable only once, you may use the anonymous
    variable '_'.

    Structures comprises of a functor and a sequence of terms, it's
    arguments.
    A functor is characterised by the name and the arity.
    (Number of arguments)
    The sequence of terms must be written comma seperated in round
    brackets. eg. testfunctor(first, second, third).

    3.1.2 Lists

    As lists are the most used data structures in prolog, the reader
    offers a simple way of writing them.
    Lists are either the empty list [] or a structure with the binary
    functor '.' and two arguments, the head and tail of the list.
    The standart syntax for a list like

        .
           / \
        first .
             / \
         second .
                / \
         third    []

    is .(first, .(second, .(third, []))).
    The simpler syntax is [first, second, third].
    If the tail of the above example is not the empty list, but a
    random term one can write
    [first, second, third | RandomTermIsTailOfTheList].
    Thus the above example could be written
    [first, second, third | []] as well.

    Another notation for lists is the string.
    Strings are lists of integers which correspond to ASCII characters.
    Strings are written in double quotes.
    "Prolog" is the same as [80, 114, 111, 108, 111, 103].

    3.2 Operators

    It is possible to declare unary and binary functors as operators.
    These operators are only of interest to the reader and do not add
    any computational power to Xprolog.
    For instance the valid prolog term +(1,2) may as well be written
    as 1 + 2.
    An operator comprises of the sort of operator, the preccedence
    and of the atom that should be an operator.
    < For a detailed description of operators see CM >

    The following operators are hard coded in Xprolog :
    (List from Xprolog sources, file init.c)
    { ":-", &XFXFUNCTOR, 255},
    { "?-", &FXFUNCTOR, 255},
    { ":-", &FXFUNCTOR, 255},
    { ";", &XFYFUNCTOR, 254},
    { ",", &XFYFUNCTOR, 253},
    { "spy", &FXFUNCTOR, 250},
    { "nospy", &FXFUNCTOR, 250},
    { "\\", &FXFUNCTOR, 60},        /* a single backslash !!! */
    { "not", &FXFUNCTOR, 60},
    { ".", &XFYFUNCTOR, 51},
    { "is", &XFXFUNCTOR, 40},
    { "=..", &XFXFUNCTOR, 40},
    { "=", &XFXFUNCTOR, 40},
    { "\\=", &XFXFUNCTOR, 40},
    { "<", &XFXFUNCTOR, 40},
    { "=<", &XFXFUNCTOR, 40},
    { ">=", &XFXFUNCTOR, 40},
    { ">", &XFXFUNCTOR, 40},
    { "==", &XFXFUNCTOR, 40},
    { "\\==", &XFXFUNCTOR, 40},
    { "=:=", &XFXFUNCTOR, 40},
    { "=\\=", &XFXFUNCTOR, 40},
    { "@<", &XFXFUNCTOR, 40},
    { "@>", &XFXFUNCTOR, 40},
    { "@=<", &XFXFUNCTOR, 40},
    { "@>=", &XFXFUNCTOR, 40},
    { "-", &FXFUNCTOR, 31},
    { "-", &YFXFUNCTOR, 31},
    { "+", &YFXFUNCTOR, 31},
    { "/\\", &YFXFUNCTOR, 31},
    { "\\/", &YFXFUNCTOR, 21},
    { "*", &YFXFUNCTOR, 21},
    { "/", &YFXFUNCTOR, 21},
    { "mod", &XFXFUNCTOR, 11},
    { "<<", &XFXFUNCTOR, 11},
    { ">>", &XFXFUNCTOR, 11},

    An operator declaration may be overridden but cannot be erased.
    Operator types are : fx fy xf yf xfx xfy yfx yfy.
    Operators are declared by :
    'op(precedence, type, atom)'.
    The precedence may be in the range 1-255. (cf. above)

    - Brackets must be seperated from an operator by a blank.
    - Arguments to a structure may have a maximal precedence of 254.
      If it is necessary to have higher precedences, enclose the term
      in brackets.
    - To use an operator as an ordinary atom, enclose it in brackets too.

    4.0 System Hooks and Hacks

    The following builtin (c defined) predicates are not intended for
    use in a 'normal' prolog program but are used for interaction
    and manipulation of the underlying system.

    halt.
        The proper way to stop Xprolog and return to the desktop.

    abort.
        Aborts the current pending goals, cleans the trail, copy
        and resolutionstack and restarts the main goal.

    fileerrors.
        After fileerrors was called, any error during io leads
        to an error message and to an abort.

    nofilerrors.
        After nofilerrorsw as called, io error lead to an failure
        of the builtin predicate.

    sh.
        Invokes a command shell. If the enviroment variable SHELL
        is not set, the default shell will be used.

    system(atom).
        Invokes the command atom through a command shell.

    statistics.
        Returns some usefull statistics.

    prompt(old, new).
        Unifies old and new to the old an new prompt. Usefull for
        determine the current prompt or changeing the prompt.
        (see _boot for an example)

    $clause(head, body, don't_touch_me)
        Hook for implementing 'clause(head, body)'.
        If invoked from the call port, the third argument must be
        an unbound variable.
        $clause tries to unify head and body with the head and body
        of the first fitting clause descriptor.
        The third argument is then CHANGED(literally!) to an
        integer with the adress of the current clause descriptor as
        it's value.
        If $clause is reinvoked from the retry port, the next fitting
        clause descriptor is searched and the integer is advanced.
        Thus it is possible to find all clauses in the database.
        If there is no further clause, the third argument is
        recreated as a fresh variable.

    debug.
        Switches debug mode on. Leash is set to half.

    nodebug.
        Switches debug mode off.

    $functor(name, arity, don't_touch_me)
        General hook. (Used in 'listing' for instance)
        The third argument is used as in $clause, but holds now
        the adress of the last tried functor.
        $functor returns all known functors. (through backtracking)

    $goalvars(list)
        Hook for the toplevel interpreter loop.
        When the reader reads a prolog term, all encountered
        variables and their names are stored in an internal
        symbol table.
        To save these variables for later purposes (prompting
        the results) one should call $goalvars.
        $goalvars builds a list of ',' terms that hold the variable's
        name and the variable itself.
        For example the term 'test(FirstVariable, _, _234)'
        results in [('FirstVariable', _23), ('_234', _24)].

    $more(variable)
        Hook for the toplevel interpreter loop.
        $more unifies the argument with 'yes' iff there is
        a backtrack log for a goal that was called after the
        parents goal was called. (difficult ?)
        Example: in the conjunction of goals
        a, b, call(C), more(VARIABLE), d.
        the VARIABLE is set to yes iff the goals a, b or the
        meta goal C offers untried alternatives.
        Thus $more is used to determine if the user's goal had
        some alternatives.
        (see _boot for a working example)

    $prompt(atom)
        $prompt is used to write a prompt. It is a hack for
        a programming mistake that makes Xprolog sometimes think
        it has just read an empty line.
        (And then it shows a new prompt which is unwanted)
        < this bug will probably be removed in later versions >

    protect(list_of_structures)
        All given structures (precisely their functors) are
        marked as protected.
        Afterwards they cannot be removed by abolish or retract.
        Hint : use anonymous variables or integers as arguments.

    unprotect(list_of_structures)
        Reverse the effect of protect.

    hide(list_of_structures)
        All given structures are marked as hidden.
        They won't be returned by $functor.

    reveal(list_of_structures)
        Reverse the effects of hide.

    save(atom)
        Saves the current data in the prototype space,
        clause space and functor space in an image with the given name.
        Note that images between different processor types are
        incompatible.
        The current sizes of all data areas are saved too.
        If Xprolog is started with such an image, the options are
        overridden by the saved area sizes.

    reboot
        Restarts Xprolog without loading it again.
        Usefull after the database was screwed up.

    $leash(number)
        Sets the port bitmask for the tracer.
        (the following lines are from Xprolog sources, prolog.h)
        #define CALL_PORT     0x1
        #define FAIL_PORT    0x2
        #define RETRY_PORT    0x4
        #define EXIT_PORT    0x8
        With $leash it is possible to trace a selected set of
        ports.

    reconsulting(number)
        Sets the reconsulting flag to number.
        If 1, reconsult mode is active, if 0 it is inactive.

    Xprolog offers a very special feature.
    One can write 'special case' predicates in C and the more general
    procedure in prolog. This feature is currently implemented in
    the append predicate only.
    The C predicate for append assumes that the first two arguments are
    proper lists and unifies the appended lists with the third argument.
    If this fails, the 'standard' prolog procedure is used.
    (ie. append consist of three clauses, the first is a builtin
    c function and the second and third are written in prolog)
    < due to a bug listing can't show those procedures >

    5.0 IO Predicates

    Up to 15 streams may be open at any one time.
    Everytime one stream is the current input stream and another
    stream the current output stream.
    If no stream is opened, the users terminal acts like a file.
    This is the default stream 'user'.
    Filenames must be specified as in the underlying operating system.
    Filenames are simple atoms, and must be quoted if necessary.
    Normaly IO error cause an abort, but if 'nofileerrors' was called,
    the predicate simply fails.
    The end of file of the current input stream is signalled by the
    atom 'end_of_file'.

    5.1 Reading Programs

    consult(filename)
        Reads the clauses in the file and asserts them. (cf. sect. 3.0)

    reconsult(filename)
        Like consult, except that the procedures that will be
        redefined are deleted before asserting the new clauses.

    [filename|filenames]
        Each specified file in the list is consulted, or reconsulted
        if the filename is preceeded by a '-'.

    5.2 File Handling

    see(filename)
        The file becomes the new current input stream.
        If the file was not opened yet, it will be opened.

    seeing(filename)
        The filename will be unified with the name of the
        current input stream.

    seen
        The current input stream is closed and user becomes
        the new current input stream.

    tell(filename)
        Opens the file (if not open) and makes it the new
        current output stream.

    telling(filename)
        The filename will be unified with the name of the
        current output stream.

    told
        The current ouput stream is closed and user
        becomes the new current output stream.

    close(filename)
        Closes filename.

    fileerrors
        Any IO error will cause an abort.

    nofileerrors
        Any IO error will just fail the predicate.

    exists(filename)
        Succeeds if the file exists and is writeable.

    rename(old, new)
        Renames the file old to new.
        If new is [], then old is removed.

    5.3 Input Output

    read(Term)
        A term (delimited by '.' and a new line) is read and
        unified with Term.

    read_line(List)
        The next line is read and List is unified with the
        list of characters in that line. Ie. the line
        is treated as a string.

    write(Term)
        The Term is written to the output stream.

    writeq(Term)
        The Term is written with it's names quoted where
        necessary. The output of writeq can be reread by the
        reader.

    display(Term)
        Same as write, but only the prefix notation of terms
        is used.

    write_line(String)
        The String(list of characters) is written.
        The line is terminated by a line feed.

    print(Term)
        Hook for including a pretty printer.
        Variables are printed with write, but other terms
        are written with 'portray(Term)'.

    nl.
        A new line is started on the output stream.

    get0(char)
        The next character is read and it's ASCII code is unified
        with char.
        Note that on a end of file on the current input stream
        get0 returns not an integer but 'end_of_file'.

    get(char)
        Same as get0, but only nonblank printable characters are
        read. Other character are skipped.

    skip(char)
        Skips characters until char is found.

    put(char)
        Prints the character with the ASCII code char.

    tab(N)
        Prints N spaces on the output stream.

    flush
        Flushes the current output stream. Usefull
        for buffered IO.

    seek(X)
        Unifies the current position in the current input
        stream with X.

    get_key(char, scancode)
        Special predicate for Atari ST only.
        Reads any character from the keyboard without echo!!
        Returns the ASCII code in char and the scancode.
        The scancode is the position information from the
        keyboard. (see your copy of the Atari ST internals)

    6.0 Arithmetic

    Note that Xprolog has only integers and no floats as in
    Cprolog.

    Arithmetic is performed by builtins which take arithmetic
    expressions as arguments.
    Valid arithmetic expresssions are (when x and y are expressions)

    x+y        addition
    x-y        subtraction
    x*y        multiplication
    x/y        integer division
    x mod y     x modulo y
    - x        minus
    x /\ y        bitwise conjunction
    x \/ y        bitwise disjunction
    x << y        bitwise leftshift of x by y bits
    x >> y        bitwise rightshift
    \x        bitwise negation
    cputime        number of milliseconds since Xprolog started
    heapused    used space in the prototype space in bytes
    [character]    the ASCCI code of the character
    any Number

    Builtin predicates that evaluate expressions are

    Z is X
        X is evaluated and Z is unified with the result.

    X =:= Y
        The values of X and Y are equal.

    X =\= Y
        The values of X and Y are not equal.

    X < Y
        The value of X is less the value of Y.

    X > Y

    X =< Y

    X >= Y

    7.0 Convenience and Control

    P , Q
        P and Q.

    P ; Q
        P or Q.

    true.
        Always succeeds.

    fail.
        Never succeeds.

    X = Y
        X is unified with Y. Defined as 'X=Y.'

    !
        The cut. Discard all pending choices since the parent
        goal was started.

    repeat
        Has infinite choices.
        Defined as if by :
        repeat.
        repeat :- repeat.

    { clause }
        Same as assert((clause)).

    8.0 Meta Logic

    var(X)
        X is a variable.

    nonvar(X)
        X is not a variable.

    atom(X)
        X is an atom.

    integer(X)
        X is an integer.

    atomic(X)
        X is an atom or an integer.

    structure(X)
        X is a structured term. (known as compound term)
        Note that atom(X) implies structure(X).

    builtin(X)
        X is a built in predicate

    functor(Term, Name, Arity)
        If Term is given, Name and Arity are set to the name and
        arity of the Term's functor.
        If Term is not given (ie. a unbound variable) a structure
        is generated (with anonymous variables as arguments)
        with the given name and arity.

    arg(N, Term, X)
        Unifies X with the N's argument of Term.

    Term =.. List
        List is a List whose head is an atom corresponding to
        the functor of Term and its tail is the argument list of Term.
        If Term is not given, List must be instantiated.
        Examples:
        product(0,N,N-1) =.. [product,0,N,N-1].
        X =.. [1,a,b] will fail as 1 is no valid name.

    name(Atom, List)
        If Atom is given, List will be unified with the list
        of the ASCII codes of Atom's name.
        If Atom is not given, it is unified with an atom whose
        name is build by the list of ASCII codes.
        i.e. name(prolog, "prolog").

    call(Goal)
        The Goal is executed as if the Goal appeared in the
        place of call(Goal). Note that the Cut ('!') is local
        to the Goal.


    9.0 Term Comparison

    X == Y
        Test if X and Y are strictly equal.

    X \== Y
        Test if X and Y are not strictly equal.

    X @< Y
        Test if X is less than Y in the standard order.
        < standard order as in Cprolog >

    X @> Y

    X @=< Y

    X @>= Y

    compare(Op, X, Y)
        Aplies Op to X and Y.
        Op may be '<', '>', '='.

    subatom(first, second)
        Checks if the name of the first atom lies in the name
        of the second atom.

    subATOM(first, second)
        Like subatom but case independent.

    10.0 Database

    assert(Clause)
        Same as assertz.

    asserta(Clause)
        Adds the clause as the first clause of the procedure.

    assertz(Clause)
        Adds the clause as the last clause of the procedure.

    clause(Head, Body)
        Head must be bound to a structure.
        The Database is searched for a matching clause.
        Body is the unified with the body of the found clause.
        If we found a fact, Body will be unified with 'true'.
        Clause may be retried to get all matching clauses.

    retract(Head)
        The first matching clause is remove from the database.

    abolish(Name, Arity)
        Removes all clauses whose name is Name and arity is Arity.

    !! Note !! Currently no check is made to prevent a program
    from retracting itself. Clauses are removed immediately.
    This may result even in a crash of Xprolog !!!!