title framework.sh
section 7
project bgscripts-core
volume Shell Programmer's Manual
date April 2020
=====
NAME
  framework.sh - shell library for bgscripts collection
DESCRIPTION
  Provide a set of functions useful for shell scripting in Unix-like environments. Written in bash but designed for POSIX-compliance whenever possible.
PUBLIC FUNCTIONS
Some functions are private, but some are available for other scripts to use.
  debuglev  
call: debuglev 5 && ferror "Debug level is at least five."

This function is called extensively by all the bgscripts programs. It compares the internal global debug level (set by the `-d` parameter)
  debuglevoutput  
call: echo "output" | debuglevoutput 8

Compare debug level to provided number, and display standard input if debug level is >= provided number.
  fisnum   
call: fisnum $1 && echo "it is a number"

Return true if passed value is a number.
  fistruthy  
call: fistruthy "${value}" && echo "this is true!"

Return true if the lowercase of the parameter is "y", "yes", "1", "true", or "always".
  setval  
example:

    setval 1 sendsh sendopts<<eofsendsh     # if $1="1" then setvalout="critical-fail" on failure
    /usr/local/share/bgscripts/send.sh -hs  # setvalout maybe be "fail" otherwise
    /usr/share/bgscripts/send.sh -hs        # on success, setvalout="valid-sendsh"
    /usr/local/bin/send.sh -hs
    /usr/bin/mail -s
    eofsendsh
    test "${setvalout}" = "critical-fail" && ferror "${scriptfile}: 4. mailer not found. Aborted." && exit 4

Setval accepts parameter names, and will set these parameter names to the first line where the first item on the line is a valid executable.
  flecho  
call: flecho "${var}"

Flecho is a framework implementation of `lecho(1)`. It even calls it if it finds it! Otherwise, use built-in logic, to print parameters prepended with timestamp, hostname, and username.
  convert_to_seq  
call: convert_to_seq '5,6-10,15'

Convert comma-separated ranges of numbers or individual numbers into each integer included in the range.
  fsudo  
call: fsudo "command to run with sudo"

Run this command with sudo. Not terribly useful, unless the `sudo(1)` binary is hard to find.
  fwhich  
call: fwhich "${infile1}"

Invoke `readlink(1)` `-f` with the parameters.
  ferror  
call: ferror "Message for stderr"

Display parameters to standard error.
  prepend, append  
call: cat /file | prepend "something"

Use these to prepend or append the parameters to the contents of the pipe. Not really better than `sed(1)`.
  setdebug  

This is useful only within the `ftemplate.sh(7)` in function parseFlag. When `-d` is passed to an instantiated ftemplate script, call setdebug which will load the value into the internal variable ${debug} which is useful with function *debuglev* previously described in this man page.
  isvalidip  
call: isvalidip "${input}" && echo yes

The magic regex from the Internet for IPv4 addresses.
  get_conf
call: get_conf "/etc/defaults/myscript"

Load a pseudo-shell script just for the variables. Only apply a variable if undefined. This protects precedence. See `ftemplate.sh(7)` GET_CONF section.
  define_if_new  
call: define_if_new SCRIPT_VARIABLENAME "/etc/default/scriptname"

Define a variable if it is not yet defined. Unfortunately it always evaluates the parameters so this is less efficient than simply calling

    test -z "${SCRIPT_VARIABLENAME}" && SCRIPT_VARIABLENAME="something"
  fchmodref  
call: fchmodref "${oldfile}" "${newfile}"

Useful on FreeBSD where (presumably non-GNU) chmod does not have the --reference parameter.
  return_code
call: return_code 45

Simply calls "return $1", so not better than just doing that yourself.
  validateparams  
call: validateparams PARAMNAME1 PARAMNAME2 - "$@"

Load PARAMNAME1, PARAMNAME2 and so on with the values from "$@". Calls parseParam as needed to deal with flags (defined as a parameter beginning with one or more dash characters) who might consume later parameters. Any parameters not consumed by flags, will be assigned to PARAMNAME1, PARAMNAME2, etc. Any additional parameters not given explicit names iwll be assigned to opt1, opt2, etc. Define variable `thiscount` with the number of opt1 variables defined this way. See `ftemplate.sh(7)` VALIDATEPARAMS section.
PUBLIC VARIABLES
* today=YYYY-mm-dd
* now=YYYY-mm-dd HH:MM:ss
* server=`hostname`
* thistty=$( tty )
* thisip
* thisos
* thisflavor
* thisflavorversion
* thisppid
* cronpid
* is_cronjob (boolean)
* stdin_piped (boolean)
* stdout_piped (boolean)
* stderr_piped (boolean)
* stdin_local (boolean)
* is_root
OPTIONS
* `--fcheck`  Return to stdout only the version of framework and exit.
ENVIRONMENT
* FRAMEWORK_NOLOG  If set to any non-null value, omit logging to /var/log/framework.log.
SEE ALSO
`ftemplate.sh(7)`
