GitHub - fkemser/SHtemplate: A template repository for POSIX-/Bourne-Shell(sh) projects.

SHtemplate

A template repository for POSIX-/Bourne-Shell(sh) projects.
Explore the docs »

View Demo · Report Bug · Request Feature

Table of Contents

About The Project
- Built With
- Testing Environment
Getting Started
Template Structure
/src/lang/run.<...>.lang.sh (Repository String Constants Files)
/src/run.sh (Repository Run File)
Adding support for other languages
Further Code Samples
Usage (/src/run.sh) (Example)
Roadmap
Contributing
License
Contact
Acknowledgments

About The Project

This is a (mostly) POSIX-/Bourne-Shell(sh)-compliant repository template that provides boilerplates for

checking requirements, e.g. commands, (running) services, superuser rights, etc.
checking and parsing arguments
generating well-formatted help (-h|--help) messages
interactive (dialog-based) menus
multi-language support in terminal and/or dialog messages where the system's current language is automatically detected
defining trap handlers, e.g. for cleanup operations on exit
PID based locking ensuring that only one instance runs at a time
daemon mode (with sample code for parallel file processing)

(back to top)

Built With

(back to top)

Testing Environment

The project has been developed and tested on the following system:

Info	Description
OS	Debian GNU/Linux 12 (bookworm)
Kernel	5.15.133.1-microsoft-standard-WSL2
Packages	coreutils (9.1-1)
	dash (0.5.12-2)
	dialog (1.3-20230209-1)
	libc-bin (2.36-9+deb12u3)

(back to top)

Getting Started

Prerequisites

Please make sure that the following dependencies are installed:

a POSIX-compatible shell, e.g. Debian Almquist Shell (dash), and
Dialog, a tool to provide interactive dialogue boxes within terminals.

Below you can find distribution-specific installation instructions.

Alpine Linux

sudo apk add coreutils dialog

Debian

sudo apt install coreutils dash dialog libc-bin

(back to top)

Installation

Clone the repo

git clone --recurse-submodules https://github.com/fkemser/SHtemplate.git

Open the repository with your favourite code editor. Search and replace the following placeholders (including <>) in all files:

❗ The placeholders highlighted in bold are mandatory and must not be empty.

<...>	Description	Example
<ABOUT_AUTHORS>	Author name and mail address (multiple authors separated by newline)	John Doe (john.doe@example.com) Jane Doe (jane.doe@example.com)
<ABOUT_DESCRIPTION>	One-line description of what the project is about. Please start with a low letter and leave the terminating '.' out.	a script based on `SHtemplate` used to ...
<ABOUT_INSTITUTION>	Institution (multiple lines allowed)	Example Inc. 123 Main Street Anytown, CA 12345 USA
<ABOUT_LICENSE>	Project license (SPDX-License-Identifier) ¹	GPL-3.0-or-later
<ABOUT_LOGO>	ASCII logo to display when running the script in interactive (`dialog`) mode	-
<ABOUT_PROJECT>	Project/Repository title	My Project
<ABOUT_VERSION>	Release/Version number	1.0.0
<ABOUT_YEARS>	Project year(s)	2023-2024

The following folders and files are only used by this README and can be safely deleted:
```
cd ./SHtemplate
rm -r res
rm README.md
```

(back to top)

Customization

Before you continue to customize the template it is recommended to ask yourself the following questions:

What are the main goals of my script?
How shall this script be run? As a (normal) script, interactively, (infinitely) as a daemon, or mixedly?
Which parameters do I need, which arguments are allowed?
Which commands/packages have to be installed before?
Are there any other requirements?
Should there be any special handling on exit and/or interrupt, e.g. cleanup procedures?

(back to top)

Template Structure

Overview

The template is separated into multiple files where each file does a different job.

/	/	/	Description
etc
	`run.cfg.sh`		Configuration File (`/src/run.sh`)
	`<...>.cfg.sh`		Further Configuration Files
lib
	SHlib		Shell Library (submodule)
	SHtemplateLIB		SHtemplate Library (submodule)
	`...`		Further libraries / library subdirectories
src
	lang
		`run.0.lang.sh`	Language-Independent String Constants File (`/src/run.sh`)
		`run.<ll>.lang.sh`	Language-Specific String Constants Files (`/src/run.sh`)
		`<...>.lang.sh`	Further String Constants Files
	`init.sh`		Repository Initialization Script
	`run.sh`		Repository Run File
