Skip to content
A draft standard for individual (bash) shell functions, their collection into families and libraries.
Branch: master
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.gitignore
README.org
author.org
famguide.org
index.org
orgheader.org
report.org
reportble.org
shdoc.org
shelf.org
style.css
thinking.org
trace.org
universalOrgPreface.org
utilguide.org

README.org

Shelflib – User Guide to SHELF practice

Scope

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.

Families

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.

fam – the family model for naming functions

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.

report – or assert for verifying function arguments

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.

shdoc – the SHell DOCumentation standard

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.

trace – function execution tracing, and

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.

util – a few programming functions

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.

User Guides

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.

fam family

report family

reportlib, main

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

Multi-family libraries

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.

Historical note

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.

References

external

SHELF local

You can’t perform that action at this time.