Tag Manual
Table of Contents
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
- a tag is preserved in the canonical format
- 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.
- 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 Thoughts
- think in terms of a database table, though stay away from an implementation
- some tags are a single datum
- some, like `date` may have a string
- some, like `uses` may be multi-valued
- a few, like the opening implied `shdoc` are multi-lined
Therefore one table looks like
- name – the function name
- abstract – one-line synopsis
- libr – its home library
- date, early
- date, most recent
- uses – multi-valued functions, commands, system files
Another table looks like"
- name – the function
- seqn – line-number of multi-line shdoc
- shdoc – remainder of the opening comments.
A management table defines the types
- name – join attribute
- key – name, name.seqn
- mval – multi-valued
- pair – date, comment
1.5 References
1.5.1 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.2 Documents
These 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
- Standards Documents
- Function Standard, The - Requirements for a standard bash shell function
- Library Standard, The - Requirements for a standard function library
- Application Requirements
- Shdoc Requirements - Requirments for the SHDOC application
- Application Requirements - Requirments for the APP builder application
- 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
- External References
- Sh-bang - standard starting line of the script file