an open source interpreter for the Kernel Programming Language.
git clone http://git.hanabi.in/repos/klisp.git
Log | Files | Refs | README

interpreter.texi (5404B)

      1 @c -*-texinfo-*-
      2 @setfilename ../src/interpreter
      4 @node Interpreter, Booleans, Introduction, Top
      5 @comment  node-name,  next,  previous,  up
      6 @chapter Interpreter
      7 @cindex interpreter
      9 This section describes the @command{klisp}, a Kernel Programming Language
     10 stand-alone interpreter.
     12 @section Invocation
     13 @command{klisp} is invoked like this:
     14 @example
     15 klisp [options] [script]
     16 @end example
     18 @section Description
     19 @command{klisp} is a stand-alone klisp interpreter for the Kernel
     20 Programming Language.  It loads and evaluates Kernel programs in
     21 textual source form.  @command{klisp} can be used as a batch
     22 interpreter and also interactively.  The given @code{options}
     23 (@pxref{Command Line Options}) are evaluated and then the klisp
     24 program in file @code{script} is loaded and evaluated.  All
     25 evaluations mentioned, including the initialization that is described
     26 below, take place in the same (initially) standard environment. All
     27 values that result from these evaluation are discarded, but if the
     28 @code{root-continuation} or @code{error-continuation} are passed a
     29 value, the evaluation of @code{options} is interrupted and
     30 @command{klisp} terminates. 
     31 @xref{Interpreter Exit Status,,Exit Status}, for a description of the
     32 exit status in each case. 
     34 The string @code{script} together with all arguments are available as
     35 a list of strings via the applicative @code{get-script-arguments}.  If
     36 these arguments contain spaces or other characters special to the
     37 shell, then they should be quoted (but note that the quotes will be
     38 removed by the shell).  The complete command line, including the name
     39 of the interpreter, options, the script, and its arguments are
     40 available as a list of strings via the applicative
     41 @code{get-interpreter-arguments}. 
     43 At the very beginning, before even handling the command line,
     44 @command{klisp} reads and evaluates the contents of the environment
     45 variable @code{KLISP_INIT}, if it is defined.  To use an init file,
     46 just define @code{KLISP_INIT} to the following form: @code{(load
     47 "/path/to/init-file")}.  Notice that @command{klisp} expects exactly one
     48 expression in @code{KLISP_INIT}, if it is defined.  So it is an error
     49 to have no expressions or more than one in @code{KLISP_INIT}.  The
     50 same is true of the argument to the @code{-e} option, as both are
     51 implemented in terms of @code{string-eval}. 
     52 @c TODO add xref to string-eval
     54 In interactive mode, @command{klisp} prompts the user, reads
     55 expressions from the standard input, and evaluates them as they are
     56 read. The default prompt is "klisp> ".
     58 @anchor{Command Line Options}
     59 @section Options
     60 @c @cindex Command Line Options
     61 @c TODO move this to an appendix
     62 Options start with @option{-} and are described below. You can use
     63 @option{--} to signal the end of options. If no arguments are given,
     64 then @option{-v}  @option{-i} is assumed when the standard input is a
     65 terminal; otherwise, @option{-} is assumed.  If no @var{script}, or
     66 option @option{-e} or @code{-l} is given, @option{-i} is assumed.
     68 @table @option
     70 @item -
     71 @c TODO implement option index @opindex - ...
     72 @c cindex ...
     73 load and execute the standard input as a file,
     74 that is,
     75 not interactively,
     76 even when the standard input is a terminal.
     77 .TP
     79 @item -e @var{expr}
     80 @c @opindex -e ...
     81 @c @cindex -e ...
     82 evaluate expression @var{expr}.  You need to quote @var{expr} if it
     83 contains spaces, quotes, or other characters special to the shell. 
     85 @item -i
     86 @c @opindex -i ...
     87 @c @cindex -i ...
     88 enter interactive mode after @var{script} is executed.
     90 @item -l @var{name}
     91 @c @opindex -l ...
     92 @c @cindex -l ...
     93 evaluate @code{(load "name")} before @var{script} is executed.
     94 Typically used to do environment initialization. 
     96 @item -r @var{name}
     97 @c @opindex -r ...
     98 @c @cindex -r ...
     99 evaluate @code{(require "name")} before @var{script} is
    100 executed. Typically used to load libraries. 
    102 @item -v 
    103 @c @opindex -v ...
    104 @c @cindex -v ...
    105 show version and copyright information.
    107 @end table
    109 @c TODO move this to an appendix
    110 @anchor{Interpreter Exit Status}
    111 @section Exit Status
    112 @c @cindex Exit Status
    113 If the @var{script} or @file{stdin} reach @var{EOF} or if there is no
    114 @var{script}, @code{EXIT_SUCCESS} is returned.  If the
    115 @var{error-continuation} is passed an object during init, arguments or script
    116 evaluation @code{EXIT_FAILURE} is returned.  If the
    117 @var{root-continuation} is passed an object, @command{klisp} tries to
    118 convert the value passed to the @var{root-continuation} to an exit
    119 status as follows: 
    121 @table @code
    123 @item integer
    124 If the value is an integer it is used as exit status.
    126 @item boolean
    127 If the value is a boolean then @code{EXIT_SUCCESS} is returned for
    128 @code{#t} and @code{EXIT_FAILURE} for @code{#f}.
    130 @item inert
    131 If the value is inert, then @code{EXIT_SUCCESS} is returned.
    133 @item else
    134 In any other case @code{EXIT_FAILURE} is returned.
    135 @end table
    137 @section Environment Variables
    138 @c @cindex Interpreter Environment Variables
    140 The following environment variables affect the behaviour of @command{klisp}
    142 @table @env
    143 @item KLISP_INIT
    144 @c TODO index for env variables
    145 A Kernel expression to be evaluated before any arguments to the
    146 interpreter.  To use an init file, just define @var{KLISP_INIT} to the
    147 following form @code{(load "/path/to/init-file")}
    149 @item KLISP_PATH
    150 A semicolon separated list of templates for controlling the search of
    151 required files.  Each template can use the char @code{?} to be
    152 replaced by the required name at run-time.
    154 @end table