Commit | Line | Data |
---|---|---|
07d83abe MV |
1 | @c -*-texinfo-*- |
2 | @c This is part of the GNU Guile Reference Manual. | |
3 | @c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004 | |
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 | ||
166 | New application-defined object types (@pxref{Defining New Types | |
167 | (Smobs)}) have an @code{equalp} handler which is called by | |
168 | @code{equal?}. This lets an application traverse the contents or | |
169 | control what is considered @code{equal?} for two objects of such a | |
170 | type. If there's no such handler, the default is to just compare as | |
171 | per @code{eq?}. | |
07d83abe MV |
172 | @end deffn |
173 | ||
174 | ||
175 | @node Object Properties | |
176 | @subsection Object Properties | |
177 | ||
178 | It's often useful to associate a piece of additional information with a | |
179 | Scheme object even though that object does not have a dedicated slot | |
180 | available in which the additional information could be stored. Object | |
181 | properties allow you to do just that. | |
182 | ||
07d83abe MV |
183 | Guile's representation of an object property is a procedure-with-setter |
184 | (@pxref{Procedures with Setters}) that can be used with the generalized | |
185 | form of @code{set!} (REFFIXME) to set and retrieve that property for any | |
186 | Scheme object. So, setting a property looks like this: | |
187 | ||
188 | @lisp | |
189 | (set! (my-property obj1) value-for-obj1) | |
190 | (set! (my-property obj2) value-for-obj2) | |
191 | @end lisp | |
192 | ||
193 | @noindent | |
194 | And retrieving values of the same property looks like this: | |
195 | ||
196 | @lisp | |
197 | (my-property obj1) | |
198 | @result{} | |
199 | value-for-obj1 | |
200 | ||
201 | (my-property obj2) | |
202 | @result{} | |
203 | value-for-obj2 | |
204 | @end lisp | |
205 | ||
206 | To create an object property in the first place, use the | |
207 | @code{make-object-property} procedure: | |
208 | ||
209 | @lisp | |
210 | (define my-property (make-object-property)) | |
211 | @end lisp | |
212 | ||
213 | @deffn {Scheme Procedure} make-object-property | |
214 | Create and return an object property. An object property is a | |
215 | procedure-with-setter that can be called in two ways. @code{(set! | |
216 | (@var{property} @var{obj}) @var{val})} sets @var{obj}'s @var{property} | |
217 | to @var{val}. @code{(@var{property} @var{obj})} returns the current | |
218 | setting of @var{obj}'s @var{property}. | |
219 | @end deffn | |
220 | ||
221 | A single object property created by @code{make-object-property} can | |
222 | associate distinct property values with all Scheme values that are | |
223 | distinguishable by @code{eq?} (including, for example, integers). | |
224 | ||
225 | Internally, object properties are implemented using a weak key hash | |
226 | table. This means that, as long as a Scheme value with property values | |
227 | is protected from garbage collection, its property values are also | |
228 | protected. When the Scheme value is collected, its entry in the | |
229 | property table is removed and so the (ex-) property values are no longer | |
230 | protected by the table. | |
231 | ||
232 | @menu | |
233 | * Property Primitives:: Low level property implementation. | |
234 | * Old-fashioned Properties:: An older approach to properties. | |
235 | @end menu | |
236 | ||
237 | ||
238 | @node Property Primitives | |
239 | @subsubsection Low Level Property Implementation. | |
240 | ||
241 | @deffn {Scheme Procedure} primitive-make-property not-found-proc | |
242 | @deffnx {C Function} scm_primitive_make_property (not_found_proc) | |
243 | Create a @dfn{property token} that can be used with | |
244 | @code{primitive-property-ref} and @code{primitive-property-set!}. | |
245 | See @code{primitive-property-ref} for the significance of | |
246 | @var{not-found-proc}. | |
247 | @end deffn | |
248 | ||
249 | @deffn {Scheme Procedure} primitive-property-ref prop obj | |
250 | @deffnx {C Function} scm_primitive_property_ref (prop, obj) | |
251 | Return the property @var{prop} of @var{obj}. | |
252 | ||
253 | When no value has yet been associated with @var{prop} and @var{obj}, | |
254 | the @var{not-found-proc} from @var{prop} is used. A call | |
255 | @code{(@var{not-found-proc} @var{prop} @var{obj})} is made and the | |
256 | result set as the property value. If @var{not-found-proc} is | |
257 | @code{#f} then @code{#f} is the property value. | |
258 | @end deffn | |
259 | ||
260 | @deffn {Scheme Procedure} primitive-property-set! prop obj val | |
261 | @deffnx {C Function} scm_primitive_property_set_x (prop, obj, val) | |
262 | Set the property @var{prop} of @var{obj} to @var{val}. | |
263 | @end deffn | |
264 | ||
265 | @deffn {Scheme Procedure} primitive-property-del! prop obj | |
266 | @deffnx {C Function} scm_primitive_property_del_x (prop, obj) | |
267 | Remove any value associated with @var{prop} and @var{obj}. | |
268 | @end deffn | |
269 | ||
270 | ||
271 | @node Old-fashioned Properties | |
272 | @subsubsection An Older Approach to Properties | |
273 | ||
274 | Traditionally, Lisp systems provide a different object property | |
275 | interface to that provided by @code{make-object-property}, in which the | |
276 | object property that is being set or retrieved is indicated by a symbol. | |
277 | ||
278 | Guile includes this older kind of interface as well, but it may well be | |
279 | removed in a future release, as it is less powerful than | |
280 | @code{make-object-property} and so increases the size of the Guile | |
281 | library for no benefit. (And it is trivial to write a compatibility | |
282 | layer in Scheme.) | |
283 | ||
284 | @deffn {Scheme Procedure} object-properties obj | |
285 | @deffnx {C Function} scm_object_properties (obj) | |
286 | Return @var{obj}'s property list. | |
287 | @end deffn | |
288 | ||
289 | @deffn {Scheme Procedure} set-object-properties! obj alist | |
290 | @deffnx {C Function} scm_set_object_properties_x (obj, alist) | |
291 | Set @var{obj}'s property list to @var{alist}. | |
292 | @end deffn | |
293 | ||
294 | @deffn {Scheme Procedure} object-property obj key | |
295 | @deffnx {C Function} scm_object_property (obj, key) | |
296 | Return the property of @var{obj} with name @var{key}. | |
297 | @end deffn | |
298 | ||
299 | @deffn {Scheme Procedure} set-object-property! obj key value | |
300 | @deffnx {C Function} scm_set_object_property_x (obj, key, value) | |
301 | In @var{obj}'s property list, set the property named @var{key} | |
302 | to @var{value}. | |
303 | @end deffn | |
304 | ||
305 | ||
306 | @node Sorting | |
307 | @subsection Sorting | |
308 | ||
309 | @c FIXME::martin: Review me! | |
310 | ||
311 | @cindex sorting | |
312 | @cindex sorting lists | |
313 | @cindex sorting vectors | |
314 | ||
315 | Sorting is very important in computer programs. Therefore, Guile comes | |
316 | with several sorting procedures built-in. As always, procedures with | |
317 | names ending in @code{!} are side-effecting, that means that they may | |
318 | modify their parameters in order to produce their results. | |
319 | ||
320 | The first group of procedures can be used to merge two lists (which must | |
321 | be already sorted on their own) and produce sorted lists containing | |
322 | all elements of the input lists. | |
323 | ||
324 | @deffn {Scheme Procedure} merge alist blist less | |
325 | @deffnx {C Function} scm_merge (alist, blist, less) | |
326 | Merge two already sorted lists into one. | |
327 | Given two lists @var{alist} and @var{blist}, such that | |
328 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)}, | |
329 | return a new list in which the elements of @var{alist} and | |
330 | @var{blist} have been stably interleaved so that | |
331 | @code{(sorted? (merge alist blist less?) less?)}. | |
332 | Note: this does _not_ accept vectors. | |
333 | @end deffn | |
334 | ||
335 | @deffn {Scheme Procedure} merge! alist blist less | |
336 | @deffnx {C Function} scm_merge_x (alist, blist, less) | |
337 | Takes two lists @var{alist} and @var{blist} such that | |
338 | @code{(sorted? alist less?)} and @code{(sorted? blist less?)} and | |
339 | returns a new list in which the elements of @var{alist} and | |
340 | @var{blist} have been stably interleaved so that | |
341 | @code{(sorted? (merge alist blist less?) less?)}. | |
342 | This is the destructive variant of @code{merge} | |
343 | Note: this does _not_ accept vectors. | |
344 | @end deffn | |
345 | ||
346 | The following procedures can operate on sequences which are either | |
347 | vectors or list. According to the given arguments, they return sorted | |
348 | vectors or lists, respectively. The first of the following procedures | |
349 | determines whether a sequence is already sorted, the other sort a given | |
350 | sequence. The variants with names starting with @code{stable-} are | |
351 | special in that they maintain a special property of the input sequences: | |
352 | If two or more elements are the same according to the comparison | |
353 | predicate, they are left in the same order as they appeared in the | |
354 | input. | |
355 | ||
356 | @deffn {Scheme Procedure} sorted? items less | |
357 | @deffnx {C Function} scm_sorted_p (items, less) | |
358 | Return @code{#t} iff @var{items} is a list or a vector such that | |
359 | for all 1 <= i <= m, the predicate @var{less} returns true when | |
360 | applied to all elements i - 1 and i | |
361 | @end deffn | |
362 | ||
363 | @deffn {Scheme Procedure} sort items less | |
364 | @deffnx {C Function} scm_sort (items, less) | |
365 | Sort the sequence @var{items}, which may be a list or a | |
366 | vector. @var{less} is used for comparing the sequence | |
367 | elements. This is not a stable sort. | |
368 | @end deffn | |
369 | ||
370 | @deffn {Scheme Procedure} sort! items less | |
371 | @deffnx {C Function} scm_sort_x (items, less) | |
372 | Sort the sequence @var{items}, which may be a list or a | |
373 | vector. @var{less} is used for comparing the sequence | |
374 | elements. The sorting is destructive, that means that the | |
375 | input sequence is modified to produce the sorted result. | |
376 | This is not a stable sort. | |
377 | @end deffn | |
378 | ||
379 | @deffn {Scheme Procedure} stable-sort items less | |
380 | @deffnx {C Function} scm_stable_sort (items, less) | |
381 | Sort the sequence @var{items}, which may be a list or a | |
382 | vector. @var{less} is used for comparing the sequence elements. | |
383 | This is a stable sort. | |
384 | @end deffn | |
385 | ||
386 | @deffn {Scheme Procedure} stable-sort! items less | |
387 | @deffnx {C Function} scm_stable_sort_x (items, less) | |
388 | Sort the sequence @var{items}, which may be a list or a | |
389 | vector. @var{less} is used for comparing the sequence elements. | |
390 | The sorting is destructive, that means that the input sequence | |
391 | is modified to produce the sorted result. | |
392 | This is a stable sort. | |
393 | @end deffn | |
394 | ||
395 | The procedures in the last group only accept lists or vectors as input, | |
396 | as their names indicate. | |
397 | ||
398 | @deffn {Scheme Procedure} sort-list items less | |
399 | @deffnx {C Function} scm_sort_list (items, less) | |
400 | Sort the list @var{items}, using @var{less} for comparing the | |
401 | list elements. This is a stable sort. | |
402 | @end deffn | |
403 | ||
404 | @deffn {Scheme Procedure} sort-list! items less | |
405 | @deffnx {C Function} scm_sort_list_x (items, less) | |
406 | Sort the list @var{items}, using @var{less} for comparing the | |
407 | list elements. The sorting is destructive, that means that the | |
408 | input list is modified to produce the sorted result. | |
409 | This is a stable sort. | |
410 | @end deffn | |
411 | ||
412 | @deffn {Scheme Procedure} restricted-vector-sort! vec less startpos endpos | |
413 | @deffnx {C Function} scm_restricted_vector_sort_x (vec, less, startpos, endpos) | |
414 | Sort the vector @var{vec}, using @var{less} for comparing | |
3dd6e0cf MV |
415 | the vector elements. @var{startpos} (inclusively) and |
416 | @var{endpos} (exclusively) delimit | |
07d83abe MV |
417 | the range of the vector which gets sorted. The return value |
418 | is not specified. | |
419 | @end deffn | |
420 | ||
421 | ||
422 | @node Copying | |
423 | @subsection Copying Deep Structures | |
424 | ||
425 | @c FIXME::martin: Review me! | |
426 | ||
427 | The procedures for copying lists (@pxref{Lists}) only produce a flat | |
428 | copy of the input list, and currently Guile does not even contain | |
429 | procedures for copying vectors. @code{copy-tree} can be used for these | |
430 | application, as it does not only copy the spine of a list, but also | |
431 | copies any pairs in the cars of the input lists. | |
432 | ||
433 | @deffn {Scheme Procedure} copy-tree obj | |
434 | @deffnx {C Function} scm_copy_tree (obj) | |
435 | Recursively copy the data tree that is bound to @var{obj}, and return a | |
cdf1ad3b | 436 | the new data structure. @code{copy-tree} recurses down the |
07d83abe MV |
437 | contents of both pairs and vectors (since both cons cells and vector |
438 | cells may point to arbitrary objects), and stops recursing when it hits | |
439 | any other object. | |
440 | @end deffn | |
441 | ||
442 | ||
443 | @node General Conversion | |
444 | @subsection General String Conversion | |
445 | ||
446 | @c FIXME::martin: Review me! | |
447 | ||
448 | When debugging Scheme programs, but also for providing a human-friendly | |
449 | interface, a procedure for converting any Scheme object into string | |
450 | format is very useful. Conversion from/to strings can of course be done | |
451 | with specialized procedures when the data type of the object to convert | |
452 | is known, but with this procedure, it is often more comfortable. | |
453 | ||
454 | @code{object->string} converts an object by using a print procedure for | |
455 | writing to a string port, and then returning the resulting string. | |
456 | Converting an object back from the string is only possible if the object | |
457 | type has a read syntax and the read syntax is preserved by the printing | |
458 | procedure. | |
459 | ||
460 | @deffn {Scheme Procedure} object->string obj [printer] | |
461 | @deffnx {C Function} scm_object_to_string (obj, printer) | |
462 | Return a Scheme string obtained by printing @var{obj}. | |
463 | Printing function can be specified by the optional second | |
464 | argument @var{printer} (default: @code{write}). | |
465 | @end deffn | |
466 | ||
467 | ||
468 | @node Hooks | |
469 | @subsection Hooks | |
470 | @tpindex Hooks | |
471 | ||
472 | A hook is a list of procedures to be called at well defined points in | |
473 | time. Typically, an application provides a hook @var{h} and promises | |
474 | its users that it will call all of the procedures in @var{h} at a | |
475 | defined point in the application's processing. By adding its own | |
476 | procedure to @var{h}, an application user can tap into or even influence | |
477 | the progress of the application. | |
478 | ||
479 | Guile itself provides several such hooks for debugging and customization | |
480 | purposes: these are listed in a subsection below. | |
481 | ||
482 | When an application first creates a hook, it needs to know how many | |
483 | arguments will be passed to the hook's procedures when the hook is run. | |
484 | The chosen number of arguments (which may be none) is declared when the | |
485 | hook is created, and all the procedures that are added to that hook must | |
486 | be capable of accepting that number of arguments. | |
487 | ||
488 | A hook is created using @code{make-hook}. A procedure can be added to | |
489 | or removed from a hook using @code{add-hook!} or @code{remove-hook!}, | |
490 | and all of a hook's procedures can be removed together using | |
491 | @code{reset-hook!}. When an application wants to run a hook, it does so | |
492 | using @code{run-hook}. | |
493 | ||
494 | @menu | |
495 | * Hook Example:: Hook usage by example. | |
496 | * Hook Reference:: Reference of all hook procedures. | |
497 | * C Hooks:: Hooks for use from C code. | |
498 | * GC Hooks:: Garbage collection hooks. | |
499 | * REPL Hooks:: Hooks into the Guile REPL. | |
500 | @end menu | |
501 | ||
502 | ||
503 | @node Hook Example | |
504 | @subsubsection Hook Usage by Example | |
505 | ||
506 | Hook usage is shown by some examples in this section. First, we will | |
507 | define a hook of arity 2 --- that is, the procedures stored in the hook | |
508 | will have to accept two arguments. | |
509 | ||
510 | @lisp | |
511 | (define hook (make-hook 2)) | |
512 | hook | |
513 | @result{} #<hook 2 40286c90> | |
514 | @end lisp | |
515 | ||
516 | Now we are ready to add some procedures to the newly created hook with | |
517 | @code{add-hook!}. In the following example, two procedures are added, | |
518 | which print different messages and do different things with their | |
519 | arguments. | |
520 | ||
521 | @lisp | |
522 | (add-hook! hook (lambda (x y) | |
523 | (display "Foo: ") | |
524 | (display (+ x y)) | |
525 | (newline))) | |
526 | (add-hook! hook (lambda (x y) | |
527 | (display "Bar: ") | |
528 | (display (* x y)) | |
529 | (newline))) | |
530 | @end lisp | |
531 | ||
532 | Once the procedures have been added, we can invoke the hook using | |
533 | @code{run-hook}. | |
534 | ||
535 | @lisp | |
536 | (run-hook hook 3 4) | |
537 | @print{} Bar: 12 | |
538 | @print{} Foo: 7 | |
539 | @end lisp | |
540 | ||
541 | Note that the procedures are called in the reverse of the order with | |
542 | which they were added. This is because the default behaviour of | |
543 | @code{add-hook!} is to add its procedure to the @emph{front} of the | |
544 | hook's procedure list. You can force @code{add-hook!} to add its | |
545 | procedure to the @emph{end} of the list instead by providing a third | |
546 | @code{#t} argument on the second call to @code{add-hook!}. | |
547 | ||
548 | @lisp | |
549 | (add-hook! hook (lambda (x y) | |
550 | (display "Foo: ") | |
551 | (display (+ x y)) | |
552 | (newline))) | |
553 | (add-hook! hook (lambda (x y) | |
554 | (display "Bar: ") | |
555 | (display (* x y)) | |
556 | (newline)) | |
557 | #t) ; @r{<- Change here!} | |
558 | ||
559 | (run-hook hook 3 4) | |
560 | @print{} Foo: 7 | |
561 | @print{} Bar: 12 | |
562 | @end lisp | |
563 | ||
564 | ||
565 | @node Hook Reference | |
566 | @subsubsection Hook Reference | |
567 | ||
568 | When you create a hook with @code{make-hook}, you must specify the arity | |
569 | of the procedures which can be added to the hook. If the arity is not | |
570 | given explicitly as an argument to @code{make-hook}, it defaults to | |
571 | zero. All procedures of a given hook must have the same arity, and when | |
572 | the procedures are invoked using @code{run-hook}, the number of | |
573 | arguments passed must match the arity specified at hook creation time. | |
574 | ||
575 | The order in which procedures are added to a hook matters. If the third | |
576 | parameter to @code{add-hook!} is omitted or is equal to @code{#f}, the | |
577 | procedure is added in front of the procedures which might already be on | |
578 | that hook, otherwise the procedure is added at the end. The procedures | |
579 | are always called from the front to the end of the list when they are | |
580 | invoked via @code{run-hook}. | |
581 | ||
582 | The ordering of the list of procedures returned by @code{hook->list} | |
583 | matches the order in which those procedures would be called if the hook | |
584 | was run using @code{run-hook}. | |
585 | ||
586 | Note that the C functions in the following entries are for handling | |
587 | @dfn{Scheme-level} hooks in C. There are also @dfn{C-level} hooks which | |
588 | have their own interface (@pxref{C Hooks}). | |
589 | ||
590 | @deffn {Scheme Procedure} make-hook [n_args] | |
591 | @deffnx {C Function} scm_make_hook (n_args) | |
592 | Create a hook for storing procedure of arity @var{n_args}. | |
593 | @var{n_args} defaults to zero. The returned value is a hook | |
594 | object to be used with the other hook procedures. | |
595 | @end deffn | |
596 | ||
597 | @deffn {Scheme Procedure} hook? x | |
598 | @deffnx {C Function} scm_hook_p (x) | |
599 | Return @code{#t} if @var{x} is a hook, @code{#f} otherwise. | |
600 | @end deffn | |
601 | ||
602 | @deffn {Scheme Procedure} hook-empty? hook | |
603 | @deffnx {C Function} scm_hook_empty_p (hook) | |
604 | Return @code{#t} if @var{hook} is an empty hook, @code{#f} | |
605 | otherwise. | |
606 | @end deffn | |
607 | ||
608 | @deffn {Scheme Procedure} add-hook! hook proc [append_p] | |
609 | @deffnx {C Function} scm_add_hook_x (hook, proc, append_p) | |
610 | Add the procedure @var{proc} to the hook @var{hook}. The | |
611 | procedure is added to the end if @var{append_p} is true, | |
612 | otherwise it is added to the front. The return value of this | |
613 | procedure is not specified. | |
614 | @end deffn | |
615 | ||
616 | @deffn {Scheme Procedure} remove-hook! hook proc | |
617 | @deffnx {C Function} scm_remove_hook_x (hook, proc) | |
618 | Remove the procedure @var{proc} from the hook @var{hook}. The | |
619 | return value of this procedure is not specified. | |
620 | @end deffn | |
621 | ||
622 | @deffn {Scheme Procedure} reset-hook! hook | |
623 | @deffnx {C Function} scm_reset_hook_x (hook) | |
624 | Remove all procedures from the hook @var{hook}. The return | |
625 | value of this procedure is not specified. | |
626 | @end deffn | |
627 | ||
628 | @deffn {Scheme Procedure} hook->list hook | |
629 | @deffnx {C Function} scm_hook_to_list (hook) | |
630 | Convert the procedure list of @var{hook} to a list. | |
631 | @end deffn | |
632 | ||
633 | @deffn {Scheme Procedure} run-hook hook . args | |
634 | @deffnx {C Function} scm_run_hook (hook, args) | |
635 | Apply all procedures from the hook @var{hook} to the arguments | |
636 | @var{args}. The order of the procedure application is first to | |
637 | last. The return value of this procedure is not specified. | |
638 | @end deffn | |
639 | ||
640 | If, in C code, you are certain that you have a hook object and well | |
641 | formed argument list for that hook, you can also use | |
642 | @code{scm_c_run_hook}, which is identical to @code{scm_run_hook} but | |
643 | does no type checking. | |
644 | ||
645 | @deftypefn {C Function} void scm_c_run_hook (SCM hook, SCM args) | |
646 | The same as @code{scm_run_hook} but without any type checking to confirm | |
647 | that @var{hook} is actually a hook object and that @var{args} is a | |
648 | well-formed list matching the arity of the hook. | |
649 | @end deftypefn | |
650 | ||
651 | For C code, @code{SCM_HOOKP} is a faster alternative to | |
652 | @code{scm_hook_p}: | |
653 | ||
654 | @deftypefn {C Macro} int SCM_HOOKP (x) | |
655 | Return 1 if @var{x} is a Scheme-level hook, 0 otherwise. | |
656 | @end deftypefn | |
657 | ||
658 | ||
659 | @subsubsection Handling Scheme-level hooks from C code | |
660 | ||
661 | Here is an example of how to handle Scheme-level hooks from C code using | |
662 | the above functions. | |
663 | ||
664 | @example | |
665 | if (scm_is_true (scm_hook_p (obj))) | |
666 | /* handle Scheme-level hook using C functions */ | |
667 | scm_reset_hook_x (obj); | |
668 | else | |
669 | /* do something else (obj is not a hook) */ | |
670 | @end example | |
671 | ||
672 | ||
673 | @node C Hooks | |
674 | @subsubsection Hooks For C Code. | |
675 | ||
676 | The hooks already described are intended to be populated by Scheme-level | |
677 | procedures. In addition to this, the Guile library provides an | |
678 | independent set of interfaces for the creation and manipulation of hooks | |
679 | that are designed to be populated by functions implemented in C. | |
680 | ||
681 | The original motivation here was to provide a kind of hook that could | |
682 | safely be invoked at various points during garbage collection. | |
683 | Scheme-level hooks are unsuitable for this purpose as running them could | |
684 | itself require memory allocation, which would then invoke garbage | |
685 | collection recursively @dots{} However, it is also the case that these | |
686 | hooks are easier to work with than the Scheme-level ones if you only | |
687 | want to register C functions with them. So if that is mainly what your | |
688 | code needs to do, you may prefer to use this interface. | |
689 | ||
690 | To create a C hook, you should allocate storage for a structure of type | |
691 | @code{scm_t_c_hook} and then initialize it using @code{scm_c_hook_init}. | |
692 | ||
693 | @deftp {C Type} scm_t_c_hook | |
694 | Data type for a C hook. The internals of this type should be treated as | |
695 | opaque. | |
696 | @end deftp | |
697 | ||
698 | @deftp {C Enum} scm_t_c_hook_type | |
699 | Enumeration of possible hook types, which are: | |
700 | ||
701 | @table @code | |
702 | @item SCM_C_HOOK_NORMAL | |
703 | @vindex SCM_C_HOOK_NORMAL | |
704 | Type of hook for which all the registered functions will always be called. | |
705 | @item SCM_C_HOOK_OR | |
706 | @vindex SCM_C_HOOK_OR | |
707 | Type of hook for which the sequence of registered functions will be | |
708 | called only until one of them returns C true (a non-NULL pointer). | |
709 | @item SCM_C_HOOK_AND | |
710 | @vindex SCM_C_HOOK_AND | |
711 | Type of hook for which the sequence of registered functions will be | |
712 | called only until one of them returns C false (a NULL pointer). | |
713 | @end table | |
714 | @end deftp | |
715 | ||
716 | @deftypefn {C Function} void scm_c_hook_init (scm_t_c_hook *hook, void *hook_data, scm_t_c_hook_type type) | |
717 | Initialize the C hook at memory pointed to by @var{hook}. @var{type} | |
718 | should be one of the values of the @code{scm_t_c_hook_type} enumeration, | |
719 | and controls how the hook functions will be called. @var{hook_data} is | |
720 | a closure parameter that will be passed to all registered hook functions | |
721 | when they are called. | |
722 | @end deftypefn | |
723 | ||
724 | To add or remove a C function from a C hook, use @code{scm_c_hook_add} | |
725 | or @code{scm_c_hook_remove}. A hook function must expect three | |
726 | @code{void *} parameters which are, respectively: | |
727 | ||
728 | @table @var | |
729 | @item hook_data | |
730 | The hook closure data that was specified at the time the hook was | |
731 | initialized by @code{scm_c_hook_init}. | |
732 | ||
733 | @item func_data | |
734 | The function closure data that was specified at the time that that | |
735 | function was registered with the hook by @code{scm_c_hook_add}. | |
736 | ||
737 | @item data | |
738 | The call closure data specified by the @code{scm_c_hook_run} call that | |
739 | runs the hook. | |
740 | @end table | |
741 | ||
742 | @deftp {C Type} scm_t_c_hook_function | |
743 | Function type for a C hook function: takes three @code{void *} | |
744 | parameters and returns a @code{void *} result. | |
745 | @end deftp | |
746 | ||
747 | @deftypefn {C Function} void scm_c_hook_add (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data, int appendp) | |
748 | Add function @var{func}, with function closure data @var{func_data}, to | |
749 | the C hook @var{hook}. The new function is appended to the hook's list | |
750 | of functions if @var{appendp} is non-zero, otherwise prepended. | |
751 | @end deftypefn | |
752 | ||
753 | @deftypefn {C Function} void scm_c_hook_remove (scm_t_c_hook *hook, scm_t_c_hook_function func, void *func_data) | |
754 | Remove function @var{func}, with function closure data @var{func_data}, | |
755 | from the C hook @var{hook}. @code{scm_c_hook_remove} checks both | |
756 | @var{func} and @var{func_data} so as to allow for the same @var{func} | |
757 | being registered multiple times with different closure data. | |
758 | @end deftypefn | |
759 | ||
760 | Finally, to invoke a C hook, call the @code{scm_c_hook_run} function | |
761 | specifying the hook and the call closure data for this run: | |
762 | ||
763 | @deftypefn {C Function} {void *} scm_c_hook_run (scm_t_c_hook *hook, void *data) | |
764 | Run the C hook @var{hook} will call closure data @var{data}. Subject to | |
765 | the variations for hook types @code{SCM_C_HOOK_OR} and | |
766 | @code{SCM_C_HOOK_AND}, @code{scm_c_hook_run} calls @var{hook}'s | |
767 | registered functions in turn, passing them the hook's closure data, each | |
768 | function's closure data, and the call closure data. | |
769 | ||
770 | @code{scm_c_hook_run}'s return value is the return value of the last | |
771 | function to be called. | |
772 | @end deftypefn | |
773 | ||
774 | ||
775 | @node GC Hooks | |
776 | @subsubsection Hooks for Garbage Collection | |
777 | ||
778 | Whenever Guile performs a garbage collection, it calls the following | |
779 | hooks in the order shown. | |
780 | ||
781 | @defvr {C Hook} scm_before_gc_c_hook | |
782 | C hook called at the very start of a garbage collection, after setting | |
783 | @code{scm_gc_running_p} to 1, but before entering the GC critical | |
784 | section. | |
785 | ||
786 | If garbage collection is blocked because @code{scm_block_gc} is | |
787 | non-zero, GC exits early soon after calling this hook, and no further | |
788 | hooks will be called. | |
789 | @end defvr | |
790 | ||
791 | @defvr {C Hook} scm_before_mark_c_hook | |
792 | C hook called before beginning the mark phase of garbage collection, | |
793 | after the GC thread has entered a critical section. | |
794 | @end defvr | |
795 | ||
796 | @defvr {C Hook} scm_before_sweep_c_hook | |
797 | C hook called before beginning the sweep phase of garbage collection. | |
798 | This is the same as at the end of the mark phase, since nothing else | |
799 | happens between marking and sweeping. | |
800 | @end defvr | |
801 | ||
802 | @defvr {C Hook} scm_after_sweep_c_hook | |
803 | C hook called after the end of the sweep phase of garbage collection, | |
804 | but while the GC thread is still inside its critical section. | |
805 | @end defvr | |
806 | ||
807 | @defvr {C Hook} scm_after_gc_c_hook | |
808 | C hook called at the very end of a garbage collection, after the GC | |
809 | thread has left its critical section. | |
810 | @end defvr | |
811 | ||
812 | @defvr {Scheme Hook} after-gc-hook | |
813 | @vindex scm_after_gc_hook | |
814 | Scheme hook with arity 0. This hook is run asynchronously | |
815 | (@pxref{Asyncs}) soon after the GC has completed and any other events | |
816 | that were deferred during garbage collection have been processed. (Also | |
817 | accessible from C with the name @code{scm_after_gc_hook}.) | |
818 | @end defvr | |
819 | ||
820 | All the C hooks listed here have type @code{SCM_C_HOOK_NORMAL}, are | |
72b3aa56 | 821 | initialized with hook closure data NULL, are invoked by |
07d83abe MV |
822 | @code{scm_c_hook_run} with call closure data NULL. |
823 | ||
824 | @cindex guardians, testing for GC'd objects | |
825 | The Scheme hook @code{after-gc-hook} is particularly useful in | |
826 | conjunction with guardians (@pxref{Guardians}). Typically, if you are | |
827 | using a guardian, you want to call the guardian after garbage collection | |
828 | to see if any of the objects added to the guardian have been collected. | |
829 | By adding a thunk that performs this call to @code{after-gc-hook}, you | |
830 | can ensure that your guardian is tested after every garbage collection | |
831 | cycle. | |
832 | ||
833 | ||
834 | @node REPL Hooks | |
835 | @subsubsection Hooks into the Guile REPL | |
836 | ||
837 | ||
838 | @c Local Variables: | |
839 | @c TeX-master: "guile.texi" | |
840 | @c End: |