specl: support multi-document YAML stream files.

* src/specl.in (slurp): Don't discard additional documents from the
yaml.load stream.
* NEWS: Update.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
specl: require now works intuitively from a spec file.

* specs/environmest_spec.yaml (describe environments): Change
specifications to how require calls should affect the lookup of
symbols they define.
* src/specl.lua (initenv): Before deferring to the system
loaders, try to find a required file along package.path and if
found, load it in the context of the innermost environment.
* docs/specl.md (Environments verses `require`): Remove.
`require` works properly in spec files now.
* NEWS: Update.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
specl: initialise spec environments earlier.

* src/specl.lua (run_examples): initialise with local symbols
earlier, so that they are available to before and after blocks.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
specl: remove dead code from Lua spec format days.

* src/specl.lua (compile_examples): No need to check for already
compiled code now that we only support YAML specs.
(compile_example): Simplify accordingly.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
specl: top-level before and after support.

* src/specl.in (slurp): Hoist document-level before and after
functions out of the enumerated examples table.
Prepend the current spec directory to `package.path`.
* specs/specl_spec.yaml (describe specl before): Move from
here...
* src/specl.lua (run): Top level now has hoisted before and
afters, so pass it to `run_examples` rather than `run_contexts`.
(compile_specs): Likewise.
* specs/spec_helper.lua (run_spec): ...to here.
* docs/specl.md (Separating Helper Functions): Add documentation
and a basic example.
* NEWS: Update.

Signed-off-by: Gary V. Vaughan <gary@gnu.org>
refactor: rearrange specl function into a more logical order.

* src/specl.lua: Reorder function definitions.

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