If you're wondering how to read these documents, consult the README.
A standard for writing bash shell functions is presented. Requirements are established for function presentation and syntax. A canonical form is established. Reserved behavior is identified; features are advanced for assertion checking, self-documentation and instrumentation. A naming convention is presented to identify related functions and to identify test functions.
Other papers make a collection: The Library Standard, to collect functions in a shell library, and The Standard Function Library, a standard library of standard functions supporting the preferable, and reserved behaviors. Other papers (see References, Documents) support these standards.
The requirements, reserved behavior and naming conventions are used by the author. Examples from existing functions are shown.
declare -f builtin:Standard functions:
: as a comment (implicit in the first requirement )A function meeting these requirements is a standard function
The latter two preferences are supported by functions and applications referenced in The Standard Function Library
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:
Since an arbitrary function, rendered in it's canonical form loses any sharp # comments, the null operator **:** is the required comment.
Semantic restrictions using the null operator exist and must be avoided
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
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 concept of a function family, a group of functions sharing a common initial stem, will require certain naming conventions. Independent of function families, some functions behavior may be sufficiently generic that no family name is appropriate. And some subfunction names may be quite general in service of the family that they may have requirements levied against them. A local function may be defined within a function. It's scope is available to the current shell until it is unset
The function practice document discusses these categories and introduces reserved names in these categories.
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:
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.
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 ....
declare -f function_name:#! env bashThese local papers are housed in the author's section of his commonplace book, which references The Function Standard. On your first visit here, start with README