interpreter.texi (5404B)
1 @c -*-texinfo-*- 2 @setfilename ../src/interpreter 3 4 @node Interpreter, Booleans, Introduction, Top 5 @comment node-name, next, previous, up 6 @chapter Interpreter 7 @cindex interpreter 8 9 This section describes the @command{klisp}, a Kernel Programming Language 10 stand-alone interpreter. 11 12 @section Invocation 13 @command{klisp} is invoked like this: 14 @example 15 klisp [options] [script] 16 @end example 17 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. 33 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}. 42 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 53 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> ". 57 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. 67 68 @table @option 69 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 78 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. 84 85 @item -i 86 @c @opindex -i ... 87 @c @cindex -i ... 88 enter interactive mode after @var{script} is executed. 89 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. 95 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. 101 102 @item -v 103 @c @opindex -v ... 104 @c @cindex -v ... 105 show version and copyright information. 106 107 @end table 108 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: 120 121 @table @code 122 123 @item integer 124 If the value is an integer it is used as exit status. 125 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}. 129 130 @item inert 131 If the value is inert, then @code{EXIT_SUCCESS} is returned. 132 133 @item else 134 In any other case @code{EXIT_FAILURE} is returned. 135 @end table 136 137 @section Environment Variables 138 @c @cindex Interpreter Environment Variables 139 140 The following environment variables affect the behaviour of @command{klisp} 141 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")} 148 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. 153 154 @end table