← Back to branch summary

~ubuntu-branches/ubuntu/trusty/guile-2.0/trusty

« back to all changes in this revision

Viewing changes to doc/ref/srfi-modules.texi

  • Committer: Package Import Robot
  • Author(s): Rob Browning
  • Date: 2012-02-04 11:33:28 UTC
  • mfrom: (1.1.1)
  • Revision ID: package-import@ubuntu.com-20120204113328-op7l4os5fo5f8mm3
Tags: 2.0.5+1-1
* Incorporate upstream version 2.0.5.

* Delete 0001-Fix-the-SRFI-60-copy-bit-documentation.patch,
  0002-Define-_GNU_SOURCE-to-fix-the-GNU-kFreeBSD-build.patch, and
  0003-Include-gc.h-rather-than-gc-gc_version.h-in-pthread-.patch.

Show diffs side-by-side

added added

removed removed

Lines of Context:
doc/ref/srfi-modules.texi
1
1
@c -*-texinfo-*-
2
2
@c This is part of the GNU Guile Reference Manual.
3
 
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011
 
3
@c Copyright (C)  1996, 1997, 2000, 2001, 2002, 2003, 2004, 2006, 2007, 2008, 2009, 2010, 2011, 2012
4
4
@c   Free Software Foundation, Inc.
5
5
@c See the file guile.texi for copying conditions.
6
6
 
16
16
over the available SRFIs and some usage hints.  For complete
17
17
documentation, design rationales and further examples, we advise you to
18
18
get the relevant SRFI documents from the SRFI home page
19
 
