api-binding.texi 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219220221222223224225226227228229230231232233234235236237238239240241242243244245246247248249250251252253254255256257258259260261262263264265266267268269270271272273274275276277278279280281282283284285286287288289290291292293294295296297298299300301302303304305306307308309310311312313314315316317318319320321322323324325326327
  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, 2009, 2010, 2011
  4. @c Free Software Foundation, Inc.
  5. @c See the file guile.texi for copying conditions.
  6. @node Binding Constructs
  7. @section Definitions and Variable Bindings
  8. Scheme supports the definition of variables in different contexts.
  9. Variables can be defined at the top level, so that they are visible in
  10. the entire program, and variables can be defined locally to procedures
  11. and expressions. This is important for modularity and data abstraction.
  12. @menu
  13. * Top Level:: Top level variable definitions.
  14. * Local Bindings:: Local variable bindings.
  15. * Internal Definitions:: Internal definitions.
  16. * Binding Reflection:: Querying variable bindings.
  17. @end menu
  18. @node Top Level
  19. @subsection Top Level Variable Definitions
  20. @cindex variable definition
  21. At the top level of a program (i.e., not nested within any other
  22. expression), a definition of the form
  23. @lisp
  24. (define a @var{value})
  25. @end lisp
  26. @noindent
  27. defines a variable called @code{a} and sets it to the value @var{value}.
  28. If the variable already exists in the current module, because it has
  29. already been created by a previous @code{define} expression with the
  30. same name, its value is simply changed to the new @var{value}. In this
  31. case, then, the above form is completely equivalent to
  32. @lisp
  33. (set! a @var{value})
  34. @end lisp
  35. @noindent
  36. This equivalence means that @code{define} can be used interchangeably
  37. with @code{set!} to change the value of variables at the top level of
  38. the REPL or a Scheme source file. It is useful during interactive
  39. development when reloading a Scheme file that you have modified, because
  40. it allows the @code{define} expressions in that file to work as expected
  41. both the first time that the file is loaded and on subsequent occasions.
  42. Note, though, that @code{define} and @code{set!} are not always
  43. equivalent. For example, a @code{set!} is not allowed if the named
  44. variable does not already exist, and the two expressions can behave
  45. differently in the case where there are imported variables visible from
  46. another module.
  47. @deffn {Scheme Syntax} define name value
  48. Create a top level variable named @var{name} with value @var{value}.
  49. If the named variable already exists, just change its value. The return
  50. value of a @code{define} expression is unspecified.
  51. @end deffn
  52. The C API equivalents of @code{define} are @code{scm_define} and
  53. @code{scm_c_define}, which differ from each other in whether the
  54. variable name is specified as a @code{SCM} symbol or as a
  55. null-terminated C string.
  56. @deffn {C Function} scm_define (sym, value)
  57. @deffnx {C Function} scm_c_define (const char *name, value)
  58. C equivalents of @code{define}, with variable name specified either by
  59. @var{sym}, a symbol, or by @var{name}, a null-terminated C string. Both
  60. variants return the new or preexisting variable object.
  61. @end deffn
  62. @code{define} (when it occurs at top level), @code{scm_define} and
  63. @code{scm_c_define} all create or set the value of a variable in the top
  64. level environment of the current module. If there was not already a
  65. variable with the specified name belonging to the current module, but a
  66. similarly named variable from another module was visible through having
  67. been imported, the newly created variable in the current module will
  68. shadow the imported variable, such that the imported variable is no
  69. longer visible.
  70. Attention: Scheme definitions inside local binding constructs
  71. (@pxref{Local Bindings}) act differently (@pxref{Internal Definitions}).
  72. Many people end up in a development style of adding and changing
  73. definitions at runtime, building out their program without restarting
  74. it. (You can do this using @code{reload-module}, the @code{reload} REPL
  75. command, the @code{load} procedure, or even just pasting code into a
  76. REPL.) If you are one of these people, you will find that sometimes you
  77. there are some variables that you @emph{don't} want to redefine all the
  78. time. For these, use @code{define-once}.
  79. @fnindex defvar
  80. @deffn {Scheme Syntax} define-once name value
  81. Create a top level variable named @var{name} with value @var{value}, but
  82. only if @var{name} is not already bound in the current module.
  83. @end deffn
  84. Old Lispers probably know @code{define-once} under its Lisp name,
  85. @code{defvar}.
  86. @node Local Bindings
  87. @subsection Local Variable Bindings
  88. @cindex local bindings
  89. @cindex local variables
  90. As opposed to definitions at the top level, which creates bindings that
  91. are visible to all code in a module, it is also possible to define
  92. variables which are only visible in a well-defined part of the program.
  93. Normally, this part of a program will be a procedure or a subexpression
  94. of a procedure.
  95. With the constructs for local binding (@code{let}, @code{let*},
  96. @code{letrec}, and @code{letrec*}), the Scheme language has a block
  97. structure like most other programming languages since the days of
  98. @sc{Algol 60}. Readers familiar to languages like C or Java should
  99. already be used to this concept, but the family of @code{let}
  100. expressions has a few properties which are well worth knowing.
  101. The most basic local binding construct is @code{let}.
  102. @deffn syntax let bindings body
  103. @var{bindings} has the form
  104. @lisp
  105. ((@var{variable1} @var{init1}) @dots{})
  106. @end lisp
  107. that is zero or more two-element lists of a variable and an arbitrary
  108. expression each. All @var{variable} names must be distinct.
  109. A @code{let} expression is evaluated as follows.
  110. @itemize @bullet
  111. @item
  112. All @var{init} expressions are evaluated.
  113. @item
  114. New storage is allocated for the @var{variables}.
  115. @item
  116. The values of the @var{init} expressions are stored into the variables.
  117. @item
  118. The expressions in @var{body} are evaluated in order, and the value of
  119. the last expression is returned as the value of the @code{let}
  120. expression.
  121. @end itemize
  122. The @var{init} expressions are not allowed to refer to any of the
  123. @var{variables}.
  124. @end deffn
  125. The other binding constructs are variations on the same theme: making new
  126. values, binding them to variables, and executing a body in that new,
  127. extended lexical context.
  128. @deffn syntax let* bindings body
  129. Similar to @code{let}, but the variable bindings are performed
  130. sequentially, that means that all @var{init} expression are allowed to
  131. use the variables defined on their left in the binding list.
  132. A @code{let*} expression can always be expressed with nested @code{let}
  133. expressions.
  134. @lisp
  135. (let* ((a 1) (b a))
  136. b)
  137. @equiv{}
  138. (let ((a 1))
  139. (let ((b a))
  140. b))
  141. @end lisp
  142. @end deffn
  143. @deffn syntax letrec bindings body
  144. Similar to @code{let}, but it is possible to refer to the @var{variable}
  145. from lambda expression created in any of the @var{inits}. That is,
  146. procedures created in the @var{init} expression can recursively refer to
  147. the defined variables.
  148. @lisp
  149. (letrec ((even? (lambda (n)
  150. (if (zero? n)
  151. #t
  152. (odd? (- n 1)))))
  153. (odd? (lambda (n)
  154. (if (zero? n)
  155. #f
  156. (even? (- n 1))))))
  157. (even? 88))
  158. @result{}
  159. #t
  160. @end lisp
  161. Note that while the @var{init} expressions may refer to the new
  162. variables, they may not access their values. For example, making the
  163. @code{even?} function above creates a closure (@pxref{About Closure})
  164. referencing the @code{odd?} variable. But @code{odd?} can't be called
  165. until after execution has entered the body.
  166. @end deffn
  167. @deffn syntax letrec* bindings body
  168. Similar to @code{letrec}, except the @var{init} expressions are bound to
  169. their variables in order.
  170. @code{letrec*} thus relaxes the letrec restriction, in that later
  171. @var{init} expressions may refer to the values of previously bound
  172. variables.
  173. @lisp
  174. (letrec ((a 42)
  175. (b (+ a 10)))
  176. (* a b))
  177. @result{} ;; Error: unbound variable: a
  178. (letrec* ((a 42)
  179. (b (+ a 10)))
  180. (* a b))
  181. @result{} 2184
  182. @end lisp
  183. @end deffn
  184. There is also an alternative form of the @code{let} form, which is used
  185. for expressing iteration. Because of the use as a looping construct,
  186. this form (the @dfn{named let}) is documented in the section about
  187. iteration (@pxref{while do, Iteration})
  188. @node Internal Definitions
  189. @subsection Internal definitions
  190. @c FIXME::martin: Review me!
  191. A @code{define} form which appears inside the body of a @code{lambda},
  192. @code{let}, @code{let*}, @code{letrec}, @code{letrec*} or equivalent
  193. expression is called an @dfn{internal definition}. An internal
  194. definition differs from a top level definition (@pxref{Top Level}),
  195. because the definition is only visible inside the complete body of the
  196. enclosing form. Let us examine the following example.
  197. @lisp
  198. (let ((frumble "froz"))
  199. (define banana (lambda () (apple 'peach)))
  200. (define apple (lambda (x) x))
  201. (banana))
  202. @result{}
  203. peach
  204. @end lisp
  205. Here the enclosing form is a @code{let}, so the @code{define}s in the
  206. @code{let}-body are internal definitions. Because the scope of the
  207. internal definitions is the @strong{complete} body of the
  208. @code{let}-expression, the @code{lambda}-expression which gets bound to
  209. the variable @code{banana} may refer to the variable @code{apple}, even
  210. though its definition appears lexically @emph{after} the definition of
  211. @code{banana}. This is because a sequence of internal definition acts
  212. as if it were a @code{letrec*} expression.
  213. @lisp
  214. (let ()
  215. (define a 1)
  216. (define b 2)
  217. (+ a b))
  218. @end lisp
  219. @noindent
  220. is equivalent to
  221. @lisp
  222. (let ()
  223. (letrec* ((a 1) (b 2))
  224. (+ a b)))
  225. @end lisp
  226. Internal definitions are only allowed at the beginning of the body of an
  227. enclosing expression. They may not be mixed with other expressions.
  228. Another noteworthy difference to top level definitions is that within
  229. one group of internal definitions all variable names must be distinct.
  230. That means where on the top level a second define for a given variable
  231. acts like a @code{set!}, an exception is thrown for internal definitions
  232. with duplicate bindings.
  233. As a historical note, it used to be that internal bindings were expanded
  234. in terms of @code{letrec}, not @code{letrec*}. This was the situation
  235. for the R5RS report and before. However with the R6RS, it was recognized
  236. that sequential definition was a more intuitive expansion, as in the
  237. following case:
  238. @lisp
  239. (let ()
  240. (define a 1)
  241. (define b (+ a a))
  242. (+ a b))
  243. @end lisp
  244. @noindent
  245. Guile decided to follow the R6RS in this regard, and now expands
  246. internal definitions using @code{letrec*}.
  247. @node Binding Reflection
  248. @subsection Querying variable bindings
  249. Guile provides a procedure for checking whether a symbol is bound in the
  250. top level environment.
  251. @deffn {Scheme Procedure} defined? sym [module]
  252. @deffnx {C Function} scm_defined_p (sym, module)
  253. Return @code{#t} if @var{sym} is defined in the module @var{module} or
  254. the current module when @var{module} is not specified; otherwise return
  255. @code{#f}.
  256. @end deffn
  257. @c Local Variables:
  258. @c TeX-master: "guile.texi"
  259. @c End: