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
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
|
@c -*-texinfo-*-
@c This is part of the GNU Guile Reference Manual.
@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012, 2013
@c Free Software Foundation, Inc.
@c See the file guile.texi for copying conditions.
@node Read/Load/Eval/Compile
@section Reading and Evaluating Scheme Code
This chapter describes Guile functions that are concerned with reading,
loading, evaluating, and compiling Scheme code at run time.
@menu
* Scheme Syntax:: Standard and extended Scheme syntax.
* Scheme Read:: Reading Scheme code.
* Scheme Write:: Writing Scheme values to a port.
* Fly Evaluation:: Procedures for on the fly evaluation.
* Compilation:: How to compile Scheme files and procedures.
* Loading:: Loading Scheme code from file.
* Load Paths:: Where Guile looks for code.
* Character Encoding of Source Files:: Loading non-ASCII Scheme code from file.
* Delayed Evaluation:: Postponing evaluation until it is needed.
* Local Evaluation:: Evaluation in a local lexical environment.
* Local Inclusion:: Compile-time inclusion of one file in another.
* REPL Servers:: Serving a REPL over a socket.
@end menu
@node Scheme Syntax
@subsection Scheme Syntax: Standard and Guile Extensions
@menu
* Expression Syntax::
* Comments::
* Block Comments::
* Case Sensitivity::
* Keyword Syntax::
* Reader Extensions::
@end menu
@node Expression Syntax
@subsubsection Expression Syntax
An expression to be evaluated takes one of the following forms.
@table @nicode
@item @var{symbol}
A symbol is evaluated by dereferencing. A binding of that symbol is
sought and the value there used. For example,
@example
(define x 123)
x @result{} 123
@end example
@item (@var{proc} @var{args}@dots{})
A parenthesised expression is a function call. @var{proc} and each
argument are evaluated, then the function (which @var{proc} evaluated
to) is called with those arguments.
The order in which @var{proc} and the arguments are evaluated is
unspecified, so be careful when using expressions with side effects.
@example
(max 1 2 3) @result{} 3
(define (get-some-proc) min)
((get-some-proc) 1 2 3) @result{} 1
@end example
The same sort of parenthesised form is used for a macro invocation,
but in that case the arguments are not evaluated. See the
descriptions of macros for more on this (@pxref{Macros}, and
@pxref{Syntax Rules}).
@item @var{constant}
Number, string, character and boolean constants evaluate ``to
themselves'', so can appear as literals.
@example
123 @result{} 123
99.9 @result{} 99.9
"hello" @result{} "hello"
#\z @result{} #\z
#t @result{} #t
@end example
Note that an application must not attempt to modify literal strings,
since they may be in read-only memory.
@item (quote @var{data})
@itemx '@var{data}
@findex quote
@findex '
Quoting is used to obtain a literal symbol (instead of a variable
reference), a literal list (instead of a function call), or a literal
vector. @nicode{'} is simply a shorthand for a @code{quote} form.
For example,
@example
'x @result{} x
'(1 2 3) @result{} (1 2 3)
'#(1 (2 3) 4) @result{} #(1 (2 3) 4)
(quote x) @result{} x
(quote (1 2 3)) @result{} (1 2 3)
(quote #(1 (2 3) 4)) @result{} #(1 (2 3) 4)
@end example
Note that an application must not attempt to modify literal lists or
vectors obtained from a @code{quote} form, since they may be in
read-only memory.
@item (quasiquote @var{data})
@itemx `@var{data}
@findex quasiquote
@findex `
Backquote quasi-quotation is like @code{quote}, but selected
sub-expressions are evaluated. This is a convenient way to construct
a list or vector structure most of which is constant, but at certain
points should have expressions substituted.
The same effect can always be had with suitable @code{list},
@code{cons} or @code{vector} calls, but quasi-quoting is often easier.
@table @nicode
@item (unquote @var{expr})
@itemx ,@var{expr}
@findex unquote
@findex ,
Within the quasiquote @var{data}, @code{unquote} or @code{,} indicates
an expression to be evaluated and inserted. The comma syntax @code{,}
is simply a shorthand for an @code{unquote} form. For example,
@example
`(1 2 ,(* 9 9) 3 4) @result{} (1 2 81 3 4)
`(1 (unquote (+ 1 1)) 3) @result{} (1 2 3)
`#(1 ,(/ 12 2)) @result{} #(1 6)
@end example
@item (unquote-splicing @var{expr})
@itemx ,@@@var{expr}
@findex unquote-splicing
@findex ,@@
Within the quasiquote @var{data}, @code{unquote-splicing} or
@code{,@@} indicates an expression to be evaluated and the elements of
the returned list inserted. @var{expr} must evaluate to a list. The
``comma-at'' syntax @code{,@@} is simply a shorthand for an
@code{unquote-splicing} form.
@example
(define x '(2 3))
`(1 ,@@x 4) @result{} (1 2 3 4)
`(1 (unquote-splicing (map 1+ x))) @result{} (1 3 4)
`#(9 ,@@x 9) @result{} #(9 2 3 9)
@end example
Notice @code{,@@} differs from plain @code{,} in the way one level of
nesting is stripped. For @code{,@@} the elements of a returned list
are inserted, whereas with @code{,} it would be the list itself
inserted.
@end table
@c
@c FIXME: What can we say about the mutability of a quasiquote
@c result? R5RS doesn't seem to specify anything, though where it
@c says backquote without commas is the same as plain quote then
@c presumably the "fixed" portions of a quasiquote expression must be
@c treated as immutable.
@c
@end table
@node Comments
@subsubsection Comments
@c FIXME::martin: Review me!
Comments in Scheme source files are written by starting them with a
semicolon character (@code{;}). The comment then reaches up to the end
of the line. Comments can begin at any column, and the may be inserted
on the same line as Scheme code.
@lisp
; Comment
;; Comment too
(define x 1) ; Comment after expression
(let ((y 1))
;; Display something.
(display y)
;;; Comment at left margin.
(display (+ y 1)))
@end lisp
It is common to use a single semicolon for comments following
expressions on a line, to use two semicolons for comments which are
indented like code, and three semicolons for comments which start at
column 0, even if they are inside an indented code block. This
convention is used when indenting code in Emacs' Scheme mode.
@node Block Comments
@subsubsection Block Comments
@cindex multiline comments
@cindex block comments
@cindex #!
@cindex !#
@c FIXME::martin: Review me!
In addition to the standard line comments defined by R5RS, Guile has
another comment type for multiline comments, called @dfn{block
comments}. This type of comment begins with the character sequence
@code{#!} and ends with the characters @code{!#}, which must appear on a
line of their own. These comments are compatible with the block
comments in the Scheme Shell @file{scsh} (@pxref{The Scheme shell
(scsh)}). The characters @code{#!} were chosen because they are the
magic characters used in shell scripts for indicating that the name of
the program for executing the script follows on the same line.
Thus a Guile script often starts like this.
@lisp
#! /usr/local/bin/guile -s
!#
@end lisp
More details on Guile scripting can be found in the scripting section
(@pxref{Guile Scripting}).
@cindex R6RS block comments
@cindex SRFI-30 block comments
Similarly, Guile (starting from version 2.0) supports nested block
comments as specified by R6RS and
@url{http://srfi.schemers.org/srfi-30/srfi-30.html, SRFI-30}:
@lisp
(+ #| this is a #| nested |# block comment |# 2)
@result{} 3
@end lisp
For backward compatibility, this syntax can be overridden with
@code{read-hash-extend} (@pxref{Reader Extensions,
@code{read-hash-extend}}).
There is one special case where the contents of a comment can actually
affect the interpretation of code. When a character encoding
declaration, such as @code{coding: utf-8} appears in one of the first
few lines of a source file, it indicates to Guile's default reader
that this source code file is not ASCII. For details see @ref{Character
Encoding of Source Files}.
@node Case Sensitivity
@subsubsection Case Sensitivity
@cindex fold-case
@cindex no-fold-case
@c FIXME::martin: Review me!
Scheme as defined in R5RS is not case sensitive when reading symbols.
Guile, on the contrary is case sensitive by default, so the identifiers
@lisp
guile-whuzzy
Guile-Whuzzy
@end lisp
are the same in R5RS Scheme, but are different in Guile.
It is possible to turn off case sensitivity in Guile by setting the
reader option @code{case-insensitive}. For more information on reader
options, @xref{Scheme Read}.
@lisp
(read-enable 'case-insensitive)
@end lisp
It is also possible to disable (or enable) case sensitivity within a
single file by placing the reader directives @code{#!fold-case} (or
@code{#!no-fold-case}) within the file itself.
@node Keyword Syntax
@subsubsection Keyword Syntax
@node Reader Extensions
@subsubsection Reader Extensions
@deffn {Scheme Procedure} read-hash-extend chr proc
@deffnx {C Function} scm_read_hash_extend (chr, proc)
Install the procedure @var{proc} for reading expressions
starting with the character sequence @code{#} and @var{chr}.
@var{proc} will be called with two arguments: the character
@var{chr} and the port to read further data from. The object
returned will be the return value of @code{read}.
Passing @code{#f} for @var{proc} will remove a previous setting.
@end deffn
@node Scheme Read
@subsection Reading Scheme Code
@rnindex read
@deffn {Scheme Procedure} read [port]
@deffnx {C Function} scm_read (port)
Read an s-expression from the input port @var{port}, or from
the current input port if @var{port} is not specified.
Any whitespace before the next token is discarded.
@end deffn
The behaviour of Guile's Scheme reader can be modified by manipulating
its read options.
@cindex options - read
@cindex read options
@deffn {Scheme Procedure} read-options [setting]
Display the current settings of the global read options. If
@var{setting} is omitted, only a short form of the current read options
is printed. Otherwise if @var{setting} is the symbol @code{help}, a
complete options description is displayed.
@end deffn
The set of available options, and their default values, may be had by
invoking @code{read-options} at the prompt.
@smalllisp
scheme@@(guile-user)> (read-options)
(square-brackets keywords #f positions)
scheme@@(guile-user)> (read-options 'help)
copy no Copy source code expressions.
positions yes Record positions of source code expressions.
case-insensitive no Convert symbols to lower case.
keywords #f Style of keyword recognition: #f, 'prefix or 'postfix.
r6rs-hex-escapes no Use R6RS variable-length character and string hex escapes.
square-brackets yes Treat `[' and `]' as parentheses, for R6RS compatibility.
hungry-eol-escapes no In strings, consume leading whitespace after an
escaped end-of-line.
curly-infix no Support SRFI-105 curly infix expressions.
@end smalllisp
Note that Guile also includes a preliminary mechanism for setting read
options on a per-port basis. For instance, the @code{case-insensitive}
read option is set (or unset) on the port when the reader encounters the
@code{#!fold-case} or @code{#!no-fold-case} reader directives.
Similarly, the @code{#!curly-infix} reader directive sets the
@code{curly-infix} read option on the port, and
@code{#!curly-infix-and-bracket-lists} sets @code{curly-infix} and
unsets @code{square-brackets} on the port (@pxref{SRFI-105}). There is
currently no other way to access or set the per-port read options.
The boolean options may be toggled with @code{read-enable} and
@code{read-disable}. The non-boolean @code{keywords} option must be set
using @code{read-set!}.
@deffn {Scheme Procedure} read-enable option-name
@deffnx {Scheme Procedure} read-disable option-name
@deffnx {Scheme Syntax} read-set! option-name value
Modify the read options. @code{read-enable} should be used with boolean
options and switches them on, @code{read-disable} switches them off.
@code{read-set!} can be used to set an option to a specific value. Due
to historical oddities, it is a macro that expects an unquoted option
name.
@end deffn
For example, to make @code{read} fold all symbols to their lower case
(perhaps for compatibility with older Scheme code), you can enter:
@lisp
(read-enable 'case-insensitive)
@end lisp
For more information on the effect of the @code{r6rs-hex-escapes} and
@code{hungry-eol-escapes} options, see (@pxref{String Syntax}).
@node Scheme Write
@subsection Writing Scheme Values
Any scheme value may be written to a port. Not all values may be read
back in (@pxref{Scheme Read}), however.
@rnindex write
@rnindex print
@deffn {Scheme Procedure} write obj [port]
Send a representation of @var{obj} to @var{port} or to the current
output port if not given.
The output is designed to be machine readable, and can be read back
with @code{read} (@pxref{Scheme Read}). Strings are printed in
double quotes, with escapes if necessary, and characters are printed in
@samp{#\} notation.
@end deffn
@rnindex display
@deffn {Scheme Procedure} display obj [port]
Send a representation of @var{obj} to @var{port} or to the current
output port if not given.
The output is designed for human readability, it differs from
@code{write} in that strings are printed without double quotes and
escapes, and characters are printed as per @code{write-char}, not in
@samp{#\} form.
@end deffn
As was the case with the Scheme reader, there are a few options that
affect the behavior of the Scheme printer.
@cindex options - print
@cindex print options
@deffn {Scheme Procedure} print-options [setting]
Display the current settings of the read options. If @var{setting} is
omitted, only a short form of the current read options is
printed. Otherwise if @var{setting} is the symbol @code{help}, a
complete options description is displayed.
@end deffn
The set of available options, and their default values, may be had by
invoking @code{print-options} at the prompt.
@smalllisp
scheme@@(guile-user)> (print-options)
(quote-keywordish-symbols reader highlight-suffix "@}" highlight-prefix "@{")
scheme@@(guile-user)> (print-options 'help)
highlight-prefix @{ The string to print before highlighted values.
highlight-suffix @} The string to print after highlighted values.
quote-keywordish-symbols reader How to print symbols that have a colon
as their first or last character. The
value '#f' does not quote the colons;
'#t' quotes them; 'reader' quotes them
when the reader option 'keywords' is
not '#f'.
escape-newlines yes Render newlines as \n when printing
using `write'.
@end smalllisp
These options may be modified with the print-set! syntax.
@deffn {Scheme Syntax} print-set! option-name value
Modify the print options. Due to historical oddities, @code{print-set!}
is a macro that expects an unquoted option name.
@end deffn
@node Fly Evaluation
@subsection Procedures for On the Fly Evaluation
Scheme has the lovely property that its expressions may be represented
as data. The @code{eval} procedure takes a Scheme datum and evaluates
it as code.
@rnindex eval
@c ARGFIXME environment/environment specifier
@deffn {Scheme Procedure} eval exp module_or_state
@deffnx {C Function} scm_eval (exp, module_or_state)
Evaluate @var{exp}, a list representing a Scheme expression,
in the top-level environment specified by @var{module_or_state}.
While @var{exp} is evaluated (using @code{primitive-eval}),
@var{module_or_state} is made the current module. The current module
is reset to its previous value when @code{eval} returns.
XXX - dynamic states.
Example: (eval '(+ 1 2) (interaction-environment))
@end deffn
@rnindex interaction-environment
@deffn {Scheme Procedure} interaction-environment
@deffnx {C Function} scm_interaction_environment ()
Return a specifier for the environment that contains
implementation--defined bindings, typically a superset of those
listed in the report. The intent is that this procedure will
return the environment in which the implementation would
evaluate expressions dynamically typed by the user.
@end deffn
@xref{Environments}, for other environments.
One does not always receive code as Scheme data, of course, and this is
especially the case for Guile's other language implementations
(@pxref{Other Languages}). For the case in which all you have is a
string, we have @code{eval-string}. There is a legacy version of this
procedure in the default environment, but you really want the one from
@code{(ice-9 eval-string)}, so load it up:
@example
(use-modules (ice-9 eval-string))
@end example
@deffn {Scheme Procedure} eval-string string [#:module=#f] [#:file=#f] @
[#:line=#f] [#:column=#f] @
[#:lang=(current-language)] @
[#:compile?=#f]
Parse @var{string} according to the current language, normally Scheme.
Evaluate or compile the expressions it contains, in order, returning the
last expression.
If the @var{module} keyword argument is set, save a module excursion
(@pxref{Module System Reflection}) and set the current module to
@var{module} before evaluation.
The @var{file}, @var{line}, and @var{column} keyword arguments can be
used to indicate that the source string begins at a particular source
location.
Finally, @var{lang} is a language, defaulting to the current language,
and the expression is compiled if @var{compile?} is true or there is no
evaluator for the given language.
@end deffn
@deffn {C Function} scm_eval_string (string)
@deffnx {C Function} scm_eval_string_in_module (string, module)
These C bindings call @code{eval-string} from @code{(ice-9
eval-string)}, evaluating within @var{module} or the current module.
@end deffn
@deftypefn {C Function} SCM scm_c_eval_string (const char *string)
@code{scm_eval_string}, but taking a C string in locale encoding instead
of an @code{SCM}.
@end deftypefn
@deffn {Scheme Procedure} apply proc arg @dots{} arglst
@deffnx {C Function} scm_apply_0 (proc, arglst)
@deffnx {C Function} scm_apply_1 (proc, arg1, arglst)
@deffnx {C Function} scm_apply_2 (proc, arg1, arg2, arglst)
@deffnx {C Function} scm_apply_3 (proc, arg1, arg2, arg3, arglst)
@deffnx {C Function} scm_apply (proc, arg, rest)
@rnindex apply
Call @var{proc} with arguments @var{arg} @dots{} and the
elements of the @var{arglst} list.
@code{scm_apply} takes parameters corresponding to a Scheme level
@code{(lambda (proc arg1 . rest) ...)}. So @var{arg1} and all but the
last element of the @var{rest} list make up @var{arg} @dots{}, and the
last element of @var{rest} is the @var{arglst} list. Or if @var{rest}
is the empty list @code{SCM_EOL} then there's no @var{arg} @dots{}, and
(@var{arg1}) is the @var{arglst}.
@var{arglst} is not modified, but the @var{rest} list passed to
@code{scm_apply} is modified.
@end deffn
@deffn {C Function} scm_call_0 (proc)
@deffnx {C Function} scm_call_1 (proc, arg1)
@deffnx {C Function} scm_call_2 (proc, arg1, arg2)
@deffnx {C Function} scm_call_3 (proc, arg1, arg2, arg3)
@deffnx {C Function} scm_call_4 (proc, arg1, arg2, arg3, arg4)
@deffnx {C Function} scm_call_5 (proc, arg1, arg2, arg3, arg4, arg5)
@deffnx {C Function} scm_call_6 (proc, arg1, arg2, arg3, arg4, arg5, arg6)
@deffnx {C Function} scm_call_7 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7)
@deffnx {C Function} scm_call_8 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8)
@deffnx {C Function} scm_call_9 (proc, arg1, arg2, arg3, arg4, arg5, arg6, arg7, arg8, arg9)
Call @var{proc} with the given arguments.
@end deffn
@deffn {C Function} scm_call (proc, ...)
Call @var{proc} with any number of arguments. The argument list must be
terminated by @code{SCM_UNDEFINED}. For example:
@example
scm_call (scm_c_public_ref ("guile", "+"),
scm_from_int (1),
scm_from_int (2),
SCM_UNDEFINED);
@end example
@end deffn
@deffn {C Function} scm_call_n (proc, argv, nargs)
Call @var{proc} with the array of arguments @var{argv}, as a
@code{SCM*}. The length of the arguments should be passed in
@var{nargs}, as a @code{size_t}.
@end deffn
@deffn {Scheme Procedure} apply:nconc2last lst
@deffnx {C Function} scm_nconc2last (lst)
@var{lst} should be a list (@var{arg1} @dots{} @var{argN}
@var{arglst}), with @var{arglst} being a list. This function returns
a list comprising @var{arg1} to @var{argN} plus the elements of
@var{arglst}. @var{lst} is modified to form the return. @var{arglst}
is not modified, though the return does share structure with it.
This operation collects up the arguments from a list which is
@code{apply} style parameters.
@end deffn
@deffn {Scheme Procedure} primitive-eval exp
@deffnx {C Function} scm_primitive_eval (exp)
Evaluate @var{exp} in the top-level environment specified by
the current module.
@end deffn
@node Compilation
@subsection Compiling Scheme Code
The @code{eval} procedure directly interprets the S-expression
representation of Scheme. An alternate strategy for evaluation is to
determine ahead of time what computations will be necessary to
evaluate the expression, and then use that recipe to produce the
desired results. This is known as @dfn{compilation}.
While it is possible to compile simple Scheme expressions such as
@code{(+ 2 2)} or even @code{"Hello world!"}, compilation is most
interesting in the context of procedures. Compiling a lambda expression
produces a compiled procedure, which is just like a normal procedure
except typically much faster, because it can bypass the generic
interpreter.
Functions from system modules in a Guile installation are normally
compiled already, so they load and run quickly.
@cindex automatic compilation
Note that well-written Scheme programs will not typically call the
procedures in this section, for the same reason that it is often bad
taste to use @code{eval}. By default, Guile automatically compiles any
files it encounters that have not been compiled yet (@pxref{Invoking
Guile, @code{--auto-compile}}). The compiler can also be invoked
explicitly from the shell as @code{guild compile foo.scm}.
(Why are calls to @code{eval} and @code{compile} usually in bad taste?
Because they are limited, in that they can only really make sense for
top-level expressions. Also, most needs for ``compile-time''
computation are fulfilled by macros and closures. Of course one good
counterexample is the REPL itself, or any code that reads expressions
from a port.)
Automatic compilation generally works transparently, without any need
for user intervention. However Guile does not yet do proper dependency
tracking, so that if file @file{@var{a}.scm} uses macros from
@file{@var{b}.scm}, and @var{@var{b}.scm} changes, @code{@var{a}.scm}
would not be automatically recompiled. To forcibly invalidate the
auto-compilation cache, pass the @code{--fresh-auto-compile} option to
Guile, or set the @code{GUILE_AUTO_COMPILE} environment variable to
@code{fresh} (instead of to @code{0} or @code{1}).
For more information on the compiler itself, see @ref{Compiling to the
Virtual Machine}. For information on the virtual machine, see @ref{A
Virtual Machine for Guile}.
The command-line interface to Guile's compiler is the @command{guild
compile} command:
@deffn {Command} {guild compile} [@option{option}...] @var{file}...
Compile @var{file}, a source file, and store bytecode in the compilation cache
or in the file specified by the @option{-o} option. The following options are
available:
@table @option
@item -L @var{dir}
@itemx --load-path=@var{dir}
Add @var{dir} to the front of the module load path.
@item -o @var{ofile}
@itemx --output=@var{ofile}
Write output bytecode to @var{ofile}. By convention, bytecode file
names end in @code{.go}. When @option{-o} is omitted, the output file
name is as for @code{compile-file} (see below).
@item -W @var{warning}
@itemx --warn=@var{warning}
@cindex warnings, compiler
Emit warnings of type @var{warning}; use @code{--warn=help} for a list
of available warnings and their description. Currently recognized
warnings include @code{unused-variable}, @code{unused-toplevel},
@code{unbound-variable}, @code{arity-mismatch}, @code{format},
@code{duplicate-case-datum}, and @code{bad-case-datum}.
@item -f @var{lang}
@itemx --from=@var{lang}
Use @var{lang} as the source language of @var{file}. If this option is omitted,
@code{scheme} is assumed.
@item -t @var{lang}
@itemx --to=@var{lang}
Use @var{lang} as the target language of @var{file}. If this option is omitted,
@code{objcode} is assumed.
@item -T @var{target}
@itemx --target=@var{target}
Produce bytecode for @var{target} instead of @var{%host-type}
(@pxref{Build Config, %host-type}). Target must be a valid GNU triplet,
such as @code{armv5tel-unknown-linux-gnueabi} (@pxref{Specifying Target
Triplets,,, autoconf, GNU Autoconf Manual}).
@end table
Each @var{file} is assumed to be UTF-8-encoded, unless it contains a
coding declaration as recognized by @code{file-encoding}
(@pxref{Character Encoding of Source Files}).
@end deffn
The compiler can also be invoked directly by Scheme code using the procedures
below:
@deffn {Scheme Procedure} compile exp [#:env=#f] @
[#:from=(current-language)] @
[#:to=value] [#:opts=()]
Compile the expression @var{exp} in the environment @var{env}. If
@var{exp} is a procedure, the result will be a compiled procedure;
otherwise @code{compile} is mostly equivalent to @code{eval}.
For a discussion of languages and compiler options, @xref{Compiling to
the Virtual Machine}.
@end deffn
@deffn {Scheme Procedure} compile-file file [#:output-file=#f] @
[#:from=(current-language)] [#:to='objcode] @
[#:env=(default-environment from)] @
[#:opts='()] @
[#:canonicalization='relative]
Compile the file named @var{file}.
Output will be written to a @var{output-file}. If you do not supply an
output file name, output is written to a file in the cache directory, as
computed by @code{(compiled-file-name @var{file})}.
@var{from} and @var{to} specify the source and target languages.
@xref{Compiling to the Virtual Machine}, for more information on these
options, and on @var{env} and @var{opts}.
As with @command{guild compile}, @var{file} is assumed to be
UTF-8-encoded unless it contains a coding declaration.
@end deffn
@deffn {Scheme Procedure} compiled-file-name file
Compute a cached location for a compiled version of a Scheme file named
@var{file}.
This file will usually be below the @file{$HOME/.cache/guile/ccache}
directory, depending on the value of the @env{XDG_CACHE_HOME}
environment variable. The intention is that @code{compiled-file-name}
provides a fallback location for caching auto-compiled files. If you
want to place a compile file in the @code{%load-compiled-path}, you
should pass the @var{output-file} option to @code{compile-file},
explicitly.
@end deffn
@defvr {Scheme Variable} %auto-compilation-options
This variable contains the options passed to the @code{compile-file}
procedure when auto-compiling source files. By default, it enables
useful compilation warnings. It can be customized from @file{~/.guile}.
@end defvr
@node Loading
@subsection Loading Scheme Code from File
@rnindex load
@deffn {Scheme Procedure} load filename [reader]
Load @var{filename} and evaluate its contents in the top-level
environment.
@var{reader} if provided should be either @code{#f}, or a procedure with
the signature @code{(lambda (port) @dots{})} which reads the next
expression from @var{port}. If @var{reader} is @code{#f} or absent,
Guile's built-in @code{read} procedure is used (@pxref{Scheme Read}).
The @var{reader} argument takes effect by setting the value of the
@code{current-reader} fluid (see below) before loading the file, and
restoring its previous value when loading is complete. The Scheme code
inside @var{filename} can itself change the current reader procedure on
the fly by setting @code{current-reader} fluid.
If the variable @code{%load-hook} is defined, it should be bound to a
procedure that will be called before any code is loaded. See
documentation for @code{%load-hook} later in this section.
@end deffn
@deffn {Scheme Procedure} load-compiled filename
Load the compiled file named @var{filename}.
Compiling a source file (@pxref{Read/Load/Eval/Compile}) and then
calling @code{load-compiled} on the resulting file is equivalent to
calling @code{load} on the source file.
@end deffn
@deffn {Scheme Procedure} primitive-load filename
@deffnx {C Function} scm_primitive_load (filename)
Load the file named @var{filename} and evaluate its contents in the
top-level environment. @var{filename} must either be a full pathname or
be a pathname relative to the current directory. If the variable
@code{%load-hook} is defined, it should be bound to a procedure that
will be called before any code is loaded. See the documentation for
@code{%load-hook} later in this section.
@end deffn
@deftypefn {C Function} SCM scm_c_primitive_load (const char *filename)
@code{scm_primitive_load}, but taking a C string instead of an
@code{SCM}.
@end deftypefn
@defvar current-reader
@code{current-reader} holds the read procedure that is currently being
used by the above loading procedures to read expressions (from the file
that they are loading). @code{current-reader} is a fluid, so it has an
independent value in each dynamic root and should be read and set using
@code{fluid-ref} and @code{fluid-set!} (@pxref{Fluids and Dynamic
States}).
Changing @code{current-reader} is typically useful to introduce local
syntactic changes, such that code following the @code{fluid-set!} call
is read using the newly installed reader. The @code{current-reader}
change should take place at evaluation time when the code is evaluated,
or at compilation time when the code is compiled:
@findex eval-when
@example
(eval-when (compile eval)
(fluid-set! current-reader my-own-reader))
@end example
The @code{eval-when} form above ensures that the @code{current-reader}
change occurs at the right time.
@end defvar
@defvar %load-hook
A procedure to be called @code{(%load-hook @var{filename})} whenever a
file is loaded, or @code{#f} for no such call. @code{%load-hook} is
used by all of the loading functions (@code{load} and
@code{primitive-load}, and @code{load-from-path} and
@code{primitive-load-path} documented in the next section).
For example an application can set this to show what's loaded,
@example
(set! %load-hook (lambda (filename)
(format #t "Loading ~a ...\n" filename)))
(load-from-path "foo.scm")
@print{} Loading /usr/local/share/guile/site/foo.scm ...
@end example
@end defvar
@deffn {Scheme Procedure} current-load-port
@deffnx {C Function} scm_current_load_port ()
Return the current-load-port.
The load port is used internally by @code{primitive-load}.
@end deffn
@node Load Paths
@subsection Load Paths
The procedure in the previous section look for Scheme code in the file
system at specific location. Guile also has some procedures to search
the load path for code.
@defvar %load-path
List of directories which should be searched for Scheme modules and
libraries. When Guile starts up, @code{%load-path} is initialized to
the default load path @code{(list (%library-dir) (%site-dir)
(%global-site-dir) (%package-data-dir))}. The @env{GUILE_LOAD_PATH}
environment variable can be used to prepend or append additional
directories (@pxref{Environment Variables}).
@xref{Build Config}, for more on @code{%site-dir} and related
procedures.
@end defvar
@deffn {Scheme Procedure} load-from-path filename
Similar to @code{load}, but searches for @var{filename} in the load
paths. Preferentially loads a compiled version of the file, if it is
available and up-to-date.
@end deffn
A user can extend the load path by calling @code{add-to-load-path}.
@deffn {Scheme Syntax} add-to-load-path dir
Add @var{dir} to the load path.
@end deffn
For example, a script might include this form to add the directory that
it is in to the load path:
@example
(add-to-load-path (dirname (current-filename)))
@end example
It's better to use @code{add-to-load-path} than to modify
@code{%load-path} directly, because @code{add-to-load-path} takes care
of modifying the path both at compile-time and at run-time.
@deffn {Scheme Procedure} primitive-load-path filename [exception-on-not-found]
@deffnx {C Function} scm_primitive_load_path (filename)
Search @code{%load-path} for the file named @var{filename} and
load it into the top-level environment. If @var{filename} is a
relative pathname and is not found in the list of search paths,
an error is signalled. Preferentially loads a compiled version of the
file, if it is available and up-to-date.
If @var{filename} is a relative pathname and is not found in the list of
search paths, one of three things may happen, depending on the optional
second argument, @var{exception-on-not-found}. If it is @code{#f},
@code{#f} will be returned. If it is a procedure, it will be called
with no arguments. (This allows a distinction to be made between
exceptions raised by loading a file, and exceptions related to the
loader itself.) Otherwise an error is signalled.
For compatibility with Guile 1.8 and earlier, the C function takes only
one argument, which can be either a string (the file name) or an
argument list.
@end deffn
@deffn {Scheme Procedure} %search-load-path filename
@deffnx {C Function} scm_sys_search_load_path (filename)
Search @code{%load-path} for the file named @var{filename}, which must
be readable by the current user. If @var{filename} is found in the list
of paths to search or is an absolute pathname, return its full pathname.
Otherwise, return @code{#f}. Filenames may have any of the optional
extensions in the @code{%load-extensions} list; @code{%search-load-path}
will try each extension automatically.
@end deffn
@defvar %load-extensions
A list of default file extensions for files containing Scheme code.
@code{%search-load-path} tries each of these extensions when looking for
a file to load. By default, @code{%load-extensions} is bound to the
list @code{("" ".scm")}.
@end defvar
As mentioned above, when Guile searches the @code{%load-path} for a
source file, it will also search the @code{%load-compiled-path} for a
corresponding compiled file. If the compiled file is as new or newer
than the source file, it will be loaded instead of the source file,
using @code{load-compiled}.
@defvar %load-compiled-path
Like @code{%load-path}, but for compiled files. By default, this path
has two entries: one for compiled files from Guile itself, and one for
site packages. The @env{GUILE_LOAD_COMPILED_PATH} environment variable
can be used to prepend or append additional directories
(@pxref{Environment Variables}).
@end defvar
When @code{primitive-load-path} searches the @code{%load-compiled-path}
for a corresponding compiled file for a relative path it does so by
appending @code{.go} to the relative path. For example, searching for
@code{ice-9/popen} could find
@code{/usr/lib/guile/2.0/ccache/ice-9/popen.go}, and use it instead of
@code{/usr/share/guile/2.0/ice-9/popen.scm}.
If @code{primitive-load-path} does not find a corresponding @code{.go}
file in the @code{%load-compiled-path}, or the @code{.go} file is out of
date, it will search for a corresponding auto-compiled file in the
fallback path, possibly creating one if one does not exist.
@xref{Installing Site Packages}, for more on how to correctly install
site packages. @xref{Modules and the File System}, for more on the
relationship between load paths and modules. @xref{Compilation}, for
more on the fallback path and auto-compilation.
Finally, there are a couple of helper procedures for general path
manipulation.
@deffn {Scheme Procedure} parse-path path [tail]
@deffnx {C Function} scm_parse_path (path, tail)
Parse @var{path}, which is expected to be a colon-separated string, into
a list and return the resulting list with @var{tail} appended. If
@var{path} is @code{#f}, @var{tail} is returned.
@end deffn
@deffn {Scheme Procedure} parse-path-with-ellipsis path base
@deffnx {C Function} scm_parse_path_with_ellipsis (path, base)
Parse @var{path}, which is expected to be a colon-separated string, into
a list and return the resulting list with @var{base} (a list) spliced in
place of the @code{...} path component, if present, or else @var{base}
is added to the end. If @var{path} is @code{#f}, @var{base} is
returned.
@end deffn
@deffn {Scheme Procedure} search-path path filename [extensions [require-exts?]]
@deffnx {C Function} scm_search_path (path, filename, rest)
Search @var{path} for a directory containing a file named
@var{filename}. The file must be readable, and not a directory. If we
find one, return its full filename; otherwise, return @code{#f}. If
@var{filename} is absolute, return it unchanged. If given,
@var{extensions} is a list of strings; for each directory in @var{path},
we search for @var{filename} concatenated with each @var{extension}. If
@var{require-exts?} is true, require that the returned file name have
one of the given extensions; if @var{require-exts?} is not given, it
defaults to @code{#f}.
For compatibility with Guile 1.8 and earlier, the C function takes only
three arguments.
@end deffn
@node Character Encoding of Source Files
@subsection Character Encoding of Source Files
@cindex source file encoding
@cindex primitive-load
@cindex load
Scheme source code files are usually encoded in ASCII, but, the
built-in reader can interpret other character encodings. The
procedure @code{primitive-load}, and by extension the functions that
call it, such as @code{load}, first scan the top 500 characters of the
file for a coding declaration.
A coding declaration has the form @code{coding: XXXXXX}, where
@code{XXXXXX} is the name of a character encoding in which the source
code file has been encoded. The coding declaration must appear in a
scheme comment. It can either be a semicolon-initiated comment or a block
@code{#!} comment.
The name of the character encoding in the coding declaration is
typically lower case and containing only letters, numbers, and hyphens,
as recognized by @code{set-port-encoding!} (@pxref{Ports,
@code{set-port-encoding!}}). Common examples of character encoding
names are @code{utf-8} and @code{iso-8859-1},
@url{http://www.iana.org/assignments/character-sets, as defined by
IANA}. Thus, the coding declaration is mostly compatible with Emacs.
However, there are some differences in encoding names recognized by
Emacs and encoding names defined by IANA, the latter being essentially a
subset of the former. For instance, @code{latin-1} is a valid encoding
name for Emacs, but it's not according to the IANA standard, which Guile
follows; instead, you should use @code{iso-8859-1}, which is both
understood by Emacs and dubbed by IANA (IANA writes it uppercase but
Emacs wants it lowercase and Guile is case insensitive.)
For source code, only a subset of all possible character encodings can
be interpreted by the built-in source code reader. Only those
character encodings in which ASCII text appears unmodified can be
used. This includes @code{UTF-8} and @code{ISO-8859-1} through
@code{ISO-8859-15}. The multi-byte character encodings @code{UTF-16}
and @code{UTF-32} may not be used because they are not compatible with
ASCII.
@cindex read
@cindex encoding
@cindex port encoding
@findex set-port-encoding!
There might be a scenario in which one would want to read non-ASCII
code from a port, such as with the function @code{read}, instead of
with @code{load}. If the port's character encoding is the same as the
encoding of the code to be read by the port, not other special
handling is necessary. The port will automatically do the character
encoding conversion. The functions @code{setlocale} or by
@code{set-port-encoding!} are used to set port encodings
(@pxref{Ports}).
If a port is used to read code of unknown character encoding, it can
accomplish this in three steps. First, the character encoding of the
port should be set to ISO-8859-1 using @code{set-port-encoding!}.
Then, the procedure @code{file-encoding}, described below, is used to
scan for a coding declaration when reading from the port. As a side
effect, it rewinds the port after its scan is complete. After that,
the port's character encoding should be set to the encoding returned
by @code{file-encoding}, if any, again by using
@code{set-port-encoding!}. Then the code can be read as normal.
@deffn {Scheme Procedure} file-encoding port
@deffnx {C Function} scm_file_encoding (port)
Scan the port for an Emacs-like character coding declaration near the
top of the contents of a port with random-accessible contents
(@pxref{Recognize Coding, how Emacs recognizes file encoding,, emacs,
The GNU Emacs Reference Manual}). The coding declaration is of the form
@code{coding: XXXXX} and must appear in a Scheme comment. Return a
string containing the character encoding of the file if a declaration
was found, or @code{#f} otherwise. The port is rewound.
@end deffn
@node Delayed Evaluation
@subsection Delayed Evaluation
@cindex delayed evaluation
@cindex promises
Promises are a convenient way to defer a calculation until its result
is actually needed, and to run such a calculation only once. Also
@pxref{SRFI-45}.
@deffn syntax delay expr
@rnindex delay
Return a promise object which holds the given @var{expr} expression,
ready to be evaluated by a later @code{force}.
@end deffn
@deffn {Scheme Procedure} promise? obj
@deffnx {C Function} scm_promise_p (obj)
Return true if @var{obj} is a promise.
@end deffn
@rnindex force
@deffn {Scheme Procedure} force p
@deffnx {C Function} scm_force (p)
Return the value obtained from evaluating the @var{expr} in the given
promise @var{p}. If @var{p} has previously been forced then its
@var{expr} is not evaluated again, instead the value obtained at that
time is simply returned.
During a @code{force}, an @var{expr} can call @code{force} again on
its own promise, resulting in a recursive evaluation of that
@var{expr}. The first evaluation to return gives the value for the
promise. Higher evaluations run to completion in the normal way, but
their results are ignored, @code{force} always returns the first
value.
@end deffn
@node Local Evaluation
@subsection Local Evaluation
Guile includes a facility to capture a lexical environment, and later
evaluate a new expression within that environment. This code is
implemented in a module.
@example
(use-modules (ice-9 local-eval))
@end example
@deffn syntax the-environment
Captures and returns a lexical environment for use with
@code{local-eval} or @code{local-compile}.
@end deffn
@deffn {Scheme Procedure} local-eval exp env
@deffnx {C Function} scm_local_eval (exp, env)
@deffnx {Scheme Procedure} local-compile exp env [opts=()]
Evaluate or compile the expression @var{exp} in the lexical environment
@var{env}.
@end deffn
Here is a simple example, illustrating that it is the variable
that gets captured, not just its value at one point in time.
@example
(define e (let ((x 100)) (the-environment)))
(define fetch-x (local-eval '(lambda () x) e))
(fetch-x)
@result{} 100
(local-eval '(set! x 42) e)
(fetch-x)
@result{} 42
@end example
While @var{exp} is evaluated within the lexical environment of
@code{(the-environment)}, it has the dynamic environment of the call to
@code{local-eval}.
@code{local-eval} and @code{local-compile} can only evaluate
expressions, not definitions.
@example
(local-eval '(define foo 42)
(let ((x 100)) (the-environment)))
@result{} syntax error: definition in expression context
@end example
Note that the current implementation of @code{(the-environment)} only
captures ``normal'' lexical bindings, and pattern variables bound by
@code{syntax-case}. It does not currently capture local syntax
transformers bound by @code{let-syntax}, @code{letrec-syntax} or
non-top-level @code{define-syntax} forms. Any attempt to reference such
captured syntactic keywords via @code{local-eval} or
@code{local-compile} produces an error.
@node Local Inclusion
@subsection Local Inclusion
This section has discussed various means of linking Scheme code
together: fundamentally, loading up files at run-time using @code{load}
and @code{load-compiled}. Guile provides another option to compose
parts of programs together at expansion-time instead of at run-time.
@deffn {Scheme Syntax} include file-name
Open @var{file-name}, at expansion-time, and read the Scheme forms that
it contains, splicing them into the location of the @code{include},
within a @code{begin}.
If @var{file-name} is a relative path, it is searched for relative to
the path that contains the file that the @code{include} for appears in.
@end deffn
If you are a C programmer, if @code{load} in Scheme is like
@code{dlopen} in C, consider @code{include} to be like the C
preprocessor's @code{#include}. When you use @code{include}, it is as
if the contents of the included file were typed in instead of the
@code{include} form.
Because the code is included at compile-time, it is available to the
macroexpander. Syntax definitions in the included file are available to
later code in the form in which the @code{include} appears, without the
need for @code{eval-when}. (@xref{Eval When}.)
For the same reason, compiling a form that uses @code{include} results
in one compilation unit, composed of multiple files. Loading the
compiled file is one @code{stat} operation for the compilation unit,
instead of @code{2*@var{n}} in the case of @code{load} (once for each
loaded source file, and once each corresponding compiled file, in the
best case).
Unlike @code{load}, @code{include} also works within nested lexical
contexts. It so happens that the optimizer works best within a lexical
context, because all of the uses of bindings in a lexical context are
visible, so composing files by including them within a @code{(let ()
...)} can sometimes lead to important speed improvements.
On the other hand, @code{include} does have all the disadvantages of
early binding: once the code with the @code{include} is compiled, no
change to the included file is reflected in the future behavior of the
including form.
Also, the particular form of @code{include}, which requires an absolute
path, or a path relative to the current directory at compile-time, is
not very amenable to compiling the source in one place, but then
installing the source to another place. For this reason, Guile provides
another form, @code{include-from-path}, which looks for the source file
to include within a load path.
@deffn {Scheme Syntax} include-from-path file-name
Like @code{include}, but instead of expecting @code{file-name} to be an
absolute file name, it is expected to be a relative path to search in
the @code{%load-path}.
@end deffn
@code{include-from-path} is more useful when you want to install all of
the source files for a package (as you should!). It makes it possible
to evaluate an installed file from source, instead of relying on the
@code{.go} file being up to date.
@node REPL Servers
@subsection REPL Servers
@cindex REPL server
The procedures in this section are provided by
@lisp
(use-modules (system repl server))
@end lisp
When an application is written in Guile, it is often convenient to
allow the user to be able to interact with it by evaluating Scheme
expressions in a REPL.
The procedures of this module allow you to spawn a @dfn{REPL server},
which permits interaction over a local or TCP connection. Guile itself
uses them internally to implement the @option{--listen} switch,
@ref{Command-line Options}.
@deffn {Scheme Procedure} make-tcp-server-socket [#:host=#f] @
[#:addr] [#:port=37146]
Return a stream socket bound to a given address @var{addr} and port
number @var{port}. If the @var{host} is given, and @var{addr} is not,
then the @var{host} string is converted to an address. If neither is
given, we use the loopback address.
@end deffn
@deffn {Scheme Procedure} make-unix-domain-server-socket [#:path="/tmp/guile-socket"]
Return a UNIX domain socket, bound to a given @var{path}.
@end deffn
@deffn {Scheme Procedure} run-server [server-socket]
@deffnx {Scheme Procedure} spawn-server [server-socket]
Create and run a REPL, making it available over the given
@var{server-socket}. If @var{server-socket} is not provided, it
defaults to the socket created by calling @code{make-tcp-server-socket}
with no arguments.
@code{run-server} runs the server in the current thread, whereas
@code{spawn-server} runs the server in a new thread.
@end deffn
@deffn {Scheme Procedure} stop-server-and-clients!
Closes the connection on all running server sockets.
@end deffn
@c Local Variables:
@c TeX-master: "guile.texi"
@c End:
|