Begin work on README

Begin the work on the README, which will double as reference docs for
now.

1 files changed, 148 insertions, 0 deletions

diff --git a/clformat/readme.md b/clformat/readme.md
new file mode 100644
index 0000000..55b5299
--- /dev/null
+++ b/clformat/readme.md
@@ -0,0 +1,148 @@
+CLFormat
+========
+
+An implemention of something strongly reminiscent of the Common Lisp FORMAT
+string-formatting function.
+
+Directives
+----------
+
+FORMAT strings are made up of free-form text, interspersed with directives. A
+directive is always started with a ~, and consists of the following parts.
+1. An optional set of prefix parameters
+2. An optional set of directive modifiers
+3. The name of the directive.
+
+### Prefix parameters
+Prefix parameters are used to configure options for a directive. These include
+things the number of columns to print a field in, or what radix to print a
+number in. They are separated from each other by commas.
+
+A prefix parameter can be one of the following:
+* A signed decimal number
+* A single character, preceeded by a single quote `'`
+* The letter V
+    Specifies that the value for this parameter should be read from the
+	parameters to the format string
+* The character #
+    Specifies that the value for this parameter should be the number of
+	parameters to the format string remaining
+* The character %
+    Specifies that the value for this parameter should be the current position
+	in the format string parameter list
+* A double quoted string.
+
+Prefix parameters are normally referred to positionally, but they can be given a
+name by starting the parameter with a `#` character, following it with a
+parameter name (which can be any series of printing characters that is not a
+whitespace character and is not one of the following seperator characters `,`,
+`:`, `;`), then a name-separator (`:` or ';`) followed by one of the values, as
+specified above.
+
+Whether or not a named parameter can also be referred to positionally is
+determined by the name-separator: `;` says it can, `:` says it can't.
+
+As for specifying more parameters than the directive takes, the rules are as
+follows:
+* You may specify as many non-positional parameters as you want
+* You may not specify more or less positional parameters than the directive says
+  it takes
+
+In addition, as a useful feature, parameter names may be abbreviated to the
+shortest possible unique value. For example, if a directive took the following
+parameters (`foo`, `foobar` and `fizz`), the following would be valid specifiers:
+* `foo` (refers to `foo`)
+* `foobar` (refers to `foobar`)
+* `foob` (refers to `foobar`)
+* `fizz` (refers to `fizz`)
+* `fi` (refers to `fizz`)
+* `f` (not allowed, ambiguous reference)
+### Modifier sets
+A modifier set is any combination of the following characters, with duplicate
+characters having no effect: 
+```
+* $
+* :
+* *
+* @
+```
+
+### Directive names
+A directive name can be either:
+* A single non-whitespace, non-/ character that is optionally preceded by a
+  grave
+* A name enclosed in /'s
+
+If it is a name enclosed in /'s, then it is a call to a user specified function.
+Otherwise, it is an invocation of one of the built-in directives.
+
+## Directives
+The following is a list of all of the directives that are currently
+implemented, as well as a short description of what that directive does
+
+| Directive | Name | Description|
+|-----------|------|------------|
+| A   | Aesthetic   | General string printer. |
+| S   |             | This is an alias for the A directive |
+| C   | Character   | Print out a single character |
+| B   | Binary      | Print out a base-2 integer |
+| O   | Octal       | Print out a base-8 integer |
+| D   | Decimal     | Print out a base-10 integer |
+| X   | Hexadecimal | Print out a base-16 number |
+| R   | Radix       | Print out a integer in an arbitrary base |
+| &   | Freshline   | Print out a newline, if we didn't just print one |
+| %   | Newline     | Print out a literal new line (\n) |
+| \|  | Formfeed    | Print out a formfeed character and start a new page |
+| ~   | Tilde       | Print out a literal tilde |
+| ?   | Recursive   | Invoke a sub-format string |
+| *   | Go-to       | Move around in the parameter list |
+| ^   | Escape      | Escape from an enclosing directive |
+| [   | Conditional | Select a format string, based on a condition |
+| {   | Iteration   | Repeatedly invoke a format string. |
+| (   | Case        | Perform case-manipulation on text |
+| \`[ | Inflection  | Perform inflection on a format string |
+| T   | Tabulate    | Print something in a table-like format |
+
+The following are directives that are not valid to use outside of specific other
+directives
+
+| Directive | Name | Description|
+|-----------|------|------------|
+| ]   | Conditional end | End a conditional directive
+| ;   | Clause separator | Separate two clauses in a block directive
+| )   | Case end | End a case directive
+| \`] | Inflection end | End a inflection directive
+| <   | Inflect start | Start a inflection control |
+| >   | Inflect end | End a inflection control |
+
+The following are directives that have not been implemented
+
+| Directive | Name | Description|
+|-----------|------|------------|
+| \`< | Layout start | Start a layout controlling block |
+| \`> | Layout end | End a layout controlling block |
+| F   | Fixed-Format floating point | Print a floating point number with a fixed number of characters|
+| E   | Exponential floating point | Print a engineering-style floating point number |
+| G   | General floating point | Print a floating point number |
+| $   | Monetary floating point | Print a floating point number as currency |
+| W   | String print | Use A directive instead 
+| P   | Plural | Use the \`[ and \`] directives instead
+
+The next section of the document is a reference for each directive type,
+detailing how that directive works, how many and what sort of parameters it
+takes, and all of that sort of thing
+
+## A Directive
+The A directive is the general purpose string formatting directive, serving as
+roughly analagous to the S directive in many printf-type strings.
+
+It takes zero, one or four parameters (described by the table below), as well as one argument.
+
+| Sample String | Description |
+|-----------------------------|
+| ~a | Print out the next format argument as a string. |
+| ~*mincol:[0]*a | Print out the next format argument, taking at least *mincol* columns | 
+| ~*mincol:[0],colinc:[1],minpad:[0],padchar:[' ]*a | Print out the next format argument, adding at least *minpad* instances of *padchar*, then adding copies of *padchar* in *colinc* sized blocks until the total output size is at least *mincol* columns long. |
+
+Padding will be inserted after the string, unless the `@` modifier has
+been specified, in which case it will go before the string.