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