Shellapi

The co-related functionalities are grouped into modules , i.e separate, independent bash source files. The list of functions are gathered at the end of the document.

The module shell-api-yaml.sh contains a mix of 2 APIs:

The inhouse YAML API is mainly achieved by calling YAML__setFile "yourfilepath" true and then invoking YAML__get "youryamlkey" yourvariable

The following section documents some few typical framework features supplied by the library. There’s also an API documentation. However, some parts of it are still lacking.

As complement, it might be useful to check actual implementations relying on it, for example, the tools sumo, arc and shotplan, which are readable bash scripts.

An app generated with Genapp app skeketon generator enables an instant step-in as follows:

Single dash '-' are for any one-letter option, with an optional value

Double dashes -- are for multi-letter option names, optionally followed by '=' and a value

Dashless value can also be used, typically for commands

A module is loaded (sourced) using the following syntax, e.g. here loading module shell-api-dev.sh:

eval $_loadm<<<'shell-api-dev.sh'

Basically it "sources" the script into the current one, additionally:

Any other source script part of the app project, i.e. located below the source directory, can be loaded (sourced) using the following syntax, e.g. here the loading of source file arcv__vars.sh of the sumo project can be loaded as follows:

eval $_loada<<<'arcv__vars.sh'

This is the equivalent of the following which is less convenient to use:

source "${ARCV__VARS["MYDIR"]}/arcv__vars.sh"

By default, a configuration file is at the app’s disposal, located in the .config folder of the user’s home directory (letter case is relevant):

$HOME/.config/<Appname>/<appname>.yml

If this file does not exist, a default one is created from the default configuration file generated along with the app (.yml extension) upon first launch.

At startup, the library automatically loads the configuration data and stores it in the bash map named <APPNAME>__VARS[].

The bash map key is the uppercased YAML key where spaces are replaced with underscores. The following examples shows how the read data are mapped:

The configuration line will result in the execution of the following during app initialization:

A basic logging API is available. The generated logs are plain text and the log file is located in the .local folder of the user’s home directory (letter case is relevant):

$HOME/.local/<appname>/log.txt

At the moment, it will be endless growing and survive over successive runs.

Logging levels

There are 4 types of messages which are highlighted with different colors when also displayed on the terminal:

If the app which is developped from the generated skeleton requires additional system packages, those can be programmed to be installed automatically on-the-fly, anywhere where required in the source code, by using the built-in _loadDep function.

The prerequisite is that the app implements the callback […​]__loadDep(). An app generated with Genapp app skeketon generator contains by default the following callback, which attempts to load the package via APT:

Other package types can be installed, see the following sample code:

By default, the libray catches the system signals and invokes the user-defined […​]__cleanup() callback, if any, passing on the caught exit code as argument.

Temporary files or folders created with File__createTempFile and File__createTempDir can be automatically cleaned up at application exit by calling File__deleteAllTempItems.

XSLT__transformToText and XSLT__modifyXML eases XSLT transformation with xsltproc :

So that the developer can only focus on the core transformation rules;

A symbolic link to the shell api library from which Genapp app skeketon generator was executed will be set up inside the generated app. The user is then free to manage the link, e.g. by changing it to another installed version.

The generated Makefile enables to manage the dependency transparently as follows:

For this reason, it is recommended to use installation via Debian packages, since the dependencies will be managed consistently across different versions of shell api.

By default, a configuration file is at the app’s disposal as described in the shell-api documentation. Here, for the sample 'TestApp' app generated in Example, the configuration file is:

.config/TestApp/testapp.yml

The configuration management of the original software was originally managed on a non-disclosed server with arcv. The original revision log of arcv can be tracked on this page: Full revision log page.

Since version 1.1.2, the full original source code is available on GitHub under LGPL license. Therefore, it will be used as the main source reference for the public version.

Release history: https://slashetc.fr/en/developertoolsforlinux/shellapi/#_release_history

The clean release packages and the release source code files are available on GitHub at https://github.com/michelm33/shell-api

Reported bugs are tracked via the GitHub page https://github.com/michelm33/shell-api

There’s a bunch of unit tests available in the 'self-test' module. However, many of them were one-shot runs commented out afterwards.

In the long run, the tests should ideally be organized in an automated test hardness, which is run prior to any release.

The API is deemed to be somehow instrinsically tested through the various tools using it extensively for their running, and indireclty via their own automated tests.