These function libraries implement the SHELF DRAFT Standard, and provide tools supporting shell functions and library development.
Not required in the SHELF Draft, these libraries add PUBLIC and PRIVATE status to local functions. The PUBLIC functions are collected in their respective public libraries. The SHELF Draft recognizes a library may contain more than one family.
Directories here each have a mklib
, a library of local bash shell
functions. The product of each mk is a public library of one or
more function families.
- the SHELF Draft Standard: https://github.com/applemcg/shelf/blob/master/shelf.org
- the make utility: https://en.wikipedia.org/wiki/Make_(software)
- on Smart Names: https://github.com/applemcg/bash/blob/master/smpub/smartnames.org
- library Development: https://github.com/applemcg/bash/blob/master/smpub/librarydevelopment.org
From the latest addition I learned the template for a source document:
- /{github-user-url}/{REPO}/blob/master/{subdir/filename}
This REPO builds PUBLIC libraries to support the SHELF, and provides development tools to identify PUBLIC and PRIVATE functions.
A part of the SHELF, a family named fam supplies functions to define and use the family features. While the SHELF doesn’t specify a PUBLIC - PRIVATE distinction, it’s family feature provides the means to distinguish and identify PUBLIC and PRIVATE functions.
The Smart-Public facility supplies the naming conventions to collect the function types and install the PUBLIC functions in their public library. At the moment, the libraries are function-specific, and the need will arise to install other run-time components: awk scripts, shell scripts, compiled programs and binary libraries, etc.
The Smart-Public folder smpub, supplies the tools to name the PUBLIC and PRIVATE function lists, to name the PUBLIC_LIBRARY, and the conventional run-time directories. It’s libraries:
publib
– the public family, the function public_public lists it’s PUBLIC functionssmartlib
– the smart family, has general-purpose functions define, add, and delete names from a list. An insight, thesmart_function
allows run-time code to ignore otherwise PRIVATE functions.mgmtlib
– the libmg family, manages library construction. It’s centerpiece,public_update
updates a family’s changed _public functions in the current PUBLIC_LIBRARYmklib
– composed of purely local, or PRIVATE functions supplies make tools for the shell, without the burden of using the stand-alone make utility. This could become a PUBLIC library when it’s sufficiently general-purpose. For the time being, each of the public libraries will be built by their own mklib.
- The library is reconstructed by this command where
functions
returns the function names defined in the library.
declare -f $(functions shelflib) > newshelflib
- Since the
declare -f
bash built-in formats the functions, then sharp-comments are stripped. Two ways to work around the apparent liability are offered. - A library may have one or more functions named {something} _init.
For example, the
shelflib
may have a function namedshelf_init
- since the SHELF standard describes a family feature, a family of
functions in shelflib may have supporting functions are named
shelf_doc
,shelf_help
,shelf_manpp
, etc. - there is a function to define a family. it supplies default definitions for some supporting functions
This REPO also supplies features for library management. A source library identifies functions as PUBLIC or PRIVATE. A UTILITY function is a public function, not sharing the family name.
To facilitate testing, code best lives in a source (e.g. “src”) tree,
separate from the run-time. User commands update changed PUBLIC
functions in the public
library which is on the user’s PATH
variable.
Functions are updated in groups, and stamped with the date of update, a comment in the body.
A function returns the location of the PRIVATE directory, where the
family is maintained. Libraries in the _source
directory identify
the PUBLIC and PRIVATE functions.
{family}_source # e.g. public_source $ public_source /Users/applemcg/git/bash/smpub $
Functions destined for a PUBLIC library may come from different sources.
A most recent (January ‘18) development: in a source (non-runtime) tree, a library should not call its _init function. Why? In order to distinguish development from run-time behavior, at run-time the library needs self-initialization, in development it doesn’t. In development, the functions may be loaded into memory, and jointly tested without one library exposing it’s dependencies on another before testing.
This point is key to this mode of development. With the goal of minimizing co-dependent families, A has dependencies on B, and B on A, if either library is self-initialized, they may require the other’s initialization before theirs may complete.
In these instances, a mklib recognizes this requirement, offering concurrent loading separate from initialization.
Since the online world is not navigated by the shell alone, the other features in a runtime environment are planned for inclusion. Since these objects are usually complete files, they may be readily included later.
Support for a negotiation feature, “which public library does this family belong to”. For example based on the user’s job within a company:
- every shell user in organization wants these function families
- everyone in this department gets a particular family: development, operations, support, production
This should also permit re-arranging the family-library assignment with little effort.
A private library may contain multiple FAMILIES, collected to permit concurrent unit testing. The privilege should not be abused, by collecting too many families in a single private library
For example, there may be co-dependencies which offer difficult chicken-or-egg situations. The SHELF recognized this possibility, but left no direction on why or why not families share a library at the source level.