finish the bash-arrays.md article.

1 files changed, 47 insertions, 13 deletions

diff --git a/public/bash-arrays.md b/public/bash-arrays.md
index a34f58a..480d168 100644
--- a/public/bash-arrays.md
+++ b/public/bash-arrays.md
@@ -2,11 +2,6 @@ Bash arrays
 ===========
 :copyright 2013 Luke Shumaker
 
-Note: This page is incomplete—it does not cover setting or altering
-the contents of an array, only reading from it.  Note to self: that
-means I need to describe `array=(tokens...)`, `array+=(tokens...)` and
-`shift`.
-
 Way too many people don't understand Bash arrays.  Many of them argue
 that if you need arrays, you shouldn't be using Bash.  If we reject
 the notion that one should never use Bash for scripting, then thinking
@@ -17,15 +12,37 @@ understand arrays is this: command line arguments are exposed as an
 array.  Does your script take any arguments on the command line?
 Great, you need to work with an array!
 
-General array syntax
---------------------
+Normal array syntax
+-------------------
+
+<table>
+  <caption>
+    <h1>Setting an array</h1>
+    <p><var>tokens...</var> is expanded and split into array elements
+       the same way command line arguments are.</p>
+  </caption>
+  <tbody>
+    <tr>
+      <td><code>array=(<var>tokens...</var>)</code></td>
+      <td>Set the contents of the entire array.</td>
+    </tr><tr>
+      <td><code>array+=(<var>tokens...</var>)</code></td>
+      <td>Appends <var>tokens...</var> to the end of the array.</td>
+    </tr><tr>
+      <td><code>array[<var>n</var>]=<var>value</var></code></td>
+      <td>Sets an individual entry in the array, the first entry is at
+          <var>n</var>=0.</td>
+    </tr>
+  </tbody>
+</table>
 
-The most important things to understanding arrays is to quote them,
-and understanding the difference between `@` and `*`.
+Now, for accessing the array.  The most important things to
+understanding arrays is to quote them, and understanding the
+difference between `@` and `*`.
 
 <table>
   <caption>
-    <h1>Getting the entire array</h1>
+    <h1>Getting an entire array</h1>
     <p>There is <em>no</em> valid reason to not wrap these in double
        quotes.</p>
   </caption>
@@ -66,7 +83,7 @@ To get individual entries, the syntax is
 
 <table>
   <caption>
-    <h1>Getting a single entry from the array</h1>
+    <h1>Getting a single entry from an array</h1>
   </caption>
   <tbody>
     <tr>
@@ -126,8 +143,8 @@ Notice that `"${array[@]}"` is equivalent to `"${array[@]:0}"`.
   </tbody>
 </table>
 
-Accessing the arguments array
------------------------------
+Argument array syntax
+---------------------
 
 Accessing the arguments is mostly that simple, but that array doesn't
 actually have a variable name.  It's special.  Instead, it is exposed
@@ -135,6 +152,10 @@ through a series of special variables (normal variables can only start
 with letters and underscore), that *mostly* match up with the normal
 array syntax.
 
+Setting the arguments array, on the other hand, is pretty different.
+That's fine, because setting the arguments array is less usefull
+anyway.
+
 <table>
   <caption>
     <h1>Accessing the arguments array</h1>
@@ -166,6 +187,10 @@ array syntax.
     <tr><td><code>"${array[*]::<var>len</var>}"</code></td><td><code>"${*::<var>len</var>}"</code></td></tr>
     <tr><th colspan=2>Array length</th></tr>
     <tr><td><code>${#array[@]}</code></td><td><code>$#</code> + 1</td></tr>
+    <tr><th colspan=2>Setting the array</th></tr>
+    <tr><td><code>array=("${array[0]}" <var>tokens...</var>)</code></td><td><code>set -- <var>tokens...</var></code></td></tr>
+    <tr><td><code>array=("${array[0]}" "${array[@]:2}")</code></td><td><code>shift</code></td></tr>
+    <tr><td><code>array=("${array[0]}" "${array[@]:<var>n+1</var>}")</code></td><td><code>shift <var>n</var></code></td></tr>
   </tbody>
 </table>
 
@@ -204,3 +229,12 @@ behave like the <var>n</var>=0 entry doesn't exist.
 These make sense because argument 0 is the name of the script—we
 almost never want that when parsing arguments. You'd spend more code
 getting the values that it currently gives you.
+
+Now, for an explanation of setting the arguments array.  You cannot
+set argument <var>n</var>=0.  The `set` command is used to manipulate
+the arguments passed to Bash after the fact—similarly, you could use
+`set -x` to make Bash behave like you ran it as `bash -x`; like most
+GNU programs, the `--` tells it to not parse any of the options
+specially. The `shift` command shifts each entry <var>n</var> spots to
+the left, using <var>n</var>=1 if no value is specified; and leaving
+argument 0 alone.