Step help as own function within step definition script

fixes #1

seqs/gitea.sh

@@ -8,21 +8,21 @@ giteaDownload="https://dl.gitea.io/gitea/1.7.5/gitea-1.7.5-linux-arm-7"
 giteaService="https://raw.githubusercontent.com/go-gitea/gitea/master/contrib/systemd/gitea.service"
 giteaServiceLoc="/etc/systemd/system/gitea.service"
 
-function step_1 {
+step_1_info() { echo "Updating apt"; }
-  echo -e "Updating apt\n"
+step_1() {
   apt update
 }
 
-function step_2 {
+step_2_info() { echo "Downloading $toolName to user home: $giteaDownload"; }
-  echo -e "Downloading $toolName to user home: $giteaDownload\n"
+step_2() {
   cd
   wget -O gitea $giteaDownload
   saveReturn $?
   endReturn 
 }
 
-function step_3 {
+step_3_info() { echo "Adding user for $toolName (git:git)"; }
-  echo -e "Adding user for $toolName (git:git)"
+step_3() {
   adduser \
      --system \
      --shell /bin/bash \
@@ -35,8 +35,8 @@ function step_3 {
   endReturn 
 }
 
-function step_4 {
+step_4_info() { echo "Create required directory structure"; }
-  echo -e "Create required directory structure"
+step_4() {
   mkdir -p /var/lib/gitea/{custom,data,log}
   chown -R git: /var/lib/gitea/
   chmod -R 750 /var/lib/gitea/
@@ -50,16 +50,16 @@ function step_4 {
   endReturn 
 }
 
-function step_5 {
+step_5_info() { echo "Creating systemd service"; }
-  echo -e "Creating systemd service"
+step_5() {
   wget -O $giteaServiceLoc  $giteaService
-  echo -en "Uncomment needed services (enter to continue): "
+  echo -en "Uncomment needed services mysql (enter to continue): "
   read
   vi $giteaServiceLoc
 }
 
-function step_6 {
+step_6_info() { echo -e "Starting $toolName service\n"; }
-  echo -e "Starting $toolName service"
+step_6() {
   systemctl enable gitea
   systemctl start gitea
   echo "Before proceeding to installation you may need to create a database first with step 10"
@@ -70,13 +70,12 @@ function step_6 {
 }
 
 
-
+step_10_info() { echo -e "Create mysql database for $toolName\n"; }
-function step_10 {
+step_10() {
   local mysqlDatabase
   local mysqlUser
   local mysqlPass
 
-  echo "Setup mysql database"
   echo "Existing mysql databases:"
   mysql -u root -e 'SHOW DATABASES;'
 
@@ -107,28 +106,11 @@ function step_10 {
   mysql -u root -e 'FLUSH PRIVILEGES;'
 }
 
-function step_20 {
+step_20_info() { echo "Secure settings after installation"; }
-  echo -e "Secure settings after installation"
+step_20() {
   chmod 750 /etc/gitea
   chmod 644 /etc/gitea/app.ini
 }
 
-help() {
+# Path to sequencer
-  echo    "  $toolName Documentation"
-  echo    "    1: Updating apt"
-  echo    "    2: Downloading $toolName to user home: $giteaDownload"
-  echo    "    3: Adding user for $toolName (git:git)"
-  echo    "    4: Create required directory structure"
-  echo    "    5: Creating systemd service"
-  echo    "    6: Starting $toolName service"
-  echo
-  echo    "   10: Setup mysql database" 
-  echo
-  echo    "   20: Secure settings after installation"
-  echo
-}
-
-
-#
-## Path to sequencer
 . ../sequencer/sequencer.sh

seqs/librenms.sh

@@ -4,31 +4,32 @@
 ## Installation and maintenance for LibreNMS
 ## Using buster repositories for php 7.3 installation
 
+toolName="LibreNMS"
 librePhpDeps="composer php-cli-prompt php-composer-ca-bundle php-composer-semver php-composer-spdx-licenses php-json-schema php-psr-log php-symfony-console php-symfony-filesystem php-symfony-finder php-symfony-polyfill-mbstring php-symfony-process"
 librePackages="fping git graphviz imagemagick mtr-tiny nmap python-memcache python-mysqldb rrdtool snmp snmpd whoisi nagios-plugins"
 
 
-function step_1 {
+step_1_info() { echo "Updating apt"; }
-  echo -e "Updating apt\n"
+step_1() {
-  #apt update
+  apt update
 }
 
-function step_2 {
+step_2_info() { echo -e "Installing $toolname dependencies: $librePackages\n"; }
-  echo -e "Installing: $librePackages\n"
+step_2() {
   apt install $librePackages
   saveReturn $?
   endReturn 
 }
 
-function step_3 {
+step_3_info() { echo -e "Installing -t buster PHP related packages\n$librePhpDeps\n"; }
-  echo -e "Installing -t buster PHP related packages\n$librePhpDeps\n" 
+step_3() {
   apt -t buster install $librePhpDeps
   saveReturn $?
   endReturn 
 }
 
-function step_4 {
+step_4_info() { echo "Adding $toolName user (librenms:librenms)"; }
-  echo -e "Adding librenms user"
+step_4() {
   useradd librenms -d /opt/librenms -M -r
   saveReturn $?
   usermod -a -G librenms www-data
@@ -36,20 +37,20 @@ function step_4 {
   endReturn 
 }
 
-function step_5 {
+step_5_info() { echo "Installing $toolName using composer"; }
-  echo -e "Installing librenms using composer"
+step_5() {
   cd /opt
   composer create-project --no-dev --keep-vcs librenms/librenms librenms dev-master
   saveReturn $?
   endReturn 
 }
 
-function step_10 {
+step_10_info() { echo "Create mysql database for $toolName"; }
+step_10() {
   local mysqlDatabase
   local mysqlUser
   local mysqlPass
 
-  echo "Setup mysql database"
   echo "Existing mysql databases:"
   mysql -u root -e 'SHOW DATABASES;'
 
@@ -80,8 +81,9 @@ function step_10 {
   mysql -u root -e 'FLUSH PRIVILEGES;'
 }
 
-function step_11 {
+step_11_info() { echo "MariaDB configuration"; }
-  echo "MariaDB configuration"
+step_11() {
+  echo
   echo "Edit or create /etc/mysql/mariadb.conf.d/90-myconfig.cnf and add:"
   echo
   echo "------------------------"
@@ -94,8 +96,9 @@ function step_11 {
   echo "service mysql restart"
 }
 
-function step_12 {
+step_12_info() { echo "PHP fpm/cli configuration"; }
-  echo "PHP fpm/cli configuration"
+step_12() {
+  echo
   echo "Ensure date.timezone is set in php.ini to your preferred time zone. See http://php.net/manual/en/timezones.php for a list of supported timezones. Valid examples are: \"America/New_York\", \"Europe/Berlin\", \"Etc/UTC\"."
   echo
   echo "vi /etc/php/7.3/fpm/conf.d/90-custom_pi.ini"
@@ -109,8 +112,8 @@ function step_12 {
   echo "service php7.3-fpm restart"
 }
 
-function step_40 {
+step_40_info() { echo "Switch $toolName installation to monthly stable"; }
-  echo "Switch Librenms installation to monthly stable"
+step_40() {
   echo
   echo "Add following to /opt/librenms/config.php"
   echo
@@ -122,31 +125,12 @@ function step_40 {
   echo "cd /opt/librenms && git fetch --tags && git checkout \$(git describe --tags \$(git rev-list --tags --max-count=1))"
 }
 
-function step_42 {
+step_42_info() { echo "Fix librenms permission"; }
-  echo "Fix librenms permission"
+step_42() {
   chown -R librenms:librenms /opt/librenms
-
   setfacl -d -m g::rwx /opt/librenms/bootstrap/cache /opt/librenms/storage /opt/librenms/logs /opt/librenms/rrd
-
   chmod -R ug=rwX /opt/librenms/bootstrap/cache /opt/librenms/storage /opt/librenms/logs /opt/librenms/rrd
 }
 
-help() {
+# Path to sequencer
-  echo    "  Step Documentation"
-  echo    "    1: Updating apt"
-  echo -e "    2: Install packages:\n\t$librePackages"
-  echo -e "    3: Installing -t buster PHP related packages:\n\t$librePhpDeps" 
-  echo    "    4: Adding librenms user"
-  echo    "    5: Installing librenms using composer"
-  echo
-  echo    "   10: Setup mysql database" 
-  echo    "   11: MariaDB configuration"
-  echo    "   12: PHP fpm/cli configuration"
-  echo
-  echo    "   40: Switch Librenms installation to monthly stable"
-  echo    "   42: Fix librenms permission"
-}
-
-#
-## Path to sequencer
 . ../sequencer/sequencer.sh

sequencer/sequencer.sh

@@ -2,12 +2,13 @@
 
 ## Sequencer script is doing nothing on its own. It is included by a step definition
 ## script which uses the sequencer to provide sequencial operations with or without
-## user interaction (see template.sh)
+## user interaction (see stepTemplate.sh)
 
 ## Start of generic script part
 
 QUIET=0
 ERNO=0
+MAX_STEP=255
 TEMPLATE_NAME=stepTemplateExample.sh
 
 function helpSequencer() {
@@ -17,7 +18,7 @@ function helpSequencer() {
   echo "    -q : Don't ask for permission to execute next step"
   echo "         If called without starting step number only this help is shown"
   echo 
-  echo "  [Step Number(s) 1-255]"
+  echo "  [Step Number(s) 1-${MAX_STEP}]"
   echo "      Single step number  : starting point of process"
   echo "    Multiple step numbers : execute only given steps"
   echo "                            execute only one step with using special step 0"
@@ -27,18 +28,25 @@ function helpSequencer() {
 # endCheckEmpty [VariableName] [DESCRIPTION]
 #    DESCRIPTION : Optional text for error
 function endCheckEmpty() {
-   local errorText=$1
+  local errorText=$1
-   eval 'local ref=$'$1
+  eval 'local ref=$'$1
-   
+  
-   if [ ! -z "$2" ] ; then
+  if [ ! -z "$2" ] ; then
-	errorText=$2
+    errorText=$2
-   fi
+  fi
-   if [ -z $ref ] ; then
+  if [ -z $ref ] ; then
-	echo -e "[Error] $errorText must not be empty.\nAborting installation."
+    echo -e "[Error] $errorText must not be empty.\nAborting installation."
-	exit 666
+    exit 666
   fi 
 }
 
+function existsFunction() {
+  local NOTFOUND=0
+  eval 'local ref=$'$1
+  declare -F $1 &>>/dev/null || NOTFOUND=1
+  return $NOTFOUND
+}
+
 function saveReturn() {
   if [ $1 -ne 0 ] ; then
     ERNO=$1
@@ -96,6 +104,10 @@ function execute() {
   fi 
 
   echo -en "\n[STEP $1] "
+  existsFunction step_${1}_info
+  if [ $? -eq 0 ] ; then
+    step_${1}_info $1
+  fi
   if [ $QUIET -ne 1 ] ; then
     read -p "Start: y/n(default)? " answer
     case $answer in
@@ -113,10 +125,10 @@ function execute() {
 }
 
 # continous <Starting Step Number>
-# (max 255)
+# (max $MAX_STEP)
 # execute installation continously from given starting step
 function continous() {
-  for ((i=$1; i<=255; i++)); do
+  for ((i=$1; i<=${MAX_STEP}; i++)); do
     execute -q $i
     local res=$?
     if [ $res -ne 0 ] ; then
@@ -146,13 +158,10 @@ function createTemplate() {
   fi
   echo "#!/bin/bash" > $TEMPLATE_NAME
   echo >> $TEMPLATE_NAME
-  echo "function step_1 {" >> $TEMPLATE_NAME
+  echo "# Step 1 is mandatory" >> $TEMPLATE_NAME
-  echo "  echo \"My custom step one\"" >> $TEMPLATE_NAME
+  echo "step_1_info() { echo \"My custom step \$1\"; }" >> $TEMPLATE_NAME
-  echo "}" >> $TEMPLATE_NAME
+  echo "step_1() {" >> $TEMPLATE_NAME
-  echo >> $TEMPLATE_NAME
+  echo "  echo \"Doing something...\"" >> $TEMPLATE_NAME
-  echo "help() {" >> $TEMPLATE_NAME
-  echo "  echo \"  Step Documentation\"" >> $TEMPLATE_NAME
-  echo "  echo \"    1: My custom step\"" >> $TEMPLATE_NAME
   echo "}" >> $TEMPLATE_NAME
   echo >> $TEMPLATE_NAME
   echo ". $0" >> $TEMPLATE_NAME
@@ -163,13 +172,12 @@ function createTemplate() {
 
 # Always display sequencer help and, if available, definition script help
 function displayHelp() {
-  local NOTFOUND=0
  
   helpSequencer
 
-  # check if help function exists
+  # check if step definition exists by looking for step_1()
-  declare -F help &>>/dev/null || NOTFOUND=1
+  existsFunction step_1
-  if [ $NOTFOUND -eq 1 ] ; then
+  if [ $? -ne 0 ] ; then
     echo -e "\n  It seems ${0##*/} was called directly."
     echo -e "  Please create a step definition script first.\n"
     read -p "  Create a step definition template now? y/n(default)? " answer
@@ -188,7 +196,24 @@ function displayHelp() {
     esac
     exit 1;
   else
-    help
+    echo "  Step documentation:"
+    for ((i=1; i<=${MAX_STEP}; i++)); do
+     
+      # Display step reference in help if step function exists 
+      existsFunction step_${i}
+      if [ $? -ne 0 ] ; then
+	continue
+      fi
+      printf '    Step %3s : ' $i
+      
+      # Display step help only if function exists
+      existsFunction step_${i}_info
+      if [ $? -eq 0 ] ; then
+        step_${i}_info $i 
+      else
+        echo " - step_${i}_info() missing"
+      fi
+    done
   fi
 }
 

stepTemplate.sh

@@ -2,47 +2,43 @@
 
 ##
 ## Sequencer interface:
-##   - step_[1 - 255] functions performing custom operations
+##   - step_[1 - 255]_info [STEP NUMBER]
-##   - help() function describing functionality
+##        functions providing short header for help and user interaction
+##   - step_[1 - 255] [STEP NUMBER]
+##        functions performing custom operations
 ## 
 
-function step_1 {
+step_1_info() { echo "Step $1 header"; }
-  echo -e "Eins"
+step_1() {
   cat .nofile
   saveReturn $?
 }
 
-function step_2 {
+step_2_info() { echo "Step $1 header"; }
+step_2() {
   echo -e "Zwei"
   endReturn
   echo zwo
 }
 
-function step_3 {
+step_3_info() { echo "Step $1 header"; }
+step_3() {
   echo -e "Drei"
   echo drei
 }
 
-function step_10 {
+step_10_info() { echo "Step $1 header"; }
+step_10() {
   echo -e "Zehn"
   echo zehn 
 }
 
-function step_11 {
+step_11_info() { echo "Step $1 header"; }
+step_11() {
   echo -e"Elf"
   echo elf
 }
 
-help() {
-  echo "  Step Documentation"
-  echo "    1: Step with failure and saveReturn"
-  echo "    2: Step with endReturn at the beginning"
-  echo "    3: Regular step without return check (last step when starting with 1 or 2)"
-  echo
-  echo "   10: Regular step without return check (staring point for separate sequence)"
-  echo "   11: Regular step without return check (last step of sequence starting with 10)"
-}
-
 #
 ## Path to local sequencer.sh script