SC2039 - We simply have to use `local` whenever it's possible, and
although it's not defined in POSIX, most common shells do support it
(well, at least Dash, Bash and Zsh).
SC1090 - Sourcing non-constant file is pretty much the main idea of
Shellfu, so avoiding that part does not make sense.
Overview of changes:
* Added workaround to shellfu_api test only against own modules
* Added option to append clarifying message to usage messages
Usage messages can now be made more useful by warning user what
exactly was wrong. Warnings will appear after the usage message
and before command exits and decorated with 'bad usage: ' prefix;
this is so that user will be more likely notice and understand them.
Note that this could be done earlier by using -E option and adding
the warning yourself inside usage() function, but the -w option lets
you keep usage() very simple and yet leads to more consistency.
* Codebase maintenance
* Refactored charmenu.sh
The docstring was not very useful so this it was overhauled
completely. Also more proper coding style is now in place.
* `shellfu` command will now de-duplicate $SHELLFU_PATH
shellfu init function, and by extension some shellfu-doc modes,
would list a module twice if its path ended up twice on
SHELLFU_PATH. That should no longer happen.
* Added mdfmt, a Markdown formatting helper
This module consists of single function with aim to help generate
Markdown text from your scripts.
* Updated and improved usage-related pretty.sh docstrings
* Fixed PRETTY_DEBUG_EXCLUDE double double-underscore bug
PRETTY_DEBUG_EXCLUDE would not work properly on functions like
`foo__bar__baz`, where the second double-underscore would make it
think module name was `foo__bar`, when in fact it's `foo`.
* Added journald logging module for pretty.sh
Using systemd-cat, this module employs journald as way of
communicating with user.
* Added shellfu-sh pseudo-package
On RPM-based distributions, somebody has to own 'include-sh'
directory. Also having shellfu-FOO package helps module packages
declare their "Shellfu flavor" (ie. `Requires: shellfu-sh` sends
clear message that a module is "POSIX-oriented".
* Updated packaging and meta-data
Files responsinle for packaging and versioning meta-data have been
altered to catch up with newer versions of MKit. This should have
almost no effect on package (only 'effect' I can think of is a purely
decorative change in `--version` output).
* Fixed typo in SPEC file
SPEC file claimed that Shellfu is distributed under LGPL2, while
it's actually GPL3. (We should consider changing it to LGPL2,
though.)
* Replaced LICENSE file with Markdown version
Because Markdown is cooler. For a more serious reason, MKit now has
*newstub* script, which can help regenerate MKit structure including
LICENSE file, and this script can only do Markdown (because Markdown
is cooler). TL;DR: It will be less hassle to keep MKit stuff fresh.
* Updated emnedded TFKit (v0.0.14) and MKit (v0.0.21)
Until TFKit is able to run tests in sandbox (instead of running tests
against installed SUT), this test will throw false positives in case
any other Shellfu modules are present.
This commit adds workaround that should be removed when new TFKit
version is installed.
If function name after the module prefix contained double underscore,
the old code would not parse module name properly, e.g.
foo__bar__baz
would consider 'foo__bar' as module name, when only 'foo' should be
considered.
Overview of changes:
* Fixed bug in function doc exporting that caused all function
docstrings be treated as verbatim text in POD
* Fixed case when shellfu-doc was called with non-existent file
* Added --encoding option to shellfu-doc
* Added inigrep test for special chars in section/key/value
* Added validation of section/key names to inigrep
* Build scripts maintenance
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.
Alois Mahdal
Alois Mahdal