Initial documentation for Lace

5 files changed, 200 insertions, 0 deletions

diff --git a/doc/syntax b/doc/syntax
new file mode 100644
index 0000000..5ac4115
--- /dev/null
+++ b/doc/syntax
@@ -0,0 +1,94 @@
+# Syntax of Lace
+
+Lace rule files are parsed line-by-line.  There is no provision at
+this time for rules to be split across multiple lines.  If you require
+such, please submit a patch.
+
+Lace splits each line into a series of tokens.  Tokens are always
+strings and they can be optionally quoted to allow for spaces in them.
+Certain tokens then have constraints placed on them so that further
+parsing will be unambiguous.
+
+The lexing into tokens is done similarly to how shell does it.  This
+means that each whitespace-separated "word" is then subjected to
+quoting rules.  Lace does not have many special characters.  The
+backslash introduces escaped values in all cases and lace does not
+differentiate between single and double quotes.  Backslash escaped
+characters sometimes have special meaning if inside quotes.  For
+example, the following strings lex in the following ways:
+
+1. hello world
+   * Two tokens, one of each word.
+2. hello   world
+   * The same as 1.
+3. "hello world"
+   * One token with both words separated by one space
+4. 'hello world'
+   * Same as 3.
+5. hello\ world
+   * Same as 3 and 4.
+6. up\town
+   * One token, consisting of the letters: uptown
+6. "up\town"
+   * One token, consisting of the letters: up TAB own
+7. \"
+   * One token, a double-quote character
+8. '"'
+   * The same as 7
+9. "\""
+   * The same as 7 and 8.
+
+As you can see, the lexing rules are not trivial, but should not come
+as a surprise to anyone used to standard command-line lexing
+techniques.
+
+Comments in Lace are prefixed by a hash '#', a double-slash '//' or a
+double-dash '--'.  The first word of the line must start with one of
+these markers (but may contain other text also), for example:
+
+# This is a command
+// As is this
+-- And this
+
+#But also this
+//And this
+--And also this
+
+Blank lines are permitted and ignored (except for counting), any
+prefixed or postfixed whitespace is deleted before lexing begins.  As
+such:
+
+# This is a comment
+  # So is this
+
+This allows for sub-rulesets to be indented as the author pleases,
+without altering the meaning of the rules.
+
+The first word of a rule defines its type.  You can think of it as the
+command being run.  Lace, by default, provides a small number of rule
+types:
+
+1. Definitions
+   * This define access control stanzas.  The definitions produced are
+     used in further rules to control access.  Lace does not allow any
+     name to be reused.
+2. Includes
+   * Lace can include further rules at any point during a ruleset.  If
+     the rules are to be optionally run then Lace cannot perform static
+     analysis of the definitions within the ruleset.  Instead it will
+     rely on runtime catching of multiple-definitions etc.
+3. Access control statements
+   * These are the core functions of Lace.  Namely the allow and deny
+     statements.  These use control definitions from earlier in a ruleset
+     to determine whether to allow or deny access.  The first allow
+     or deny statement which passes will stop execution of the ruleset.
+4. Default statement
+  * The 'default' statement can only be run once and provides Lace with
+    information on what to do in the case of no allow or deny rule passing.
+
+For further information on the syntax of each rule type, see the
+corresponding file syntax-<ruletype>
+
+In those files, if you encounter the words WILL, MAY, SHOULD, MUST, or
+their negatives, specifically in all-caps, then the meaning of the
+words is taken in the spirit of the RFC usage of them.
diff --git a/doc/syntax-allow-deny b/doc/syntax-allow-deny
new file mode 100644
index 0000000..094352b
--- /dev/null
+++ b/doc/syntax-allow-deny
@@ -0,0 +1,17 @@
+Syntax of Allow and Deny statements
+-----------------------------------
+
+These access control statements start 'allow' or 'deny', followed by a
+single token reason to be returned to the caller, followed by zero or
+more definitions, all of which must pass for the statement to execute.
+
+allow "Administrators can do anything" is-admin
+deny "Plebs may do nothing" is-pleb
+
+allow ''
+
+As with definitions, includes, etc, if rule names are prefixed with an
+exclamation point then their sense is inverted, e.g.
+
+deny "Only admins may alter hooks" altering-hooks !is-admin
+
diff --git a/doc/syntax-default b/doc/syntax-default
new file mode 100644
index 0000000..91b9c0d
--- /dev/null
+++ b/doc/syntax-default
@@ -0,0 +1,32 @@
+The syntax of the default statement
+-----------------------------------
+
+The default statement is interesting.  It has no behaviour at runtime,
+but at compile time it alters the behaviour of the compiler with
+respect to the end of the ruleset.
+
+If, when the ruleset has finished compiling, the last allow or deny
+was not unconditional, then the compiler will, in the absence of a
+'default' statement, inject a terminal allow/deny of the opposite
+sense of the last explicit operation, unconditionally and with a
+reason of the empty string.
+
+If a 'default' statement was encountered during processing then it
+will be used instead.
+
+The syntax of the 'default' statement is:
+
+'default' 'allow' <reason>?
+or
+'default' 'deny' <reason>?
+
+If reasons are not provided, the string "Default behaviour" is
+substituted.
+
+Once a single 'default' statement has been encountered during
+compilation it is an error, and the compiler WILL cease, if it
+encounters an additional 'default' statement.
+
+Since it's common for rulesets to stem from a single core point, it's
+recommended that the application define a policy at the start of these
+core statements.
diff --git a/doc/syntax-define b/doc/syntax-define
new file mode 100644
index 0000000..277fb54
--- /dev/null
+++ b/doc/syntax-define
@@ -0,0 +1,34 @@
+Syntax of definition statements
+-------------------------------
+
+Definition statements start with one of 'def' or 'define'.  They may
+also start 'acl' to look more squiddish.
+
+The rough syntax of a definition statement is:
+
+'def' <name> <controltype> <0-or-more-args>
+
+There are some loose constraints on the name and controltype
+arguments.  The name SHOULD NOT contain quote characters and MUST NOT
+start with an exclamation point.  The controltype simply SHOULD NOT
+contain quotes.
+
+The control types are typically provided by the program which is using
+Lace.  However Lace does provide some simple control types which can
+be useful and callers are welcome to add them to their engines.
+
+The two simplest control types Lace provides are the allof and anyof
+controls.  They, as their arguments, take two or more rule names and
+match if all or any (respectively) of their arguments resolve to true.
+As with other parts of Lace, if the rule names are prefixed by
+exclamation points then their result is inverted before being tested.
+
+These give you ways to produce common subexpressions of the 'AND' and
+'OR' forms to be used in later rules.
+
+Lace also provides a match control type which does a string comparison
+on a context value.  The match control type takes two arguments.  The
+key to match and the value to test against.  If the value starts with
+a tilde then Lace will use Lua pattern matches.  This is not a
+terribly useful control type and is provided purely for simple cases
+where the caller does not need more complex control types.
diff --git a/doc/syntax-include b/doc/syntax-include
new file mode 100644
index 0000000..7f70d1a
--- /dev/null
+++ b/doc/syntax-include
@@ -0,0 +1,23 @@
+Syntax of include statements
+----------------------------
+
+Include statements take a source token to include and an optional list
+of definitions which must all be true before the include will take
+place.
+
+'include' <sourcename> <0-or-more-definitions>
+
+If the include ends with a question mark then should the sourcename
+not be available at the time, it will be silently ignored.
+
+Nominally an included ruleset is linearly inserted into the execution
+stream there and then.  In practice, while include statements result
+in compilation of the rulesets at the same time, the contents of the
+ruleset will not be run unless the definitions all pass.  This means
+that the defines will not happen unless the definitions all pass.  As
+such, use conditional includes carefully.
+
+If an "optional" include source isn't available, it is as though the
+definitions did not pass.  If a mandatory include source isn't
+available then compilation of the ruleset will fail immediately.
+