The Library Standard

Table of Contents

If you're wondering how to read these documents, see the discussion in the References, under Where To Start.

1 The Library Standard

1.1 Introduction

A standard for collecting bash shell functions into a standard library is advanced. Requirements are established for collected function_names and function side effects in sourcing the library,

A naming convention is presented to identify related functions and to identify test functions.

1.2 Requirements

Standard libraries.

  1. are files, named with the last three characters lib, e.g. standardlib
  2. contain functions from zero or more function families
  3. whose functions shall adhere to the requirements of The Function Standard
  4. when sourced, shall not write on the stdout
  5. when sourced, have made provision to execute any {family}_init functions defined in the files.
  6. a {family}_init function shall test for and call an existing {family}_user function.

A function library meeting these requirements is a standard library

Functions to support these requirements are supplied in The Standard Function Library

1.3 Naming Conventions

1.3.1 {family}_user

An optionally supplied {family}_user function may override any feature or behavior of the {family}_init function. The {family}_user function needn't be supplied, and probably shouldn't be in the same library as the rest of the family's functions. Documentation for the {family}_init function must clearly state the conditions for using the {family}_user function. An example is given in Reserved Subfunctions of The Standard Function Library.

1.3.2 {family}_init

All initialization functions are named {family}_init. Similar to the _init sub-function, a family may use others names which categorize behavior similar to all libraries, such as list, help, doc, ….

The function practice document discusses these categories and introduces reserved names in these categories.

  1. family names
  2. general utility functions
  3. common subfunction names
  4. local functions, internal to other functions with conventional semantics.

1.4 Initialization

A library is "source"d to include its functions in the current shell environment. Any of the library's functions may be executed from the command line. 

$ source standardlib    # or . standardlib

Since a standard library may have many families, fama, famb, ... and any of these may require initialization, provision must be made, when the library is sourced, to execute any {family}_init

1.5 References

1.5.1 Where to Start

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.

  1. Formal Approach

    If you are interested in a more formal approach, choose this reading sequence:

    The Tag Manual discusses uses of a new feature introduced here, the null-command comment. The tag was introduced mostly to provide the shdoc feature, internal documentation, motivated by traditional languages, javadoc, pydoc, …

  2. Shell Programmer

    If you have some shell programming experience, choose this order:

  3. Gaining Experience

    While the material here is not for the beginning shell programmer, the author recommends his e-book Shell Functions, which has a link to a series of YouTube videos on the method. Visiting the videos, you will find a host of other introductions to the shell.

1.5.2 Definitions

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

1.5.3 Documents

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

  1. Standards Documents
  2. Application Requirements
  3. Practice Documents
    • Standard Function Library – A Standard Function Library adhering to the Function and Library Standards, implementing functions which support the preferred behaviors
    • Tag Manual – tag semantics, defining other tags, it's open-ended.
    • Function Practice, A – Applying the lessons of the Standard Function Library
  4. External References
    • Sh-bang – standard starting line of the script file

Author: Marty McGowan

Created: 2020-01-27 Mon 15:03

Validate