Turns out that since shellfu-doc uses pretty.sh (and makes good use of
it), what we had was broken cyclic dependency.
shellfu-doc and shellfu-embed are useful mostly for developers, though,
so it's no shame to split them.
Overview of changes:
* Improved manpage generation: added --name option to override page
name and re-polished to look a bit more like traditional manpages
* Fixed an outdated test
Try to get closer to how typical manpage looks like:
* Use NAME and DESCRIPTION sections.
* Make structure more flat (FUNCTIONS and VARIABLES on 1st level).
* Use `=item` formatting for function/variable references.
This should be especially useful in scenarios where docstrings are
exported directly from module file, but the filename is not
representative as module name.
This would typically happen where shellfu is only used for documentation
handling but not module handling.
Overview of changes:
* Breaking changes:
* Added support for shell-specific modules
shellfu() is now POSIX-compliant, and on init, will now detect
shell type (bash, sh) and use that later to decide where to look
for modules.
This means that all libraries are now placed under folders
named according to compatibility with bash, Bourne shell (POSIX)
or similar, and meaning of SHELLFU_INCLUDE changes from single
folder path to *prefix* to the separate shell-specific folders.
(SHELLFU_PATH, intended for library bundlers remains unchanged,
so other than deployment-related code should not be affected.)
This has also effect on file distribution in packages: lot of
stuff has moved under (previously "empty") *shellfu* package.
* Moved library exploration to shellfu-doc
Inerface (and code) for features like listing available modules or
showing documentation has been moved to shellfu-doc. shellfu-get
is now just a fixed string printer.
* Hid "private" functions / modules in listings
By default, shellfu-doc will not list functions and modules
starting with underscore.
You can use `-a` option to show all, but remember that these are
*not* intended for use outside module files. In other words,
these interfaces are not supported and can (and will) be removed
or changed as needed *without any notice*.
* Rewrote inigrep to reduced version with new API
inigrep API has started to show its age, making trivial things
less than trivial and corner cases standing in the way. Also,
from design perspective, it did too much; in particular, the
feature to guess filename from key path was really outside the
original scope.
This file-guessing feature has been thus moved to saturnin,
which has been designed to deal with things like that (and after
all was the only user of this inigrep feature); it should have
been there all along.
inigrep ended up with simpler, easier to grasp API.
* Renamed most globals
Module globals now don't have the `SHELLFU_` prefix. This
renames basically all module globals.
Also, SHELLFU_DEBUG_EXCLUDE, SHELLFU_DEBUG and SHELLFU_VERBOSE
now belong to pretty.sh, as they should be, so now it's
PRETTY_DEBUG, PRETTY_VERBOSE and PRETTY_DEBUG_EXCLUDE.
* Switched all read(1) calls to raw mode (won't interpret backslash
escape sequences)
read(1) calls won't interpret sequences such as `\n`, `\t` or
backslash at the end of a line. This mode (default for read(1)
is counter-intuitive and confusing; and should be almost never
used.
* Rewrote shellfu-doc to clean up CLI and improve usability; new
features include reading as manpage, export in Markdown, POD and
man and support for module ("main") docstrings and variable
docstrings.
* Revamped mkusage backend with focus on more rich but still
simple and consistent usage messages.
* Hid few minor APIs
Namely, globals `PRETTY_COLOR_*` from _pretty_color.sj and
sub-command try_import from `shellfu()`. None of these were
documented or easy to reach, so this should not break anything.
* Documentation:
* Added proper README.md
Shellfu at last has something that (albeit a bit long) can be
called a proper README without too much shame. It contains some
basic story of Why, installation instructions as well as tiny
tutorial to get people started.
* Added some missing sections to Shellfu Style Guide.
The guide is now somehow complete-ish; it does not yet cover eg.
the namespacing, but I'm not sure that should be even included.
* Added few missing docstrings
Rather arbitrarily, but working towards goal of having all
modules documented. (New shellfu-doc sure is something we want
to be able to show off)
* Removed old documentation, examples, guidelines and notes.
Most of these were either confusing, incomplete or obsolete;
the new README (and shellfu-doc) serve much better purpose.
* Core library:
* Added support for Bash variable types in pretty.debug -v
* Improved caller detection in pretty.sh
* Added notify mode to pretty.sh (uses notify-send)
* Fixed bug when empty lined were excluded from debug_pipe()
* Fixed bug when SHELLFU_DEBUG_EXCLUDE would affect also think(),
warn() and die()
* Improved shellfu() internal debug
* Maintenance:
* Cleaned up style guide
* Updated test suite
* Minor performance improvements
* Minor cleanups
* Cleaned up and improved style of supporting scripts
* Improved packaging
* Infrastructure maintenance
These were never intended to be used outside _pretty_color; the fact
that _pretty_color is internal does not mean *its* internal globals do
not need to follow underscore rules.
Move SHELLFU_DEBUG* and SHELLFU_VERBOSE to pretty where they belong
These variables are not specific to shellfu internals but in all ways
specific to pretty.sh module. The prefix is mostly historical cruft.
Let's clean that up.
Old naming is inconsistent from how functions are named, which can be
pretty confusing.
Also, there's no such naming requirement for user's modules; the
recommended way is to use unique project-specific prefix for both
functions and globals.
Risk of conflict should be managed by naming modules uniquely and/or
being careful with deployment in new environments.
Main changes:
* Removed ability to guess, search and merge files.
Old inigrep was doing too much. Instead of just being "grep for
INIs", it tried to guess file arguments, look for data in local
folders and smartly merge files based on locality, effectively
becoming sort of a configuration registry tool. While that function
can be (and was) highly useful, it is vastly outside inigrep's main
purpose; coupling like this made inigrep much harder to understand.
At the same time, only saturnin applications really used this;
so it became obvious where such behavior belongs, so relevant
code was moved to saturnin__conf, which now acts as wrapper around
the new inigrep.
* Rewrote API.
Old API was designed around the original idea, long long time ago,
when use cases were not clear yet. This fact propagates as the old
API being a bit gimmicky, too "granular" with little usability gain
but great graspability loss.
New API, on the other hand, simplifies section/key syntax and
concentrates on few simple modes, easy to understand and/or ignore.
* Added module-level documentation.
Now that shellfu-doc can work as manpage reader, it would be shame
to not include at least some basic documentation inside modules.
inigrep (albeit being one-function module) is proud to be the first
one in shellfu core module set to have at least simple introduction.
Great rewrite with revamped CLI, many added features and bugfixes.
* New CLI optimized for simple use. Default action is to show
module doc in manpage viewer.
* Respects variable documentation.
* Respects module documentation (first stray docstring).
* Can export (ugly but usable) module docs as Markdown, POD or
manpage.
* Dropped useless features as --cat (one can always open the file)
or display of partial documentation.
* Provided more rich usage hint.
* Rewrote tests with focus on more probable scenarios.
Use declare builtin to generate debug output.
We gain support for all Bash types, declare will do the formatting for
us, plus we can easily cover Unset state.
We needed to improve TF_RUN for this to work properly:
* fixup wrapping so that shebang, which influences
detection of SHELLFU_COMPAT, comes first (if there is one),
* and call the test script directly for the shebang to matter
(i.e. do not force `bash` in Bash mode upon all).
Although normally we prefer to sat "result must look like oracle",
that is, have result on RHS, and oracle on LHS of a comparison, with
udiff this produces far more readable result, e.g.:
--- oracle/try_import_fn.new
+++ result/try_import_fn.new
-foo
if foo was expected but is missing,
--- oracle/try_import_fn.new
+++ result/try_import_fn.new
+bar
if bar came unexpected.
shellfu-get (whose only job is to print one of hardcoded strings depending
on $1) and shellfu.sh should be as light as possible. Most of this code
is only useful (and intended) for library exploration, which is domain
of shellfu-doc.
A neat side-effect is, that in its new home, we don't have to be so
fussy about performance and footprinting, so we can afford luxury such
as putting code into functions and documenting them, using $1 for first
argument, using shellfu libraries(!)...
Needless to say, this is an incompatible CLI change (or it would have
half the effect), so we take the opportunity to re-do the CLI to match
the new home.
Remove '()' decoration from $caller internal variable. Decorations are
matter of presentations; at this level the brackets are only confusing.
To decide whether a caller is main script or direct descendant thereof,
called main(), use negative index of the stack array FUNCNAME (0 in first
case, 1 in the second). To signal that to the `_pretty_*` plug-ins,
use a dedicated boolean.
This also accounts for cases when a main() function is declared somewhere
else than in the main binary. Older code would simply assume (based
on the name being "main") that it's called from main binary and rewrite
$caller, possibly causing confusion. Now, only the originally intended
special cases behave specially.
This is simply impossible; debug_pipe is wrapper around debug which is
identified soon enough, so "debug_pipe" can't be assigned to $frontend.
Also, _pretty__get_frontend() will never return bracket-decorated
function name.
Alois Mahdal
Alois Mahdal