Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
d9a4a1cd | 3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2011, 2012, 2013, 2014 |
07d83abe MV |
4 | @c Free Software Foundation, Inc. |
5 | @c See the file guile.texi for copying conditions. | |
6 | ||
07d83abe MV |
7 | @node Utility Functions |
8 | @section General Utility Functions | |
9 | ||
10 | @c FIXME::martin: Review me! | |
11 | ||
12 | This chapter contains information about procedures which are not cleanly | |
13 | tied to a specific data type. Because of their wide range of | |
14 | applications, they are collected in a @dfn{utility} chapter. | |
15 | ||
16 | @menu | |
17 | * Equality:: When are two values `the same'? | |
18 | * Object Properties:: A modern interface to object properties. | |
19 | * Sorting:: Sort utility procedures. | |
20 | * Copying:: Copying deep structures. | |
21 | * General Conversion:: Converting objects to strings. | |
22 | * Hooks:: User-customizable event lists. | |
23 | @end menu | |
24 | ||
25 | ||
26 | @node Equality | |
27 | @subsection Equality | |
07d83abe MV |
28 | @cindex sameness |
29 | @cindex equality | |
30 | ||
0b8b0a3f KR |
31 | There are three kinds of core equality predicates in Scheme, described |
32 | below. The same kinds of comparisons arise in other functions, like | |
33 | @code{memq} and friends (@pxref{List Searching}). | |
34 | ||
35 | For all three tests, objects of different types are never equal. So | |
36 | for instance a list and a vector are not @code{equal?}, even if their | |
37 | contents are the same. Exact and inexact numbers are considered | |
38 | different types too, and are hence not equal even if their values are | |
39 | the same. | |
40 | ||
41 | @code{eq?} tests just for the same object (essentially a pointer | |
42 | comparison). This is fast, and can be used when searching for a | |
43 | particular object, or when working with symbols or keywords (which are | |
44 | always unique objects). | |
45 | ||
46 | @code{eqv?} extends @code{eq?} to look at the value of numbers and | |
47 | characters. It can for instance be used somewhat like @code{=} | |
48 | (@pxref{Comparison}) but without an error if one operand isn't a | |
49 | number. | |
50 | ||
51 | @code{equal?} goes further, it looks (recursively) into the contents | |
52 | of lists, vectors, etc. This is good for instance on lists that have | |
53 | been read or calculated in various places and are the same, just not | |
54 | made up of the same pairs. Such lists look the same (when printed), | |
55 | and @code{equal?} will consider them the same. | |
56 | ||
57 | @sp 1 | |
07d83abe MV |
58 | @deffn {Scheme Procedure} eq? x y |
59 | @deffnx {C Function} scm_eq_p (x, y) | |
0b8b0a3f KR |
60 | @rnindex eq? |
61 | Return @code{#t} if @var{x} and @var{y} are the same object, except | |
62 | for numbers and characters. For example, | |
63 | ||
64 | @example | |
65 | (define x (vector 1 2 3)) | |
66 | (define y (vector 1 2 3)) | |
67 | ||
68 | (eq? x x) @result{} #t | |
69 | (eq? x y) @result{} #f | |
70 | @end example | |
71 | ||
72 | Numbers and characters are not equal to any other object, but the | |
73 | problem is they're not necessarily @code{eq?} to themselves either. | |
74 | This is even so when the number comes directly from a variable, | |
75 | ||
76 | @example | |
77 | (let ((n (+ 2 3))) | |
78 | (eq? n n)) @result{} *unspecified* | |
79 | @end example | |
80 | ||
81 | Generally @code{eqv?} below should be used when comparing numbers or | |
82 | characters. @code{=} (@pxref{Comparison}) or @code{char=?} | |
83 | (@pxref{Characters}) can be used too. | |
84 | ||
85 | It's worth noting that end-of-list @code{()}, @code{#t}, @code{#f}, a | |
86 | symbol of a given name, and a keyword of a given name, are unique | |
87 | objects. There's just one of each, so for instance no matter how | |
88 | @code{()} arises in a program, it's the same object and can be | |
89 | compared with @code{eq?}, | |
90 | ||
91 | @example | |
92 | (define x (cdr '(123))) | |
93 | (define y (cdr '(456))) | |
94 | (eq? x y) @result{} #t | |
95 | ||
96 | (define x (string->symbol "foo")) | |
97 | (eq? x 'foo) @result{} #t | |
98 | @end example | |
07d83abe MV |
99 | @end deffn |
100 | ||
101 | @deftypefn {C Function} int scm_is_eq (SCM x, SCM y) | |
102 | Return @code{1} when @var{x} and @var{y} are equal in the sense of | |
0b8b0a3f KR |
103 | @code{eq?}, otherwise return @code{0}. |
104 | ||
105 | @findex == | |
106 | The @code{==} operator should not be used on @code{SCM} values, an | |
107 | @code{SCM} is a C type which cannot necessarily be compared using | |
108 | @code{==} (@pxref{The SCM Type}). | |
07d83abe MV |
109 | @end deftypefn |
110 | ||
0b8b0a3f | 111 | @sp 1 |
07d83abe MV |
112 | @deffn {Scheme Procedure} eqv? x y |
113 | @deffnx {C Function} scm_eqv_p (x, y) | |
0b8b0a3f KR |
114 | @rnindex eqv? |
115 | Return @code{#t} if @var{x} and @var{y} are the same object, or for | |
116 | characters and numbers the same value. | |
117 | ||
118 | On objects except characters and numbers, @code{eqv?} is the same as | |
119 | @code{eq?} above, it's true if @var{x} and @var{y} are the same | |
120 | object. | |
121 | ||
122 | If @var{x} and @var{y} are numbers or characters, @code{eqv?} compares | |
123 | their type and value. An exact number is not @code{eqv?} to an | |
124 | inexact number (even if their value is the same). | |
125 | ||
126 | @example | |
127 | (eqv? 3 (+ 1 2)) @result{} #t | |
128 | (eqv? 1 1.0) @result{} #f | |
129 | @end example | |
07d83abe MV |
130 | @end deffn |
131 | ||
0b8b0a3f | 132 | @sp 1 |
07d83abe MV |
133 | @deffn {Scheme Procedure} equal? x y |
134 | @deffnx {C Function} scm_equal_p (x, y) | |
0b8b0a3f KR |
135 | @rnindex equal? |
136 | Return @code{#t} if @var{x} and @var{y} are the same type, and their | |
137 | contents or value are equal. | |
138 | ||
42be21d8 | 139 | For a pair, string, vector, array or structure, @code{equal?} compares the |
72b3aa56 | 140 | contents, and does so using the same @code{equal?} recursively, |
0b8b0a3f KR |
141 | so a deep structure can be traversed. |
142 | ||
143 | @example | |
144 | (equal? (list 1 2 3) (list 1 2 3)) @result{} #t | |
145 | (equal? (list 1 2 3) (vector 1 2 3)) @result{} #f | |
146 | @end example | |
147 | ||
148 | For other objects, @code{equal?} compares as per @code{eqv?} above, | |
149 | which means characters and numbers are compared by type and value (and | |
150 | like @code{eqv?}, exact and inexact numbers are not @code{equal?}, | |
151 | even if their value is the same). | |
152 | ||
153 | @example | |
154 | (equal? 3 (+ 1 2)) @result{} #t | |
155 | (equal? 1 1.0) @result{} #f | |
156 | @end example | |
157 | ||
158 | Hash tables are currently only compared as per @code{eq?}, so two | |
159 | different tables are not @code{equal?}, even if their contents are the | |
160 | same. | |
161 | ||
162 | @code{equal?} does not support circular data structures, it may go | |
163 | into an infinite loop if asked to compare two circular lists or | |
164 | similar. | |
165 | ||
d9a4a1cd AW |
166 | GOOPS object types (@pxref{GOOPS}), including foreign object types |
167 | (@pxref{Defining New Foreign Object Types}), can have an @code{equal?} | |
168 | implementation specialized on two values of the same type. If | |
169 | @code{equal?} is called on two GOOPS objects of the same type, | |
170 | @code{equal?} will dispatch out to a generic function. This lets an | |
171 | application traverse the contents or control what is considered | |
172 | @code{equal?} for two objects of such a type. If there's no such | |
173 | handler, the default is to just compare as per @code{eq?}. | |
07d83abe MV |
174 | @end deffn |
175 | ||
176 | ||
177 | @node Object Properties | |
178 | @subsection Object Properties | |
179 | ||
180 | It's often useful to associate a piece of additional information with a | |
181 | Scheme object even though that object does not have a dedicated slot | |
182 | available in which the additional information could be stored. Object | |
183 | properties allow you to do just that. | |
184 | ||
07d83abe MV |
185 | Guile's representation of an object property is a procedure-with-setter |
186 | (@pxref{Procedures with Setters}) that can be used with the generalized | |
187 | form of @code{set!} (REFFIXME) to set and retrieve that property for any | |
188 | Scheme object. So, setting a property looks like this: | |
189 | ||
190 | @lisp | |
191 | (set! (my-property obj1) value-for-obj1) | |
192 | (set! (my-property obj2) value-for-obj2) | |
193 | @end lisp | |
194 | ||
195 | @noindent | |
196 | And retrieving values of the same property looks like this: | |
197 | ||
198 | @lisp | |
199 | (my-property obj1) | |
200 | @result{} | |
201 | value-for-obj1 | |
202 | ||
203 | (my-property obj2) | |
204 | @result{} | |
205 | value-for-obj2 | |
206 | @end lisp | |
207 | ||
208 | To create an object property in the first place, use the | |
209 | @code{make-object-property} procedure: | |
210 | ||
211 | @lisp | |
212 | (define my-property (make-object-property)) | |
213 | @end lisp | |
214 | ||
215 | @deffn {Scheme Procedure} make-object-property | |
216 | Create and return an object property. An object property is a | |
217 | procedure-with-setter that can be called in two ways. @code{(set! | |
218 | (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property} | |
219 | to @var{val}. @code{(@var{property} @var{obj})} returns the current | |
220 | setting of @var{obj}'s @var{property}. | |
221 | @end deffn | |
222 | ||
223 | A single object property created by @code{make-object-property} can | |
224 | associate distinct property values with all Scheme values that are | |
da6ecd49 | 225 | distinguishable by @code{eq?} (ruling out numeric values). |
07d83abe MV |
226 | |
227 | Internally, object properties are implemented using a weak key hash | |
228 | table. This means that, as long as a Scheme value with property values | |
229 | is protected from garbage collection, its property values are also | |
230 | protected. When the Scheme value is collected, its entry in the | |
231 | property table is removed and so the (ex-) property values are no longer | |
232 | protected by the table. | |
233 | ||
79488112 AW |
234 | Guile also implements a more traditional Lispy interface to properties, |
235 | in which each object has an list of key-value pairs associated with it. | |
236 | Properties in that list are keyed by symbols. This is a legacy | |
237 | interface; you should use weak hash tables or object properties instead. | |
07d83abe MV |
238 | |
239 | @deffn {Scheme Procedure} object-properties obj | |
240 | @deffnx {C Function} scm_object_properties (obj) | |
241 | Return @var{obj}'s property list. | |
242 | @end deffn | |
243 | ||
244 | @deffn {Scheme Procedure} set-object-properties! obj alist | |
245 | @deffnx {C Function} scm_set_object_properties_x (obj, alist) | |
246 | Set @var{obj}'s property list to @var{alist}. | |
247 | @end deffn | |
248 | ||
249 | @deffn {Scheme Procedure} object-property obj key | |
250 | @deffnx {C Function} scm_object_property (obj, key) | |
251 | Return the property of @var{obj} with name @var{key}. | |
252 | @end deffn | |
253 | ||
254 | @deffn {Scheme Procedure} set-object-property! obj key value | |
255 | @deffnx {C Function} scm_set_object_property_x (obj, key, value) | |
256 | In @var{obj}'s property list, set the property named @var{key} | |
257 | to @var{value}. | |
258 | @end deffn | |
259 | ||
260 | ||
261 | @node Sorting | |
262 | @subsection Sorting | |
263 | ||
264 | @c FIXME::martin: Review me! | |
265 | ||
266 | @cindex sorting | |
267 | @cindex sorting lists | |
268 | @cindex sorting vectors | |
269 | ||
270 | Sorting is very important in computer programs. Therefore, Guile comes | |
271 | with several sorting procedures built-in. As always, procedures with | |
272 | names ending in @code{!} are side-effecting, that means that they may | |
273 | modify their parameters in order to produce their results. | |
274 | ||
275 | The first group of procedures can be used to merge two lists (which must | |
276 | be already sorted on their own) and produce sorted lists containing | |
277 | all elements of the input lists. | |
278 | ||
279 | @deffn {Scheme Procedure} merge alist blist less | |
280 | @deffnx {C Function} scm_merge (alist, blist, less) | |
281 | Merge two already sorted lists into one. | |
282 | Given two lists @var{alist} and @var{blist}, such that | |
283 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)}, | |
284 | return a new list in which the elements of @var{alist} and | |
285 | @var{blist} have been stably interleaved so that | |
286 | @code{(sorted? (merge alist blist less?) less?)}. | |
287 | Note: this does _not_ accept vectors. | |
288 | @end deffn | |
289 | ||
290 | @deffn {Scheme Procedure} merge! alist blist less | |
291 | @deffnx {C Function} scm_merge_x (alist, blist, less) | |
292 | Takes two lists @var{alist} and @var{blist} such that | |
293 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
294 | returns a new list in which the elements of @var{alist} and | |
295 | @var{blist} have been stably interleaved so that | |
296 | @code{(sorted? (merge alist blist less?) less?)}. | |
297 | This is the destructive variant of @code{merge} | |
298 | Note: this does _not_ accept vectors. | |
299 | @end deffn | |
300 | ||
301 | The following procedures can operate on sequences which are either | |
302 | vectors or list. According to the given arguments, they return sorted | |
303 | vectors or lists, respectively. The first of the following procedures | |
304 | determines whether a sequence is already sorted, the other sort a given | |
305 | sequence. The variants with names starting with @code{stable-} are | |
306 | special in that they maintain a special property of the input sequences: | |
307 | If two or more elements are the same according to the comparison | |
308 | predicate, they are left in the same order as they appeared in the | |
309 | input. | |
310 | ||
311 | @deffn {Scheme Procedure} sorted? items less | |
312 | @deffnx {C Function} scm_sorted_p (items, less) | |
a4b4fbbd | 313 | Return @code{#t} if @var{items} is a list or vector such that, |
fd07759b LC |
314 | for each element @var{x} and the next element @var{y} of |
315 | @var{items}, @code{(@var{less} @var{y} @var{x})} returns | |
a4b4fbbd | 316 | @code{#f}. Otherwise return @code{#f}. |
07d83abe MV |
317 | @end deffn |
318 | ||
319 | @deffn {Scheme Procedure} sort items less | |
320 | @deffnx {C Function} scm_sort (items, less) | |
321 | Sort the sequence @var{items}, which may be a list or a | |
322 | vector. @var{less} is used for comparing the sequence | |
323 | elements. This is not a stable sort. | |
324 | @end deffn | |
325 | ||
326 | @deffn {Scheme Procedure} sort! items less | |
327 | @deffnx {C Function} scm_sort_x (items, less) | |
328 | Sort the sequence @var{items}, which may be a list or a | |
329 | vector. @var{less} is used for comparing the sequence | |
330 | elements. The sorting is destructive, that means that the | |
331 | input sequence is modified to produce the sorted result. | |
332 | This is not a stable sort. | |
333 | @end deffn | |
334 | ||
335 | @deffn {Scheme Procedure} stable-sort items less | |
336 | @deffnx {C Function} scm_stable_sort (items, less) | |
337 | Sort the sequence @var{items}, which may be a list or a | |
338 | vector. @var{less} is used for comparing the sequence elements. | |
339 | This is a stable sort. | |
340 | @end deffn | |
341 | ||
342 | @deffn {Scheme Procedure} stable-sort! items less | |
343 | @deffnx {C Function} scm_stable_sort_x (items, less) | |
344 | Sort the sequence @var{items}, which may be a list or a | |
345 | vector. @var{less} is used for comparing the sequence elements. | |
346 | The sorting is destructive, that means that the input sequence | |
347 | is modified to produce the sorted result. | |
348 | This is a stable sort. | |
349 | @end deffn | |
350 | ||
351 | The procedures in the last group only accept lists or vectors as input, | |
352 | as their names indicate. | |
353 | ||
354 | @deffn {Scheme Procedure} sort-list items less | |
355 | @deffnx {C Function} scm_sort_list (items, less) | |
356 | Sort the list @var{items}, using @var{less} for comparing the | |
357 | list elements. This is a stable sort. | |
358 | @end deffn | |
359 | ||
360 | @deffn {Scheme Procedure} sort-list! items less | |
361 | @deffnx {C Function} scm_sort_list_x (items, less) | |
362 | Sort the list @var{items}, using @var{less} for comparing the | |
363 | list elements. The sorting is destructive, that means that the | |
364 | input list is modified to produce the sorted result. | |
365 | This is a stable sort. | |
366 | @end deffn | |
367 | ||
368 | @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos | |
369 | @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos) | |
370 | Sort the vector @var{vec}, using @var{less} for comparing | |
3dd6e0cf MV |
371 | the vector elements. @var{startpos} (inclusively) and |
372 | @var{endpos} (exclusively) delimit | |
07d83abe MV |
373 | the range of the vector which gets sorted. The return value |
374 | is not specified. | |
375 | @end deffn | |
376 | ||
377 | ||
378 | @node Copying | |
379 | @subsection Copying Deep Structures | |
380 | ||
381 | @c FIXME::martin: Review me! | |
382 | ||
383 | The procedures for copying lists (@pxref{Lists}) only produce a flat | |
384 | copy of the input list, and currently Guile does not even contain | |
385 | procedures for copying vectors. @code{copy-tree} can be used for these | |
386 | application, as it does not only copy the spine of a list, but also | |
387 | copies any pairs in the cars of the input lists. | |
388 | ||
389 | @deffn {Scheme Procedure} copy-tree obj | |
390 | @deffnx {C Function} scm_copy_tree (obj) | |
ecb87335 | 391 | Recursively copy the data tree that is bound to @var{obj}, and return |
cdf1ad3b | 392 | the new data structure. @code{copy-tree} recurses down the |
07d83abe MV |
393 | contents of both pairs and vectors (since both cons cells and vector |
394 | cells may point to arbitrary objects), and stops recursing when it hits | |
395 | any other object. | |
396 | @end deffn | |
397 | ||
398 | ||
399 | @node General Conversion | |
400 | @subsection General String Conversion | |
401 | ||
402 | @c FIXME::martin: Review me! | |
403 | ||
404 | When debugging Scheme programs, but also for providing a human-friendly | |
405 | interface, a procedure for converting any Scheme object into string | |
406 | format is very useful. Conversion from/to strings can of course be done | |
407 | with specialized procedures when the data type of the object to convert | |
408 | is known, but with this procedure, it is often more comfortable. | |
409 | ||
410 | @code{object->string} converts an object by using a print procedure for | |
411 | writing to a string port, and then returning the resulting string. | |
412 | Converting an object back from the string is only possible if the object | |
413 | type has a read syntax and the read syntax is preserved by the printing | |
414 | procedure. | |
415 | ||
416 | @deffn {Scheme Procedure} object->string obj [printer] | |
417 | @deffnx {C Function} scm_object_to_string (obj, printer) | |
418 | Return a Scheme string obtained by printing @var{obj}. | |
419 | Printing function can be specified by the optional second | |
420 | argument @var{printer} (default: @code{write}). | |
421 | @end deffn | |
422 | ||
423 | ||
424 | @node Hooks | |
425 | @subsection Hooks | |
426 | @tpindex Hooks | |
427 | ||
428 | A hook is a list of procedures to be called at well defined points in | |
429 | time. Typically, an application provides a hook @var{h} and promises | |
430 | its users that it will call all of the procedures in @var{h} at a | |
431 | defined point in the application's processing. By adding its own | |
432 | procedure to @var{h}, an application user can tap into or even influence | |
433 | the progress of the application. | |
434 | ||
435 | Guile itself provides several such hooks for debugging and customization | |
436 | purposes: these are listed in a subsection below. | |
437 | ||
438 | When an application first creates a hook, it needs to know how many | |
439 | arguments will be passed to the hook's procedures when the hook is run. | |
440 | The chosen number of arguments (which may be none) is declared when the | |
441 | hook is created, and all the procedures that are added to that hook must | |
442 | be capable of accepting that number of arguments. | |
443 | ||
444 | A hook is created using @code{make-hook}. A procedure can be added to | |
445 | or removed from a hook using @code{add-hook!} or @code{remove-hook!}, | |
446 | and all of a hook's procedures can be removed together using | |
447 | @code{reset-hook!}. When an application wants to run a hook, it does so | |
448 | using @code{run-hook}. | |
449 | ||
450 | @menu | |
451 | * Hook Example:: Hook usage by example. | |
452 | * Hook Reference:: Reference of all hook procedures. | |
453 | * C Hooks:: Hooks for use from C code. | |
454 | * GC Hooks:: Garbage collection hooks. | |
455 | * REPL Hooks:: Hooks into the Guile REPL. | |
456 | @end menu | |
457 | ||
458 | ||
459 | @node Hook Example | |
460 | @subsubsection Hook Usage by Example | |
461 | ||
462 | Hook usage is shown by some examples in this section. First, we will | |
463 | define a hook of arity 2 --- that is, the procedures stored in the hook | |
464 | will have to accept two arguments. | |
465 | ||
466 | @lisp | |
467 | (define hook (make-hook 2)) | |
468 | hook | |
469 | @result{} #<hook 2 40286c90> | |
470 | @end lisp | |
471 | ||
472 | Now we are ready to add some procedures to the newly created hook with | |
473 | @code{add-hook!}. In the following example, two procedures are added, | |
474 | which print different messages and do different things with their | |
475 | arguments. | |
476 | ||
477 | @lisp | |
478 | (add-hook! hook (lambda (x y) | |
479 | (display "Foo: ") | |
480 | (display (+ x y)) | |
481 | (newline))) | |
482 | (add-hook! hook (lambda (x y) | |
483 | (display "Bar: ") | |
484 | (display (* x y)) | |
485 | (newline))) | |
486 | @end lisp | |
487 | ||
488 | Once the procedures have been added, we can invoke the hook using | |
489 | @code{run-hook}. | |
490 | ||
491 | @lisp | |
492 | (run-hook hook 3 4) | |
493 | @print{} Bar: 12 | |
494 | @print{} Foo: 7 | |
495 | @end lisp | |
496 | ||
497 | Note that the procedures are called in the reverse of the order with | |
498 | which they were added. This is because the default behaviour of | |
499 | @code{add-hook!} is to add its procedure to the @emph{front} of the | |
500 | hook's procedure list. You can force @code{add-hook!} to add its | |
501 | procedure to the @emph{end} of the list instead by providing a third | |
502 | @code{#t} argument on the second call to @code{add-hook!}. | |
503 | ||
504 | @lisp | |
505 | (add-hook! hook (lambda (x y) | |
506 | (display "Foo: ") | |
507 | (display (+ x y)) | |
508 | (newline))) | |
509 | (add-hook! hook (lambda (x y) | |
510 | (display "Bar: ") | |
511 | (display (* x y)) | |
512 | (newline)) | |
513 | #t) ; @r{<- Change here!} | |
514 | ||
515 | (run-hook hook 3 4) | |
516 | @print{} Foo: 7 | |
517 | @print{} Bar: 12 | |
518 | @end lisp | |
519 | ||
520 | ||
521 | @node Hook Reference | |
522 | @subsubsection Hook Reference | |
523 | ||
524 | When you create a hook with @code{make-hook}, you must specify the arity | |
525 | of the procedures which can be added to the hook. If the arity is not | |
526 | given explicitly as an argument to @code{make-hook}, it defaults to | |
527 | zero. All procedures of a given hook must have the same arity, and when | |
528 | the procedures are invoked using @code{run-hook}, the number of | |
529 | arguments passed must match the arity specified at hook creation time. | |
530 | ||
531 | The order in which procedures are added to a hook matters. If the third | |
532 | parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the | |
533 | procedure is added in front of the procedures which might already be on | |
534 | that hook, otherwise the procedure is added at the end. The procedures | |
535 | are always called from the front to the end of the list when they are | |
536 | invoked via @code{run-hook}. | |
537 | ||
538 | The ordering of the list of procedures returned by @code{hook->list} | |
539 | matches the order in which those procedures would be called if the hook | |
540 | was run using @code{run-hook}. | |
541 | ||
542 | Note that the C functions in the following entries are for handling | |
543 | @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which | |
544 | have their own interface (@pxref{C Hooks}). | |
545 | ||
546 | @deffn {Scheme Procedure} make-hook [n_args] | |
547 | @deffnx {C Function} scm_make_hook (n_args) | |
548 | Create a hook for storing procedure of arity @var{n_args}. | |
549 | @var{n_args} defaults to zero. The returned value is a hook | |
550 | object to be used with the other hook procedures. | |
551 | @end deffn | |
552 | ||
553 | @deffn {Scheme Procedure} hook? x | |
554 | @deffnx {C Function} scm_hook_p (x) | |
555 | Return @code{#t} if @var{x} is a hook, @code{#f} otherwise. | |
556 | @end deffn | |
557 | ||
558 | @deffn {Scheme Procedure} hook-empty? hook | |
559 | @deffnx {C Function} scm_hook_empty_p (hook) | |
560 | Return @code{#t} if @var{hook} is an empty hook, @code{#f} | |
561 | otherwise. | |
562 | @end deffn | |
563 | ||
564 | @deffn {Scheme Procedure} add-hook! hook proc [append_p] | |
565 | @deffnx {C Function} scm_add_hook_x (hook, proc, append_p) | |
566 | Add the procedure @var{proc} to the hook @var{hook}. The | |
567 | procedure is added to the end if @var{append_p} is true, | |
568 | otherwise it is added to the front. The return value of this | |
569 | procedure is not specified. | |
570 | @end deffn | |
571 | ||
572 | @deffn {Scheme Procedure} remove-hook! hook proc | |
573 | @deffnx {C Function} scm_remove_hook_x (hook, proc) | |
574 | Remove the procedure @var{proc} from the hook @var{hook}. The | |
575 | return value of this procedure is not specified. | |
576 | @end deffn | |
577 | ||
578 | @deffn {Scheme Procedure} reset-hook! hook | |
579 | @deffnx {C Function} scm_reset_hook_x (hook) | |
580 | Remove all procedures from the hook @var{hook}. The return | |
581 | value of this procedure is not specified. | |
582 | @end deffn | |
583 | ||
584 | @deffn {Scheme Procedure} hook->list hook | |
585 | @deffnx {C Function} scm_hook_to_list (hook) | |
586 | Convert the procedure list of @var{hook} to a list. | |
587 | @end deffn | |
588 | ||
df0a1002 | 589 | @deffn {Scheme Procedure} run-hook hook arg @dots{} |
07d83abe | 590 | @deffnx {C Function} scm_run_hook (hook, args) |
df0a1002 BT |
591 | Apply all procedures from the hook @var{hook} to the arguments @var{arg} |
592 | @enddots{}. The order of the procedure application is first to last. | |
593 | The return value of this procedure is not specified. | |
07d83abe MV |
594 | @end deffn |
595 | ||
596 | If, in C code, you are certain that you have a hook object and well | |
597 | formed argument list for that hook, you can also use | |
598 | @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but | |
599 | does no type checking. | |
600 | ||
601 | @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args) | |
602 | The same as @code{scm_run_hook} but without any type checking to confirm | |
603 | that @var{hook} is actually a hook object and that @var{args} is a | |
604 | well-formed list matching the arity of the hook. | |
605 | @end deftypefn | |
606 | ||
607 | For C code, @code{SCM_HOOKP} is a faster alternative to | |
608 | @code{scm_hook_p}: | |
609 | ||
610 | @deftypefn {C Macro} int SCM_HOOKP (x) | |
611 | Return 1 if @var{x} is a Scheme-level hook, 0 otherwise. | |
612 | @end deftypefn | |
613 | ||
614 | ||
615 | @subsubsection Handling Scheme-level hooks from C code | |
616 | ||
617 | Here is an example of how to handle Scheme-level hooks from C code using | |
618 | the above functions. | |
619 | ||
620 | @example | |
621 | if (scm_is_true (scm_hook_p (obj))) | |
622 | /* handle Scheme-level hook using C functions */ | |
623 | scm_reset_hook_x (obj); | |
624 | else | |
625 | /* do something else (obj is not a hook) */ | |
626 | @end example | |
627 | ||
628 | ||
629 | @node C Hooks | |
630 | @subsubsection Hooks For C Code. | |
631 | ||
632 | The hooks already described are intended to be populated by Scheme-level | |
633 | procedures. In addition to this, the Guile library provides an | |
634 | independent set of interfaces for the creation and manipulation of hooks | |
635 | that are designed to be populated by functions implemented in C. | |
636 | ||
637 | The original motivation here was to provide a kind of hook that could | |
638 | safely be invoked at various points during garbage collection. | |
639 | Scheme-level hooks are unsuitable for this purpose as running them could | |
640 | itself require memory allocation, which would then invoke garbage | |
641 | collection recursively @dots{} However, it is also the case that these | |
642 | hooks are easier to work with than the Scheme-level ones if you only | |
643 | want to register C functions with them. So if that is mainly what your | |
644 | code needs to do, you may prefer to use this interface. | |
645 | ||
646 | To create a C hook, you should allocate storage for a structure of type | |
647 | @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}. | |
648 | ||
649 | @deftp {C Type} scm_t_c_hook | |
650 | Data type for a C hook. The internals of this type should be treated as | |
651 | opaque. | |
652 | @end deftp | |
653 | ||
654 | @deftp {C Enum} scm_t_c_hook_type | |
655 | Enumeration of possible hook types, which are: | |
656 | ||
657 | @table @code | |
658 | @item SCM_C_HOOK_NORMAL | |
659 | @vindex SCM_C_HOOK_NORMAL | |
660 | Type of hook for which all the registered functions will always be called. | |
661 | @item SCM_C_HOOK_OR | |
662 | @vindex SCM_C_HOOK_OR | |
663 | Type of hook for which the sequence of registered functions will be | |
664 | called only until one of them returns C true (a non-NULL pointer). | |
665 | @item SCM_C_HOOK_AND | |
666 | @vindex SCM_C_HOOK_AND | |
667 | Type of hook for which the sequence of registered functions will be | |
668 | called only until one of them returns C false (a NULL pointer). | |
669 | @end table | |
670 | @end deftp | |
671 | ||
672 | @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type) | |
673 | Initialize the C hook at memory pointed to by @var{hook}. @var{type} | |
674 | should be one of the values of the @code{scm_t_c_hook_type} enumeration, | |
675 | and controls how the hook functions will be called. @var{hook_data} is | |
676 | a closure parameter that will be passed to all registered hook functions | |
677 | when they are called. | |
678 | @end deftypefn | |
679 | ||
680 | To add or remove a C function from a C hook, use @code{scm_c_hook_add} | |
681 | or @code{scm_c_hook_remove}. A hook function must expect three | |
682 | @code{void *} parameters which are, respectively: | |
683 | ||
684 | @table @var | |
685 | @item hook_data | |
686 | The hook closure data that was specified at the time the hook was | |
687 | initialized by @code{scm_c_hook_init}. | |
688 | ||
689 | @item func_data | |
690 | The function closure data that was specified at the time that that | |
691 | function was registered with the hook by @code{scm_c_hook_add}. | |
692 | ||
693 | @item data | |
694 | The call closure data specified by the @code{scm_c_hook_run} call that | |
695 | runs the hook. | |
696 | @end table | |
697 | ||
698 | @deftp {C Type} scm_t_c_hook_function | |
699 | Function type for a C hook function: takes three @code{void *} | |
700 | parameters and returns a @code{void *} result. | |
701 | @end deftp | |
702 | ||
703 | @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp) | |
704 | Add function @var{func}, with function closure data @var{func_data}, to | |
705 | the C hook @var{hook}. The new function is appended to the hook's list | |
706 | of functions if @var{appendp} is non-zero, otherwise prepended. | |
707 | @end deftypefn | |
708 | ||
709 | @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data) | |
710 | Remove function @var{func}, with function closure data @var{func_data}, | |
711 | from the C hook @var{hook}. @code{scm_c_hook_remove} checks both | |
712 | @var{func} and @var{func_data} so as to allow for the same @var{func} | |
713 | being registered multiple times with different closure data. | |
714 | @end deftypefn | |
715 | ||
716 | Finally, to invoke a C hook, call the @code{scm_c_hook_run} function | |
717 | specifying the hook and the call closure data for this run: | |
718 | ||
719 | @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data) | |
720 | Run the C hook @var{hook} will call closure data @var{data}. Subject to | |
721 | the variations for hook types @code{SCM_C_HOOK_OR} and | |
722 | @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s | |
723 | registered functions in turn, passing them the hook's closure data, each | |
724 | function's closure data, and the call closure data. | |
725 | ||
726 | @code{scm_c_hook_run}'s return value is the return value of the last | |
727 | function to be called. | |
728 | @end deftypefn | |
729 | ||
730 | ||
731 | @node GC Hooks | |
732 | @subsubsection Hooks for Garbage Collection | |
733 | ||
734 | Whenever Guile performs a garbage collection, it calls the following | |
735 | hooks in the order shown. | |
736 | ||
737 | @defvr {C Hook} scm_before_gc_c_hook | |
738 | C hook called at the very start of a garbage collection, after setting | |
739 | @code{scm_gc_running_p} to 1, but before entering the GC critical | |
740 | section. | |
741 | ||
742 | If garbage collection is blocked because @code{scm_block_gc} is | |
743 | non-zero, GC exits early soon after calling this hook, and no further | |
744 | hooks will be called. | |
745 | @end defvr | |
746 | ||
747 | @defvr {C Hook} scm_before_mark_c_hook | |
748 | C hook called before beginning the mark phase of garbage collection, | |
749 | after the GC thread has entered a critical section. | |
750 | @end defvr | |
751 | ||
752 | @defvr {C Hook} scm_before_sweep_c_hook | |
753 | C hook called before beginning the sweep phase of garbage collection. | |
754 | This is the same as at the end of the mark phase, since nothing else | |
755 | happens between marking and sweeping. | |
756 | @end defvr | |
757 | ||
758 | @defvr {C Hook} scm_after_sweep_c_hook | |
759 | C hook called after the end of the sweep phase of garbage collection, | |
760 | but while the GC thread is still inside its critical section. | |
761 | @end defvr | |
762 | ||
763 | @defvr {C Hook} scm_after_gc_c_hook | |
764 | C hook called at the very end of a garbage collection, after the GC | |
765 | thread has left its critical section. | |
766 | @end defvr | |
767 | ||
768 | @defvr {Scheme Hook} after-gc-hook | |
769 | @vindex scm_after_gc_hook | |
770 | Scheme hook with arity 0. This hook is run asynchronously | |
771 | (@pxref{Asyncs}) soon after the GC has completed and any other events | |
772 | that were deferred during garbage collection have been processed. (Also | |
773 | accessible from C with the name @code{scm_after_gc_hook}.) | |
774 | @end defvr | |
775 | ||
776 | All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are | |
72b3aa56 | 777 | initialized with hook closure data NULL, are invoked by |
07d83abe MV |
778 | @code{scm_c_hook_run} with call closure data NULL. |
779 | ||
780 | @cindex guardians, testing for GC'd objects | |
781 | The Scheme hook @code{after-gc-hook} is particularly useful in | |
782 | conjunction with guardians (@pxref{Guardians}). Typically, if you are | |
783 | using a guardian, you want to call the guardian after garbage collection | |
784 | to see if any of the objects added to the guardian have been collected. | |
785 | By adding a thunk that performs this call to @code{after-gc-hook}, you | |
786 | can ensure that your guardian is tested after every garbage collection | |
787 | cycle. | |
788 | ||
789 | ||
790 | @node REPL Hooks | |
791 | @subsubsection Hooks into the Guile REPL | |
792 | ||
793 | ||
794 | @c Local Variables: | |
795 | @c TeX-master: "guile.texi" | |
796 | @c End: |