Commits

Alex Suraci  committed 1b49853

parameterize docs -> dynamic environment docs

  • Participants
  • Parent commits c131f21

Comments (0)

Files changed (3)

File doc/main/dynamic.atomo

+#title:{Dynamic Environment}tag:"dynamic"
+
+Atomo has a dynamic system similar to Scheme's #code:{parameterize} and Common Lisp's #code:{defvar}.
+
+The usual convention of using #code:{*earmuffs*} for dynamic variable names is fine, but it's not really necessary as it's harder for them to collide with normal variables (accessing is either explicit or lexical, and updating is explicit).
+
+#define:{
+  top define: name as: root
+  > root
+}body:{
+  Creates a new dynamic variable called #atomo:name, defining an accessor in #atomo:top. The accessor simply performs #atomo:(name _?).
+
+  If the dynamic variable already exists, it is replaced.
+
+  #example:({
+    define: *foo* as: 10
+    *foo* _?
+    *foo*
+  })
+}
+
+#define:{
+  name _?
+  > any
+}body:{
+  Retrieves the binding for #atomo:name from the dynamic environment.
+
+  #example:({
+    define: *foo* as: 10
+    *foo* _?
+  })
+
+  Normally you won't need to do this, since #atomo:(define:as:) defines an accessor for you, so you can just say the name.
+}
+
+#define:{
+  name =! value
+  > value
+}body:{
+  Updates the most recent binding for #atomo:name as #atomo:value. This cannot replace the root value.
+
+  #example:({
+    define: *foo* as: 0
+    with: *foo* as: 1 do: { *foo* =! 2; *foo* }
+    *foo* =! 2
+  })
+}
+
+#define:{
+  with: name as: binding do: action
+  | action is-a?: Block
+  > any
+}body:{
+  Calls #atomo:action with #atomo:name bound as #atomo:binding.
+
+  #example:({
+    define: *foo* as: 0
+    with: *foo* as: 1 do: { *foo* }
+    *foo*
+  })
+}
+
+#define:{
+  with: bindings do: action
+  | bindings is-a?: List
+  | action is-a?: Block
+  > any
+}body:{
+  Calls #atomo:action with the given #atomo:Associations of variables to their new bindings. Expands into multiple #atomo:(with:as:do:) calls.
+  Calls #atomo:action with #atomo:name bound as #atomo:binding.
+
+  #example:({
+    define: *foo* as: 0
+    define: *bar* as: $a
+    with: [*foo* -> 1, *bar* -> $b] do: { [*foo*, *bar*] }
+    [*foo*, *bar*]
+  })
+}
+
+#define:{
+  modify: name as: modifier do: action
+  | action is-a?: Block
+  | modifier responds-to?: @call:
+  > any
+}body:{
+  Similar to #atomo:(with:as:do:), but passes the current value to #atomo:modifier to yield the new binding.
+
+  #example:({
+    define: *foo* as: 0
+    modify: *foo* as: @(+ 1) do: { *foo* }
+    *foo*
+  })
+}

File doc/main/parameters.atomo

-#title:{Parameterization}tag:"parameters"
-
-#define:{
-    Parameter
-    > Object
-}body:{
-    Atomo's #atomo:Parameter system provides thread-safe overriding and defining of global values. They are usually used when it may be ideal for users to override a certain value now and then, but would not be very nice as arguments passed throughout your entire system, or as toplevel values that can be modified willy-nilly.
-}
-
-#define:{
-    Parameter new: v
-    > Parameter
-}body:{
-    Defines a new parameter containing the initial value of #atomo:v.
-
-    #example:({
-        x = Parameter new: 20
-    })
-}
-
-#define:{
-    p _?
-    | p is-a?: Parameter
-    > any
-}body:{
-    Retrieves the current value of the parameter.
-
-    #example:({
-        x = Parameter new: 0
-        x _?
-    })
-}
-
-#define:{
-    p =! v
-    | p is-a?: Parameter
-    > v
-}body:{
-    Sets #atomo:(p)'s value in the current process to #atomo:v, returning the same value back.
-
-    #example:({
-        x = Parameter new: 0
-        x =! 1
-        x _?
-    })
-
-    Note that this will not change the value for new processes:
-
-    #example:({
-        x = Parameter new: 0
-        x =! 1
-        { x _? print } spawn
-        Timer sleep: 1 ms
-        x _?
-    })
-}
-
-#define:{
-    p set-default: v
-    | p is-a?: Parameter
-    > v
-}body:{
-    Sets the default value for #atomo:p to #atomo:v, returning the same value back.
-
-    This will not affect processes (including the current one) that have set their own values, via #atomo:(=!).
-}
-
-#define:{
-    with: p as: new-value do: action
-    | p is-a?: Parameter
-    | action is-a?: Block
-    > any
-}body:{
-    Temporarily sets the value for #atomo:p in the current process to #atomo:new-value.
-    
-    The parameter is guaranteed by #atomo:(before:after:) to be set to the new value when entering the #atomo:action continuation, and restored to the old value when leaving (or in the even of an error).
-
-    Returns the result of #atomo:action.
-
-    #example:({
-        x = Parameter new: 0
-        with: x as: 1 do: { x _? }
-        x _?
-    })
-}
-
-#define:{
-    with-default: p as: new-value do: action
-    | p is-a?: Parameter
-    | action is-a?: Block
-    > any
-}body:{
-    Similar to #atomo:(with:as:do:), but using #atomo:(set-default:).
-}
-
-#define:{
-    with: bindings do: action
-    | bindings is-a?: List
-    | action is-a?: Block
-    > any
-}body:{
-    Similar #atomo:(with:as:do:), but with a list of #atomo:(Association)s from #atomo:(Parameter)s to their values.
-
-    #example:({
-        x = Parameter new: 3
-        y = Parameter new: 4
-        with: [x -> 6, y -> 7] do: { x _? * y _? }
-        x _? * y _?
-    })
-}
-
-#define:{
-    with-defaults: bindings do: action
-    | bindings is-a?: List
-    | action is-a?: Block
-    > any
-}body:{
-    Similar #atomo:(with:do:), but using #atomo:(set-default:).
-}

File doc/main/start.atomo

 #include-section:"syntax.atomo"
 #include-section:"ecosystem.atomo"
 #include-section:"core.atomo"
+#include-section:"dynamic.atomo"
 #include-section:"lists.atomo"
 #include-section:"strings.atomo"
 #include-section:"blocks.atomo"
 #include-section:"comparable.atomo"
 #include-section:"io.atomo"
 #include-section:"timer.atomo"
-#include-section:"parameters.atomo"
 #include-section:"association.atomo"