1SCHEME2JS(1) Scheme to JavaScript compiler SCHEME2JS(1)
2
6 scheme2js - compiles Scheme programs to JavaScript
7
9 scheme2js [-h|--help] [--version] [-v|--verbose] [--js-dot-notation]
10 [--bigloo-modules] [--compress] [--infotron] [--encapsulate-modules]
11 [--export-globals] [--allow-unresolved] [--js-this] [--js-return]
12 [--statics-suffix suffix] [--constant-runtime] [--indent width] [-O
13 level] [--tailrec] [--while] [--inlining] [--max-inline-size size]
14 [--rec-inline-nb nb] [--var-elimination] [--propagation] [--con‐
15 stant-propagation] [--bigloo-runtime-eval] [--correct-modulo] [--opti‐
16 mize-calls] [--optimize-boolify] [--optimize-consts] [--trampoline]
17 [--max-tail-depth depth] [--suspend-resume] [--call/cc] [-g] [-d stage]
18 [-I dir] -o outfile infile
19
21 scheme2js takes infile and writes to outfile. If in/outfile is '-'
22 stdin/out is used. The input must be a Scheme file. scheme2js trans‐
23 lates the program into JavaScript.
24
26 All boolean options can be prefixed with 'no-', to deactivate them. For
27 example '--no-js-dot-notation' would disable JavaScript's dot-notation.
28 Options are evaluated in order. If conflicting options are given, the
29 last entry wins. This allows to use -O and then to adjust the values
30 subsequently.
31 IO
33 -o outfile
34 Write output into outfile. If outfile equals "-" then the
35 result will be printed to stdout.
36 -I dir
38 Add dir to Include-path. This path will be searched for
39 imported modules.
40 infile
42 The Scheme Input-file.
43 --compress
45 Compress the generated output. Nearly all unnecessary spaces
46 are removed.
47 INFORMATION
49 -h|--help
50 Prints a help-message.
51 --version
53 Prints the version of scheme2js.
54 -v|--verbose
56 Activate verbose output.
57 JAVASCRIPT INTERFACE
59 --js-dot-notation
60 Allow JavaScript dot-notation in source-file. This allows
61 access to object-properties like o.x.
62 --infotron
64 Activates support for Infotrons. See Section Infotron for more
65 details.
66 --bigloo-modules
68 Uses Bigloo style module declarations (see the Modules section
69 below).
70 --encapsulate-modules
72 Wrap the module (the compiled file) into an anonymous function.
73 Global variables that are not exported (for instance top-level
74 'let'-variables) thus do not pollute the JavaScript top-level.
75 --export-globals
77 Export all global variables. Variables introduced by global
78 'let's are not affected by this flag. By default all global
79 variables of files without 'module'-clause are exported. Files
80 with 'module'-clause do only export variables declared in the
81 module-clause.
82 --allow-unresolved
84 Variables that are unresolved are supposed to be JavaScript
85 variables or exported variables from other modules. By default
86 files without 'module'-clause allow unresolved. Files with a
87 'module'-clause yield error-messages on unknown variables.
88 --js-this
90 Allow the access of JavaScript's 'this' inside Scheme proce‐
91 dures.
92 --js-return
94 Introduces a special form: 'return', which has the same seman‐
95 tics as JavaScript's 'return'.
96 --constant-runtime
98 Assume runtime is constant. Disallows assignments to run‐
99 time-functions. When enabled the interface files runtime_inter‐
100 face.js and runtime_interface_callcc.js are not needed anymore.
101 --statics-suffix suffix
103 Sets the suffix for static variables. Static variables are
104 global variables that are not exported. This avoids name-clashes
105 with non-exported variables of different modules. If a module is
106 encapsulated, then this flag has no effect. By default '_' fol‐
107 lowed by the file-name without extension is used (which is the
108 same as the module's name).
109 --indent width
111 Sets the indentation width for the produced code.
112 OPTIMIZATIONS
114 --tailrec
115 Transform (obvious) tail-recursive loops into 'while'-loops.
116 --while
118 Searches for common loop-pattern. Improves the generated
119 'while'-loops.
120 --inlining
122 Inlines (small) functions, and functions, that are only used
123 once (-> no code size increase).
124 --max-inline-size size
126 Only inline functions smaller than size. The calculated size
127 is a rough estimate of the final code-size. Small functions have
128 a size of about 30.
129 --rec-inline-nb nb
131 Inline at most nb nested functions. That is, if a function has
132 been inlined, continue inlining inside the inlined function's
133 body, but only nb times. A value of 1 forbits inlining inside
134 the body of an inlined function. Functions that are only called
135 at one location are exempted from this limitation.
136 --var-elimination
138 Reduce the number of variables, by substituting variables.
139 '(let ((x expr)) (let ((y x)) ....))' becomes '(let ((y expr))
140 ...)'.
141 --propagation
143 Enables constant-propagation. Whenever possible var-references
144 are propagated too: if variable 'x' has the same value as 'y'
145 the references to 'x' are replaced by a reference to 'y'.
146 --constant-propagation
148 Propagates constant variables. Suppose 'x' is initialized with
149 a constant value 'c'. Then all references to 'x' are replaced
150 by 'c'
151 --bigloo-runtime-eval
153 Use a Bigloo 'eval' during compilation when a constant expres‐
154 sions (for instance '(+ 2 5)) is encountered. Only a limited
155 'safe' subset of runtime-functions are evaluated this way. How‐
156 ever the result might not be the same as if evaluated at run‐
157 time. For example (/ 5 2) would yield 2 when evaluated by
158 Bigloo, but yields 2.5 when evaluated at runtime.
159 --correct-modulo
161 The semantics of Scheme's and JavaScript's modulo differ. With
162 this flag the more expensive R5RS modulo is simulated in
163 JavaScript. Only of relevance when --optimize-calls is acti‐
164 vated.
165 --optimize-calls
167 Peephole optimization of small runtime-functions. Runtime func‐
168 tions like '+', 'null?', etc. are directly inlined with their
169 JavaScript equivalent and do not invoke any function-call.
170 --optimize-boolify
172 During boolification do not test against 'false' if the expres‐
173 sion is known to be of type bool.
174 --optimize-consts
176 Store explicit constants (like lists and vectors) in global
177 variables, so they are not recreated.
178 -O level
180 Sets the optimization level (default is -O 1).
181 Each optimization level enables/disables several flags at once:
182 -O0 --no-tailrec --no-inlining --no-inline-runtime --no-con‐
184 stant-runtime --no-propagation --no-constant-propagation
185 --no-while --correct-modulo --no-optimize-calls
186 --no-optimize-boolify --no-optimize-set!
187 --max-tail-depth 40 --no-var-elimination --no-opti‐
188 mize-consts --no-bigloo-runtime-eval
189 -O1 --tailrec --inlining --max-rec-inline 3 --max-inline-size
191 30 --inline-runtime --constant-runtime --propagation
192 --constant-propagation --while --no-correct-modulo
193 --optimize-calls --optimize-boolify --optimize-set!
194 --max-tail-depth 40 --var-elimination --optimize-consts
195 --no-bigloo-runtime-eval
196 -O2 --tailrec --inlining --max-rec-inline 1 --max-inline-size
198 15 --no-inline-runtime --constant-runtime --propagation
199 --constant-propagation --while --no-correct-modulo
200 --optimize-calls --optimize-boolify --optimize-set!
201 --max-tail-depth 40 --var-elimination --optimize-consts
202 --bigloo-runtime-eval
203 -O3 --tailrec --inlining --max-rec-inline 4 --max-inline-size
205 45 --inline-runtime --constant-runtime --propagation
206 --constant-propagation --while --no-correct-modulo
207 --optimize-calls --optimize-boolify --optimize-set!
208 --max-tail-depth 40 --var-elimination --optimize-consts
209 -Obench
211 --tailrec --inlining --max-rec-inline 4 --max-inline-size
212 45 --inline-runtime --constant-runtime --propagation
213 --constant-propagation --while --no-correct-modulo
214 --optimize-calls --optimize-boolify --optimize-set!
215 --max-tail-depth 40 --var-elimination --optimize-consts
216 --bigloo-runtime-eval
217 TRAMPOLINES AND CALL/CC
219 --trampoline
220 Enables trampolines. The given implementation does not provide
221 naive trampolines, but a more efficient version that only
222 returns trampolines after a constant number of tail-calls.
223 --max-tail-depth depth
225 Sets the maximum depth of consecutive tail-calls before a tram‐
226 poline is returned. This option is only relevant when trampo‐
227 lines are enabled.
228 --suspend-resume
230 Enables 'suspend/resume', a weaker (but faster) version of
231 'call/cc'. A call to 'suspend' captures the current continua‐
232 tion. 'Suspend' does not return however, and the only way to
233 continue the execution is to invoke the captured continuation.
234 The captured continuation can only be invoked once. This form is
235 useful, when the program needs to pause, and wait for an event.
236 --call/cc
238 Enables 'call/cc'.
239 --extern-invokes-call/cc
241 Assume imported variables (or unresolved variables) call
242 'call/cc' (even if they do not have a 'call/cc' entry in their
243 'export'-clause).
244 DEBUG
246 -g
247 Adds debugging information.
248 -d stage
250 Depending on 'stage' either print the expanded source, or a
251 Scheme-version of the AST at the chosen compilation stage (into
252 outfile). If you really need this, have a look at the source
253 for valid 'stage's.
254
256 share/runtime.js
257 The runtime stripped of 'call/cc'-related procedures.
258 share/runtime_interface.js
260 Compiled programs access the runtime through the variables
261 declared in this file. Only needed, when '--constant-runtime' is
262 not used.
263 share/runtime_callcc.js
265 The 'call/cc' part of the runtime. If a program is compiled
266 without 'call/cc' or 'suspend/resume' support, then this file is
267 not needed.
268 share/runtime_interface_callcc.js
270 Compiled programs access the 'call/cc' runtime through vari‐
271 ables declared in this file. Only needed, when the program has
272 been compiled with 'call/cc' or 'suspend/resume' support and
273 '--constant-runtime' is not activated.
274
276 Bigger programs can be split into modules. In this case the first
277 expression of the input-file must be a module-clause. Currently two
278 module-clauses are supported. An old deprecated one, and a new one that
279 has been modeled after Bigloo.
280 For the new one see Bigloo. Contrary to Bigloo the file-name and the
281 module-name must be the same (thus avoiding the need for an '.afile').
282 This limitation might be changed in future versions. In addition to the
283 Bigloo clauses a 'JS' and 'scheme2js-pragma' clause is supported. The
284 'JS' clause serves to import JavaScript variables. The
285 'scheme2js-pragma' to add additional optimization information for
286 exported variables. It is an A-List with the variable-name used as key.
287 Here an example with all recognized optimization-clauses:
288 Explanatory example:
289 (module my-module ;; filename must be my-module.scm/sch
290 (import some-other-module
291 and-a-second-module)
292 (include "some-file"
293 "another-file")
294 (export (macro macro1) ;; a (define-macro (macro1 ..) must be in the source
295 (macro macro2)) ;; same here
296 (export (my-fun::bool arg ...) ;; a function returning a bool.
297 my-var) ;; export simply a variable
298 (scheme2js-pragma ;; optimization-information for exported variables.
299 (my-fun (JS "myFun") ;; use "myFun" as JS id for this variable.
300 (call/cc? #t) ;; this function may invoke call/cc,
301 (call/cc-params (0 2)))) ;; but only if arg 0 or 2 invoke call/cc.
302 (JS "some_JS_var")) ;; import 'some_JS_var' as 'some_JS_var'
303 (JS scheme-var) ;; import mangled form of 'scheme-var' as 'scheme-var'
304 (JS (scm-var "jsVar") ;; import 'jsVar' as 'scm-var'
305 (scm-var2 jsVar2))) ;; imort 'jsVar2' as 'scm-var2' (no mangling)
306 Here is an example for the old deprecated module-form:
308 (module my-module ;; filename must be my-module.scm/sch
309 (import some-other-module
310 and-a-second-module)
311 (include "some-file"
312 "another-file")
313 (export-macros ;; export (and use in module) macros.
314 (define-macro (macro-name ...) (...))) ;; same syntax as if in module-body.
315 (export (my-fun?
316 (JS js-id) ;; the JS-id
317 (type bool) ;; declare (return-)type of variable/function.
318 (constant? #t) ;; must not be changed from the outside
319 (call/cc? #t) ;; may invoke call/cc
320 (call/cc-params (0 2))) ;; but only if arg 0 or 2 invoke call/cc.
321 my-var ;; just export the variable without any additional information.
322 my-fun2) ;; works for functions too.
323 (JS ;; import from JavaScript (same syntax as 'export')
324 (time-out-set! (JS setTimeout)) ;; import setTimeout as time-out-set!
325 window)) ;; import window as window
326 The module-name must be equal to the filename (minus path and exten‐
328 sion).
329 When exporting variables, only the variable-name is needed. The 'JS'
330 entry allows to export functions to JavaScript under a different name,
331 and the remaining entries help scheme2js to optimize the program.
332 When module 'foo' is imported, then a file foo.scm or foo.sch is
333 searched in the include-directories (given with -I ).
334 Modules without any top-level (but with a module-clause) can be used to
335 declare JavaScript functions and make them accessible to Scheme mod‐
336 ules.
337
339 Infotrons are modules for JDA (http://foundry.maya.com/jda/). When
340 activated with '--infotron' scheme2js recognizes modules starting with
341 an 'infotron' clause as infotrons and compiles them accordingly. Main
342 changes to plain modules are:
343 - infotrons start with 'infotron' instead of 'module',
344 - they must not export any variables or macros
345 - they can declare 'uuid'-clauses (or the more convenient 'uuid-seed'
346 string which is then used to construct a uuid),
347 - they can declare 'properties' that are accepted during the initial
348 configuration.
349 - they can define the name for the initial configuration in the 'con‐
350 fig-name' clause. By default 'config' is used. and
351 - they can declare the inputs ('iterms') and outputs ('oterms')
352 - top-level must have defines at top.
353 Example:
354 (infotron jsAlert
355 (uuid-seed "jsAlert - Florian Loitsch - Inria")
356 (iterms (trigger_in on_trigger 10))
357 (oterms close_event_out)
358 (properties message))
359 (define (on_trigger msg)
361 (alert config.message)
362 (close_event_out msg))
363
366 Hop (http://hop.inria.fr)
367 JDA (http://foundry.maya.com/jda/)
368 R5RS (http://www.schemers.org/Documents/Standards/R5RS/)
369
371 Due to limitations in JavaScript, there are no integers (exact num‐
372 bers).
373 At the moment scheme2js does not support hygienic macros.
374 The 'eval' function is still missing, too.
375
377 Florian Loitsch
378 Email: florian.loitsch@sophia.inria.fr
379
381 Version: 20110717
382Scheme to JavaScript compiler 17 July 2011 SCHEME2JS(1)