This library supports the SHELF Standard. Since the the SHELF Standard uses function families, this is the User Guide for the shelflib. As such it introduces four function families and a utility group of functions. Each of these five (four familes, one group) have their own User Guide,
The function family introduces nothing new to shell syntax or ability to access function libraries. It does set a practice to organize function collections inside a function library.
From a practical standpoint, each family or group has its own source
file. These are combined into a single shell library shelflib
and installed in the user’s runtime. Instructions follow.
When installed, the user has roughly 80 bash shell functions to extend the practice to their own work.
If you have not yet read the SHELF Standard, now would be a good time before proceeding.
These are the four families and utility group of functions. Each section introduces the family or group to indentify it’s distinct purpose in support of the SHELF Standard. The next section introduces the respective User Guides.
The fam family generates the framework to define a function family. To define a family, call the main entry point:
... fam_iam # Family, I am
from an intialization function. This establishes the family framework. For example, the fam family instantiates itself as a family thusly:
fam_init () { fam_iam; ... other initialization; }
...
fam_init 1>&2; # if the only family in a library
To see how multiple families are collected in a single library, see the discussion on Multi-family libraries.
A reporting function is used in a shell function to assert its arguments as to number, type of file, or string length, or any assertion you can support with a function.
A typical use of an assertion:
report_not{something} $1 && return N
where N is usually a 1, … the number of an error return from the user function, and “something” is readable, writable, executable, ….
Here is a sample function.
function report_notreadable
{
[[ -r $1 ]] && return 1;
report_usage $1 is NOT readable
}
Since this function does not test it’s own arugment count (does it indeed have an argument, it’s best used following a test to verify the argument exists.
... report_notargcount 2 $# flag file && return 1 report_notreadable $2 && return 2
for example, where report_notargcount is:
report_notargcount ()
{
[[ $2 -ge $1 ]] && return 1;
report_usage need at least $1 arg/s: $(shift 2; echo $*)
}
Note how the function treats arguments after the second. Woe to the user who abuses a reporting function.
In the examples above, a positive statement asserts an argument isn’t something, and return a failure when that’s the case. So, the user function lines up as many assertions on it’s arguments as needed. The first one to fail produces the required message and returns from the function with a message on stderr from report_usage. Otherwise the function executes as desired.
These functions encourage a programmer to write a brief introductory user guide to each function. Here is the shdoc Family User Guide.
The family name is the shd prefix. The functions in this family set a standard for shell doclib capture and presentation. Precedent for the practice was first established by Javadoc and more recently in Perldoc and Pydoc.
A majority of online references to “shdoc” are few and disjoint. The most common reference to an shdoc package is a tool kit for caputuring command line usage and is built for the TeX community.
The tracing feature of these shell functions uses trace_call in a function body after some assertion validation using the report functions. While it’s not dependent on all assertions passing, it seems useful to dispose of the assertions, which announce a failure, and then announce the function body is ready to work.
Tracing my be enabled or disabled, by trace_on or trace_off. Either of them reset the function behavior to either trace_stderr, or simply return, respectively.
Trace_call echo’s each call to the stderr, which may be separately saved or altogether ignored:
... 2> trace.err # say, or ... 2> /dev/null # the "bit-bucket"
For each call, the trace_call collects two function names: the current function and it’s calling function. This enables a user to construct a calling tree from a log.
These are generic functions, not worth finding a family to call home. Such names as foreach, ignore, comment, functions, …
As such, their inclusion in the collecting library was simply to satisfy one requirement: that no function in the library refer to a function not in the library.
When the families and utility group are combined in a single library, no function refers to a function not in the library.
These are listed in order of encounter.
And here is the report function family.
First a copyright, then the initialization function. Since this is a family, the only necessary call is to fam_iam
The SHELF Standard allows a single executable statment when sourceing
a library, which leaves nothing on the standard output. Since each family
has it’s own initialization function, it is only necessary for the library
to invoke the separate familiy initialization. For the shelflib this
is how it happens:
shelf_init ()
{
fam_init
report_init
shdoc_init
trace_init
}
shelf_init 1>&2
as the last code in the shelf library. Presumably the utility functions do not need initialization, or they too would be a family.
This library was originally built from a single, tangled, OrgMode source file. In order to make the files accessible to the general audience, the de-tangled files are now the source control objects, and therefore available for edit in their own individual right.
Separate libraries are combined into an single public library with parallel work in smart-public functons.