source: project/chicken/branches/release/manual/Using the interpreter @ 7931

Last change on this file since 7931 was 7931, checked in by felix winkelmann, 12 years ago

merged from prerelease branch rev. 7930 - release version 3.0.0; fixed wrong version numbers in some files

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