The Standard Function

A function name is preferably lower case. Where the function contains an underscore, the word preceding the underscore is considered to define a family of functions. The word or words after the underscore identify a subfunction in the family. A single function, with no underscore, shares the family name, serves as the main function of the family. This raises the notion of entry points, functions called from the command line. These represent the user interface to the family of functions.

The standard function preferably makes assertion-checking statements about it's various arguments, returning distinct error conditions for assertion failures.

The list of conditions includes:

• minimum number of arguments
• those arguments expected to be a file
• those arguments expected to be a function
• those arguments expected to be an identifiable type of object
• any result of a test statement (specific file types, string pattern, …)

1. Since an arbitrary function, rendered in it's canonical form loses any sharp # comments, the null operator : is the required comment.
2. Semantic restrictions using the null operator exist and must be avoided
3. The null operator may be used to reserve information behaviors.

$ standard_function () { 
     # this comment does not survive the canonical format; 
     return; }
$ declare -f standard_function   # produces
standard_function () 
{ 
    return
}
...
$ standard_function ( ) { : this comment SURVIVEs the canonical format; return ; }
$ declare -f standard_function
standard_function () 
{ 
    : this comment SURVIVEs the canonical format;
    return
}
$ 

Reserved behavior identifies syntactic or meta-syntactic behavior reserved for information such as shdoc a Shell Documentation standard. A reserved behavior is introduced by a null-command tag.

A tag feature enables the function to hold meta-information

standard_function ()
{
    : {tag}: {information}
}

A companion, the Tag Manual is the user's guide to tags. A handful have a standard practice; many suggest further development.

standard_function ()
{
    : tag: a sample tag, such as;
    : date: 2019-12-24 -- last modified
    : ...
    ...
}

The functions comment, ignore, quietly alter the behavior of stdout, stderr to reflect their names, and are covered in The Standard Function Library

A function's first untagged null-comments are the shdoc for the function, a brief description of the function's behavior. The first of these is considered the function abstract.

standard_function ()
{
    : the shdoc of a standard function, this line is the function abstract:
    : and further lines describe explicit behavior.
    : tag: a sample tag, such as;
    : date: 2019-12-24 -- last modified
    : ...
    ...
}

Shell documentation is supported with the shdoc function (SHell DOCumentation). The function and function family are covered in The Standard Function Library

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.

In the body of a function, this is how a default argument is assigned:

standard_functions ()
{
    ...
    local var=${1:-defaultValue}
    ...
}

See The Standard Function Library for examples of use.

An alternate semantics is open for discussion. Rather than the current

report_not...condition... && return N

possibly a more familiar form might be:

assert_is...condition... || return N

An assert_is function would necessarily return the complementary status of the report_not function.

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