home *** CD-ROM | disk | FTP | other *** search
/ Acorn User 2 / AUCD2.iso / program / huprolog.arc / !HUprolog / MANUAL < prev    next >
Text File  |  1990-12-09  |  13KB  |  309 lines
  1. HU-PROLOG - Humboldt University Prolog  RISC-OS version 1.1
  2.  
  3. SYNOPSIS
  4. prolog [-v] [-BOOT] [ -r restorefile ] [-l libfile] 
  5.        [-a max_no_atoms] [-t max_no_terms] [-c max_no_crit_vars]
  6.        [-g max_no_active_goals] [-s max_size_string_table]
  7.  
  8.  
  9. COPYRIGHT
  10.      HUProlog is freeware.  It may be freely copied and redistributed,
  11.      provided all the files present in the original
  12.      distribution are included, unaltered.  If it is redistrubted for
  13.      profit it would be appreciated if 10 per cent or so of the 
  14.      distribution fee is sent to the authors listed below.  They are by no 
  15.      means wealthy.  Users of this software are asked to make a donation 
  16.      appropriate to their wealth and usage.
  17.      Commercial Prolog's cost a lot of money... 
  18.  
  19.      There is, of course, no guarantee or warranty of any kind.
  20.  
  21.      (c) 1990 C.Horn, M.Dziadzka, M.Horn
  22.  
  23.      Ported, adapted, and maintained for RISC-OS by Andrew Stevens
  24.      RISC-OS Modifications (c) 1990 Andrew Stevens
  25.  
  26. DESCRIPTION
  27.  
  28.      HUProlog is, an almost 100 per cent straight implementation of
  29.      standard Edinburgh syntax Prolg as described in Clocksin and
  30.      Mellish's ``Programming in Prolog'' (Springer Verlag)
  31.      and a host of other works. The sections below detail the deviations.
  32.      If you're learning Prolog a good book to start with is Ivan Bratko's.
  33.      I forget the title, but it has Prolog in it - a decent computer bookshop
  34.      will either stock or easily find it for you.
  35.  
  36.      HU-Prolog is most definately NOT a toy Prolog.  The authors and
  37.      myself are all professional AI and computer science research workers,
  38.      and rely on HU-Prolog for a variety of large-scale Prolog
  39.      programming tasks.  It is definately one of the fastest purely
  40.      interpreted Prolog's around (the only faster one I know of is the
  41.      Edinburgh NIP implementation).  WAM-based compiling Prolog's
  42.      are faster, but at the price of greatly increased memory requirements.
  43.      Even then ``real programs'' as opposed to benchmarks rarely run 
  44.      more than twice as fast.  Eventually I (or someone else) may port
  45.      Sicstus or SB Prolog for RISC-OS, in the meantime HU is as good as
  46.     it gets.
  47.  
  48.      For source code availability see the AUTHOR's section at the end.
  49.  
  50. INSTALLATION
  51.      To install HU-Prolog execute the Obey file ``BUILDSS''.
  52.      This will build a file called ``huplstate'' that contains
  53.      the default start-up state for HU-Prolog.  HU-Prolog can then
  54.      be installed by putting the files ``hup'', ``prolog'', and
  55.      ``huplstate'' into wherever you like to keep command line
  56.      orientated programs.   The process requires a WIMPSLOT of 640K -
  57.      though you may find you can get away with a little less.
  58.  
  59.      You may also find you will also need to
  60.      install an up to date shared C library and/or floating point
  61.      emulation library, but this is fairly improbable.  
  62.  
  63. RUNNING HU-Prolog
  64.      Once installed HU-Prolog is run by executing the ``hup'' obey
  65.      script.  By far the best place to do this is within a TASK window
  66.      running under !Edit (or some other editor).  This allows Prolog
  67.      to multi-task, and gives you decent command dialogue editting
  68.      facilities.
  69.  
  70.      Obviously, you need to set the WIMPSLOT to some appropriate
  71.      value if you wish to run HU-Prolog with large programs.  New releases
  72.      of the C library are reputed extend WIMPSLOT's automatically to suit
  73.      program's requirements, but until then a bit of manual tweaking is
  74.      required.  As a guide:
  75.  
  76.      Term's and critical variables require 8 bytes each, whilst
  77.      Atom's require 28 bytes each and Active Goals require 32 bytes each.
  78.      Prolog itself requires around 140K -- the executable file is squeezed.
  79.     
  80. START UP AND EXITING
  81.       When HUProlog starts up it first loads its initial state.  If no -r
  82.       ``restore state' command line argument is given this is the file
  83.       <HUPro$Dir>.huplstate.    The ``hup'' script automatically
  84.       sets HUPro$Dir to the directory where it was executed unless it
  85.       has already been set.
  86.  
  87.       Next the start-up file is consulted.  If no -l ``startup file''
  88.       command line argument is given this is the file named in the
  89.       <HUPro$RC> system variable.  If this variable isn't set the
  90.       file ``prologrc'' is tried.   No error oocurs if the startup
  91.       file doesn't exist.
  92.  
  93.       You exit HU-Prolog by typing either control-D or ``end_of_file.''.
  94.       Details of the facilities available in HU-Prolog, BUGS, and source
  95.       code availability are described below.
  96.           
  97.  
  98. OPTIONS
  99.        -r     -    Restore named saved state.
  100.  
  101.        -l     -    Consult named file at start-up
  102.  
  103.        -v     -    Turn off verbosity - no prompt (etc).
  104.  
  105.        -BOOT  -    Bootstrap HUProlog after recompilation
  106.  
  107.        -a     -    Set max number atoms for which space is to be 
  108.                    allocated.  DEFAULT 2000.
  109.  
  110.        -t     -    Set max number of terms for which space is to
  111.                    be allocated.  DEFAULT 40000.
  112.  
  113.        -c     -    Set maximum number of critical variables for which
  114.                    stack space is to be allocated.  DEFAULT 4000.
  115.  
  116.        -g     -    Set maximum number of active goals for whcih stack space
  117.                    is to be allocated.  DEFAULT 2000.
  118.  
  119.        -s     -    Set number of bytes of string space to be allocated.
  120.                    DEFAULT 15000.
  121.  
  122.         Defaults represent a memory usage of aound 650K - suitable for a
  123.         1M byte Archy.
  124.  
  125. OMMISIONS
  126.  
  127.      The only significant ommision is that HU-Prolog does not implement
  128.      the (rarely used outside natural language research) syntax for
  129.      defining definate clause grammars.
  130.  
  131.      As with a lot of Prolog's (all?) setof and bagof are not overwhelmingly
  132.      efficient.   HU-Prolog has these loaded in the default saved states,
  133.      but also includes the more efficient (and useful) findall/3 and findset/3.  
  134.      A fancy (and efficient) sorting predicate ksort/2,ksort/4 is also
  135.      included.  Source can be found in in the set_of file.
  136.  
  137. EXTENSIONS
  138.      fileerrrors, fileerrors(on) - File errors cause an abort
  139.      nofileerrors, fileeerrors(off) - File errors merely cause a fail.
  140.      syneclose          - Close file being read when syntax error detected.  Default.
  141.      nosyneclose        - Leave file being read open when syntax error detected.
  142.      warn(off)          - No warning messages  Default
  143.      warn(on)           - Warning messages
  144.      ocheck(off)        - No occurs check during unification - standard Prolog. Default.
  145.      ocheck(on)         - Occurs check udring unification (much slower with
  146.                           big terms, but it means unification cannot 
  147.                           accidentally loop).
  148.      sysmode(off)       - System defined operators may not be changed.
  149.      sysmode(on)        - System define operators may be changed.
  150.      echo(off)          - Don't echo queries  Default
  151.      echo(on)           - echo queries. 
  152.  
  153.      is_member/2        - Fast list membership test 
  154.      no_member/2        - Fast list non-mebmbership test,
  155.      sysappend/3        - Fast append for proper lists.
  156.  
  157.     assert(Term,Ref),
  158.     asserta(Term,Ref),
  159.     assertz(Term,Ref)   - Database assertion returning database reference
  160.     clause(Head,Body,Ref ) - Fast clause access using database reference
  161.     abolist(Head,Body,Ref) - Fast clause abolition using database ref.
  162.     retract(Term,Ref)   - Fast database retract using reference
  163.  
  164.     sort/2              - Sort a list of terms, stripping duplicates.
  165.     sort1/2             - Sort a list of terms, preserving duplicates.
  166.     stats               - Print memory usage statistics.
  167.     argc/1              - Give number of uninterpreted command line args
  168.     argv/2              - Get one of the uninterpreted command line args
  169.     <<,>>               - Bitwise shift functions for `is' expressions
  170.     &,\,~               - Bitwise and, or, and not for `is' expressions
  171.     &&,\\,/             - Boolean and, or and not for `is' expressions
  172.  
  173.  
  174.     Errors can be trapped by defining the predicate error/2
  175.     When an error occurs this will be invoked with the first
  176.     argument bound to the goal causing the error, and the second to
  177.     the associated error message.
  178.  
  179.     User interrupts (hitting the ESC key) can be trapped by defining
  180.     the predicate interrupt/0 in the code loaded in the initial
  181.     -BOOT start-up.  Similarly calls to undefined predicates can
  182.     be trapped by defining undefined. 
  183.  
  184. SAVED STATES
  185.  
  186.      The default saved state for Prolog is built by what amounts to
  187.      typing:
  188.  
  189.      prolog -BOOT
  190.      [prologrc,set_of].     % You can of course load other stuff here!
  191.      save(huplstate).
  192.      ^D
  193.  
  194.      at HU-Prolog.
  195.  
  196.      You can dump a saved state at any time in a Prolog run by executing
  197.      save(filename).  The resulting prolog state can be restored by
  198.      re-starting prolog with the file specified with -r flag.  Note that
  199.      saved states can be pretty large.  500K is not unusual.  I suspect
  200.      bad things are likely to happen if you attempt to load a saved state
  201.      into prolog that has had insufficient space allocated.
  202.  
  203.      If you wish to build a saved state on top of the ``bare'' Prolog system,
  204.      simply start prolog with the -BOOT flag set, load in the stuff you want
  205.      and then save.
  206.  
  207.    
  208. DEBUGGING
  209.  
  210.      HUProlog has the usual Prolog trace and spy-point facilities.
  211.      A spy-point can be set on a predicate by the query:
  212.      spy( name-of-predicate) or
  213.      spy( name-of-predicate/arity-of-predicate)
  214.      nospy( <as above> ) removes spy-points.
  215.      nodebug temporarily causes spy-points to be ignored.
  216.      debug  causes spy-points to be obeyed again.
  217.  
  218.      trace turns on tracing.
  219.      notrace turns off tracing.
  220.  
  221.      When tracing or at a spy-point:
  222.      t - starts tracing
  223.      n - goes to next spy-point
  224.      CR - traces or goes to next spy-point depending
  225.           on whether current tracing or spying.
  226.      f - causes the current query to fail
  227.      a - aborts the current program execution
  228.  
  229.      The default saved states add in a handler for
  230.      escape-key-pressed interrupts which allows
  231.      a - aborts current program execution
  232.      @ - allows a sub-query to be executed
  233.      t - turns on tracing.
  234.  
  235.      Due to a deficiency in the way file consultation works,
  236.      this handler will not work when invoked during the
  237.      consultation of a file.   Input is taken from the file
  238.      being consulted, rather than the console.
  239.  
  240. AUTHORS
  241.       C.Horn, M.Dziadzka, M.Horn
  242.       Department of Mathematics     
  243.       Humboldt-University
  244.       (East) Berlin
  245.       Germany.
  246.  
  247.       Due to German re-unification the original authors are probably
  248.       more reliably contacted though me (Andrew Stevens).
  249.  
  250.      Archimedes port:   Andrew Stevens  
  251.      Andrew Stevens,      JANET: as@uk.ac.ed.aipna
  252.      18 Kings Meadow,     INTERNET:  as@aipna.ed.ac.uk
  253.      Overton,             UUCP:   ...!ukc!aipna!as
  254.      Basingstoke,
  255.      HANTS.
  256.  
  257.      RG25 3HP
  258.  
  259.      Please feel free to contact me (Andrew Stevens) if you have any queries - 
  260.      though it might take me a little while to reply. Especially by postal mail.  
  261.      If you are interested in modifying, debugging(!), or enhancing HU-Prolog 
  262.      source code is available.  If you have access to JANET it is available on the
  263.      newcastle info-server info-server@uk.ac.newcastle.
  264.  
  265.      The addition of an interface to the RISC-OS GUI
  266.      would be most appreciated!
  267.  
  268. BUGS
  269.     open/1  sometimes fails mysteriously.
  270.  
  271.     Saved states are not stored very efficiently - ASCII numbers!
  272.  
  273.     The bodge with syneclose is a messy consequence of the fact
  274.     that RISC-OS is too stupid to allow writing to open files.
  275.  
  276.     see's behaviour when not properly nested with seen's
  277.     is not entirely standard I think. It is, however, sensible.
  278.  
  279.     If you attempt to redefine a system predicate in
  280.     the start-up file outside boot mode the system crashes.
  281.     The start-up file is, furthermore, not read during boot mode!
  282.  
  283.     The debugger handles backtracking very poorly.
  284.  
  285.     The setof and bagof predicates are not built-in's, only loaded.
  286.  
  287.     The sort predicates use a O(n^2) algorithm.  For big sorts use the
  288.     ksort predicate defined in set_of - it is O(n*log(n)).
  289.  
  290.     The program does *not* multi-task or run under the desktop on its
  291.     own.  It multi-tasks etc just fine, however, when run under a !Edit
  292.     task window.
  293.  
  294.     It is not clear when saved states made with HUProlog with
  295.     one set of memory allocations will load into one set up
  296.     with others.
  297.  
  298.     It certainly will work provided if the creating HUProlog
  299.     was configured with all parameters  smaller than the loading 
  300.     HUProlog.
  301.  
  302.     It should also work if the loading HUProlog is big enough
  303.     in all parameters, and the saved state was dumped ``clean''.
  304.     I.e. the save/1 predicate was invoked from the Prolog
  305.     command prompt.  No guarantees, however - thats why this is
  306.     in the BUGS list!
  307.  
  308.  
  309.