docs updates

docs/reference/core.any

@@ -4,6 +4,61 @@
 
 \title{Core}
 
+\macro{self}{any}{
+  The current object.
+
+  \example{
+    1 instance-eval: self
+    "hello" instance-eval: self
+  }
+}
+
+\macro{true}{true}{
+  The value representing truth and virtue.
+
+  \example{
+    2 + 2 == 4
+  }
+}
+
+\macro{false}{false}{
+  The value representing falsity and vice.
+
+  \hl{false} and \hl{nil} are the only two values considered non-true.
+
+  \example{
+    2 + 2 == 5
+  }
+}
+
+\macro{nil}{nil}{
+  The value representing the absense of value.
+
+  \hl{false} and \hl{nil} are the only two values considered non-true.
+
+  \example{
+    [1, 2, 3][4]
+  }
+}
+
+\macro{undefined}{undefined}{
+  Perhaps a peculiar constant coming from Ruby, representing the true absense
+  of value. For example, this is used to specify that an argument should be
+  considered unspecified, and cause it to inherit its default value if there
+  is one.
+
+  \example{
+    foo(a = 1, b = 2) := [a, b]
+    foo(undefined, 3)
+  }
+
+  It is also used for unspecified values in a \hl{Particle}.
+
+  \example{
+    .foo(1, _) arguments
+  }
+}
+
 \macro{~receiver ~(message ? to-word)}{any}{
   A basic message send.
 
@@ -13,7 +68,7 @@
   }
 }
 
-\macro{~receiver ~(message ? to-word)(~*arguments)}{any}{
+\macro{~receiver (~(message ? to-word))(~*arguments)}{any}{
   A basic message send with arguments.
 
   \example{
@@ -63,15 +118,24 @@
   }
 }
 
-\macro{~(message ? to-word)(~*args): ~*body}{any}{
+\macro{(~(message ? to-word))(~*args): ~*body}{any}{
   A private message send with arguments and a proc-arg.
 
   \example{
-    foo(bar) &baz := baz call(bar)
+    foo(_) &baz := baz call
     foo(41): puts("called")
   }
 }
 
+\macro{(~(message ? to-word))(~*args) [~*block-args]: ~*body}{any}{
+  A private message send with arguments and a proc-arg with arguments.
+
+  \example{
+    foo(bar) &baz := baz call(bar)
+    foo(41) [x]: puts("called with " + x inspect)
+  }
+}
+
 \macro{~receiver ~(message ? to-word): ~*body)}{any}{
   A message send with a proc-arg to \hl{receiver}.
 
@@ -80,19 +144,31 @@
   }
 }
 
-\macro{~receiver ~(message ? to-word)(~*args): ~*body)}{any}{
-  A message send with arguments and a proc-arg to \hl{receiver}.
+\macro{~receiver ~(message ? to-word) [~*block-args]: ~*body)}{any}{
+  A message send to \hl{receiver} with a proc-arg with arguments.
+
+  \example{
+    [1, 2, 3] collect [x]: x + 1
+  }
+}
+
+\macro{~receiver (~(message ? to-word))(~*args): ~*body)}{any}{
+  A message send to \hl{receiver} with arguments and a proc-arg.
 
   \example{
     [0, 2] zip([1, 3]): puts("xyz")
   }
 }
 
+\macro{~receiver (~(message ? to-word))(~*args) [~*block-args]: ~*body)}{any}{
+  A message send to \hl{receiver} with arguments and a proc-arg with arguments.
+
+  \example{
+    [1, 2, 3] inject(0) [x, y]: x + y
+  }
+}
+
 {-
   TODO:
-  collect(a) [x] { x + 1 }
-  [1, 2, 3] collect [x] { x + 1 }
-  [1, 2, 3] collect(a) [x] { x + 1 }
-
-  and others (see kernel/core)
+  others (see kernel/core)
 -}