source: project/wiki/man/4/Using the interpreter @ 15299

Last change on this file since 15299 was 15299, checked in by svnwiki, 10 years ago

Changes applied for Sam Varner (71.59.4.63) through svnwiki:

Minor wording changes.

File size: 10.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 [[http://galinha.ucpel.tche.br/Using%20the%20compiler#Compiler%20command%20line%20format|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}} 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}} and {{-quiet}}.
31
32; -P  -pretty-print EXPRESSIONS : Evaluate {{EXPRESSIONS}} and print the results of each expression using {{pretty-print}}. Implies {{-batch}} 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 {{./.csirc}} or {{$HOME/.csirc}} exists, then it is loaded before the read-eval-print loop commences.
43
44;     -no-parentheses-synonyms STYLE : 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; -R  -require-extension NAME : Equivalent to evaluating {{(require-extension NAME)}}.
61
62; -v  -version : Write the banner with version information to standard output and exit.
63
64
65=== Writing Scheme scripts
66
67Since UNIX shells use the {{#!}} notation for starting scripts,
68anything following the characters {{#!}} is ignored, with the exception of the special
69symbols {{#!optional, #!key, #!rest}} and {{#!eof}}.
70
71The easiest way is to use the {{-script}} option like this:
72
73 % cat foo
74 #! /usr/local/bin/csi -script
75 (print (eval (with-input-from-string
76                 (car (command-line-arguments))
77                  read)))
78
79 % chmod +x foo
80 % foo "(+ 3 4)"
81 7
82
83The parameter {{command-line-arguments}} is set to a list of the
84parameters that were passed to the Scheme script.  Scripts can be compiled
85to standalone executables (don't forget to declare used library units).
86
87CHICKEN supports writing shell scripts in Scheme for other platforms as well,
88using a slightly different approach. The first example would look like
89this on Windows:
90
91 C:>type foo.bat
92 @;csibatch %0 %1 %2 %3 %4 %5 %6 %7 %8 %9
93 (print (eval (with-input-from-string
94                 (car (command-line-arguments))
95                 read)))
96
97 C:>foo "(+ 3 4)"
98 7
99
100Like UNIX scripts, batch files can be compiled. Windows batch scripts do not
101accept more than 8 arguments.
102
103Since it is sometimes useful to run a script in the interpreter without actually executing it
104(for example to test specific parts of it), the option {{-ss}} can be used as an alternative to {{-script}}.
105{{-ss PATHNAME}} is equivalent to {{-script PATHNAME}} but invokes {{(main (command-line-arguments))}}
106after loading all top-level forms of the script file. The result of {{main}} is returned as the exit status
107to the shell. Any non-numeric result exits with status zero:
108
109 % cat hi.scm
110 (define (main args)
111   (print "Hi, " (car args))
112   0)
113 % csi -ss hi.scm you
114 Hi, you
115 % csi -q
116 #;1> ,l hi.scm
117 #;2> (main (list "ye all"))
118 Hi, ye all
119 0
120 #;3>
121
122=== Toplevel commands
123
124The toplevel loop understands a number of special commands:
125
126; ,? : Show summary of available toplevel commands.
127
128; ,l FILENAME ... : Load files with given {{FILENAME}}s
129
130; ,ln FILENAME ... : Load files and print result(s) of each top-level expression.
131
132; ,p EXP : Pretty-print evaluated expression {{EXP}}.
133
134; ,d EXP : Describe result of evaluated expression {{EXP}}.
135
136; ,du EXP : Dump contents of the result of evaluated expression {{EXP}}.
137
138; ,dur EXP N : Dump {{N}} bytes of the result of evaluated expression {{EXP}}.
139
140; ,exn : Describes the last exception that occurred and adds it to the result history (it can be accessed using the {{#}} notation).
141
142; ,q : Quit the interpreter.
143
144; ,r : Show system information.
145
146; ,s TEXT ... : Execute shell-command.
147
148; ,t EXP : Evaluate form and print elapsed time.
149
150; ,x EXP : Pretty-print macroexpanded expression {{EXP}} (the expression is not evaluated).
151
152; ,tr SYMBOL ... : Enables tracing of the toplevel procedures with the given names.
153
154<enscript highlight=scheme>
155#;1> (fac 10)                       ==> 3628800
156#;2> ,tr fac
157#;3> (fac 3)
158|(fac 3)
159| (fac 2)
160|  (fac 1)
161|   (fac 0)
162|   fac -> 1
163|  fac -> 1
164| fac -> 2
165|fac -> 6                          ==> 6
166#;4> ,utr fac
167#;5> (fac 3)                        ==> 6
168</enscript>
169k
170
171; ,utr SYMBOL ... : Disables tracing of the given toplevel procedures.
172
173; ,br SYMBOL ... : Sets a breakpoint at the procedures named {{SYMBOL ...}}. Breakpoint can also be trigged using the {{breakpoint}} procedure.
174
175; ,ubr SYMBOL ... : Removes breakpoints.
176
177; ,c : Continues execution from the last invoked breakpoint.
178
179; ,breakall : Enable breakpoints for all threads (this is the default).
180
181; ,breakonly THREAD : Enable breakpoints only for the thread returned by the expression {{THREAD}}.
182
183; ,info : Lists traced procedures and breakpoints.
184
185; ,step EXPR : Evaluates {{EXPR}} in single-stepping mode. On each procedure call you will be presented with a menu that allows stepping to the next call, leaving single-stepping mode or triggering a breakpoint. Note that you will see some internal calls, and unsafe or heavily optimized compiled code might not be stepped at all. Single-stepping mode is also possible by invoking the {{singlestep}} procedure.
186
187You can define your own toplevel commands using the {{toplevel-command}}
188procedure:
189
190=== toplevel-command
191
192 [procedure] (toplevel-command SYMBOL PROC [HELPSTRING])
193
194Defines or redefines a toplevel interpreter command which can be invoked by entering
195{{,SYMBOL}}. {{PROC}} will be invoked when the command is entered and may
196read any required argument via {{read}} (or {{read-line}}). If the optional
197argument {{HELPSTRING}} is given, it will be listed by the {{,?}} command.
198
199=== History access
200
201The interpreter toplevel accepts the special object {{#[INDEX]}} which
202returns the result of entry number {{INDEX}} in the history list. If the expression
203for that entry resulted in multiple values, the first result (or an unspecified value for no values)
204is returned. If no {{INDEX}} is given (and if a whitespace or closing paranthesis character follows
205the {{#}}, then the result of the last expression is returned.
206Note that the value returned is implicitly quoted.
207
208=== set-describer!
209
210 [procedure] (set-describer! TAG PROC)
211
212Sets a custom description handler that invokes {{PROC}} when the {{,d}} command is invoked
213with a record-type object that has the type {{TAG}} (a symbol). {{PROC}} is called with
214two arguments: the object to be described and an output-port. It should write a possibly useful
215textual description of the object to the passed output-port. For example:
216
217 #;1> (define-record-type point (make-point x y) point?
218        (x point-x)
219        (y point-y))
220 #;2> (set-describer! 'point
221        (lambda (pt o)
222          (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
223 #;3> ,d (make-point 1 2)
224 a point with x=1 and y=2
225
226=== Auto-completion and edition
227
228On platforms that support it, it is possible to get auto-completion of symbols,
229history (over different {{csi}} sessions) and a more feature-full
230editor for the expressions you type
231using the [[http://www.call-with-current-continuation.org/eggs/readline.html]] egg by
232Tony Garnock Jones.
233It is very useful for interactive use of csi.
234
235To enable it install the egg and put this in your {{~/.csirc}} file:
236
237 (use readline regex)
238 (current-input-port (make-gnu-readline-port))
239 (gnu-history-install-file-manager
240   (string-append (or (getenv "HOME") ".") "/.csi.history"))
241
242More details are available in [[http://www.call-with-current-continuation.org/eggs/readline.html|the egg's documentation]].
243
244
245---
246Previous: [[Using the compiler]]
247
248Next: [[Supported language]]
Note: See TracBrowser for help on using the repository browser.