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