test	`...`		Test folder, only used for Daemon Mode Sample

(back to top)

`/etc/run.cfg.sh`

Use this file to introduce constants and variables that the user can set before(!) running run.sh. To better structure your code you can define multiple configuration files. To do so, please make sure that all files

have the file extension .cfg.sh and
are stored within /etc/.

(back to overview)

`/lib/...`

This is the place to add further shell libraries. By default SHlib (/lib/SHlib) and SHtemplateLIB (/lib/SHtemplateLIB) are already included.

❗ Please do not delete /lib/SHlib and /lib/SHtemplateLIB as the template relies on them.

To add your own library files please make sure that they

have the file extension .lib.sh and

are stored within one of the following paths:

/lib/<filename>.lib.sh
/lib/<subdir>/<filename>.lib.sh
/lib/<subdir>/lib/<filename>.lib.sh

In case you would like to add an existing repository just change into the template's root directory and add it as a submodule, e.g.

cd <rootdir>
git submodule add https://github.com/fkemser/SHlib lib/SHlib

(back to overview)

`/src/init.sh`

This file is loaded by /src/run.sh to initialize the repository, e.g. by setting file/folder structure, loading libraries, etc. Use this file to publish additional file/folder paths (constants) within your repository.

(back to overview)

`/src/lang/run.<...>.lang.sh` (Repository String Constants Files)

Use these files to store string constants for help messages, command outputs, interactive menus, etc. Afterwards you can reference them in /src/run.sh by using their constant identifiers.

For better code readability and maintenance the constants are distributed over multiple files: run.0.lang.sh for language-independent constants and run.<ll>.lang.sh for language-specific constants where <ll> in the filename is the language's ISO 639-1 ID in lowercase letters, e.g. run.en.lang.sh contains all English strings, run.de.lang.sh all German strings, etc.

⚠️ Regarding the constant identifiers: Please follow the naming convention below, otherwise certain features, e.g. the semi-automatic creation of the script's help, will not work correctly.

Used in interactive (`dialog`) menus

For more information please run dialog --help or man dialog.

Constant	Example (identifier)	Description	Parameter (`dialog`)
L_`<S>`_`<LL>`_DLG_ITM_`<REF>`	L_RUN_EN_DLG_ITM_ARG_ITEM_ITEM1	List item	(item1)...
L_`<S>`_`<LL>`_DLG_TTL_`<REF>`	L_RUN_EN_DLG_TTL_ARG_ITEM	Title	[--title (title)]
L_`<S>`_`<LL>`_DLG_TXT_`<REF>`	L_RUN_EN_DLG_TXT_ARG_ITEM	Text	(text)

Used in `help()`, parameter section (`SYNOPSIS`)

Constant	Example (identifier)	Example (value)	Description
L_`<S>`_`<LL>`_HLP_DES_`<REF>`	L_RUN_EN_HLP_DES_ARG_INT	Help (arg_int)	Parameter description
L_`<S>`_HLP_PAR_`<REF>`	L_RUN_HLP_PAR_ARG_INT	-i\|--int (int)	Parameter cmd switch
L_`<S>`_`<LL>`_HLP_REF_`<REF>`	L_RUN_EN_HLP_REF_ARG_INT	Use '-i\|--int (int)' to specify <arg_int>'s value.	Reference description

Used in `help()`, other sections

Constant	Description	Example (identifier)	Example (value)
L_`<S>`_`<LL>`_HLP_TTL_EXAMPLES_`<I>`	Example (Title)	L_RUN_EN_HLP_TTL_EXAMPLES_1	Show Help
L_`<S>`_`<LL>`_HLP_TXT_EXAMPLES_`<I>`	Example (Text)	L_RUN_EN_HLP_TXT_EXAMPLES_1	./run.sh --help
L_`<S>`_`<LL>`_HLP_TXT_NOTES_`<I>`	Note (Text)	L_RUN_EN_HLP_TXT_NOTES_1	This is the first note.
L_`<S>`_HLP_TXT_REFERENCES_`<I>`	Reference	L_RUN_HLP_TXT_REFERENCES_1	https://www.example.com
L_`<S>`_`<LL>`_HLP_TTL_REQUIREMENTS_`<I>`	Requirements (Title)	L_RUN_EN_HLP_TTL_REQUIREMENTS_1	General
L_`<S>`_`<LL>`_HLP_TXT_REQUIREMENTS_`<I>`	Requirements (Text)	L_RUN_EN_HLP_TXT_REQUIREMENTS_1	To run this ...
L_`<S>`_`<LL>`_HLP_TTL_TLDR_`<I>`	TL;DR (Title)	L_RUN_EN_HLP_TTL_TLDR_1	Requirements
L_`<S>`_`<LL>`_HLP_TXT_TLDR_`<I>`	TL;DR (Text)	L_RUN_EN_HLP_TXT_TLDR_1	Please install ...