@url{http://srfi.schemers.org}.
 
19
@url{http://srfi.schemers.org/}.
20
20
 
21
21
@menu
22
22
* About SRFI Usage::            What to know about Guile's SRFI support.
3846
3846
@node SRFI-39
3847
3847
@subsection SRFI-39 - Parameters
3848
3848
@cindex SRFI-39
3849
 
@cindex parameter object
3850
 
@tindex Parameter
3851
 
 
3852
 
This SRFI provides parameter objects, which implement dynamically
3853
 
bound locations for values.  The functions below are available from
3854
 
 
3855
 
@example
3856
 
(use-modules (srfi srfi-39))
3857
 
@end example
3858
 
 
3859
 
A parameter object is a procedure.  Called with no arguments it
3860
 
returns its value, called with one argument it sets the value.
3861
 
 
3862
 
@example
3863
 
(define my-param (make-parameter 123))
3864
 
(my-param) @result{} 123
3865
 
(my-param 456)
3866
 
(my-param) @result{} 456
3867
 
@end example
3868
 
 
3869
 
The @code{parameterize} special form establishes new locations for
3870
 
parameters, those new locations having effect within the dynamic scope
3871
 
of the @code{parameterize} body.  Leaving restores the previous
3872
 
locations, or re-entering through a saved continuation will again use
3873
 
the new locations.
3874
 
 
3875
 
@example
3876
 
(parameterize ((my-param 789))
3877
 
  (my-param) @result{} 789
3878
 
  )
3879
 
(my-param) @result{} 456
3880
 
@end example
3881
 
 
3882
 
Parameters are like dynamically bound variables in other Lisp dialects.
3883
 
They allow an application to establish parameter settings (as the name
3884
 
suggests) just for the execution of a particular bit of code,
3885
 
restoring when done.  Examples of such parameters might be
3886
 
case-sensitivity for a search, or a prompt for user input.
3887
 
 
3888
 
Global variables are not as good as parameter objects for this sort of
3889
 
thing.  Changes to them are visible to all threads, but in Guile
3890
 
parameter object locations are per-thread, thereby truly limiting the
3891
 
effect of @code{parameterize} to just its dynamic execution.
3892
 
 
3893
 
Passing arguments to functions is thread-safe, but that soon becomes
3894
 
tedious when there's more than a few or when they need to pass down
3895
 
through several layers of calls before reaching the point they should
3896
 
affect.  And introducing a new setting to existing code is often
3897
 
easier with a parameter object than adding arguments.
3898
 
 
3899
 
 
3900
 
@sp 1
3901
 
@defun make-parameter init [converter]
3902
 
Return a new parameter object, with initial value @var{init}.
3903
 
 
3904
 
A parameter object is a procedure.  When called @code{(param)} it
3905
 
returns its value, or a call @code{(param val)} sets its value.  For
3906
 
example,
3907
 
 
3908
 
@example
3909
 
(define my-param (make-parameter 123))
3910
 
(my-param) @result{} 123
3911
 
 
3912
 
(my-param 456)
3913
 
(my-param) @result{} 456
3914
 
@end example
3915
 
 
3916
 
If a @var{converter} is given, then a call @code{(@var{converter}
3917
 
val)} is made for each value set, its return is the value stored.
3918
 
Such a call is made for the @var{init} initial value too.
3919
 
 
3920
 
A @var{converter} allows values to be validated, or put into a
3921
 
canonical form.  For example,
3922
 
 
3923
 
@example
3924
 
(define my-param (make-parameter 123
3925
 
                   (lambda (val)
3926
 
                     (if (not (number? val))
3927
 
                         (error "must be a number"))
3928
 
                     (inexact->exact val))))
3929
 
(my-param 0.75)
3930
 
(my-param) @result{} 3/4
3931
 
@end example
3932
 
@end defun
3933
 
 
3934
 
@deffn {library syntax} parameterize ((param value) @dots{}) body @dots{}
3935
 
Establish a new dynamic scope with the given @var{param}s bound to new
3936
 
locations and set to the given @var{value}s.  @var{body} is evaluated
3937
 
in that environment, the result is the return from the last form in
3938
 
@var{body}.
3939
 
 
3940
 
Each @var{param} is an expression which is evaluated to get the
3941
 
parameter object.  Often this will just be the name of a variable
3942
 
holding the object, but it can be anything that evaluates to a
3943
 
parameter.
3944
 
 
3945
 
The @var{param} expressions and @var{value} expressions are all
3946
 
evaluated before establishing the new dynamic bindings, and they're
3947
 
evaluated in an unspecified order.
3948
 
 
3949
 
For example,
3950
 
 
3951
 
@example
3952
 
(define prompt (make-parameter "Type something: "))
3953
 
(define (get-input)
3954
 
  (display (prompt))
3955
 
  ...)
3956
 
 
3957
 
(parameterize ((prompt "Type a number: "))
3958
 
  (get-input)
3959
 
  ...)
3960
 
@end example
3961
 
@end deffn
3962
 
 
3963
 
@deffn {Parameter object} current-input-port [new-port]
3964
 
@deffnx {Parameter object} current-output-port [new-port]
3965
 
@deffnx {Parameter object} current-error-port [new-port]
3966
 
This SRFI extends the core @code{current-input-port} and
3967
 
@code{current-output-port}, making them parameter objects.  The
3968
 
Guile-specific @code{current-error-port} is extended too, for
3969
 
consistency.  (@pxref{Default Ports}.)
3970
 
 
3971
 
This is an upwardly compatible extension, a plain call like
3972
 
@code{(current-input-port)} still returns the current input port, and
3973
 
@code{set-current-input-port} can still be used.  But the port can now
3974
 
also be set with @code{(current-input-port my-port)} and bound
3975
 
dynamically with @code{parameterize}.
3976
 
@end deffn
 
3849
 
 
3850
This SRFI adds support for dynamically-scoped parameters.  SRFI 39 is
 
3851
implemented in the Guile core; there's no module needed to get SRFI-39
 
3852
itself.  Parameters are documented in @ref{Parameters}.
 
3853
 
 
3854
This module does export one extra function: @code{with-parameters*}.
 
3855
This is a Guile-specific addition to the SRFI, similar to the core
 
3856
@code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3977
3857
 
3978
3858
@defun with-parameters* param-list value-list thunk
3979
3859
Establish a new dynamic scope, as per @code{parameterize} above,
3981
3861
@var{values-list}.  A call @code{(@var{thunk})} is made in the new
3982
3862
scope and the result from that @var{thunk} is the return from
3983
3863
@code{with-parameters*}.
3984
 
 
3985
 
This function is a Guile-specific addition to the SRFI, it's similar
3986
 
to the core @code{with-fluids*} (@pxref{Fluids and Dynamic States}).
3987
3864
@end defun
3988
3865
 
3989
 
 
3990
 
@sp 1
3991
 
Parameter objects are implemented using fluids (@pxref{Fluids and
3992
 
Dynamic States}), so each dynamic state has it's own parameter
3993
 
locations.  That includes the separate locations when outside any
3994
 
@code{parameterize} form.  When a parameter is created it gets a
3995
 
separate initial location in each dynamic state, all initialized to
3996
 
the given @var{init} value.
3997
 
 
3998
 
As alluded to above, because each thread usually has a separate
3999
 
dynamic state, each thread has it's own locations behind parameter
4000
 
objects, and changes in one thread are not visible to any other.  When
4001
 
a new dynamic state or thread is created, the values of parameters in
4002
 
the originating context are copied, into new locations.
4003
 
 
4004
 
SRFI-39 doesn't specify the interaction between parameter objects and
4005
 
threads, so the threading behaviour described here should be regarded
4006
 
as Guile-specific.
4007
 
 
4008
3866
@node SRFI-42
4009
3867
@subsection SRFI-42 - Eager Comprehensions
4010
3868
@cindex SRFI-42
4335
4193
return multiple values, as well as arbitrary definitions of test
4336
4194
success.  SRFI 61 is implemented in the Guile core; there's no module
4337
4195
needed to get SRFI-61 itself.  Extended @code{cond} is documented in
4338
 
@ref{if cond case,, Simple Conditional Evaluation}.
 
4196
@ref{Conditionals,, Simple Conditional Evaluation}.
4339
4197
 
4340
4198
@node SRFI-67
4341
4199
@subsection SRFI-67 - Compare procedures