source: project/wiki/man/5/Using the interpreter @ 36926

Last change on this file since 36926 was 36926, checked in by sjamaan, 21 months ago

Update wiki with git manual changes and improvements (but not upcoming features from 5.0.1)

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