refactor: move non-lua-stdlib functions out of specl.std.

* AUTHORS: Credit Reuben Thomas for the contents of
specl/std.lua.
* specl/std.lua: Change copyright header to refrect the correct
copyright and license terms of the code in this file.
(prog, warn, process_args): Move from here...
* specl/util.lua (prog, warn, process_args): ...to here.
* specl/std.lua (metatable, strbuf,clone, metamethod, render)
(tostring): New functions.  Copied from, or trivial reworkings of
code from lua-stdlib.
(M): Update accordingly.
* specl/util.lua: Import specl.std.
(M.process_files, M.slurp, M.tostring): Re-export functions from
specl.std.
* specl/specl.in: Import those APIs from specl.util instead of
specl.std.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
matchers: use util.tostring to display tables for diagnostics.

* specl/matchers.lua: Import specl.util.
(q): Use util.tostring so that tables output by failed expectations
are legible.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
refactor: move command pipe managment into environment sandbox.

Generalize the output and exit status capturing functions into
the outermost environment sandbox, where it can be used by any
spec-files.
* specs/specl_spec.yaml (exit_status, capture_output): Refactored
from here...
* specl/specl.lua (env.spec.cmdpipe): ...to here.
* specs/specl_spec.yaml (run_spec): New helper function, wrapping
spec.cmdpipe.
Adjust all callers.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
docs: re-organise and edit README.md to make way for pending docs.

* README.md (YAML): Split out from the Specifications section.
Don't list the quirks at the end, explain them in the main text
of this section.
Renumber following sections accordingly.
(Contexts): Introduce an example right away.
(Pending Examples): Pending.
(Custom Formatters): Describe API changes necessary to support
display of pending expectations and examples.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
matchers: preliminary support for pending expectations.

* README.md: Document required behaviour of pending examples.
Edit the surrounding text so that the new section fits in to
the narrative logically.
* specs/specl_spec.yaml: New examples to show how pending
examples should work.  Some are still pending!
* specl/specl.lua (run_examples): Change the formatters API
slightly, because we don't want to have already displayed an
example description on the previous line before we know whether
the description is for a still pending example.
* specl/formatter/progress.lua (expectations): Decode the new
status parameter table to display pending examples as '*'.
* specl/formatter/report.lua (tabulate): Make a suitably
colorful output table element.  Factored out of spec.
(spec): Adjust.
(example): Remove.
(expectations): Decode the new status pararameter table to show
whether the whole example is pending, or that the expectations
are specifying currently unimplemented behaviour.
* spelc/formatter/tap.lua (expectations): Likewise.
* specl/formatter/progress.lua (footer): Show pending examples
in statistics.
(M): Remove unused example entry point.
* specl/formatter/report.lua, specl/formatter/tap.lua (footer)
(M): Likewise.
* specl/matchers.lua (M.init): New entry point to prepare for
a new block of expectations, that keep track of pending status.
(M.status): New entry point. Return results after a block of
expectations have run.
* specl/specl.lua (run_examples): Use them instead of hard-
coding.
* specl/matchers.lua (M.stats): Add pend counter.
(M.expect): Don't try to match an expectation for a pending
example, or count it's status.
(M.pending): New entry point, put the current expectation block
in pending mode, and increment pend counter.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
matchers: report an empty example definition as a pending example.

* README.md (Pending Examples): Update to document empty example
definitions as denoting a pending example.
* specs/specl_spec.yaml: Remove pending status for empty example
definition specifications.
* specl/specl.lua (compile_examples): Replace any empty definition
with a call to `pending` before compiling.
* specs/speclc_spec.lua: New file. Specify that the compiler must
produce a Lua format spec file with a call to `pending` injected
into otherwise empty example definitions.
* specs/specs.mk (specl_SPECS): Add specs/speclc_spec.yaml.
(specl_LUASPECS): Add specs/speclc_spec.lua.
* build-aux/speclc.in (dump_example): Replace otherwise empty
example definitions with a call to `pending`.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
maint: remove completed TODO items.

* TODO.yaml: Remove completed TODO items.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
formatters: tweak color output for report formatter.

* specl/formatter/report.lua (footer): Use blue instead of red
for the failing report header output.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
maint: adjust output from compiled Lua spec files.

Since we effectively run every specification twice to make sure
support for Lua specs isn't broken, tweak the descriptions of
compiled specs so we can tell them apart in failure summaries.
* specs/specs.mk (.yaml.lua): Inject '(Lua spec)' into top-level
describe entries as compiled specs are written to disk.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
formatters: provide a richer accumulator API for custom formatters.

* README.md (Custom Formatters): Document the richer API.
* specs/formatters_spec.yaml: New file. Specify accumulator API
behaviour.
* specs/specs.mk (specl_SPECS): Add specs/formatters_spec.yaml.
(specl_LUASPECS): Add specs/formatters_spec.lua.
* specl/specl.lua (accumulator): Implement it.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
formatters: use table accumulators to collect pending reports.

* specl/formatter/progress.lua (expectations): Split returned
value into a `pend` and `fail` reports.
(footer): Display `pend` and `fail` summaries in verbose mode.
* specl/formatter/report.lua (expectations, footer): Likewise.
* specl/formatter/tap.lua (expectations): Display pending reports
inline as TAP comments.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>