more documentation, fixed broken test

helpers/linebook/os/posix/-head.rb

@@ -123,7 +123,7 @@ def function?(name)
 # Returns an array of positional variables for use as inputs to a function
 # block.  Splat blocks are supported; the splat expression behaves like $*.
 def signature(arity)
-  variables = Array.new(arity.abs) {|i| Variable.new(i + 1) }
+  variables = Array.new(arity.abs) {|i| var(i+1) }
 
   if arity < 0
     # This works for defaults...
@@ -136,6 +136,10 @@ def signature(arity)
   variables
 end
 
+def var(name)
+  Variable.new(name)
+end
+
 def trailer
   /(\s*(?:\ncheck_status.*?\n\s*)?)\z/
 end

helpers/linebook/os/posix/break_.erb

@@ -1,4 +1,5 @@
 Exit from for, while, or until loop.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_15]
 
 ()
 --

helpers/linebook/os/posix/continue_.erb

@@ -1,4 +1,5 @@
 Continue for, while, or until loop.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_17]
 
 ()
 --

helpers/linebook/os/posix/exit_.erb

@@ -1,4 +1,5 @@
 Cause the shell to exit.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_21]
 
 (status=nil)
 --

helpers/linebook/os/posix/return_.erb

@@ -1,4 +1,5 @@
 Return from a function.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_24]
 
 (status=nil)
 --

helpers/linebook/os/posix/utilities/export.erb

@@ -1,4 +1,5 @@
 Set the export attribute for variables.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_22]
 
 (key, value=nil)
 --

helpers/linebook/os/posix/utilities/set.rb

@@ -3,6 +3,7 @@
   set 'x' => true, 'v' => false
 
 If a block is given then options will only be reset when the block completes.
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_25]
 
 (options)
 --

helpers/linebook/os/posix/utilities/unset.rb

@@ -1,5 +1,5 @@
 Unset values and attributes of variables and functions.
-{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/unset.html]
+{[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_29]
 
 (*names)
 --

lib/linebook/os/posix.rb

@@ -142,7 +142,7 @@ def function?(name)
       # Returns an array of positional variables for use as inputs to a function
       # block.  Splat blocks are supported; the splat expression behaves like $*.
       def signature(arity)
-        variables = Array.new(arity.abs) {|i| Variable.new(i + 1) }
+        variables = Array.new(arity.abs) {|i| var(i+1) }
 
         if arity < 0
           # This works for defaults...
@@ -155,6 +155,10 @@ def signature(arity)
         variables
       end
 
+      def var(name)
+        Variable.new(name)
+      end
+
       def trailer
         /(\s*(?:\ncheck_status.*?\n\s*)?)\z/
       end
@@ -172,6 +176,7 @@ def _append(*args, &block) # :nodoc:
       end
 
       # Exit from for, while, or until loop.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_15]
       def break_()
         #  break
         #  
@@ -245,6 +250,7 @@ def _comment(*args, &block) # :nodoc:
       end
 
       # Continue for, while, or until loop.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_17]
       def continue_()
         #  continue
         #  
@@ -329,6 +335,7 @@ def _execute(*args, &block) # :nodoc:
       end
 
       # Cause the shell to exit.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_21]
       def exit_(status=nil)
         #  <% if status.nil? %>
         #  exit
@@ -441,6 +448,7 @@ def _redirect(*args, &block) # :nodoc:
       end
 
       # Return from a function.
+      # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_24]
       def return_(status=nil)
         #  <% if status.nil? %>
         #  return

lib/linebook/os/posix/utilities.rb

@@ -255,6 +255,7 @@ def _expand(*args, &block) # :nodoc:
         end
 
         # Set the export attribute for variables.
+        # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_22]
         def export(key, value=nil)
           #  <% if value.nil? %>
           #  export <%= key %>
@@ -537,6 +538,7 @@ def _sed(*args, &block) # :nodoc:
         #   set 'x' => true, 'v' => false
         # 
         # If a block is given then options will only be reset when the block completes.
+        # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_25]
         def set(options)
           if block_given?
             var = _package_.next_variable_name('set')
@@ -679,7 +681,7 @@ def _uniq(*args, &block) # :nodoc:
         end
 
         # Unset values and attributes of variables and functions.
-        # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/unset.html]
+        # {[Spec]}[http://pubs.opengroup.org/onlinepubs/9699919799/utilities/V3_chap02.html#tag_18_29]
         def unset(*names)
           execute 'unset', *names
           chain_proxy

test/linebook/os/posix/utilities_test.rb

@@ -422,7 +422,7 @@ def test_pwd
 
   def test_read
     assert_recipe %q{
-      read xx yy
+      read "xx" "yy"
     } do
       read 'xx', 'yy'
     end

test/linebook/os/posix_test.rb

@@ -873,15 +873,19 @@ def test_while__makes_a_while_statement
   end
 
   def test_while__read
-    assert_recipe %q{
-      while read xx yy
-      do
-        echo $xx $yy
-      done < file
-    } do
+    setup_recipe do
+      cat.to('file').heredoc do
+        writeln 'a b c'
+        writeln 'x y z'
+      end
       while_ _read('xx', 'yy') do
-        echo var('xx'), var('yy')
+        echo var('yy'), var('xx')
       end.from('file')
     end
+
+    assert_output_equal %{
+      b c a
+      y z x
+    }, *run_package
   end
 end