README: start touting loop.

1 files changed, 62 insertions, 1 deletions

diff --git a/README.md b/README.md
index 8dea3d6..dfc5073 100644
--- a/README.md
+++ b/README.md
@@ -32,13 +32,59 @@ Then this sort of code is possible:
     }
 
 We have implemented a facsimile of an Awk input scanning loop inside a function
-with a bit of syntactic sugar.
+with a bit of syntactic sugar. However, this these few preprocessing directives
+are just a toy example, compared to what is provided in the `cppawk` standard
+headers.
 
 `cppawk` has low dependencies. It's written in shell, and makes use of the
 `sed` and `printf` utilities.  Preprocessed programs can be captured and
 transferred for execution to systems that have Awk but do not have a
 preprocessor.
 
+## The `cppawk` Library
+
+`cppawk` is sprouting a small library of useful macros and functions.
+One of them is a powerful `loop` facility that allows iteration (both
+parallel and nested) to be expressed by combining abstract clauses.
+
+
+Here is a program designed to demonstrate the `cppawk` `loop`
+macro, with its multiple clauses.  It solves the following problem: a
+projectile is fired vertically with an initial speed of 5. Every step of the
+simulation, the speed drops by 1 due to gravity, eventually becoming negative.
+What is the maximum height achieved?
+
+    :::c
+    #include <iter.h>
+
+    BEGIN {
+      loop (from_step   (vel, 5, -1),
+            from_step   (pos, 0, vel),
+            while       (pos >= 0),
+            maximizing  (maxpos, pos))
+      {
+        print pos
+      }
+      print "maxpos =", maxpos
+    }
+
+The output is
+
+    :::txt
+    0
+    4
+    7
+    9
+    10
+    10
+    9
+    7
+    4
+    0
+    maxpos = 10
+
+This example is taken from the `testcases-iter` file.
+
 ## Roadmap
 
 `cppawk` is been carefully developed, and has a regression test suite.
@@ -66,6 +112,15 @@ There are currently
 *   `<narg.h>`: provides useful primitives for easily writing variadic macros.
     Documented by the `cppawk-narg.1` man page.
 
+*   `<iter.h>`: provides powerful iteration constructs, including a `loop`
+    macro that features the ability for the application to define
+    new iteration clauses, in addition to the numerous useful ones that
+    come with `loop`. **Currently lacking documentation***
+
+*   `<cons.h>`: provides Lisp-like functional, heterogeneous list manipulation,
+    higher order functions, some useful control operators, and functions
+    combining Lisp lists and Awk arrays such as `group_by`.
+
 ## Why?
 
 *   Why not?
@@ -79,11 +134,17 @@ There are currently
 *   You can use macros for C-style meta-programming, and for conditional
     selection of code.
 
+*   Powerful library: list manipulation, iteration, variadic functions.
+
 *   Other minor benefits: Awk has no comments other than from a `#`
     character to the end of the line. You get `/* ... */` comments
     with `cppawk`, and also `#if 0` ... `#endif` for temporarily
     disabling code.
 
+*   Some techniques from the `cppawk` header files would be useful in C and
+    C++. Everything is BSD-licensed; you are welcome to use it as you please,
+    whole or just bits and pieces.
+
 ## But GNU Awk has `@include`?
 
 *   GNU Awk's `@include` isn't a full preprocessor. There are no conditional