From b79a19ca1f3f87a14f55257fad3c1ec47e6a36ea Mon Sep 17 00:00:00 2001 From: Daniel Silverstone Date: Mon, 9 Dec 2013 21:29:40 +0100 Subject: More documentation --- config.ld | 3 ++- lib/lace.lua | 8 +++++++- lib/lace/engine.lua | 54 +++++++++++++++++++++++++++++++++++++++++++++++++++++ 3 files changed, 63 insertions(+), 2 deletions(-) diff --git a/config.ld b/config.ld index 37ac80a..e45aa68 100644 --- a/config.ld +++ b/config.ld @@ -1,5 +1,6 @@ file = {"lib"} -format = "discount" +readme = "readme.md" +format = "lua-markdown" project = "Lua Access Control Engine" title = "Lace - Lua Access Control Engine" dir = "html" diff --git a/lib/lace.lua b/lib/lace.lua index 9e039d6..2c76cb8 100644 --- a/lib/lace.lua +++ b/lib/lace.lua @@ -9,7 +9,13 @@ --- Lua Access Control Engine. -- --- +-- The Lua Access Control Engine library consists primarily of a ruleset +-- compiler and execution engine. In addition there is a lexer and also a +-- complex error reporting system designed to ensure application authors who +-- use Lace in their projects can provide good error messages to their users. +-- +-- * For compiling rulesets, see `lace.compiler.compile`. +-- * For running compiled rulesets, see `lace.engine.run`. local lex = require "lace.lex" local compiler = require "lace.compiler" diff --git a/lib/lace/engine.lua b/lib/lace/engine.lua index 5484c9b..45c2c33 100644 --- a/lib/lace/engine.lua +++ b/lib/lace/engine.lua @@ -7,6 +7,12 @@ -- For licence terms, see COPYING -- +--- The runtime engine for the Lua Access Control Engine +-- +-- Once a ruleset has been compiled, it can be run for multiple inputs without +-- needing to be recompiled. This is handy for controlling access to a +-- long-lived daemon such as an HTTP proxy. + local err = require 'lace.error' local function _dlace(ctx) @@ -15,6 +21,16 @@ local function _dlace(ctx) return ret end + +--- Set a definition. +-- +-- @tparam table exec_context The execution context for the runtime. +-- @tparam string name The name of the define to set. +-- @tparam table defn The definition function to use. +-- @treturn boolean Returns true if the definition was set successfully. +-- @treturn nil|table If the definition was not set successfully then this is +-- the error table ready to have context added to it. +-- @function define local function set_define(exec_context, name, defn) local dlace = _dlace(exec_context) dlace.defs = dlace.defs or {} @@ -25,6 +41,17 @@ local function set_define(exec_context, name, defn) return true end +--- Test a definition. +-- +-- @tparam table exec_context The execution context for the runtime. +-- @tparam string name The name of the define to test. +-- @treturn boolean|nil If the named definition does not exist, this is nil. +-- Otherwise it is true iff. the definition's function +-- results in true. +-- @treturn nil|table If the named definition does not exist, this is the error +-- table ready for filling out with more context. +-- Otherwise it is nil. +-- @function test local function test_define(exec_context, name) local dlace = _dlace(exec_context) dlace.defs = dlace.defs or {} @@ -36,6 +63,22 @@ local function test_define(exec_context, name) return defn.fn(exec_context, unpack(defn.args)) end +--- Internal routine for running sub-rulesets +-- +-- @tparam table ruleset The compiled ruleset to run. +-- @tparam table exec_context The execution context for the runtime. +-- @treturn nil|boolean|string The first return value is `nil` in the case +-- of a runtime error, `false` if a Lace error +-- was encountered during runtime, otherwise it it +-- a result string (typically `allow` or `deny`). +-- In addition, internally, an empty result string +-- will be returned if no result was set by the +-- sub-ruleset. +-- @treturn nil|string If an error was encountered, this is the error message, +-- otherwise it is an additional message to go with the +-- result if there was one, or `nil` in the case of no +-- result value being set by the ruleset. +-- @function internal_run local function internal_run_ruleset(ruleset, exec_context) -- We iterate the ruleset, returning the first time -- a rule either errors, or returns a stopping result @@ -58,6 +101,17 @@ local function internal_run_ruleset(ruleset, exec_context) return "" end +--- Run a ruleset. +-- +-- @tparam table ruleset The compiled ruleset to run. +-- @tparam table exec_context The execution context for the runtime. +-- @treturn nil|boolean|string The first return value is `nil` in the case +-- of a runtime error, `false` if a Lace error +-- was encountered during runtime, otherwise it it +-- a result string (typically `allow` or `deny`). +-- @treturn string If an error was encountered, this is the error message, +-- otherwise it is an additional message to go with the result. +-- @function run local function run_ruleset(ruleset, exec_context) local ok, ret, msg = xpcall(function() return internal_run_ruleset(ruleset, exec_context) -- cgit v1.2.1