The Standard Function Library

A library's filename conventionally ends with *lib, just the letters, not a suffix. The Standard Library's name therefore is stdlib.

A very few simple, non-family function names are reserved for widespread practice.

• comment – puts its arguments on stderr
• ignore – directs stdout of its command arguments to /dev/null
• quietly – directs stderr of its command arguments to /dev/null

comment () 
{ 
    : since the DECLARE -F idiom eats;
    : date: 2018-02-16;
    echo $* 1>&2
}
ignore () 
{ 
    : ~ cmmd args ...;
    : returns STATUS, but not STDOUT;
    : app_trace $*;
    : date: 2019-11-23;
    $@ > /dev/null
}
quietly () 
{ 
    : ~ cmmd args ...;
    : returns STATUS, but not STDERR;
    : date: 2018-02-16;
    : date: 2018-10-09;
    $@ 2> /dev/null
}

These families are reserved as preferred support functions for The Standard Function:

• report – a family which is not an app, its members perform specific assertion checking.
• shd – an application family to extract Shell Documentation, setting practice for tags
• trace – a few functions to support debugging

It's features are reserved to provide functions considered necessary for a function family:

• list – the family members
• help – summarizes the important sub-functions
• doc – the family user guide, manual pages
• init – set initial variables,
• user – reserved and called by family_init if existing

standard () 
{
    : this function is the parent of a function family;
    ...
}
standard_init ()
{
    ; generic initialization
    ...
    declare -f standard_user > /dev/null && standard_user 
}

The _init and _user sub-functions have requirements specified in The Library Standard

A local subfunction is defined within the scope of a function body. It becomes part of the global shell environment when the enclosing function is executed. It is a good practice to unset the local function when its parent is executed:

    standard_function ()
    { 
         ....
         function _localfunction () 
         {
         ...
         }
         ....
    }

$ xx () { function _xx () { ls a*lib; }; _xx; unset _xx; }; declare -f {_,}xx
$ echo =====
$ xx; declare -f {_,}xx
xx () 
{ 
    function _xx () 
    { 
        ls a*lib
    };
    _xx;
    unset _xx
}
=====
acctlib
auxlib
awklib
xx () 
{ 
    function _xx () 
    { 
        ls a*lib
    };
    _xx;
    unset _xx
}

The first use of declare -f {_,}xx doesn't see the function _xx since it hasn't been defined; the second doesn't either because it's been unset.

Test the alternative by removing the unset command from the xx function.

The standard function is encouraged to use a convenient default for any argument when supplying the default exhibits an effect to describe or exhibit the function's behavior. For example, a function to display other functions:

$ standard_function
standard_function () 
{ 
    : display the canonical form of function arguments;
    declare -f ${*:-$(myname)} 2> /dev/null
}
$ standard_function myname
myname () 
{ 
    : ~ [n];
    : returns name of caller OR callers caller ...;
    : date: 2018-02-16;
    echo ${FUNCNAME[${1:-1}]}
}

shdoc , is the first application of the null command :. It exhibits an example of its use and purpose. It also has a default usage ${*:-$(myname)}, which produces a function shdoc_doc. This might more appropriately echo the function's shell document than reflect it as a function.

$ declare -f  {_,}shdoc
_shdoc () 
{ 
    : date: 2018-02-16;
    report_notfunction $1 && return 1;
    echo "function ${1}_doc {";
    declare -f $1 | shd_justcolon;
    echo "}"
}
shdoc () 
{ 
    : this is a shell doclib "shdoc" comment;
    : an shdoc comment is the first ":"-origin lines;
    : in the shell function, the rest being the executable.;
    : date: 2019-01-28 use local _shdoc and produce declare -f format;
    foreach _shdoc ${*:-$(myname)}
}
$ shdoc
function shdoc_doc {
    : this is a shell doclib "shdoc" comment;
    : an shdoc comment is the first ":"-origin lines;
    : in the shell function, the rest being the executable.;
    : date: 2019-01-28 use local _shdoc and produce declare -f format;
}

A family of functions report_not…{condition}… is made available in The Standard Function Library

report_notargcount 1 $# "function name to trace where called" && return 1;
report_notcalledby ${1}_init && return 1;
report_notcommand $1 && return 1;
report_notcurrentdirectory $start A $PWD && return 1;
report_notdirectory $1 && return 1;
report_notfile "${1:-No Such Library}" && return;
report_notfunction $1 && return 1;
report_notlib $1 && return 1;
report_notpipe && return 1;

• All the functions in the report_not collection return true when the not condition is satisfied.
• Notice that the syntax of report_notargcount requires an expected minimum argument count and allows a usage comment
• report_notfile accepts a default argument.
• report_notpipe requires no argument and tests for a pipe

$ declare -f report_{not{argcount,pipe},usage}
report_notargcount () 
{ 
    : date: 2018-02-16;
    [[ $2 -ge $1 ]] && return 1;
    report_usage need at least $1 arg/s: ${*:3}
}
report_notpipe () 
{ 
    : returns: TRUE when STDIN "ISN'T" a pipe;
    : ... FALSE if stdin is a pipe;
    : date: 2018-02-16;
    [[ -p /dev/stdin ]] && return 1;
    report_usage "ISN'T" reading a pipe
}
report_usage () 
{ 
    : writes: usage message of report_... caller FAILURE to STDERR;
    : date: 2018-03-30;
    echo USAGE $(myname 3): $* 1>&2
}

The practice documented here is all about developing bash shell functions. In my opinion, the use of functions in bash, while readily accessible, is under-appreciated, under-used. Pick one of these approaches to the material, based on your needs and interests.

Three definitions define sets of functions, distinguishing the need for the collection: the app, family, and library. The library is the most general, the app being the most specific. The relationship is discussed in The Standard Function Library.

Where these definitions appear in requrements documents, they assume a certain implementation, in particular the definition of a tag. Since the null-operator, a gift from the shell designers, uses the colon, it seems appropriate to use the colon as the distinguishing feature of a tag, .e.g.

date: 2020-02-20  this change ....

• app – a set of functions collected to serve a set of requirements
• canonical function – a function when formatted declare -f function_name
• entry point – in an app, a function called only from the command line,
• family – a set of functions sharing common stem, e.g. family_subfunction
• library – a set of functions with zero or more families
• local function – a function used only within another function
• null operator – a shell command beginning with a :
• semantic comment – a shell function which may not display its arguments, or display them on standard error
• shell script – a shell file, whose first line is a sh-bang: #! env bash
• shdoc – a function family which implements Shell Documentation, see the Standard Function Library
• source – a builtin shell command to source or load a function library
• standard function – a function which meets the requirements of The Function Standard
• standard library – a library meeting the requirements of The Library Standard
• subfunction – a member of a function family
• tag – a colon-terminated first argument to the null command

These local papers are housed in the author's section of his commonplace book, which references The Function Standard