Tag Manual

Table of Contents

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

1 The Tag Manual

1.1 Introduction

A standard for defining and using the null-operator tag is provided. Requirements are established for defining a tag and its scope within the function.

A small set of now well-used tags are presented as given, and their semantics an use are described.

The first null-operator commands in a function are presented as the first line of a shdoc function, where it's first line is treated as a one-line summary of the function

1.2 Requirements

  1. a tag is preserved in the canonical format
  2. shall use alpha-numeric names of three or more characters where, in the function name, leading underscore is only permitted in the scope of another function.
  3. shall use the null operator : as a comment

The latter two preferences are supported by functions and applications referenced in the

1.3 Known Null-Command limitations

1.4 References

1.4.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.4.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.4.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:05

Validate