Shell Library-Function Standard – SHELF

This document is a draft for a Shell Library-Function Standard, a SHELF, for easy recall. As such it sets a practice for organizing shell functions into re-usable libraries. It introduces standards for a library, and for functions in the library. A library may contain one or more families, the organizing principal for functions.

A section of the standard suggests steps for verifying conformance.

In an attempt to keep the standard concise, here is the SHELF Rationale and Practice.

A library:

1. is named {something}lib, without a suffix. e.g. setpathlib
2. is 'source'd by the shell. e.g.

   source setpathlib  # or
   . setpathlib
   

   with the strong implication it is found on the PATH

3. when 'source'd leaves nothing on stdout
4. is not an application. It may have multiple functions used principally from the command line.
5. must have an _init function, conventionally named for its basename. e.g. setpathlib has a function setpath_init
6. must have no more than one directly executable statement, calling the initialization function, which certainly causes other execution.

   setpath_init 1>&2
   

   Here, the re-direction is to comply with the earlier requirement.

7. may have multiple families in the library, each of which may have its own _init function

A family is a group of functions sharing a common first component, before the first underscore in a name:

family_subfunction

is the name of a function in the named family.

This standard specifies certain required behavior for sub-functions:

• help – may write any useful instructions on stdout
• init – mandatory behavior calls om_iam to identify the family, and any other necessary features when the family library is sourced
• list – returns a list of the family function names.

A function included in a SHELF library:

1. has two or more characters in an alpha-numeric name, which matches the regular expression:

   [a-zA-Z][a-zA-Z0-9_]+
   

2. has a preference for a family group, e.g. {family}_{subfunction} such as setpath_init. (see the om, object and methods family of functions)
3. is formatted in the canonical format:

   declare -f fun_method
   

   since ordinary shell "#" comments are lost to this format, an alternate comment format is available (see the shdoc function).

4. should test any assertions capable of begin made on it's arguments (see the reporting functions). At the current moment, there are these two alternatives:

   assert_isfile $1 || return 1     # is the first arg a file?, OR
   report_notfile $1 && return 1    # the current practice
   

5. is encouraged to make liberal use of positional parameters, and the set facility. e.g. where a conventional use of file suffixes is at the heart of the process, rather than this:

   call_me  file.txt. file.out file.err
   

   use this instead:

   call_me file       # or
   call_me file.txt   # and therefore be defined as:
   ...
   call_me () {
      set ${1%.*}               # strip any suffix, or not!
      set $1.txt $1.out $1.err  # $1, $2, and $3 are as before.
   ...
   

6. should trace its entry:
   • after positional parameters are set, and
   • after assertion checking is complete.

   which may occur interchangeably. For example, a reliable first assertion is on the number of arguments:

   report_notargcount 1 $# No file or basename && return 1
   

   might be used as the first assertion in a function.

7. should limit control structures to one level. (see foreach in the collection of utilities).

A set of not-too-automated functions and procedures may be supplied here used to verify a library's conformance to this standard.

• the standard, online: http://mcgowans.org/marty3/commonplace/software/shelf.html
• my Commonplace Book
• the SHELF Rationale and Practice.

Search for:

• shdoc
• Javadoc
• Perldoc
• Pydoc

Email: mcgowan@alum.mit.edu

Twitter: @applemcg