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

Last change on this file since 15922 was 15922, checked in by Ivan Raikov, 10 years ago

Added information about -setup-mode to the manual properly.
Please do not add entries to the manual copy at trunk/manual but to man/4,
the principal location for the Chicken manual.
If you add entries to trunk/manual your changes will almost certainly
get clobbered the next time man/4 is merged with trunk/manual.

File size: 10.7 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; -setup-mode : When locating extension, 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
124=== Toplevel commands
125
126The toplevel loop understands a number of special commands:
127
128; ,? : Show summary of available toplevel commands.
129
130; ,l FILENAME ... : Load files with given {{FILENAME}}s
131
132; ,ln FILENAME ... : Load files and print result(s) of each top-level expression.
133
134; ,p EXP : Pretty-print evaluated expression {{EXP}}.
135
136; ,d EXP : Describe result of evaluated expression {{EXP}}.
137
138; ,du EXP : Dump contents of the result of evaluated expression {{EXP}}.
139
140; ,dur EXP N : Dump {{N}} bytes of the result of evaluated expression {{EXP}}.
141
142; ,exn : Describes the last exception that occurred and adds it to the result history (it can be accessed using the {{#}} notation).
143
144; ,q : Quit the interpreter.
145
146; ,r : Show system information.
147
148; ,s TEXT ... : Execute shell-command.
149
150; ,t EXP : Evaluate form and print elapsed time.
151
152; ,x EXP : Pretty-print macroexpanded expression {{EXP}} (the expression is not evaluated).
153
154; ,tr SYMBOL ... : Enables tracing of the toplevel procedures with the given names.
155
156<enscript highlight=scheme>
157#;1> (fac 10)                       ==> 3628800
158#;2> ,tr fac
159#;3> (fac 3)
160|(fac 3)
161| (fac 2)
162|  (fac 1)
163|   (fac 0)
164|   fac -> 1
165|  fac -> 1
166| fac -> 2
167|fac -> 6                          ==> 6
168#;4> ,utr fac
169#;5> (fac 3)                        ==> 6
170</enscript>
171k
172
173; ,utr SYMBOL ... : Disables tracing of the given toplevel procedures.
174
175; ,br SYMBOL ... : Sets a breakpoint at the procedures named {{SYMBOL ...}}. Breakpoint can also be trigged using the {{breakpoint}} procedure.
176
177; ,ubr SYMBOL ... : Removes breakpoints.
178
179; ,c : Continues execution from the last invoked breakpoint.
180
181; ,breakall : Enable breakpoints for all threads (this is the default).
182
183; ,breakonly THREAD : Enable breakpoints only for the thread returned by the expression {{THREAD}}.
184
185; ,info : Lists traced procedures and breakpoints.
186
187; ,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.
188
189You can define your own toplevel commands using the {{toplevel-command}}
190procedure:
191
192=== toplevel-command
193
194 [procedure] (toplevel-command SYMBOL PROC [HELPSTRING])
195
196Defines or redefines a toplevel interpreter command which can be invoked by entering
197{{,SYMBOL}}. {{PROC}} will be invoked when the command is entered and may
198read any required argument via {{read}} (or {{read-line}}). If the optional
199argument {{HELPSTRING}} is given, it will be listed by the {{,?}} command.
200
201=== History access
202
203The interpreter toplevel accepts the special object {{#[INDEX]}} which
204returns the result of entry number {{INDEX}} in the history list. If the expression
205for that entry resulted in multiple values, the first result (or an unspecified value for no values)
206is returned. If no {{INDEX}} is given (and if a whitespace or closing paranthesis character follows
207the {{#}}, then the result of the last expression is returned.
208Note that the value returned is implicitly quoted.
209
210=== set-describer!
211
212 [procedure] (set-describer! TAG PROC)
213
214Sets a custom description handler that invokes {{PROC}} when the {{,d}} command is invoked
215with a record-type object that has the type {{TAG}} (a symbol). {{PROC}} is called with
216two arguments: the object to be described and an output-port. It should write a possibly useful
217textual description of the object to the passed output-port. For example:
218
219 #;1> (define-record-type point (make-point x y) point?
220        (x point-x)
221        (y point-y))
222 #;2> (set-describer! 'point
223        (lambda (pt o)
224          (print "a point with x=" (point-x pt) " and y=" (point-y pt))))
225 #;3> ,d (make-point 1 2)
226 a point with x=1 and y=2
227
228=== Auto-completion and edition
229
230On platforms that support it, it is possible to get auto-completion of symbols,
231history (over different {{csi}} sessions) and a more feature-full
232editor for the expressions you type
233using the [[http://www.call-with-current-continuation.org/eggs/readline.html]] egg by
234Tony Garnock Jones.
235It is very useful for interactive use of csi.
236
237To enable it install the egg and put this in your {{~/.csirc}} file:
238
239 (use readline regex)
240 (current-input-port (make-gnu-readline-port))
241 (gnu-history-install-file-manager
242   (string-append (or (getenv "HOME") ".") "/.csi.history"))
243
244More details are available in [[http://www.call-with-current-continuation.org/eggs/readline.html|the egg's documentation]].
245
246
247---
248Previous: [[Using the compiler]]
249
250Next: [[Supported language]]
Note: See TracBrowser for help on using the repository browser.