Used in terminal output (`stdout`/`stderr`)

Constant	Description	Example (identifier)	Example (value)
L_`<S>`_`<LL>`_TXT_`<T>`	Custom language-specific text constants	L_RUN_TXT_TEXT1_EN	Text 1 (English)

Placeholders

<...>	Description	Example(s)
`<I>`	Index, starting from 1	1
`<LL>`	Language ID (ISO 639-1)	EN
`<REF>`	Function, parameter, or parameter (list) value this constant refers to	HELP, ARG_ACTION, ARG_ACTION_HELP
`<S>`	Reverse script (file) name without '.sh'	RUN
`<T>`	Identifier that describes what the string is about	ERR_NOT_FOUND

Further String Constants Files (/src/lang/*.lang.sh)

To better structure your code you can define multiple string constant files. To do so, please make sure that all files

have the file extension .lang.sh and
are stored within /src/lang/.

(back to overview)

`/src/run.sh` (Repository Run File)

⚠️ The following sections only give a brief overview. Before running any of these functions please have a look at the comments in the source files.

This is the repository's run file so this is the right place to add your code. A good way to start is to search for the TODO: sections within the source code. They will guide you through the template and tell you where to add which part of your code.

The template's design principle is based on so called modes and actions.

Modes

A mode defines how the script is executed. The template supports four different modes:

Mode	Description
daemon	Infinite (background/daemon) mode
interactive	Interactive mode using `dialog`
script	Classic script mode
submenu	Like `interactive` but with the intention to run one certain submenu and then exit. Usually used by other scripts to skip the welcome dialogue and the main menu.

ℹ️ Your script does not have to support all modes.

(back to overview)

Actions

An action consists of one or multiple commands that the user can trigger when calling the script. The template is shipped with three essential and six sample actions:

Action	Description
about	Print dialogue with information about your repository (authors, license, etc.). Only used in interactive mode.
help	Show the script's help.
exit	Exit script. Only used in interactive mode.
custom1 ... custom6	Sample actions 1 - 6

⚠️ You can replace or delete the sample actions but not the essential ones.

(back to overview)

Constants

To provide certain features, e.g. the semi-automatic creation of help(), the script relies on certain constants, variables, and functions:

Constant	Description
`ARG_ACTION_LIST_INTERACTIVE` / `ARG_ACTION_LIST_SCRIPT`	Lists of allowed actions `ARG_ACTION_...` in interactive, submenu, and script mode. Used for auto-generating help's `SYNOPSIS` section and the main menu in interactive/submenu mode.
`ID_LANG`	Current language ID (ISO 639-1), see `init_lang()`.
`INSTANCES`	Instance counter. Used to check if this script was called recursively.
`LIST_ARG`	Lists of compatible parameters (script mode only). Used for auto-generating help's `SYNOPSIS` section.
`LIST_ARG_CLEANUP_INTERACTIVE`	List of arguments that have to be cleared or reset to their default values after running `run()` function (interactive mode only).
`PIDLOCK_ENABLED`	Enable PID based locking? (`true\|false`) ⚠️ If enabled (true) the script requires superuser privileges. ⚠️
`T_DAEMON_SLEEP`	Daemon mode sleep interval (in s), see Daemon Mode Sample.

⚠️ Please edit the constants highlighted in bold to adapt the script's behaviour and appearance to your code.

(back to overview)

Variables

Variable	Description
`arg_action`	Current script action, see Actions
`arg_logdest`	Log destination (terminal, `syslog`, both), see msg()
`arg_mode`	Current script operation mode, see Modes
`trap_blocked`	Prevent trap execution? (`true\|false`) Can be used to temporarily disable trap handling.
`trap_triggered`	`trap_...()` function was called? (`true\|false`) Used to decide if trap handling has to be (manually) launched after temporarily disabling it.

❗ Please do not delete or change any of the variables as the template heavily relies on them.

(back to overview)

Functions

Function	Description / Task
`args_check()`	Check if passed arguments are valid
`args_read()`	Read/Parse arguments
`error()`	See `msg()`
`help()`	Print help message using `less` utility
`help_synopsis()`	Create help's `SYNOPSIS` section
`info()`	See `msg()`
`init_check_pre()`	Check script requirements before argument parsing
`init_check_post()`	Check script requirements after argument parsing
`init_first()`	Set default log destination, (optionally) lock the script (PID file), install trap handler and run other commands that need to be executed right at the beginning.
`init_lang()`	Set language-specific text constants
`init_update()`	Update global variables/constants and perform initialization commands that should be executed after argument parsing
`main()`	Main function
`main_daemon()`	Main subfunction (daemon mode)
`main_interactive()`	Main subfunction (interactive / submenu mode)
`main_script()`	Main subfunction (script mode)
`menu_main()`	Main menu (interactive mode)
`msg()`	Log/Print error/info/warning message and optionally exit
`run()`	Perform one certain action (cycle)
`trap_main()`	Trap (cleanup and exit) function for this script
`warning()`	See `msg()`

❗ All functions are essential and must not be deleted. However, you should edit them within the TODO: sections to adapt the script to your needs.

(back to overview)

`args_check()`

Use this function to check if passed arguments are valid. You will already find some sample checks, e.g.

file/folder checks,
data type checks,
regex checks,
value range checks.

ℹ️ For more checks please have a look at the functions lib_core_is() and lib_core_regex() in lib/SHlib/lib/core.lib.sh

(back to overview)

`args_read()`

Edit this function to add your individual command line parameters (switches). Please do also not forget to

also add them to /src/lang/run.0.lang.sh,
write your help (SYNOPSIS) texts in /src/lang/run.<ll>.lang.sh,
add them to help_synopsis(), and
add the parameters' identifiers (names) to the template's constants (ARG_ACTION_LIST_INTERACTIVE, ARG_ACTION_LIST_SCRIPT, LIST_ARG, LIST_ARG_CLEANUP_INTERACTIVE), if relevant.

(back to overview)

`help()`

This function prints the help message by using the less utility. By default the help consists of the following sections:

Section	Description
TL;DR	Quick start section
REQUIREMENT	Software and/or hardware requirements
SYNOPSIS	Usage instructions (command line switches, additional arguments, etc.)
EXAMPLES	Command examples
NOTES	Notes that are referenced within other help sections
REFERENCES	References, e.g. URLs
ABOUT	Repository-related information (author, institution, license, etc.)

⚠️ Please do not hardcode any help texts within this function. Instead, edit /src/lang/run.<...>.lang.sh to define (write) your help texts and edit help_synopsis() to modify the SYNOPSIS section of your help.

ℹ️ For a full example just have a look at the Usage section below.

(back to overview)

`help_synopsis()`

This is the function that generates the SYNOPSIS (usage) section of the script's help (-h|--help). Edit this function to "publish" your help texts that you have previously created in /src/lang/run.<...>.lang.sh.

ℹ️ The introduction containing the available actions ACTION := { ... } and options OPTION := { ... } is automatically created. This can be controlled via the constants ARG_ACTION_LIST_SCRIPT and LIST_ARG, see Constants section above.

(back to overview)

`init_check_pre()`

Edit this function to perform mandatory and/or optional requirement checks before(!) argument parsing, e.g.

available commands,
running services,
superuser rights.

(back to overview)

`init_check_post()`

Edit this function to perform mandatory and/or optional requirement checks after(!) argument parsing.

(back to overview)

`init_first()`

As the name already states this is the first function (within main()) that is executed directly after loading the initialization script /src/init.sh and running init_lang(). It is responsible for setting the right log destination: In case the script is running within a terminal window, the script outputs all messages to stdout/stderr by default. Otherwise the script uses syslog (logger) for logging.

Furthermore this function installs a trap handler that calls trap_main() allowing the script to safely exit, even on interrupts.

Edit this function in case you would like to

modify the trap handler (signals, arguments) for trap_main(),
add further initialization commands

(back to overview)

`init_lang()`

This function detects your system's default language and stores its ISO 639-1 ID in ID_LANG. This constant is used to generate language-dependent terminal, log, and dialog messages.

Edit this function in case you

would like to add support for other languages, or
have text strings for custom terminal/log messages.

⚠️ Before editing this function please make sure that this template already supports your language and that all language-specific texts (constants) have been defined in /src/lang/run.<ll>.lang.sh.

(back to overview)

`init_update()`

Edit this function to set constants/variables and run commands after(!) all arguments have been parsed and checked.

(back to overview)

`main()`

This is the script's entry point so it is the first function to be called. In most cases there is no need to edit this function. Instead, edit the mode-specific main functions main_...() right below.

(back to overview)

`main_daemon()`

This the script's entry point for running in daemon mode.

ℹ️ This function is shipped with some sample code to demonstrate the daemon mode. See also here.

(back to overview)

`main_interactive()`

This the script's entry point for running in interactive or submenu mode.

(back to overview)

`main_script()`

This the script's entry point for running in (classic) script mode.

(back to overview)

`menu_main()`

This function controls the program flow for interactive and submenu mode. Edit this function, e.g. to define which dialog menus appear for which actions.

(back to overview)

`msg()`

This function is responsible for generating terminal and syslog messages. It automatically detects the log destination depending on the user's manual setting (--log <dest>) and the current environment (interactive terminal, cron, etc.). The functions error(), info(), and warning() are wrapper functions to generate error/info/warning messages. In most cases there is no need to edit this function but you can call it (or its wrappers) from your own functions to generate terminal/syslog messages.

(back to overview)

`run()`

This is the central function for all modes but daemon mode: Here you define all commands that should be executed depending on the action and other parameters that the user has previously set, no matter if via command line arguments or interactively.

(back to overview)

`trap_main()`

This is the script's main trap function and is (by default) executed on exit or when the script is interrupted. Edit this function to define your individual trap handling routine.

ℹ️ To define the signals on which trap_main() should be triggered please have a look at init_first().

ℹ️ You can also disable trap handling temporarily, e.g. when running some code that should not be interrupted. See section Further Code Samples.

(back to overview)

Additional Sample Code

Besides the basic template, /src/run.sh is also shipped with some sample actions, parameters, and functions. They do not serve any specific purpose but are just for showing you the possibilities of the script. In contrast to the basic template you can safely delete or replace the parts described below.

(back to top)

Sample Parameters and Constants

Parameter / Constant	Description
`arg_arg_or_stdin`	Sample parameter that either takes an argument or, if not set, `stdin`'s content
`arg_bool`	Sample boolean parameter
`arg_dir`	Sample directory parameter
`arg_file`	Sample file parameter
`arg_int`	Sample integer parameter with a range of allowed values
`arg_item`	Sample list item parameter
`arg_password`	Sample password parameter
`arg_str`	Sample string parameter
`EXT_TEST`	Test file extension for sample daemon, see also Daemon Mode Sample

(back to top)

Sample Actions

There are six sample actions (custom1...custom6). Each action behaves differently in the sense of how (in which mode) it can be run and which parameters it requires or accepts.

The matrix below shows which action can be run in which mode ...

arg_action	interactive	script	submenu
custom1	-	x	-
custom2	x	x	x
custom3	x	x	x
custom4	x	x	x
custom5	x	x	x
custom6	-	-	x

ℹ️ The daemon mode is not listed here as it has its own function func1(), see also Daemon Mode Sample.

... where the second matrix shows which of the actions require which parameter(s):

arg_action	arg_arg_or_stdin	arg_bool	arg_dir	arg_file	arg_int	arg_item	arg_password	arg_str
custom1	-	-	-	-	-	-	-	-
custom2	-	o	-	-	-	o	-	-
custom3	-	-	x	-	-	-	-	-
custom4	-	-	-	-	x	-	-	x
custom5	(x)	-	-	(x)	-	-	-	-
custom6	-	-	-	-	-	-	-	-

...	Meaning
-	not relevant
o	optional (in script mode they can be passed via their command line switches, in interactive (and submenu) mode there is a dialog that can be skipped)
x	mandatory
(x)	mandatory but either ... or ...

(back to top)

Sample Functions

Function	Description
`func1()`	Sample function that can be run either in script mode or daemon mode
`menu_arg_...()`	`dialog` menus for setting sample parameters in interactive and submenu mode
`trap_func1()`	Trap (cleanup and exit) function for `func1()` (daemon mode only)

(back to top)

`func1()`

This is an example on how to write functions that can run in both, script mode and daemon mode. As a sample function it does not fulfill a certain purpose. It simply processes a given file by printing its name and a message, either to the terminal (script mode) or to syslog (daemon mode).

(back to top)

`menu_arg_...()`

These functions provide the interactive dialog-based menus for setting the sample parameters listed above, e.g. menu_arg_bool() is the menu for setting arg_bool.

(back to top)

`trap_func1()`

This is func1() 's special trap function and is only used if the script is running in daemon mode. Edit this function to define your individual trap handling routine for func1() when running the script in daemon mode.

(back to top)

Daemon Mode Sample

In daemon mode main_daemon() runs func1() not only for a single file but over all files with a pre-defined extension (EXT_TEST) within a pre-defined folder (arg_dir). This is done parallelly, meaning that there are running multiple instances of func1(), one per file, running in a subshell.

To allow the subshells to terminate safely on signals, e.g. SIGTERM, func1() installs trap_func1() as a trap handler within the subshell.

To let the daemon mode run infinitely there are two loops: One within func1() (within each subshell) and a second one in main_daemon() (within the calling script). The latter is just a backup: In case a subshell crashes, it gets "respawned" within a maximum period of time that can be defined via the constant T_DAEMON_SLEEP.

(back to top)

Adding support for other languages

To add support for other languages please follow these steps:

First check whether SHtemplateLIB, the template's own library, supports your language. If not, please follow the translation instructions there before continuing.
Create your project/repository-specific translation file /src/lang/run.<ll>.lang.sh where <ll> in the filename is the language's ISO 639-1 ID in lowercase letters, e.g. create run.es.lang.sh to store Spanish strings.
To finally enable support for the new language: Open /src/run.sh and look for the init_lang() function. Add your language's ISO 639-1 ID within the TODO: section, e.g. to support Spanish (ES), simply add:

case "${ID_LANG}" in
  ...
  ${LIB_C_ID_LANG_ES}) readonly ID_LANG="${LIB_C_ID_L_ES}";;
  ...
esac

(back to top)

Further Code Samples

There are some code snippets that did not fit into the template but yet they are worth to be mentioned.

Run a certain command (`<cmd>`) and in case of any error do not only log a pre-defined error message (`<msg>`) but also the command's previous output (`<result>`)

exec 3>&1
  result="$(<cmd> 2>&1 1>&3; exit $?)" # TODO: Replace <cmd> by your own value.
  exitcode="$?"
exec 3>&-
if [ ${exitcode} -ne 0 ]; then
  # ...                             # TODO: Put your error handling here.
  msg="<msg>"                       # TODO: Replace <msg> by your own value.
  error "${msg}" "${result}"
fi

Temporarily disable trap handling

trap_blocked="true"   # Disable trap handling
# ...
# TODO: Put commands here that should not(!) be interrupted
# ...
trap_blocked="false"  # Re-enable trap handling

# Run trap handling (manually) if trap was previously triggered
if ${trap_triggered}; then
  if ${is_subshell}; then trap_func1; else trap_main; fi
fi

Check whether the script was called recursively

if eval [ \${${INSTANCES}} -gt 1 ]; then echo "Script recursively called"; fi

(back to top)

Usage (/src/run.sh) (Example)

================================================================================
==============================     SHtemplate     ==============================
=======================     (Press 'q' to quit ...)     ========================
================================================================================

A template repository for Bourne-Shell (sh) projects.

================================================================================
================================     TL;DR     =================================
================================================================================

_________________________________ Requirements _________________________________

To install the necessary packages on your system, simply run:

Debian
> sudo apt install dialog (...)

(...further requirements...)

The script has been developed and tested on the following system:

OS:         ... (Run 'cat /etc/*release')
Kernel:     ... (Run 'uname -r')
Packages:   Dialog (...), (...)

___________________________________ Synopsis ___________________________________

There are multiple ways to run this script. For more information please have a look at <SYNOPSIS> section below.

Interactive mode (without any args):
> ./run.sh

Classic (script) mode:
> ./run.sh [ OPTION ]... ACTION [<file>]

================================================================================
=============================     REQUIREMENTS     =============================
================================================================================

___________________________________ General ____________________________________

Required Packages:
  General: (...)
  Debian:  > sudo apt install (...)

Optional Packages:
  General: (...)
  Debian:  > sudo apt install (...)

(...)

_________________________ Interactive Mode (optional) __________________________

In case you run this script interactively (see <SYNOPSIS> below)
your terminal window must have a size of <100x30> or bigger.

Required Packages:
  General: Dialog
   Debian: > sudo apt install dialog

================================================================================
===============================     SYNOPSIS     ===============================
================================================================================

There are multiple ways to run this script:

Interactive mode (without any args):
> ./run.sh

Classic (script) mode:
> ./run.sh [ OPTION ]... ACTION [<file>]

ACTION := { -h|--help | --custom1 | --custom2 | --custom3 <dir> | --custom4 <int> <str> | --custom5 [<file>] }

OPTION := { [-b|--bool] | [-f|--file <file>] | [-i|--int <int>] | [-j|--item <item>] | [--log <dest>] | [-p|--password <pwd>] | [-s|--str <string>] }

[<file>] : File to use

--------------------------------------------------------------------------------
--------------------------------     ACTION     --------------------------------
--------------------------------------------------------------------------------

-h|--help                 Show this help message                                

-D|--daemon               Run this script in daemon (background) mode           

--submenu <menu>          Run a certain submenu interactively and exit          
                                                                                
                          <menu> = { custom2 | custom3 | custom4 | custom5 |    
                          custom6 }                                             

--custom1                 Help <ARG_ACTION_CUSTOM1>                             

--custom2                 Help <ARG_ACTION_CUSTOM2> Use '-b|--bool' to enable   
                          <arg_bool>. Use '-j|--item <item>' to specify         
                          <arg_item>'s value.                                   

--custom3 <dir>           Help <ARG_ACTION_CUSTOM3>. Regarding <dir> please     
                          have a look at '-d|--dir <dir>'.                      

--custom4 <int> <str>     Help <ARG_ACTION_CUSTOM4>. Regarding <int> and <str>  
                          please have a look at '-i|--int <int>' and '-s|--str  
                          <string>'.                                            

--custom5 [<file>]        Help <ARG_ACTION_CUSTOM5>. Either use a given <file>  
                          or <stdin>'s (pipe) content ('echo "string" |         
                          ./run.sh --custom5').                                 

--custom6                 Help <ARG_ACTION_CUSTOM6>                             

--------------------------------------------------------------------------------
--------------------------------     OPTION     --------------------------------
--------------------------------------------------------------------------------

--log <dest>            Specify where to write log message to                                   
                                                                                
                            both  :  Terminal + System log                      
                          syslog  :  System log only                            
                        terminal  :  Terminal only                              
                                                                                
                        (default: 'terminal')                                   

-b|--bool               Help <arg_bool>                                         

-d|--dir <dir>          Help <arg_dir>                                          

-f|--file <file>        Help <arg_file>                                         

-i|--int <int>          Help <arg_int>                                          
                                                                                
                        <int> = [0, 10] (default: '1')                          

-j|--item <item>        Help <arg_item>                                         
                                                                                
                        item1  :  Help <ARG_ITEM_ITEM1>                         
                        item2  :  Help <ARG_ITEM_ITEM2>                         
                                                                                
                        <item> = { item1 | item2 }                              
                                                                                
                        (default: 'item1')                                      

-p|--password <pwd>     Help <arg_password>. See also (1).                      
                                                                                
                        (default: '')                                           

-s|--str <string>       Help <arg_str>                                          
                                                                                
                        (default: 'abc123')                                     

================================================================================
===============================     EXAMPLES     ===============================
================================================================================

__________________________________ Example 1 ___________________________________

> ./run.sh --custom1

__________________________________ Example 2 ___________________________________

> ./run.sh --custom2 --item item2

================================================================================
================================     NOTES     =================================
================================================================================

_____________________________________ (1) ______________________________________

It is highly recommended to pass credentials only via environmental variables. To do so, just set this value to 'env:<VAR>' (without '' <>) where <VAR> is your environmental variable's name.

Please note that passing credentials in clear-text form can be highly insecure as any other user/process could display the command line of this application by using system utilities like 'ps'.

Example: You would like to pass the password '123456'.

  Via an environmental variable (preferred)
    > export mypwd="123456"
    > ... "env:mypwd"

  Directly, in clear-text form (NOT recommended)
    > ... "123456"

_____________________________________ (2) ______________________________________

This is the text of note 2.

================================================================================
==============================     REFERENCES     ==============================
================================================================================

[1]     https://www.example.com                                                 

[2]     https://www.example.org                                                 

================================================================================
================================     ABOUT     =================================
================================================================================

  AUTHORS
    Florian Kemser and the SHtemplate contributors

  COPYRIGHT
    This file is part of SHtemplate, a template repository for 
    POSIX-/Bourne-Shell(sh) projects.
    
    Copyright (c) 2023-2024 Florian Kemser and the SHtemplate contributors
    
    Permission is hereby granted, free of charge, to any person obtaining a 
    copy of this software and associated documentation files (the "Software"), 
    to deal in the Software without restriction, including without limitation 
    the rights to use, copy, modify, merge, publish, distribute, sublicense, 
    and/or sell copies of the Software, and to permit persons to whom the 
    Software is furnished to do so, subject to the following conditions:
    
    The above copyright notice and this permission notice (including the next 
    paragraph) shall be included in all copies or substantial portions of the 
    Software.
    
    THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
    IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
    FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
    AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
    LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING 
    FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER 
    DEALINGS IN THE SOFTWARE.

(back to top)

Roadmap

See the open issues for a full list of proposed features (and known issues).

(back to top)

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

Fork the Project
Create your Feature Branch (git checkout -b feature/AmazingFeature)
Commit your Changes (git commit -m 'Add some AmazingFeature')
Push to the Branch (git push origin feature/AmazingFeature)
Open a Pull Request

(back to top)

License

Distributed under the MIT License. See LICENSE for more information.

⚠️ The license above does not apply to the files and folders within the library directory /lib. Please have a look at the LICENSE file located in the root directory of each library to get more information.

(back to top)

Contact

Project Link: https://github.com/fkemser/SHtemplate

(back to top)

Acknowledgments

(back to top)

For the full SPDX license list please have a look at 'https://spdx.org/licenses/'. However, only some licenses are supported so far, see /lib/SHtemplateLIB/lib/licenses folder. If you are not sure which license to choose just have a look at e.g. 'https://choosealicense.com'. ↩

Name		Name	Last commit message	Last commit date
Latest commit History 20 Commits
etc		etc
lib		lib
res		res
src		src
test		test
.gitmodules		.gitmodules
LICENSE		LICENSE
README.md		README.md

License

fkemser/SHtemplate

Folders and files

Latest commit

History

Repository files navigation

SHtemplate

About The Project

Built With

Testing Environment

Getting Started

Prerequisites

Alpine Linux

Debian

Installation

Customization

Template Structure

Overview

/etc/run.cfg.sh

/lib/...

/src/init.sh

/src/lang/run.<...>.lang.sh (Repository String Constants Files)

Used in interactive (dialog) menus

Used in help(), parameter section (SYNOPSIS)

Used in help(), other sections

Used in terminal output (stdout/stderr)

Placeholders

Further String Constants Files (/src/lang/*.lang.sh)

/src/run.sh (Repository Run File)

Modes

Actions

Constants

Variables

Functions

args_check()

args_read()

help()

help_synopsis()

init_check_pre()

init_check_post()

init_first()

init_lang()

init_update()

main()

main_daemon()

main_interactive()

main_script()

menu_main()

msg()

run()

trap_main()

Additional Sample Code

Sample Parameters and Constants

Sample Actions

Sample Functions

func1()

menu_arg_...()

trap_func1()

Daemon Mode Sample

Adding support for other languages

Further Code Samples

Run a certain command (<cmd>) and in case of any error do not only log a pre-defined error message (<msg>) but also the command's previous output (<result>)

Temporarily disable trap handling

Check whether the script was called recursively

Usage (/src/run.sh) (Example)

Roadmap

Contributing

License

Contact

Acknowledgments

Footnotes

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

`/etc/run.cfg.sh`

`/lib/...`

`/src/init.sh`

`/src/lang/run.<...>.lang.sh` (Repository String Constants Files)

Used in interactive (`dialog`) menus

Used in `help()`, parameter section (`SYNOPSIS`)

Used in `help()`, other sections

Used in terminal output (`stdout`/`stderr`)

`/src/run.sh` (Repository Run File)

`args_check()`

`args_read()`

`help()`

`help_synopsis()`

`init_check_pre()`

`init_check_post()`

`init_first()`

`init_lang()`

`init_update()`

`main()`

`main_daemon()`

`main_interactive()`

`main_script()`

`menu_main()`

`msg()`

`run()`

`trap_main()`

`func1()`

`menu_arg_...()`

`trap_func1()`

Run a certain command (`<cmd>`) and in case of any error do not only log a pre-defined error message (`<msg>`) but also the command's previous output (`<result>`)

Packages