-
Notifications
You must be signed in to change notification settings - Fork 0
/
s7-scm.html
989 lines (831 loc) · 34 KB
/
s7-scm.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
<!DOCTYPE html>
<html lang="en">
<!-- documentation for s7 -->
<head>
<meta http-equiv="Content-Type" content="text/html;charset=utf-8" >
<title>s7-scm</title>
<style>
EM.red {color:red; font-style:normal}
EM.normal {font-style:normal}
EM.redb {color:red; font-weight: bold; font-style: normal}
EM.error {color:chocolate; font-style:normal}
EM.emdef {font-weight: bold; font-style: normal}
EM.green {color:green; font-style:normal}
EM.gray {color:#505050; font-style:normal}
EM.big {font-size: 20px; font-style: normal;}
EM.bigger {font-size: 30px; font-style: normal;}
EM.def {font-style: normal}
H1 {text-align: center}
UL {list-style-type: none}
A {text-decoration:none}
A:hover {text-decoration:underline}
A.def {font-weight: bold;
font-style: normal;
text-decoration:none;
}
PRE.indented {padding-left: 1.0cm;}
DIV.indented {background-color: #F8F8F0;
padding-left: 0.5cm;
padding-right: 0.5cm;
padding-top: 0.5cm;
padding-bottom: 0.5cm;
margin-bottom: 0.5cm;
border: 1px solid gray;
border-radius: 20px;
-moz-border-radius: 20px;
-webkit-border-radius: 20px;
}
DIV.small {font-size: small;
padding-left: 0.5cm;
padding-right: 0.5cm;
padding-bottom: 0.5cm;
}
DIV.header {margin-top: 60px;
margin-bottom: 30px;
border: 4px solid #00ff00; /* green */
background-color: #eefdee; /* lightgreen */
padding-left: 30px;
}
DIV.shortheader {margin-top: 30px;
margin-bottom: 10px;
border: 4px solid #00ff00; /* green */
background-color: #f5f5dc;
padding-left: 30px;
padding-top: 5px;
padding-bottom: 5px;
width: 20%;
}
DIV.topheader {margin-top: 10px;
margin-bottom: 40px;
border: 4px solid #00ff00; /* green */
background-color: #f5f5dc; /* beige */
font-family: 'Helvetica';
font-size: 30px;
text-align: center;
padding-top: 10px;
padding-bottom: 10px;
}
DIV.separator {margin-top: 30px;
margin-bottom: 10px;
border: 2px solid #00ff00; /* green */
background-color: #f5f5dc; /* beige */
padding-top: 4px;
width: 30%;
border-radius: 4px;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
}
DIV.smallseparator {margin-top: 10px;
margin-bottom: 10px;
border: 2px solid #00ff00; /* green */
background-color: #f5f5dc; /* beige */
padding-top: 4px;
width: 20%;
border-radius: 4px;
-moz-border-radius: 4px;
-webkit-border-radius: 4px;
text-align: center;
}
BODY.body {background-color: #ffffff; /* white */
margin-right: 20px;
margin-left: 20px;
}
DIV.listener {background-color: #f0f8ff;
font-family: 'Monospace';
padding-left: 6px;
padding-right: 6px;
padding-bottom: 4px;
margin-left: 1.0cm;
margin-right: 4.0cm;
border: 2px solid #a0a0a0;
}
LI.li_header {padding-top: 20px;}
</style>
</head>
<body class="body">
<div class="topheader" id="s7examples">s7 examples</div>
<ul>
<li><a href="s7-scm.html#cload">cload.scm</a>
<ul>
<li><a href="s7-scm.html#libc">libc</a>
<li><a href="s7-scm.html#libgsl">libgsl</a>
<li><a href="s7-scm.html#libgdbm">libgdbm</a>
</ul>
<li><a href="s7-scm.html#case">case.scm</a>
<li><a href="s7-scm.html#debug">debug.scm</a>
<li><a href="s7-scm.html#lint">lint.scm</a>
<li><a href="s7-scm.html#schemerepl">repl.scm and nrepl.scm</a>
</ul>
<p>The s7 tarball includes several scheme files:
</p>
<ul>
<li>case.scm provides case*, an extension of case for pattern matching
<li>cload.scm is a wrapper for the FFI stuff described above
<li>debug.scm provides various debugging aids such as trace, break, and watch
<li>json.scm is a JSON reader/writer, but I got side-tracked
<li>lint.scm is the s7 equivalent of the ancient C program named lint (modern equivalent: cppcheck)
<li>loop.scm is Rick Taube's CL loop macro
<li>mockery.scm has mock data libraries (openlets masquerading as various data types)
<li>profile.scm is a profiler
<li>r7rs.scm implements some of r7rs-small
<li>reactive.scm implements some reactive programming macros (set!, let)
<li>repl.scm is a vt-100 based repl
<li>nrepl.scm is a notcurses based repl
<li>s7test.scm is a regression test for s7
<li>stuff.scm is just some arbitrary stuff
<li>write.scm has a pretty printer
</ul>
<p>
libc.scm, libgsl.scm, libm.scm, libdl.scm, notcurses_s7.c, libutf8proc.scm, and libgdbm.scm tie the associated
libraries into s7.
gdbinit has some gdb commands for s7.
</p>
<div class="header" id="cload"><h4>cload.scm</h4></div>
<p>cload.scm defines the macro c-define that reduces the overhead
involved in (dynamically) linking C entities into s7.
</p>
<pre class="indented">
(<em class=def id="definecfunction">c-define</em> c-info (prefix "") (headers ()) (cflags "") (ldflags "") output-name)
</pre>
<p>For example, <code>(c-define '(double j0 (double)) "m" "math.h")</code>
links the C math library function j0 into s7 under the name m:j0,
passing it a double argument and getting a double result (a real in s7).
</p>
<p><em>prefix</em> is some arbitrary prefix that you want prepended to various names.
</p>
<p><em>headers</em> is a list of headers (as strings) that the c-info relies on, (("math.h") for example).
</p>
<p><em>cflags</em> are any special C compiler flags that are needed ("-I." in particular), and
<em>ldflags</em> is the similar case for the loader. <em>output-name</em> is the name of the
output C file and associated library. It defaults to "temp-s7-output" followed by a number.
In libm.scm, it is set to "libm_s7" to protect it across cload calls. If cload finds an
up-to-date output C file and shared library, it simply loads the library, rather than
going through all the trouble of writing and compling it.
</p>
<p><em>c-info</em> is a list that describes the C entities that you want to load into s7.
It can be either one list describing one entity, or a list of such lists.
Each description has the form:
</p>
<pre class="indented">
(return-type entity-name-in-C (argument-type...))
</pre>
<p>where each entry is a symbol, and C names are used throughout. So, in the j0
example above, <code>(double j0 (double))</code> says we want access to j0, it returns
a C double, and it takes one argument, also a C double. s7 tries to figure out
what the corresponding s7 type is, but in tricky cases, you should tell it
by replacing the bare type name with a list: <code>(C-type underlying-C-type)</code>. For example,
the Snd function set_graph_style takes an (enum) argument of type graph_style_t.
This is actually an int, so we use <code>(graph_style_t int)</code> as the type:
</p>
<pre class="indented">
(void set_graph_style ((graph_style_t int)))
</pre>
<p>If the C entity is a constant, then the descriptor list has just two entries,
the C-type and the entity name: <code>(int F_OK)</code> for example. The entity name can also be a list:
</p>
<pre class="indented">
((graph_style_t int) (GRAPH_LINES GRAPH_DOTS GRAPH_FILLED GRAPH_DOTS_AND_LINES GRAPH_LOLLIPOPS))
</pre>
<p>This defines all the names in the list as integers.
If the C type has a space ("struct tm*"), use <code>(symbol "struct tm*")</code>
to construct the corresponding symbol.
</p>
<p>The entity is placed in the current s7 environment under the name <code>(string-append prefix ":" name)</code>
where the ":" is omitted if the prefix is null. So in the j0 example, we get in s7 the function m:j0.
c-define returns #t if it thinks the load worked, and #f otherwise.
</p>
<p>There are times when the only straightforward approach is to write the desired
C code directly. To insert C code on the fly, use (in-C "code..."). Two more such
cases that come up all the time: C-function for linkage to functions written
directly in s7 style using in-C, and C-macro for macros in the C header file that
need to be wrapped in #ifdefs.
Here are some examples:
</p>
<pre class="indented">
;;; various math library functions
(c-define '((double j0 (double))
(double j1 (double))
(double erf (double))
(double erfc (double))
(double lgamma (double)))
"m" "math.h")
;;; getenv and setenv
(c-define '(char* getenv (char*)))
(c-define '(int setenv (char* char* int)))
;;; file-exists? and delete-file
(define file-exists? (let () ; define F_OK and access only within this let
(c-define '((int F_OK) (int access (char* int))) "" "unistd.h")
(lambda (arg) (= (access arg F_OK) 0))))
(define delete-file (let ()
(c-define '(int unlink (char*)) "" "unistd.h")
(lambda (file) (= (unlink file) 0)))) ; 0=success
;;; examples from Snd:
(c-define '(char* version_info ()) "" "snd.h" "-I.")
(c-define '(mus_float_t mus_degrees_to_radians (mus_float_t)) "" "snd.h" "-I.")
(c-define '(snd_info* any_selected_sound ()) "" "snd.h" "-I.")
(c-define '(void select_channel (snd_info* int)) "" "snd.h" "-I.")
(c-define '(((graph_style_t int) (GRAPH_LINES GRAPH_DOTS GRAPH_FILLED GRAPH_DOTS_AND_LINES GRAPH_LOLLIPOPS))
(void set_graph_style ((graph_style_t int))))
"" "snd.h" "-I.")
;;; getcwd, strftime
(c-define '(char* getcwd (char* size_t)) "" "unistd.h")
(c-define (list '(void* calloc (size_t size_t))
'(void free (void*))
'(void time (time_t*)) ; ignore returned value
(list (symbol "struct tm*") 'localtime '(time_t*))
(list 'size_t 'strftime (list 'char* 'size_t 'char* (symbol "struct tm*"))))
"" "time.h")
> (let ((p (calloc 1 8))
(str (make-string 32)))
(time p)
(strftime str 32 "%a %d-%b-%Y %H:%M %Z" (localtime p))
(free p)
str)
<em class="gray">"Sat 11-Aug-2012 08:55 PDT\x00 "</em>
;;; opendir, read_dir, closedir
(c-define '((int closedir (DIR*))
(DIR* opendir (char*))
(in-C "static char *read_dir(DIR *p) \
{ \
struct dirent *dirp; \
dirp = readdir(p); \
if (!dirp) return(NULL); \
return(dirp->d_name); \
}")
(char* read_dir (DIR*)))
"" '("sys/types.h" "dirent.h"))
</pre>
<p>C-init inserts its string argument into the initialization section of
the module. In libgsl.scm, for example,
</p>
<pre class="inserted">
(C-init "gsl_set_error_handler(g_gsl_error);")
</pre>
<p>inserts that string (as C code) into libgsl_s7.c toward the beginning of the
libgsl_s7_init function (line 42346 or so).
</p>
<p>When compiling, for the simple cases above, include "-ldl -Wl,-export-dynamic" in the gcc command. So the first
FFI example is built (this is in Linux):
</p>
<pre class="indented">
gcc -c s7.c -I.
gcc -o ex1 ex1.c s7.o -lm -I. -ldl -Wl,-export-dynamic
ex1
> (load "cload.scm")
<em class="gray">c-define-1</em>
> (c-define '(double j0 (double)) "m" "math.h")
<em class="gray">#t</em>
> (m:j0 0.5)
<em class="gray">0.93846980724081</em>
</pre>
<p>See also r7rs.scm, libc.scm, libgsl.scm, libm.scm, libdl.scm, and libgdbm.scm.
libutf8proc.scm exists, but I have not tested it at all.
</p>
<p>The default in the lib*.scm files is to use the C name as the Scheme name.
This collides with (for example) the widespread use of "-", rather than "_" in Scheme, but
I have found it much more straightforward to stick with one name. In cases like
libgsl there are thousands of names, all documented at great length
by the C name. Anyone who wants to use these functions has to start with the C name.
If they are forced to fuss with some annoying Schemely translation of it,
the only sane response is: "forget it! I'll do it in C".
</p>
<div class="indented" id="libc">
<pre>
(require libc.scm)
(define (copy-file in-file out-file)
(with-let (sublet *libc* :in-file in-file :out-file out-file)
;; the rest of the function body exists in the *libc* environment, with the
;; function parameters in-file and out-file imported, so, for example,
;; (open ...) below calls the libc function open.
(let ((infd (open in-file O_RDONLY 0)))
(if (= infd -1)
(error 'io-error "can't find ~S~%" in-file)
(let ((outfd (creat out-file #o666)))
(if (= outfd -1)
(begin
(close infd)
(error 'io-error "can't open ~S~%" out-file))
(let* ((BUF_SIZE 1024)
(buf (malloc BUF_SIZE)))
(do ((num (read infd buf BUF_SIZE) (read infd buf BUF_SIZE)))
((or (<= num 0)
(not (= (write outfd buf num) num)))))
(close outfd)
(close infd)
(free buf)
out-file)))))))
(define (glob->list pattern)
(with-let (sublet *libc* :pattern pattern)
(let ((g (glob.make)))
(glob pattern 0 g)
(let ((res (glob.gl_pathv g)))
(globfree g)
res))))
;; now (load "*.scm") is (for-each load (glob->list "*.scm"))
;; a couple regular expression examples
(with-let (sublet *libc*)
(define rg (regex.make))
(regcomp rg "a.b" 0)
(display (regexec rg "acb" 0 0)) (newline) ; 0 = match
(regfree rg))
(with-let (sublet *libc*)
(define rg (regex.make))
(let ((res (regcomp rg "colou\\?r" 0)))
(if (not (zero? res))
(error 'regex-error "~S: ~S~%" "colou\\?r" (regerror res rg)))
(set! res (regexec rg "The color green" 1 0))
(display res) (newline) ; #i(4 9) = match start/end
(regfree rg)))
</pre>
</div>
<div class="indented" id="libgsl">
<pre>
(require libgsl.scm)
(define (eigenvalues M)
(with-let (sublet *libgsl* :M M)
(let* ((len (sqrt (length M)))
(gm (gsl_matrix_alloc len len))
(m (float-vector->gsl_matrix M gm))
(evl (gsl_vector_complex_alloc len))
(evc (gsl_matrix_complex_alloc len len))
(w (gsl_eigen_nonsymmv_alloc len)))
(gsl_eigen_nonsymmv m evl evc w)
(gsl_eigen_nonsymmv_free w)
(gsl_eigen_nonsymmv_sort evl evc GSL_EIGEN_SORT_ABS_DESC)
(let ((vals (make-vector len)))
(do ((i 0 (+ i 1)))
((= i len))
(set! (vals i) (gsl_vector_complex_get evl i)))
(gsl_matrix_free gm)
(gsl_vector_complex_free evl)
(gsl_matrix_complex_free evc)
vals))))
</pre>
</div>
<p>We can use gdbm (or better yet, mdb), the :readable argument to object->string, and
the fallback methods in the environments to create name-spaces (lets) with billions of
thread-safe local variables, which can be saved and communicated between s7 runs:
</p>
<div class="indented" id="libgdbm">
<pre>
(require libgdbm.scm)
(with-let *libgdbm*
(define *db*
(openlet
(inlet :file (gdbm_open "test.gdbm" 1024 GDBM_NEWDB #o664
(lambda (str) (format *stderr* "gdbm error: ~S~%" str)))
:let-ref-fallback (lambda (obj sym)
(eval-string (gdbm_fetch (obj 'file) (symbol->string sym))))
:let-set-fallback (lambda (obj sym val)
(gdbm_store (obj 'file)
(symbol->string sym)
(object->string val :readable)
GDBM_REPLACE)
val)
:make-iterator (lambda (obj)
(let ((key #f)
(length (lambda (obj) (expt 2 20))))
(#_make-iterator
(let ((+iterator+ #t))
(openlet
(lambda ()
(if key
(set! key (gdbm_nextkey (obj 'file) (cdr key)))
(set! key (gdbm_firstkey (obj 'file))))
(if (pair? key)
(cons (string->symbol (car key))
(eval-string (gdbm_fetch (obj 'file) (car key))))
key))))))))))
(set! (*db* 'str) "123") ; add a variable named 'str with the value "123"
(set! (*db* 'int) 432)
(with-let *db*
(+ int (length str))) ; -> 435
(map values *db*) ; -> '((str . "123") (int . 432))
(gdbm_close (*db* 'file)))
</pre>
<p>See <a href="s7.html#gthreads">gthreads</a> for a C-side example.
</p>
<!-- the overhead of using a data-base is not negligible, although libgdbm is probably not the fastest.
A bare set/ref 200000 times is .002 secs, via let-ref is .005, but via the data-base is .184.
Presumably thread globals won't be in inner loops, so even this looks ok, say 1 million / second.
-->
</div>
<div class="header" id="case"><h4>case.scm</h4></div>
<p>case.scm has case*, a compatible extension of case that includes pattern matching.
<code>(case* selector ((target...) body) ...)</code> uses equivalent? to match the
selector to the targets, evaluating the body associated with the first matching target.
If a target is a list or vector, the elements are checked item by item.
Each target, or element of a list or vector can be a pattern. Patterns
are of the form #<whatever> (undefined constants from s7's pointer of view).
A pattern can be:
</p>
<samp>
<ul>
<li>#<> any expr matches
<li>#<func> expr matches if (func expr)
<li>#<label:func> expr matches as above, expr is saved under "label"
<li>#<label:> any expr matches, and is saved under "label"
<li>#<label> expr must match the value saved under "label"
<li>#<...> skip exprs covered by the ellipsis
<li>#<label:...> skip as above, saved skipped exprs under "label" as a quoted list.
<li> a pattern can have any number of labelled ellipses overall,
<li> but just one unnamed ellipsis, and only one ellipsis per pair or vector
<li>#<label,func:...> a labelled ellipsis which matches if (func expr); expr is the ellipsis list,
<li> label is not optional in this case
<li>#<"regexp"> pattern is a regular expression to be matched against a string
<li>#<label:"regexp"> a labelled regular expression
</ul>
</samp>
<p>If a label occurs in the result body, the expression it labelled is substituted for it.
</p>
<pre class="indented">
(case* x ((3.14) 'pi)) ; returns 'pi if x is 3.14
(case* x ((#<symbol?>))) ; returns #t if x is a symbol
(case* x (((+ 1 #<symbol?>)))) ; matches any list of the form '(+ 1 x) or any symbol in place of "x"
(case* x (((#<symbol?> #<e1:...> (+ #<e2:...>)))
(append #<e1> #<e2>))) ; passed '(a b c d (+ 1 2)), returns '(b c d 1 2)
(case* x ((#<"a.b">))) ; matches if x is a string "a.b" where "." matches anything
(define (palindrome? x)
(case* x
((() (#<>))
#t)
(((#<start:> #<middle:...> #<start>))
(palindrome? #<middle>))
(else #f)))
</pre>
<p>case*'s matching function can be used anywhere.
</p>
<pre class="indented">
(let ((match? ((funclet 'case*) 'case*-match?))) ; this is case*'s matcher
(match? x '(+ #<symbol?> 1))) ; returns #t if x is of the form '(+ x 1), x any symbol
(define match+
(let ((match? ((funclet 'case*) 'case*-match?))
(labels ((funclet 'case*) 'case*-labels))) ; these are the labels and their values
(macro (arg)
(cond ((null? arg) ())
((match? arg '(+ #<a:> (+ #<b:...>))) `(+ ,(labels 'a) ,@(cadr (labels 'b))))
((match? arg '(+ #<> #<>)) `(+ ,@(cdr arg)))
(else #f)))))
;; (match+ (+ 1 (+ 2 3))) -> 6
</pre>
<p>See case.scm and s7test.scm for many more examples, including let and hash-table matching.
</p>
<div class="header" id="debug"><h4>debug.scm</h4></div>
<p>debug.scm has various debugging aids, including trace, break, watch, and a C-style stacktrace.
The *s7* field 'debug controls when these are active, and to what extent.
</p>
<p>(<em class="emdef">trace</em> func) adds a tracepoint to the start of the function or macro func.
(trace) adds such tracing to every subsequently defined function or macro.
(<em class="emdef">untrace</em>) turns off tracing; (untrace func) turns off tracing in func.
Similarly (<em class="emdef">break</em> func) places a breakpoint at the start of func,
(<em class="emdef">unbreak</em> func) removes it. (unbreak) removes all breakpoints.
When a breakpoint is encountered, you are placed in a repl at
that point; type C-q to continue. To trace a variable, use
(<em class="emdef">watch</em> var). watch reports whenever var is set! and
(<em class="emdef">unwatch</em> var) removes the watchpoint.
</p>
<p>
These trace, break and watchpoints are active
only if <em class="emdef">(*s7* 'debug)</em> is positive. If 'debug is 1, existing traces
and breaks are active, but no new ones are added by s7. If 'debug
is 2, s7 adds tracepoints to any subsequently defined (i.e. named) functions and macros.
If (*s7* 'debug) is 3, unnamed functions are also traced.
If any tracing is enabled, you can get a C-style stacktrace by
setting (<em class="emdef">debug-stack</em>) to a vector, then
call (<em class="emdef">show-debug-stack</em>) to see the calls.
</p>
<p>
Besides debug-stack, debug.scm also defines the convenience functions
<em class="emdef">debug-function</em>, <em class="emdef">debug-port</em>, and
<em class="emdef">debug-repl</em>. debug-port is the debugger's
output port, debug-repl drops into a repl at a breakpoint, and debug-function
provides a way to customize the debugger's behavior.
The function <em class="emdef">debug-frame</em> provides a way to examine local variables.
</p>
<pre class="indented">
> (define (g1 x) (+ x 1))
<em class="gray">g1</em>
> (trace g1) ; this loads debug.scm unless it's already loaded, and sets (*s7* 'debug) to 1
<em class="gray">g1</em>
> (procedure-source g1) ; you can add trace-in explicitly (rather than call trace)
<em class="gray">(lambda (x) (trace-in (curlet)) (+ x 1))</em>
> (g1 2)
<em class="gray">(g1 2)</em> ; file/line info is included if relevant
<em class="gray"> -> 3
3</em>
> (break g1)
<em class="gray">g1</em>
> (g1 3)
<em class="gray">break: (g1 3), C-q to exit break
break> x</em> ; this is a repl started at the breakpoint
<em class="gray">3</em>
break> -> 4 ; C-q typed to exit the break
<em class="gray">4</em>
> (define var 1)
<em class="gray">1</em>
> (watch var)
<em class="gray">#<lambda (s v ...)></em> ; this is the new setter for 'var
> (set! var 3)
<em class="gray">var set! to 3
3</em>
> (define lt (inlet 'a 3))
<em class="gray">(inlet 'a 3)</em>
> (watch (lt 'a))
<em class="gray">#<lambda (s v ...)></em>
> (set! (lt 'a) 12)
<em class="gray">let-set! a to 12
12</em>
</pre>
<p>s7test.scm has more examples</p>
<div class="header" id="lint"><h4>lint.scm</h4></div>
<p>lint tries to find errors or infelicities in your scheme code.
To try it:
</p>
<pre class="indented">
(load "lint.scm")
(lint "some-code.scm")
</pre>
<p>
There are several
variables at the start of lint.scm to control additional output:
</p>
<pre class="indented">
*report-unused-parameters*
*report-unused-top-level-functions*
*report-shadowed-variables*
*report-undefined-identifiers*
*report-multiply-defined-top-level-functions*
*report-nested-if*
*report-short-branch*
*report-one-armed-if*
*report-loaded-files*
*report-any-!-as-setter*
*report-doc-strings*
*report-func-as-arg-arity-mismatch*
*report-bad-variable-names*
*report-built-in-functions-used-as-variables*
*report-forward-functions*
*report-sloppy-assoc*
*report-bloated-arg*
*report-clobbered-function-return-value*
*report-boolean-functions-misbehaving*
*report-repeated-code-fragments*
*report-quasiquote-rewrites*
*report-combinable-lets*
</pre>
<p>See lint.scm for more about these switches. You can also extend lint by adding your own code,
or adding your functions to lint's tables, or most simply by defining signatures for your functions.
snd-lint.scm performs these tasks for Snd. (lint exports its innards via *lint*).
lint is not smart about functions defined outside the current file, so *report-undefined-variables*
sometimes gets confused. You'll sometimes get a recommendation from lint that is less than helpful; nobody's perfect.
If it's actually wrong, and not just wrong-headed, please let me know.
Also in lint.scm are html-lint and C-lint. html-lint reads an HTML file looking for
Scheme code. If any is found, it runs s7 and then lint over it, reporting troubles.
Similarly C-lint reads a C file looking for s7_eval_c_string and running lint over its string.
</p>
<div class="header" id="schemerepl"><h4>repl.scm and nrepl.scm</h4></div>
<p>There are three or four repls included with s7.
repl.scm is a textual interface based on vt-100 codes, and nrepl.scm is an
improvement of repl.scm based on the notcurses-core library.
I'll treat repl.scm first, then discuss how nrepl differs from it.
</p>
<div class="separator"></div>
<p>repl.scm implements a repl using vt100 codes and libc.scm. It includes
symbol and filename completion, a history buffer, paren matching,
indentation, multi-line edits, and a debugger window.
To move around in the history buffer, use M-p, M-n or M-. (C-p and C-n are used to move the cursor in the current expression).
You can change the keymap or the prompt; all the repl functions are
accessible through the *repl* environment. One field is 'repl-let which
gives you access to all the repl's internal variables and functions.
Another is 'top-level-let, normally (sublet (rootlet)), which is the environment in
which the repl's evaluation takes place. You can reset the repl back to its
starting point with: <code>(set! (*repl* 'top-level-let) (sublet (rootlet)))</code>.
You can save the current repl state via <code>((*repl* 'save-repl))</code>, and
restore it later via <code>((*repl* 'restore-repl))</code>. The repl's saved state
is in the file save.repl, or the filename can be passed as an argument to save-repl and restore-repl.
</p>
<p>There is one annoying consequence of using (sublet (rootlet)) for the top-level let:
if you define something in the repl, then load a file that expects to find that thing
in rootlet, it won't:
</p>
<pre class="indented">
<1> (define (func x) (+ x 1)) ; func is in (sublet (rootlet))
<em class="gray">func</em>
<2> (load "use-func.scm") ; file contents: (display (func 3))
<em class="red">error</em><em class="gray">: unbound variable func</em>
</pre>
<p>To get around this, either load the file into curlet: <code>(load "use-func.scm" (curlet))</code>,
or use with-let to place the definition in rootlet: <code>(with-let (curlet) (define (func x) (+ x 1)))</code>.
</p>
<p>Meta keys are a problem on the Mac. You can use ESC instead, but that requires
super-human capacities. I stared at replacement control keys, and nothing seemed
right. If you can think of something, it's easy to define replacements: see repl.scm
which has a small table of mappings.
</p>
<p>To run the repl, either build s7 with the compiler flag -DWITH_MAIN,
or conjure up a wrapper:
</p>
<pre class="indented">
#include "s7.h"
int main(int argc, char **argv)
{
s7_scheme *sc = s7_init();
s7_load(sc, "repl.scm");
s7_eval_c_string(sc, "((*repl* 'run))");
return(0);
}
/* gcc -o r r.c s7.o -Wl,-export-dynamic -lm -I. -ldl
*/
</pre>
<p>Besides evaluating s7 expressions, like any repl,
you can also type shell commands just as in a shell:
</p>
<pre class="indented">
<1> pwd
<em class="gray">/home/bil/cl</em>
<2> cd ..
<em class="gray">/home/bil</em>
<3> date
<em class="gray">Wed 15-Apr-2015 17:32:24 PDT</em>
</pre>
<p>In most cases, these are handled through *unbound-variable-hook*, checked using "command -v", then passed
to the underlying shell via the system function.
</p>
<p>The prompt is set by the function (*repl* 'prompt). It gets one argument,
the current line number, and should set the prompt string and its length.
</p>
<pre class="indented">
(set! (*repl* 'prompt) (lambda (num)
(with-let (*repl* 'repl-let)
(set! prompt-string "scheme> ")
(set! prompt-length (length prompt-string)))))
</pre>
<p>or, to use the red lambda example mentioned earlier:
</p>
<pre class="indented">
(set! (*repl* 'prompt)
(lambda (num)
(with-let (*repl* 'repl-let)
(set! prompt-string (bold (red (string #\xce #\xbb #\> #\space))))
(set! prompt-length 3)))) ; until we get unicode length calc
</pre>
<p>The line number provides a quick way to move around in the history buffer.
To get a previous line without laboriously typing M-p over and over,
simply type the line number (without control or meta bits), then M-.
In some CL repls, the special variable '* holds the last value computed.
In repl.scm, each value is retained in variables of the form '<n> where n
is the number shown in the prompt.
</p>
<pre class="indented">
<1> (+ 1 2)
<em class="gray">3</em>
<2> (* <1> 2)
<em class="gray">6</em>
</pre>
<p>Here is an example of adding to the keymap:
</p>
<pre class="indented">
(set! ((*repl* 'keymap) (integer->char 17)) ; C-q to quit and return to caller
(lambda (c)
(set! ((*repl* 'repl-let) 'all-done) #t)))
</pre>
<p>To access the meta keys (in the keymap), use a string:
<code>((*repl* 'keymap) (string #\escape #\p))</code>; this is Meta-p which normally accesses
the history buffer.
</p>
<p>You can call the repl from other code, poke around in the current environment (or whatever),
then return to the caller:
</p>
<pre class="indented">
(load "repl.scm")
(define (drop-into-repl e)
(let ((C-q (integer->char 17))) ; we'll use the C-q example above to get out
(let ((old-C-q ((*repl* 'keymap) C-q))
(old-top-level (*repl* 'top-level-let)))
(dynamic-wind
(lambda ()
(set! (*repl* 'top-level-let) e)
(set! ((*repl* 'keymap) C-q)
(lambda (c)
(set! ((*repl* 'repl-let) 'all-done) #t))))
(lambda ()
((<em class=red>*repl* 'run</em>))) ; run the repl
(lambda ()
(set! (*repl* 'top-level-let) old-top-level)
(set! ((*repl* 'keymap) C-q) old-C-q))))))
(let ((x 32))
(format *stderr* "x: ~A~%" x)
(<em class=red>drop-into-repl</em> (curlet))
(format *stderr* "now x: ~A~%" x))
</pre>
<p>Now load that code and:
</p>
<pre class="indented">
x: 32
<1> x
<em class="gray">32</em>
<2> (set! x 91)
<em class="gray">91</em>
<3> x
<em class="gray">91</em>
<4> now x: 91 ; here I typed C-q at the prompt
</pre>
<p>Another possibility:
</p>
<pre class="indented">
(set! (hook-functions *error-hook*)
(list (lambda (hook)
(apply format *stderr* (hook 'data))
(newline *stderr*)
(drop-into-repl (owlet)))))
</pre>
<p>See the end of repl.scm for more examples. See nrepl.scm for a better version of repl.scm.
</p>
<!--
In the repl:
(define (f x)
(catch #t
(lambda ()
(+ x 1))
(lambda (type info)
(drop-into-repl (format *stderr* "caught (+ ~S 1) in ~S~%" x (outlet (curlet))) (curlet)))))
(f #\a)
which calls the error handler above:
caught (+ #\a 1) in (inlet 'x #\a)
break: C-q to exit break
break> (curlet)
(inlet 'type wrong-type-arg 'info ("~A ~:D argument, ~S, is ~A but should be ~A" + 1 #\a "a character" "a number"))
;; that is the error handler environment
break> (outlet (curlet))
(inlet 'x #\a)
;; the environment where the error occurred
break> (with-let (outlet (outlet (outlet (curlet)))) (define (f x) (char? x)))
;; redefine f in the environment where we originally defined it
break> (f #\a)
#t
;; C-q here to exit the break repl; we return to the original repl
;; where f has been redefined:
(procedure-source f)
(lambda (x) (char? x))
The environment chain is slightly different if you call the code at the top from a file
rather than doing it all in the repl.
-->
<!--
(load "/home/bil/test/sndlib/libsndlib.so" (inlet 'init_func 's7_init_sndlib))
-->
<div class="separator"></div>
<p>Unlike repl, nrepl has support for the mouse, traversable, scrollable, and resizable panes, built-in ties to
lint.scm, debug.scm, and profile.scm, and various other enhancements.
Since it includes all the libc, notcurses FFI code, and nrepl.scm at compile-time, there
are no problems running it anywhere. To build nrepl:
</p>
<pre class="indented">
gcc -o nrepl s7.c -O2 -I. -Wl,-export-dynamic -lm -ldl -DWITH_MAIN -DWITH_NOTCURSES -lnotcurses-core
</pre>
<p>If that is too easy, try:
</p>
<pre class="indented">
gcc -c s7.c -O2 -I. -Wl,-export-dynamic -lm -ldl
gcc -o nrepl nrepl.c s7.o -lnotcurses-core -lm -I. -ldl
</pre>
<p>notcurses_s7.c needs version 2.1.6 or later of the notcurses-core library.
</p>
<p>When nrepl starts up, you have a prompt at the top of the terminal, and a status box
at the bottom. You can move around the pane via C-p and C-n (no need for repl.scm's M-p and M-n),
or use the mouse, or the arrow keys. If you set and hit a break point, a new pane is
opened in the context of the break. C-q exits the break. At the top pane, C-q exits
nrepl. C-g gives you another prompt (handy if you're caught in a messed up expression).
If you're in an infinite loop, C-c interrupts it. Otherwise C-c exits nrepl.
</p>
<p>If you set up a watcher (via watch from debug.scm), the action is displayed in
a separate box in the upper right corner. The status box displays all sorts of
informative and helpful messages, or at least that is the intent. lint.scm
checks each expression you type, and various hooks let you know when things
are happening in the background. Function signatures are posted there as well.
</p>
<p>You can customize nrepl in basically the same ways as described above for repl.scm.
You can also place these in a file named ".nrepl"; if nrepl finds such a file, it
loads it automatically at startup.
</p>
<!--
<br>
<blockquote>
<div class="indented">
<p>After months of intense typing,
Insanely declares his labors complete. "Ship it!" says Mr Big, and hands
him a million stock options. Meanwhile, in the basement behind an old door
with the eldritch sign "eep Ou", in a labyrinth of pounding pipes and fluorescent lights,
a forgotten shadow types <code>(lint "insanely-great.scm")</code>...
</p>
</div>
</blockquote>
-->
<br>
<div class="separator"></div>
<div class="related">
related documentation:
<a href="s7.html">s7 </a>
<a href="s7-ffi.html">s7-ffi </a>
</div>
</body>
</html>