title ftemplate.sh
section 7
project bgscripts-core
volume Shell Programmer's Manual
date April 2020
=====
NAME
  ftemplate.sh - template shell script for new scripts
DESCRIPTION
  This is the definitive template for making new shell scripts that use `framework.sh(7)` library. To make a new script, use `newscript(1)`.
FUNCTIONS
A few generic functions are provided.
  USAGE
Provides a basic help message template.
  CLEAN_SCRIPTTRIM
The delayed-cleanup template. This is useful for when results need to be cached for a few minutes, for a future task to pick them up.
  CTRLC
Empty, but documents how to use with `trap` to react to *CTRL-C* presses.
  CTRLZ
Empty, but documents how to use with `trap` to react to *CTRL-Z* presses.
  PARSEFLAG
The main area for reacting to flags (parameters that begin with single or double dash characters). Some special functions are useful here, from `framework.sh(7)`.
  setdebug  Useful when setting a debug value either from the provided value if one exists, or setting to default of 10.
  getval  Load next non-dashed parameter into ${tempval}. Use this variable to assign to a permanent variable.
FRAMEWORK PATH RESOLUTION
A variable, *f_needed* is defined and used to determine the minimum FRAMEWORK version needed. Check a large number of paths, starting with $FRAMEWORKBIN, $FRAMEWORKPATH/framework.sh, and a hardcoded list, ending with the canonical location which is */usr/libexec/bgscripts/framework.sh*.
OTHER FEATURES
  REACT TO OS TYPE  
An empty section for admin modification, should the script need to react differently on different OSes.
  REACT TO ROOT STATUS  
If the script needs to react differently depending on the effective user.
  SET CUSTOM SCRIPT AND VALUES
A fully realized example of *setval* from `framework.sh(7)`. Define parameters sendsh and sendopt, to the first values that match where *sendsh* is a valid executable. The first parameter is a boolean that affects if variable ${setvalout} will be set to "critical-fail" on failure. Otherwise, a failure will set ${setvalout} to "fail." If successful, set ${setvalout} to "valid-sendsh".
  VALIDATE PARAMETERS
The validateparams call will load variables named with any strings that appear before the dash. So `validateparams INFILE OUTFILE - "$@"` will load any flagless vals from the parameters to the script in to INFILE and OUTFILE. Any additional ones will be loaded in opt1, opt2, etc.
  LEARN EX_DEBUG
If the debug level was not set by parameters, and SCRIPT_DEBUG exists, then set the debug level to that. This preserves the precedence of cli parameters being the most important.
  CONFIRM TOTAL NUMBER OF FLAGLESSVALS IS CORRECT
An example section to handle invalid input.
  LOAD CONFIG FROM SIMPLECONF
Simpleconf is the `get_conf` function invoked in a particular order. Load any requested confs from parameters, then load the user-default config, and then load the system-default config. The `get_conf` function reads a file line by line, looking for variables to define. If a variable is requested and it is not already defined, then define it according to this config file.

This arrangement preserves the order of precedence.
1. parameters and flags
2. environment
3. config file (even if provided from parameters)
4. default user config: ~/.config/script/script.conf
5. default config: /etc/script/script.conf

  CONFIGURE VARIABLES AFTER PARAMETERS
Use this section to prepare more variables before beginning the main loop.
  START READ CONFIG FILE TEMPLATE
Combined with the STOP THE READ CONFIG FILE, use this section if you want to read an old-style config file with section headings. This only interprets variables, but it does so per-section.
  REACT TO BEING A CRONJOB
If `framework.sh(7)` sets ${is_cronjob}=1, then react differently.
  SET TRAPS
Set the traps before the main loop. 17 is omitted because it tends to break `dash(1)`, the default shell interpreter on Devuan.
  DEBUG SIMPLECONF
Show the environment variables that start with the script initials.
  MAIN LOOP
Main logic goes here.
  EMAIL LOGFILE
A sample statement demonstrating how to email a logfile is provided.
  STOP THE READ CONFIG FILE
Useful only when START READ CONFIG FILE TEMPLATE is also used.
SEE ALSO
`newscript(1)`, `framework.sh(7)`
