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