source: project/wiki/man/5/TODO/Using the interpreter @ 35522

Last change on this file since 35522 was 35522, checked in by felix, 7 weeks ago

man/5: moved some chapters, slight restructuring, add missing pages

File size: 13.5 KB
Line 
1[[tags: manual]]
2[[toc:]]
3
4== Using the interpreter
5
6CHICKEN provides an interpreter named {{csi}} for evaluating Scheme programs
7and expressions interactively.
8
9=== Interpreter command line format
10
11{{csi {FILENAME|OPTION}}}
12
13where {{FILENAME}} specifies a file with Scheme source-code.  If the
14extension of the source file is {{.scm}}, it may be omitted. The
15runtime options described in [[Using the compiler#Compiler command line format|Compiler command line format]] are also available
16for the interpreter.  If the environment variable {{CSI_OPTIONS}}
17is set to a list of options, then these options are additionally passed
18to every direct or indirect invocation of {{csi}}. Please note that
19runtime options (like {{-:...}}) can not be passed using this method.
20The options recognized by the interpreter are:
21
22; -- : Ignore everything on the command-line following this marker. Runtime options ({{-:...}}) are still recognized.
23
24; -i  -case-insensitive : Enables the reader to read symbols case insensitive. The default is to read case sensitive (in violation of R5RS).  This option registers the {{case-insensitive}} feature identifier.
25
26; -b  -batch : Quit the interpreter after processing all command line options.
27
28; -e  -eval EXPRESSIONS : Evaluate {{EXPRESSIONS}}. This option implies {{-batch}}, {{-no-init}} and {{-quiet}}, so no startup message will be printed and the interpreter exits after processing all {{-eval}} options and/or loading files given on the command-line.
29
30; -p  -print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
31
32; -P  -pretty-print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{pretty-print}}. Implies {{-batch}}, {{-no-init}} and {{-quiet}}.
33
34; -D  -feature SYMBOL : Registers {{SYMBOL}} to be a valid feature identifier for {{cond-expand}} and {{feature?}}.
35
36; -h  -help : Write a summary of the available command line options to standard output and exit.
37
38; -I  -include-path PATHNAME : Specifies an alternative search-path for files included via the {{include}} special form. This option may be given multiple times. If the environment variable {{CHICKEN_INCLUDE_PATH}} is set, it should contain a list of alternative include pathnames separated by {{;}}.
39
40; -K  -keyword-style STYLE : Enables alternative keyword syntax, where {{STYLE}} may be either {{prefix}} (as in Common Lisp) or {{suffix}} (as in DSSSL). Any other value is ignored.
41
42; -n  -no-init : Do not load initialization-file. If this option is not given and the file {{$HOME/.csirc}} exists, then it is loaded before the read-eval-print loop commences.
43
44;     -no-parentheses-synonyms : Disables list delimiter synonyms, [..] and {...} for (...).
45
46;     -no-symbol-escape : Disables support for escaped symbols, the |...| form.
47
48; -w  -no-warnings : Disables any warnings that might be issued by the reader or evaluated code.
49
50; -q  -quiet : Do not print a startup message. Also disables generation of call-trace information for interpreted code.
51
52;     -r5rs-syntax : Disables the CHICKEN extensions to R5RS syntax. Does not disable [[Non-standard read syntax|non-standard read syntax]].
53
54; -s  -script PATHNAME : This is equivalent to {{-batch -quiet -no-init PATHNAME}}. Arguments following {{PATHNAME}} are available by using  {{command-line-arguments}} and are not processed as interpreter options. Extra options in the environment variable {{CSI_OPTIONS}} are ignored.
55
56; -sx PATHNAME : The same as {{-s PATHNAME}} but prints each expression to {{(current-error-port)}} before it is evaluated.
57
58; -ss PATHNAME : The same as {{-s PATHNAME}} but invokes the procedure {{main}} with the value of {{(command-line-arguments)}} as its single argument. If the main procedure returns an integer result, then the interpreter is terminated, returning the integer as the status code back to the invoking process. Any other result terminates the interpreter with a zero exit status.
59
60; -setup-mode : When locating extensions, search the current directory first. By default, extensions are located first in the ''extension repository'', where {{chicken-install}} stores compiled extensions and their associated metadata.
61
62; -R  -require-extension NAME : Equivalent to evaluating {{(require-extension NAME)}}.
63
64; -v  -version : Write the banner with version information to standard output and exit.
65
66
67=== Writing Scheme scripts
68
69Since UNIX shells use the {{#!}} notation for starting scripts,
70anything following the characters {{#!}} is ignored, with the exception of the special
71symbols {{#!optional, #!key, #!rest}} and {{#!eof}}.
72
73The easiest way is to use the {{-script}} option like this:
74
75 % cat foo
76 #! /usr/local/bin/csi -script
77 (print (eval (with-input-from-string
78                 (car (command-line-arguments))
79                  read)))
80
81 % chmod +x foo
82 % ./foo "(+ 3 4)"
83 7
84
85The parameter {{command-line-arguments}} is set to a list of the
86parameters that were passed to the Scheme script.  Scripts can be compiled
87to standalone executables (don't forget to declare used library units).
88
89CHICKEN supports writing shell scripts in Scheme for other platforms as well,
90using a slightly different approach. The first example would look like
91this on Windows:
92
93 C:>type foo.bat
94 @;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
95 (print (eval (with-input-from-string
96                 (car (command-line-arguments))
97                 read)))
98
99 C:>foo "(+ 3 4)"
100 7
101
102Like UNIX scripts, batch files can be compiled. Windows batch scripts do not
103accept more than 8 arguments.
104
105Since it is sometimes useful to run a script in the interpreter without actually executing it
106(for example to test specific parts of it), the option {{-ss}} can be used as an alternative to {{-script}}.
107{{-ss PATHNAME}} is equivalent to {{-script PATHNAME}} but invokes {{(main (command-line-arguments))}}
108after loading all top-level forms of the script file. The result of {{main}} is returned as the exit status
109to the shell. Any non-numeric result exits with status zero:
110
111 % cat hi.scm
112 (define (main args)
113   (print "Hi, " (car args))
114   0)
115 % csi -ss hi.scm you
116 Hi, you
117 % csi -q
118 #;1> ,l hi.scm
119 #;2> (main (list "ye all"))
120 Hi, ye all
121 0
122 #;3>
123
124When {{csi}} is started with the {{-script}} option, the feature identifier {{chicken-script}}
125is defined, so can conditionally execute code depending on wether the file is
126executed as a script or normally loaded into the interpreter, say for debugging purposes:
127
128<enscript highlight=scheme>
129#!/bin/sh
130#| demonstrates a slightly different way to run a script on UNIX systems
131exec csi -s "$0" "$@"
132|#
133
134(define (main args) ...)
135
136(cond-expand
137  (chicken-script
138    (main (command-line-arguments)))
139  (else))
140</enscript>
141
142See also the documentation for the {{-ss}} option above.
143
144You can also have a look at [[/writing portable scripts]].
145
146
147=== Toplevel commands
148
149The toplevel loop understands a number of special commands:
150
151; ,? : Show summary of available toplevel commands.
152
153; ,c : Show call-trace items of the most recent error
154
155; ,ch : Clears stored expression results of previously evaluated expressions.
156
157; ,d EXP : Describe result of evaluated expression {{EXP}}.
158
159; ,du EXP : Dump contents of the result of evaluated expression {{EXP}}.
160
161; ,dur EXP N : Dump {{N}} bytes of the result of evaluated expression {{EXP}}.
162
163; ,e FILENAME : Runs an external editor to edit the given {{FILENAME}} (see below for more information).
164
165; ,exn : Describes the last exception that occurred and adds it to the result history (it can be accessed using the {{#}} notation).
166
167; ,f N : Select call-trace item with the given number, where the number {{0}} indicates the last item in the trace
168
169; ,g NAME : Returns the value of the local variable with the given name (which may be a symbol or string); you don't have to give the complete name - {{,g}} will return the first variable that matches the prefix given
170
171; ,h : Shows all previously evaluated expression results.
172
173; ,l FILENAME ... : Load files with given {{FILENAME}}s
174
175; ,ln FILENAME ... : Load files and print result(s) of each top-level expression.
176
177; ,m MODULENAME : switches the "current module" to {{MODULENAME}}, so expressions will be evaluated in the context of the given module.  To switch back to toplevel, use {{#f}} as a MODULENAME.  In compiled modules, only exported bindings will be visible to interactively entered code. In interpreted modules all bindings are visible.
178
179; ,p EXP : Pretty-print evaluated expression {{EXP}}.
180
181; ,q : Quit the interpreter.
182
183; ,r : Show system information.
184
185; ,s TEXT ... : Execute shell-command.
186
187; ,t EXP : Evaluate form and print elapsed time.
188
189; ,x EXP : Pretty-print macroexpanded expression {{EXP}} (the expression is not evaluated).
190
191You can define your own toplevel commands using the {{toplevel-command}}
192procedure:
193
194
195=== toplevel-command
196
197<procedure>(toplevel-command SYMBOL PROC [HELPSTRING])</procedure>
198
199Defines or redefines a toplevel interpreter command which can be invoked by entering
200{{,SYMBOL}}. {{PROC}} will be invoked when the command is entered and may
201read any required argument via {{read}} (or {{read-line}}). If the optional
202argument {{HELPSTRING}} is given, it will be listed by the {{,?}} command.
203
204This procedure is provided by the {{(chicken csi)}} module.
205
206
207=== Getting error information
208
209Interpreted code has some extended debugging information available
210that can be used to locate errors and obtaining information about the
211lexical environment that was effective at the point of error. When an
212error occurs in an evaluated expression, a "call trace" is printed -
213the list of calls up to the error location. Note that this does not
214follow a stack model: it is merely a list of recently made procedure
215calls where the last one in the list is (probably) the call of
216whatever procedure was executing before the error happened. You can
217use the {{,c}} command to show the call-trace of the last
218error. Depending on whether compiled or interpreted code was executing
219and how much debugging information is available, the call trace shows
220trace-buffer entries of the following shape:
221
222  <frame-number>:<environment?> <mode> <procedure-name> <form>
223
224{{<frame-number>}} gives the number of the call-trace entry, counting
225from zero and beginning with the most recent entry. If a {{[]}}
226follows the frame-number, then this frame contains the lexical
227environment in effect when that procedure call took place. {{<mode>}}
228is optional and is either {{<syntax>}} or {{<eval>}} indicating
229whether this trace-buffer entry represents a syntax-expansion or an
230evaluation and is not given for compiled code. {{<form>}} is also only
231available for interpreted code and shows the procedure call
232expression, possibly following the name of the procedure containing
233the call expression.
234
235If the trace-buffer entry contains lexical environment information
236than the complete environment of the call site is shown.
237
238Use {{,f}} to select a frame by number, if you want to inspect the
239lexical environment of an earlier frame. The {{,g}} command lets you
240retrieve the value of a local or lexical variable from the currently
241selected frame. Note that the variables are renamed to simplify the
242variable lookup done internally by the interpreter.
243
244=== Running an external editor
245
246The {{,e}} command runs the editor given by:
247
248* The parameter {{editor-command}} which should return a string naming
249  an external editor and defaults to {{#f}}, which means no editor is currently
250  selected (so the following alternatives are tried).
251
252* The contents of the environment variables {{EDITOR}} or {{VISUAL}}.
253
254* If the environment variable {{EMACS}} is set, the editor chosen is {{emacsclient}}.
255
256* As a truly last resort, {{vi}} is used.
257
258=== History access
259
260The interpreter toplevel accepts the special object {{#[INDEX]}} which
261returns the result of entry number {{INDEX}} in the history list. If
262the expression for that entry resulted in multiple values, the first
263result (or an unspecified value for no values) is returned. If no
264{{INDEX}} is given (and if a whitespace or closing paranthesis
265character follows the {{#}}, then the result of the last expression is
266returned.  Note that the value returned is implicitly quoted.
267
268=== set-describer!
269
270<procedure>(set-describer! TAG PROC)</procedure>
271
272Sets a custom description handler that invokes {{PROC}} when the
273{{,d}} command is invoked with a record-type object that has the type
274{{TAG}} (a symbol). {{PROC}} is called with two arguments: the object
275to be described and an output-port. It should write a possibly useful
276textual description of the object to the passed output-port. For
277example:
278
279 #;1> (define-record-type point (make-point x y) point?
280        (x point-x)
281        (y point-y))
282 #;2> (set-describer! 'point
283        (lambda (pt o)
284          (with-output-to-port o
285            (lambda ()
286              (print "a point with x=" (point-x pt) " and y=" (point-y pt))))))
287 #;3> ,d (make-point 1 2)
288 a point with x=1 and y=2
289
290This procedure is provided by the {{(chicken csi)}} module.
291
292
293=== Auto-completion and edition
294
295On platforms that support it, it is possible to get auto-completion of
296symbols, history (over different {{csi}} sessions) and a more
297feature-full editor for the expressions you type using the
298[[/eggref/4/readline|readline]] egg by Tony
299Garnock Jones.  It is very useful for interactive use of csi. See the
300egg's documentation on how to set it up. If readline is not available
301on your system consider using the self-contained
302[[/eggref/4/linenoise|linenoise]] egg
303instead. It should work on almost any system but is not as
304feature-rich as readline (e.g. it lacks reverse-i-search and
305auto-completion).
306
307---
308Previous: [[Overview]]
309
310Next: [[Using the compiler]]
Note: See TracBrowser for help on using the repository browser.