| 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. |