The Perl code did not keep hash sign, nullifying effect of the strip_doc
pipe. As a result, the function docstring would contain single space
before each non-empty line.
Markdown does not care about that (well, unless we already had 3 spaces
there in which case a block could be considered verbatim). In POD,
however, this means verbatim plaintext. Viewing as manpage later (by
far most common use case), the visual difference is normally too subtle
to notice, but at some point pod2html had spilled the beans.
Due to Bash limitations and performance concerns, few characters are
not usable in section/key names in this version of inigrep.
This commit adds validation to catch these cases and warn user instead
of silently providing invalid output.
Note that there is one case which we can't catch, and that is dot in a
key name. However, this is rather question of key paths: dot is used as
a delimiter in key paths, so allowing it in key name would lead to
ambiguous keypath syntax.
Overview of changes:
* Added possibility to set self name for mkusage() explicitly
* pretty/notify now won't spam with one notification per line
* Fixed pretty/html format for die()
* Code maintenance and cleanup
Overview of changes:
* Split tools to shellfu-dependency to get rid of (broken) cyclic
dependency.
Actually shellf-doc and shellfu-embed both make use of pretty.sh, so
we could have either cyclic package dependency or -devel package.
The latter seems more appropriate.
* Updated bash completion
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.
Alois Mahdal
Alois Mahdal