diff options
Diffstat (limited to 'doc/ref')
-rw-r--r-- | doc/ref/api-control.texi | 7 | ||||
-rw-r--r-- | doc/ref/api-evaluation.texi | 4 | ||||
-rw-r--r-- | doc/ref/api-macros.texi | 98 | ||||
-rw-r--r-- | doc/ref/api-memory.texi | 52 | ||||
-rw-r--r-- | doc/ref/api-procedures.texi | 5 | ||||
-rw-r--r-- | doc/ref/api-scheduling.texi | 128 | ||||
-rw-r--r-- | doc/ref/srfi-modules.texi | 156 | ||||
-rw-r--r-- | doc/ref/vm.texi | 2 |
8 files changed, 248 insertions, 204 deletions
diff --git a/doc/ref/api-control.texi b/doc/ref/api-control.texi index c1502b032..559677874 100644 --- a/doc/ref/api-control.texi +++ b/doc/ref/api-control.texi @@ -785,6 +785,13 @@ the current implementation that object shares structure with @var{args}, so @var{args} should not be modified subsequently. @end deffn +@deffn {C Function} scm_c_value_ref (values, idx) +Returns the value at the position specified by @var{idx} in +@var{values}. Note that @var{values} will ordinarily be a +multiple-values object, but it need not be. Any other object +represents a single value (itself), and is handled appropriately. +@end deffn + @rnindex call-with-values @deffn {Scheme Procedure} call-with-values producer consumer Calls its @var{producer} argument with no values and a diff --git a/doc/ref/api-evaluation.texi b/doc/ref/api-evaluation.texi index 6a09bef60..2e48dcbe2 100644 --- a/doc/ref/api-evaluation.texi +++ b/doc/ref/api-evaluation.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2005, 2006, 2009, 2010, 2011, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -417,6 +417,8 @@ quote-keywordish-symbols reader How to print symbols that have a colon '#t' quotes them; 'reader' quotes them when the reader option 'keywords' is not '#f'. +escape-newlines yes Render newlines as \n when printing + using `write'. @end smalllisp These options may be modified with the print-set! syntax. diff --git a/doc/ref/api-macros.texi b/doc/ref/api-macros.texi index e60864ba3..4702d2f7a 100644 --- a/doc/ref/api-macros.texi +++ b/doc/ref/api-macros.texi @@ -38,9 +38,10 @@ languages}, or EDSLs.}. * Defining Macros:: Binding macros, globally and locally. * Syntax Rules:: Pattern-driven macros. * Syntax Case:: Procedural, hygienic macros. +* Syntax Transformer Helpers:: Helpers for use in procedural macros. * Defmacros:: Lisp-style macros. * Identifier Macros:: Identifier macros. -* Syntax Parameters:: Syntax Parameters +* Syntax Parameters:: Syntax Parameters. * Eval When:: Affecting the expand-time environment. * Internal Macros:: Macros as first-class values. @end menu @@ -671,28 +672,101 @@ source file, one may write: (newline)))))) @end example -Finally, we should mention the following helper procedures defined by the core -of @code{syntax-case}: +Readers interested in further information on @code{syntax-case} macros should +see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either +edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the +@code{syntax-case} system. The book itself is available online at +@uref{http://scheme.com/tspl4/}. + +@node Syntax Transformer Helpers +@subsection Syntax Transformer Helpers + +As noted in the previous section, Guile's syntax expander operates on +syntax objects. Procedural macros consume and produce syntax objects. +This section describes some of the auxiliary helpers that procedural +macros can use to compare, generate, and query objects of this data +type. @deffn {Scheme Procedure} bound-identifier=? a b -Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same -lexically-bound identifier. +Return @code{#t} iff the syntax objects @var{a} and @var{b} refer to the +same lexically-bound identifier. @end deffn @deffn {Scheme Procedure} free-identifier=? a b -Returns @code{#t} iff the syntax objects @var{a} and @var{b} refer to the same -free identifier. +Return @code{#t} iff the syntax objects @var{a} and @var{b} refer to the +same free identifier. @end deffn @deffn {Scheme Procedure} generate-temporaries ls Return a list of temporary identifiers as long as @var{ls} is long. @end deffn -Readers interested in further information on @code{syntax-case} macros should -see R. Kent Dybvig's excellent @cite{The Scheme Programming Language}, either -edition 3 or 4, in the chapter on syntax. Dybvig was the primary author of the -@code{syntax-case} system. The book itself is available online at -@uref{http://scheme.com/tspl4/}. +@deffn {Scheme Procedure} syntax-source x +Return the source properties that correspond to the syntax object +@var{x}. @xref{Source Properties}, for more information. +@end deffn + +@deffn {Scheme Procedure} syntax-local-binding id +Resolve the identifer @var{id}, a syntax object, within the current +lexical environment, and return two values, the binding type and a +binding value. The binding type is a symbol, which may be one of the +following: + +@table @code +@item lexical +A lexically-bound variable. The value is a unique token (in the sense +of @code{eq?}) identifying this binding. +@item macro +A syntax transformer, either local or global. The value is the +transformer procedure. +@item pattern-variable +A pattern variable, bound via syntax-case. The value is an opaque +object, internal to the expander. +@item displaced-lexical +A lexical variable that has gone out of scope. This can happen if a +badly-written procedural macro saves a syntax object, then attempts to +introduce it in a context in which it is unbound. The value is +@code{#f}. +@item global +A global binding. The value is a pair, whose head is the symbol, and +whose tail is the name of the module in which to resolve the symbol. +@item other +Some other binding, like @code{lambda} or other core bindings. The +value is @code{#f}. +@end table + +This is a very low-level procedure, with limited uses. One case in +which it is useful is to build abstractions that associate auxiliary +information with macros: + +@example +(define aux-property (make-object-property)) +(define-syntax-rule (with-aux aux value) + (let ((trans value)) + (set! (aux-property trans) aux) + trans))) +(define-syntax retrieve-aux + (lambda (x) + (syntax-case x () + ((x id) + (call-with-values (lambda () (syntax-local-binding #'id)) + (lambda (type val) + (with-syntax ((aux (datum->syntax #'here + (and (eq? type 'macro) + (aux-property val))))) + #''aux))))))) +(define-syntax foo + (with-aux 'bar + (syntax-rules () ((_) 'foo)))) +(foo) +@result{} foo +(retrieve-aux foo) +@result{} bar +@end example + +@code{syntax-local-binding} must be called within the dynamic extent of +a syntax transformer; to call it otherwise will signal an error. +@end deffn @node Defmacros @subsection Lisp-style Macro Definitions diff --git a/doc/ref/api-memory.texi b/doc/ref/api-memory.texi index 375686d98..6dca7a270 100644 --- a/doc/ref/api-memory.texi +++ b/doc/ref/api-memory.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2009, 2010, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -163,6 +163,9 @@ between different modules. The function @code{scm_calloc} is similar to @code{scm_malloc}, but initializes the block of memory to zero as well. + +These functions will (indirectly) call +@code{scm_gc_register_allocation}. @end deftypefn @deftypefn {C Function} {void *} scm_realloc (void *@var{mem}, size_t @var{new_size}) @@ -174,6 +177,8 @@ and allocates a new block of size @var{new_size}. When not enough memory is available, signal an error. This function runs the GC to free up some memory when it deems it appropriate. + +This function will call @code{scm_gc_register_allocation}. @end deftypefn @@ -209,39 +214,26 @@ the memory management overhead very low. However, in Guile 2.x, @end deftypefn -@deftypefn {C Function} void scm_gc_register_collectable_memory (void *@var{mem}, size_t @var{size}, const char *@var{what}) -Informs the GC that the memory at @var{mem} of size @var{size} can -potentially be freed during a GC. That is, announce that @var{mem} is -part of a GC controlled object and when the GC happens to free that -object, @var{size} bytes will be freed along with it. The GC will -@strong{not} free the memory itself, it will just know that so-and-so -much bytes of memory are associated with GC controlled objects and the -memory system figures this into its decisions when to run a GC. - -The @var{what} argument is used for statistical purposes. It should -describe the type of object that the memory will be used for so that -users can identify just what strange objects are eating up their -memory. - -In Guile 2.x, this function has no effect. -@end deftypefn +@deftypefn {C Function} void scm_gc_register_allocation (size_t @var{size}) +Informs the garbage collector that @var{size} bytes have been allocated, +which the collector would otherwise not have known about. -@deftypefn {C Function} void scm_gc_unregister_collectable_memory (void *@var{mem}, size_t @var{size}) -Informs the GC that the memory at @var{mem} of size @var{size} is no -longer associated with a GC controlled object. You must take care to -match up every call to @code{scm_gc_register_collectable_memory} with -a call to @code{scm_gc_unregister_collectable_memory}. If you don't do -this, the GC might have a wrong impression of what is going on and run -much less efficiently than it could. +In general, Scheme will decide to collect garbage only after some amount +of memory has been allocated. Calling this function will make the +Scheme garbage collector know about more allocation, and thus run more +often (as appropriate). -In Guile 2.x, this function has no effect. +It is especially important to call this function when large unmanaged +allocations, like images, may be freed by small Scheme allocations, like +SMOBs. @end deftypefn -@deftypefn {C Function} void scm_frame_free (void *mem) -Equivalent to @code{scm_frame_unwind_handler (free, @var{mem}, -SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will -be freed when the current frame is left. +@deftypefn {C Function} void scm_dynwind_free (void *mem) +Equivalent to @code{scm_dynwind_unwind_handler (free, @var{mem}, +SCM_F_WIND_EXPLICITLY)}. That is, the memory block at @var{mem} will be +freed (using @code{free} from the C library) when the current dynwind is +left. @end deftypefn @deffn {Scheme Procedure} malloc-stats @@ -272,7 +264,7 @@ The functions @code{scm_must_malloc} and @code{scm_must_realloc} behaved like @code{scm_gc_malloc} and @code{scm_gc_realloc} do now, respectively. They would inform the GC about the newly allocated memory via the internal equivalent of -@code{scm_gc_register_collectable_memory}. However, +@code{scm_gc_register_allocation}. However, @code{scm_must_free} did not unregister the memory it was about to free. The usual way to unregister memory was to return its size from a smob free function. diff --git a/doc/ref/api-procedures.texi b/doc/ref/api-procedures.texi index 2b4a05e08..1cecadf10 100644 --- a/doc/ref/api-procedures.texi +++ b/doc/ref/api-procedures.texi @@ -674,11 +674,6 @@ Return the source of the procedure @var{proc}. Returns @code{#f} if the source code is not available. @end deffn -@deffn {Scheme Procedure} procedure-environment proc -@deffnx {C Function} scm_procedure_environment (proc) -Return the environment of the procedure @var{proc}. Very deprecated. -@end deffn - @deffn {Scheme Procedure} procedure-properties proc @deffnx {C Function} scm_procedure_properties (proc) Return the properties associated with @var{proc}, as an association diff --git a/doc/ref/api-scheduling.texi b/doc/ref/api-scheduling.texi index f107cbfcb..6b0ed22bc 100644 --- a/doc/ref/api-scheduling.texi +++ b/doc/ref/api-scheduling.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2007, 2009, 2010, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -15,6 +15,7 @@ * Blocking:: How to block properly in guile mode. * Critical Sections:: Avoiding concurrency and reentries. * Fluids and Dynamic States:: Thread-local variables, etc. +* Parameters:: Dynamic scoping in Scheme. * Futures:: Fine-grain parallelism. * Parallel Forms:: Parallel execution of forms. @end menu @@ -680,9 +681,11 @@ used for testing whether an object is actually a fluid. The values stored in a fluid can be accessed with @code{fluid-ref} and @code{fluid-set!}. -@deffn {Scheme Procedure} make-fluid +@deffn {Scheme Procedure} make-fluid [dflt] @deffnx {C Function} scm_make_fluid () -Return a newly created fluid. +@deffnx {C Function} scm_make_fluid_with_default (dflt) +Return a newly created fluid, whose initial value is @var{dflt}, or +@code{#f} if @var{dflt} is not given. Fluids are objects that can hold one value per dynamic state. That is, modifications to this value are only visible to code that executes with the same dynamic state as @@ -694,7 +697,7 @@ with its own dynamic state, you can use fluids for thread local storage. @deffn {Scheme Procedure} make-unbound-fluid @deffnx {C Function} scm_make_unbound_fluid () Return a new fluid that is initially unbound (instead of being -implicitly bound to @code{#f}. +implicitly bound to some definite value). @end deffn @deffn {Scheme Procedure} fluid? obj @@ -707,8 +710,8 @@ Return @code{#t} iff @var{obj} is a fluid; otherwise, return @deffnx {C Function} scm_fluid_ref (fluid) Return the value associated with @var{fluid} in the current dynamic root. If @var{fluid} has not been set, then return -@code{#f}. Calling @code{fluid-ref} on an unbound fluid produces a -runtime error. +its default value. Calling @code{fluid-ref} on an unbound fluid produces +a runtime error. @end deffn @deffn {Scheme Procedure} fluid-set! fluid value @@ -820,6 +823,119 @@ Like @code{scm_with_dynamic_state}, but call @var{func} with @var{data}. @end deftypefn +@node Parameters +@subsection Parameters + +@cindex SRFI-39 +@cindex parameter object +@tindex Parameter + +A parameter object is a procedure. Calling it with no arguments returns +its value. Calling it with one argument sets the value. + +@example +(define my-param (make-parameter 123)) +(my-param) @result{} 123 +(my-param 456) +(my-param) @result{} 456 +@end example + +The @code{parameterize} special form establishes new locations for +parameters, those new locations having effect within the dynamic scope +of the @code{parameterize} body. Leaving restores the previous +locations. Re-entering (through a saved continuation) will again use +the new locations. + +@example +(parameterize ((my-param 789)) + (my-param)) @result{} 789 +(my-param) @result{} 456 +@end example + +Parameters are like dynamically bound variables in other Lisp dialects. +They allow an application to establish parameter settings (as the name +suggests) just for the execution of a particular bit of code, restoring +when done. Examples of such parameters might be case-sensitivity for a +search, or a prompt for user input. + +Global variables are not as good as parameter objects for this sort of +thing. Changes to them are visible to all threads, but in Guile +parameter object locations are per-thread, thereby truly limiting the +effect of @code{parameterize} to just its dynamic execution. + +Passing arguments to functions is thread-safe, but that soon becomes +tedious when there's more than a few or when they need to pass down +through several layers of calls before reaching the point they should +affect. And introducing a new setting to existing code is often easier +with a parameter object than adding arguments. + +@defun make-parameter init [converter] +Return a new parameter object, with initial value @var{init}. + +If a @var{converter} is given, then a call @code{(@var{converter} +val)} is made for each value set, its return is the value stored. +Such a call is made for the @var{init} initial value too. + +A @var{converter} allows values to be validated, or put into a +canonical form. For example, + +@example +(define my-param (make-parameter 123 + (lambda (val) + (if (not (number? val)) + (error "must be a number")) + (inexact->exact val)))) +(my-param 0.75) +(my-param) @result{} 3/4 +@end example +@end defun + +@deffn {Scheme Syntax} parameterize ((param value) @dots{}) body @dots{} +Establish a new dynamic scope with the given @var{param}s bound to new +locations and set to the given @var{value}s. @var{body} is evaluated +in that environment, the result is the return from the last form in +@var{body}. + +Each @var{param} is an expression which is evaluated to get the +parameter object. Often this will just be the name of a variable +holding the object, but it can be anything that evaluates to a +parameter. + +The @var{param} expressions and @var{value} expressions are all +evaluated before establishing the new dynamic bindings, and they're +evaluated in an unspecified order. + +For example, + +@example +(define prompt (make-parameter "Type something: ")) +(define (get-input) + (display (prompt)) + ...) + +(parameterize ((prompt "Type a number: ")) + (get-input) + ...) +@end example +@end deffn + +Parameter objects are implemented using fluids (@pxref{Fluids and +Dynamic States}), so each dynamic state has its own parameter +locations. That includes the separate locations when outside any +@code{parameterize} form. When a parameter is created it gets a +separate initial location in each dynamic state, all initialized to the +given @var{init} value. + +As alluded to above, because each thread usually has a separate dynamic +state, each thread has its own locations behind parameter objects, and +changes in one thread are not visible to any other. When a new dynamic +state or thread is created, the values of parameters in the originating +context are copied, into new locations. + +@cindex SRFI-39 +Guile's parameters conform to SRFI-39 (@pxref{SRFI-39}). + + @node Futures @subsection Futures @cindex futures diff --git a/doc/ref/srfi-modules.texi b/doc/ref/srfi-modules.texi index 1e0ba2be3..444fc81ec 100644 --- a/doc/ref/srfi-modules.texi +++ b/doc/ref/srfi-modules.texi @@ -1,6 +1,6 @@ @c -*-texinfo-*- @c This is part of the GNU Guile Reference Manual. -@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011 +@c Copyright (C) 1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012 @c Free Software Foundation, Inc. @c See the file guile.texi for copying conditions. @@ -3846,134 +3846,14 @@ from a closed port. @node SRFI-39 @subsection SRFI-39 - Parameters @cindex SRFI-39 -@cindex parameter object -@tindex Parameter -This SRFI provides parameter objects, which implement dynamically -bound locations for values. The functions below are available from +This SRFI adds support for dynamically-scoped parameters. SRFI 39 is +implemented in the Guile core; there's no module needed to get SRFI-39 +itself. Parameters are documented in @ref{Parameters}. -@example -(use-modules (srfi srfi-39)) -@end example - -A parameter object is a procedure. Called with no arguments it -returns its value, called with one argument it sets the value. - -@example -(define my-param (make-parameter 123)) -(my-param) @result{} 123 -(my-param 456) -(my-param) @result{} 456 -@end example - -The @code{parameterize} special form establishes new locations for -parameters, those new locations having effect within the dynamic scope -of the @code{parameterize} body. Leaving restores the previous -locations, or re-entering through a saved continuation will again use -the new locations. - -@example -(parameterize ((my-param 789)) - (my-param) @result{} 789 - ) -(my-param) @result{} 456 -@end example - -Parameters are like dynamically bound variables in other Lisp dialects. -They allow an application to establish parameter settings (as the name -suggests) just for the execution of a particular bit of code, -restoring when done. Examples of such parameters might be -case-sensitivity for a search, or a prompt for user input. - -Global variables are not as good as parameter objects for this sort of -thing. Changes to them are visible to all threads, but in Guile -parameter object locations are per-thread, thereby truly limiting the -effect of @code{parameterize} to just its dynamic execution. - -Passing arguments to functions is thread-safe, but that soon becomes -tedious when there's more than a few or when they need to pass down -through several layers of calls before reaching the point they should -affect. And introducing a new setting to existing code is often -easier with a parameter object than adding arguments. - - -@sp 1 -@defun make-parameter init [converter] -Return a new parameter object, with initial value @var{init}. - -A parameter object is a procedure. When called @code{(param)} it -returns its value, or a call @code{(param val)} sets its value. For -example, - -@example -(define my-param (make-parameter 123)) -(my-param) @result{} 123 - -(my-param 456) -(my-param) @result{} 456 -@end example - -If a @var{converter} is given, then a call @code{(@var{converter} -val)} is made for each value set, its return is the value stored. -Such a call is made for the @var{init} initial value too. - -A @var{converter} allows values to be validated, or put into a -canonical form. For example, - -@example -(define my-param (make-parameter 123 - (lambda (val) - (if (not (number? val)) - (error "must be a number")) - (inexact->exact val)))) -(my-param 0.75) -(my-param) @result{} 3/4 -@end example -@end defun - -@deffn {library syntax} parameterize ((param value) @dots{}) body @dots{} -Establish a new dynamic scope with the given @var{param}s bound to new -locations and set to the given @var{value}s. @var{body} is evaluated -in that environment, the result is the return from the last form in -@var{body}. - -Each @var{param} is an expression which is evaluated to get the -parameter object. Often this will just be the name of a variable -holding the object, but it can be anything that evaluates to a -parameter. - -The @var{param} expressions and @var{value} expressions are all -evaluated before establishing the new dynamic bindings, and they're -evaluated in an unspecified order. - -For example, - -@example -(define prompt (make-parameter "Type something: ")) -(define (get-input) - (display (prompt)) - ...) - -(parameterize ((prompt "Type a number: ")) - (get-input) - ...) -@end example -@end deffn - -@deffn {Parameter object} current-input-port [new-port] -@deffnx {Parameter object} current-output-port [new-port] -@deffnx {Parameter object} current-error-port [new-port] -This SRFI extends the core @code{current-input-port} and -@code{current-output-port}, making them parameter objects. The -Guile-specific @code{current-error-port} is extended too, for -consistency. (@pxref{Default Ports}.) - -This is an upwardly compatible extension, a plain call like -@code{(current-input-port)} still returns the current input port, and -@code{set-current-input-port} can still be used. But the port can now -also be set with @code{(current-input-port my-port)} and bound -dynamically with @code{parameterize}. -@end deffn +This module does export one extra function: @code{with-parameters*}. +This is a Guile-specific addition to the SRFI, similar to the core +@code{with-fluids*} (@pxref{Fluids and Dynamic States}). @defun with-parameters* param-list value-list thunk Establish a new dynamic scope, as per @code{parameterize} above, @@ -3981,30 +3861,8 @@ taking parameters from @var{param-list} and corresponding values from @var{values-list}. A call @code{(@var{thunk})} is made in the new scope and the result from that @var{thunk} is the return from @code{with-parameters*}. - -This function is a Guile-specific addition to the SRFI, it's similar -to the core @code{with-fluids*} (@pxref{Fluids and Dynamic States}). @end defun - -@sp 1 -Parameter objects are implemented using fluids (@pxref{Fluids and -Dynamic States}), so each dynamic state has it's own parameter -locations. That includes the separate locations when outside any -@code{parameterize} form. When a parameter is created it gets a -separate initial location in each dynamic state, all initialized to -the given @var{init} value. - -As alluded to above, because each thread usually has a separate -dynamic state, each thread has it's own locations behind parameter -objects, and changes in one thread are not visible to any other. When -a new dynamic state or thread is created, the values of parameters in -the originating context are copied, into new locations. - -SRFI-39 doesn't specify the interaction between parameter objects and -threads, so the threading behaviour described here should be regarded -as Guile-specific. - @node SRFI-42 @subsection SRFI-42 - Eager Comprehensions @cindex SRFI-42 diff --git a/doc/ref/vm.texi b/doc/ref/vm.texi index cf4e135ec..398129e2b 100644 --- a/doc/ref/vm.texi +++ b/doc/ref/vm.texi @@ -438,7 +438,7 @@ expressions. @end deffn @deffn Instruction local-boxed-ref index -@deffnx Instruction local-boxed-ref index +@deffnx Instruction local-boxed-set index Get or set the value of the variable located at @var{index} within the current stack frame. A shortcut for @code{local-ref} then @code{variable-ref} or @code{variable-set}, respectively. |