keyed_vars.texi (2945B)
1 @c -*-texinfo-*- 2 @setfilename ../src/keyed variables 3 4 @node Keyed Variables, Numbers, Promises, Top 5 @comment node-name, next, previous, up 6 7 @chapter Keyed Variables 8 @cindex keyed variables 9 10 A keyed variable is a device that associates a non-symbolic key (in 11 the form of an accessor applicative) with a value depending on the 12 context in which lookup occurs. Kernel provides two types of keyed 13 variables: dynamic & static. Keyed Dynamic Variables use the dynamic 14 extent as context and Keyed Static Variables use the dynamic 15 environment. 16 17 @section Keyed Dynamic Variables 18 @cindex keyed dynamic variables 19 @c add cf xref static 20 @c TODO add xref to dynamic extent 21 A keyed dynamic variable is a device that associates a non-symbolic 22 key (in the form of an accessor applicative) with a value depending on 23 the dynamic extent in which lookup occurs. 24 25 @deffn Applicative make-keyed-dynamic-variable (make-keyed-dynamic-variable) 26 Returns a list of the form @code{(b a)}, where @code{b} and @code{a} 27 are applicatives, as follows. Each call to 28 @code{make-keyed-dynamic-variable} returns different @code{b} and 29 @code{a}. 30 31 @itemize @bullet 32 @item 33 @code{b} is an applicative that takes two arguments, the second of 34 which must be a combiner. It calls its second argument with no 35 operands (nil operand tree) in a fresh empty environment, and returns 36 the result. 37 38 @item 39 @code{a} is an applicative that takes zero arguments. If the call to 40 @code{a} occurs within the dynamic extent of a call to @code{b}, then 41 @code{a} returns the value of the first argument passed to @code{b} in 42 the smallest enclosing dynamic extent of a call to @code{b}. If the 43 call to @code{a} is not within the dynamic extent of any call to 44 @code{b}, an error is signaled. 45 @end itemize 46 @end deffn 47 48 @section Keyed Static Variables 49 @cindex keyed static variables 50 A keyed static variable is a device that binds data in an 51 environment by a non-symbolic key, where the key is an accessor 52 applicative. 53 @c add cf xref dynamic 54 55 @deffn Applicative make-keyed-static-variable (make-keyed-static-variable) 56 Returns a list of the form @code{(b a)}, where @code{b} and @code{a} 57 are applicatives, as follows. Each call to @code{make-keyed-static-variable} 58 returns different @code{b} and @code{a}. 59 60 @itemize @bullet 61 @item 62 @code{b} is an applicative that takes two arguments, the second of 63 which must be an environment. It constructs and returns a 64 child-environment of its second argument, with initially no local 65 bindings. 66 67 @item 68 @code{a} is an applicative that takes zero arguments. If the dynamic 69 environment @code{e} of the call to a has an improper ancestor that 70 was constructed by a call to @code{b}, then a returns the value of the 71 first argument passed to @code{b} in the first such environment 72 encountered by a depth-first traversal of the improper ancestors of 73 @code{e}. If @code{e} has no improper ancestors constructed via 74 @code{b}, an error is signaled. 75 @end itemize 76 @end deffn