A Function Practice

Table of Contents

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

1 A Function Practice

1.1 Introduction

Companion to The Function Standard, a Function Practice in the bash shell is outlined. The objective is to write concise, effective, and re-usable functions. Some principles are common to any software language environment, others particular to the bash shell.

The practice is used by the author. Examples from existing functions are shown.

1.2 Principles

  1. Use functions
  2. prefer the null operator (:) as a comment over the syntactic sharp (#).
  3. use the default idiom: ${var:-something}
  4. use the bash sequence idiom: {m..n}
  5. separate computation and data gathering from output
  6. factor common repeated processes from loops
  7. use the foreach function
  8. prefer awk over cut

1.3 Functions

1.3.1 Foreach

foreach () 
{ 
    : ~ command arg ...;
    : executes the COMMAND on successive ARGs;
    : date: 2017-05-12;
    : date: 2019-10-28 QUOTE the ARG;
    report_notargcount 1 $# command ... && return 1;
    for arg in "${@:2}";
    do
        $1 "$arg";
    done
}

1.4 Discussion

The alternative formats are discussed to provide reasons for specific choices.

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

    This external reddit sequence introduces the practice of factoring a script in to separately testable components.

Author: Marty McGowan

Created: 2020-01-27 Mon 15:06

Validate