Debian Codegraph @

tests/data/notebooks/outputs/ipynb_to_myst/Reference Guide for Calysto Scheme.md

raw
1 ---
2 kernelspec:
3 display_name: Calysto Scheme (Python)
4 language: scheme
5 name: calysto_scheme
6 ---
7
8 <img src="images/logo-64x64.png"/>
9 <h1>Reference Guide for Calysto Scheme</h1>
10
11 [Calysto Scheme](https://github.com/Calysto/calysto_scheme) is a real Scheme programming language, with full support for continuations, including call/cc. It can also use all Python libraries. Also has some extensions that make it more useful (stepper-debugger, choose/fail, stack traces), or make it better integrated with Python.
12
13 In Jupyter notebooks, because Calysto Scheme uses [MetaKernel](https://github.com/Calysto/metakernel/blob/master/README.rst), it has a fully-supported set of "magics"---meta-commands for additional functionality. This includes running Scheme in parallel. See all of the [MetaKernel Magics](https://github.com/Calysto/metakernel/blob/master/metakernel/magics/README.md).
14
15 Calysto Scheme is written in Scheme, and then translated into Python (and other backends). The entire functionality lies in a single Python file: https://github.com/Calysto/calysto_scheme/blob/master/calysto_scheme/scheme.py However, you can easily install it (see below).
16
17 Please see [Calysto Scheme Language](Calysto%20Scheme%20Language.ipynb) for more details on the Calysto Scheme language.
18
19 ## Installation
20
21 You can install Calysto Scheme with Python3:
22
23 ```
24 pip3 install --upgrade calysto-scheme --user -U
25 python3 -m calysto_kernel install --user
26 ```
27
28 or in the system kernel folder with:
29
30 ```
31 sudo pip3 install --upgrade calysto-scheme -U
32 sudo python3 -m calysto_kernel install
33 ```
34
35 Change pip3/python3 to use a different pip or Python. The version of Python used will determine how Calysto Scheme is run.
36
37 Use it in the console, qtconsole, or notebook with IPython 3:
38
39 ```
40 ipython console --kernel calysto_scheme
41 ipython qtconsole --kernel calysto_scheme
42 ipython notebook --kernel calysto_scheme
43 ```
44
45 In addition to all of the following items, Calysto Scheme also has access to all of Python's builtin functions, and all of Python's libraries. For example, you can use `(complex 3 2)` to create a complex number by calling Python's complex function.
46
47 ## Jupyter Enhancements
48
49 When you run Calysto Scheme in Jupyter (console, notebook, qtconsole, etc.) you get:
50
51 * TAB completions of Scheme functions and variable names
52 * display of rich media
53 * stepper/debugger
54 * magics (% macros)
55 * shell commands (! command)
56 * LaTeX equations
57 * LaTeX-style variables
58 * Python integration
59
60 +++
61
62 ### LaTeX-style variables
63
64 Calysto Scheme allows you to use LaTeX-style variables in code. For example, if you type:
65
66 ```
67 \beta
68 ```
69
70 with the cursor right after the 'a' in beta, and then press TAB, it will turn into the unicode character:
71
72 ```
73 β
74 ```
75
76 There are nearly 1300 different symbols defined (thanks to the Julia language) and documented here:
77
78 http://docs.julialang.org/en/release-0.4/manual/unicode-input/#man-unicode-input
79
80 Calysto Scheme may not implement all of those. Some useful and suggestive ones:
81
82 * \pi - π
83 * \Pi - Π
84 * \Sigma - Σ
85 * \_i - subscript i, such as vectorᵢ
86
87 ```{code-cell} scheme
88 (define α 67)
89 ```
90
91 ```{code-cell} scheme
92 α
93 ```
94
95 ```{code-cell} scheme
96 (define i 2)
97 (define vectorᵢ (vector-ref (vector 0 6 3 2) i))
98 vectorᵢ
99 ```
100
101 ### Rich media
102
103 ```{code-cell} scheme
104 (import "calysto.display")
105 ```
106
107 ```{code-cell} scheme
108 (calysto.display.HTML "This is <b>bold</b>, <i>italics</i>, <u>underlined</u>.")
109 ```
110
111 ```{code-cell} scheme
112 (import "calysto.graphics")
113 ```
114
115 ```{code-cell} scheme
116 (define canvas (calysto.graphics.Canvas))
117 ```
118
119 ```{code-cell} scheme
120 (define ball (calysto.graphics.Circle '(150 150) 100))
121 ```
122
123 ```{code-cell} scheme
124 (ball.draw canvas)
125 ```
126
127 ### Shell commands
128
129 ```{code-cell} scheme
130 ! ls /tmp
131 ```
132
133 ### Stepper/Debugger
134
135 Here is what the debugger looks like:
136
137 <img src="images/stepper_debugger.png">
138
139 It has breakpoints (click in left margin). You must press Stop to exit the debugger.
140
141 +++
142
143 ```scheme
144 %%debug
145
146 (begin
147 (define x 1)
148 (set! x 2)
149 )
150 ```
151
152 +++
153
154 ### Python Integration
155
156 You can import and use any Python library in Calysto Scheme.
157
158 In addition, if you wish, you can execute expressions and statements in a Python environment:
159
160 ```{code-cell} scheme
161 (python-eval "1 + 2")
162 ```
163
164 ```{code-cell} scheme
165 (python-exec
166 "
167 def mypyfunc(a, b):
168 return a * b
169 ")
170 ```
171
172 This is a shared environment with Scheme:
173
174 ```{code-cell} scheme
175 (mypyfunc 4 5)
176 ```
177
178 You can use `func` to turn a Scheme procedure into a Python function, and `define!` to put it into the shared environment with Python:
179
180 ```{code-cell} scheme
181 (define! mypyfunc2 (func (lambda (n) n)))
182 ```
183
184 ```{code-cell} scheme
185 (python-eval "mypyfunc2(34)")
186 ```
187
188 # Differences Between Languages
189
190 ## Major differences between Scheme and Python
191
192 1. In Scheme, double quotes are used for strings and may contain newlines
193 1. In Scheme, a single quote is short for (quote ...) and means "literal"
194 1. In Scheme, everything is an expression and has a return value
195 1. Python does not support macros (e.g., extending syntax)
196 1. In Python, "if X" is false if X is None, False, [], (,) or 0. In Scheme, "if X" is only false if X is #f or 0
197 1. Calysto Scheme uses continuations, not the call stack. However, for debugging there is a pseudo-stack when an error is raised. You can turn that off with (use-stack-trace #f)
198 1. Scheme procedures are not Python functions, but there are means to use one as the other.
199
200 ## Major Differences Between Calysto Scheme and other Schemes
201
202 1. define-syntax works slightly differently
203 1. In Calysto Scheme, #(...) is short for '#(...)
204 1. Calysto Scheme is missing many standard functions (see list at bottom)
205 1. Calysto Scheme has a built-in amb operator called `choose`
206 1. For debugging there is a pseudo-stack when errors are raised in Calysto Scheme. You can turn that off with (use-stack-trace #f)
207
208 ### Stack Trace
209
210 Calysto Scheme acts as if it has a call stack, for easier debugging. For example:
211
212 ```{code-cell} scheme
213 (define fact
214 (lambda (n)
215 (if (= n 1)
216 q
217 (* n (fact (- n 1))))))
218 ```
219
220 ```{code-cell} scheme
221 (fact 5)
222 ```
223
224 To turn off the stack trace on error:
225
226 ```scheme
227 (use-stack-trace #f)
228 ```
229 That will allow infinite recursive loops without keeping track of the "stack".
230
231 +++
232
233 # Calysto Scheme Variables
234
235 ## SCHEMEPATH
236 SCHEMEPATH is a list of search directories used with (load NAME). This is a reference, so you should append to it rather than attempting to redefine it.
237
238 ```{code-cell} scheme
239 SCHEMEPATH
240 ```
241
242 ```{code-cell} scheme
243 (set-cdr! (cdr SCHEMEPATH) (list "/var/modules"))
244 ```
245
246 ```{code-cell} scheme
247 SCHEMEPATH
248 ```
249
250 ## Getting Started
251
252 Note that you can use the word `lambda` or \lambda and then press [TAB]
253
254 ```{code-cell} scheme
255 (define factorial
256 (λ (n)
257 (cond
258 ((zero? n) 1)
259 (else (* n (factorial (- n 1)))))))
260 ```
261
262 ```{code-cell} scheme
263 (factorial 5)
264 ```
265
266 ## define-syntax
267 (define-syntax NAME RULES): a method for creating macros
268
269 ```{code-cell} scheme
270 (define-syntax time
271 [(time ?exp) (let ((start (current-time)))
272 ?exp
273 (- (current-time) start))])
274 ```
275
276 ```{code-cell} scheme
277 (time (car '(1 2 3 4)))
278 ```
279
280 ```{code-cell} scheme
281 ;;---------------------------------------------------------------------
282 ;; collect is like list comprehension in Python
283
284 (define-syntax collect
285 [(collect ?exp for ?var in ?list)
286 (filter-map (lambda (?var) ?exp) (lambda (?var) #t) ?list)]
287 [(collect ?exp for ?var in ?list if ?condition)
288 (filter-map (lambda (?var) ?exp) (lambda (?var) ?condition) ?list)])
289
290 (define filter-map
291 (lambda (f pred? values)
292 (if (null? values)
293 '()
294 (if (pred? (car values))
295 (cons (f (car values)) (filter-map f pred? (cdr values)))
296 (filter-map f pred? (cdr values))))))
297 ```
298
299 ```{code-cell} scheme
300 (collect (* n n) for n in (range 10))
301 ```
302
303 ```{code-cell} scheme
304 (collect (* n n) for n in (range 5 20 3))
305 ```
306
307 ```{code-cell} scheme
308 (collect (* n n) for n in (range 10) if (> n 5))
309 ```
310
311 ```{code-cell} scheme
312 ;;---------------------------------------------------------------------
313 ;; for loops
314
315 (define-syntax for
316 [(for ?exp times do . ?bodies)
317 (for-repeat ?exp (lambda () . ?bodies))]
318 [(for ?var in ?exp do . ?bodies)
319 (for-iterate1 ?exp (lambda (?var) . ?bodies))]
320 [(for ?var at (?i) in ?exp do . ?bodies)
321 (for-iterate2 0 ?exp (lambda (?var ?i) . ?bodies))]
322 [(for ?var at (?i ?j . ?rest) in ?exp do . ?bodies)
323 (for ?var at (?i) in ?exp do
324 (for ?var at (?j . ?rest) in ?var do . ?bodies))])
325
326 (define for-repeat
327 (lambda (n f)
328 (if (< n 1)
329 'done
330 (begin
331 (f)
332 (for-repeat (- n 1) f)))))
333
334 (define for-iterate1
335 (lambda (values f)
336 (if (null? values)
337 'done
338 (begin
339 (f (car values))
340 (for-iterate1 (cdr values) f)))))
341
342 (define for-iterate2
343 (lambda (i values f)
344 (if (null? values)
345 'done
346 (begin
347 (f (car values) i)
348 (for-iterate2 (+ i 1) (cdr values) f)))))
349 ```
350
351 ```{code-cell} scheme
352 (define matrix2d
353 '((10 20)
354 (30 40)
355 (50 60)
356 (70 80)))
357
358 (define matrix3d
359 '(((10 20 30) (40 50 60))
360 ((70 80 90) (100 110 120))
361 ((130 140 150) (160 170 180))
362 ((190 200 210) (220 230 240))))
363 ```
364
365 ```{code-cell} scheme
366 (begin
367 (define hello 0)
368 (for 5 times do (set! hello (+ hello 1)))
369 hello
370 )
371 ```
372
373 ```{code-cell} scheme
374 (for sym in '(a b c d) do (define x 1) (set! x sym) (print x))
375 ```
376
377 ```{code-cell} scheme
378 (for n in (range 10 20 2) do (print n))
379 ```
380
381 ```{code-cell} scheme
382 (for n at (i j) in matrix2d do (print (list n 'coords: i j)))
383 ```
384
385 ```{code-cell} scheme
386 (for n at (i j k) in matrix3d do (print (list n 'coords: i j k)))
387 ```
388
389 ```{code-cell} scheme
390 (define-syntax scons
391 [(scons ?x ?y) (cons ?x (lambda () ?y))])
392
393 (define scar car)
394
395 (define scdr
396 (lambda (s)
397 (let ((result ((cdr s))))
398 (set-cdr! s (lambda () result))
399 result)))
400
401 (define first
402 (lambda (n s)
403 (if (= n 0)
404 '()
405 (cons (scar s) (first (- n 1) (scdr s))))))
406
407 (define nth
408 (lambda (n s)
409 (if (= n 0)
410 (scar s)
411 (nth (- n 1) (scdr s)))))
412
413 (define smap
414 (lambda (f s)
415 (scons (f (scar s)) (smap f (scdr s)))))
416
417 (define ones (scons 1 ones))
418
419 (define nats (scons 0 (combine nats + ones)))
420
421 (define combine
422 (lambda (s1 op s2)
423 (scons (op (scar s1) (scar s2)) (combine (scdr s1) op (scdr s2)))))
424
425 (define fibs (scons 1 (scons 1 (combine fibs + (scdr fibs)))))
426
427 (define facts (scons 1 (combine facts * (scdr nats))))
428
429 (define ! (lambda (n) (nth n facts)))
430 ```
431
432 ```{code-cell} scheme
433 (! 5)
434 ```
435
436 ```{code-cell} scheme
437 (nth 10 facts)
438 ```
439
440 ```{code-cell} scheme
441 (nth 20 fibs)
442 ```
443
444 ```{code-cell} scheme
445 (first 30 fibs)
446 ```
447
448 ## for-each
449 (for-each PROCEDURE LIST): apply PROCEDURE to each item in LIST; like `map` but don't return results
450
451 ```{code-cell} scheme
452 (for-each (lambda (n) (print n)) '(3 4 5))
453 ```
454
455 ## format
456 (format STRING ITEM ...): format the string with ITEMS as arguments
457
458 ```{code-cell} scheme
459 (format "This uses formatting ~a ~s ~%" 'apple 'apple)
460 ```
461
462 ## func
463
464 Turns a lambda into a Python function.
465
466 (func (lambda ...))
467
468 ```{code-cell} scheme
469 (func (lambda (n) n))
470 ```
471
472 ## There's more!
473
474 Please see [Calysto Scheme Language](Calysto%20Scheme%20Language.ipynb) for more details on the Calysto Scheme language.