Add sfpi.sh, Shellfu's favorite plugin interface

packaging/debian/control

@@ -102,6 +102,23 @@ Description: Shellfu/Bash module to export docs from Shellfu modules
  This sub-package contains Shellfu/Bash module to export documentation
  from other Shellfu modules that follow Shellfu coding style.
 
+Package: shellfu-bash-sfpi
+Architecture: all
+Depends: shellfu-bash, shellfu-bash-pretty, shellfu-bash-sfdoc
+Description: Shellfu/Bash module to export docs from Shellfu modules
+ Shellfu is an attempt to add modularity to your shell scripts.
+ .
+ With Shellfu you can develop your shell modules separately from your
+ scripts, and test, use, explore or study them without need to be aware
+ of details such as where the actual files are placed.
+ .
+ Shellfu is mostly intended for cases when there's need for non-trivial
+ amount of reliable body of shell scripts, and access to advanced modular
+ languages such as Python or Perl is limited.
+ .
+ This sub-package contains Shellfu/Bash module to help manage, discover,
+ select and load other Shellfu modules as plugins.
+
 Package: shellfu-devel
 Architecture: all
 Depends: shellfu-bash-pretty

packaging/debian/shellfu-bash-sfpi.install

@@ -0,0 +1 @@
+/usr/share/shellfu/include-bash/sfpi.sh

packaging/template.spec

@@ -66,6 +66,15 @@ Requires: shellfu-bash-pretty
 This sub-package contains Shellfu/Bash module to export documentation
 from other Shellfu modules that follow Shellfu coding style.
 
+%package bash-sfpi
+Summary: Shellfu/Bash plugin interface
+Requires: shellfu-bash
+Requires: shellfu-bash-sfdoc
+Requires: shellfu-bash-pretty
+%description bash-sfpi
+This sub-package contains Shellfu/Bash module to help manage, discover,
+select and load other Shellfu modules as plugins.
+
 %package devel
 Summary: Essential developer tools
 Requires: shellfu-bash-pretty
@@ -160,6 +169,9 @@ make test \
 %files bash-sfdoc
 %{_datadir}/%{name}/include-bash/sfdoc.sh
 
+%files bash-sfpi
+%{_datadir}/%{name}/include-bash/sfpi.sh
+
 %files devel
 %{_bindir}/sfembed
 

src/bin/sfdoc

@@ -8,7 +8,7 @@ shellfu import sfdoc
 
 
 usage() {
-    mkusage \
+    mkusage "$@" \
         "[options] MODULE"                                              \
         "[options] --ls [MODULE]"                                       \
         "[options] --ls{var|fun} MODULE"                                \
@@ -102,18 +102,18 @@ main() {
         -O|--object)    spectype=obj;               shift ;;
         -d|--debug)     PRETTY_DEBUG=true;          shift ;;
         -a|--all)       SFDOC_SHOW_HIDDEN=true;     shift ;;
-        -I|--include)   SHELLFU_PATH="$2:$SHELLFU_PATH"; shift 2 || usage ;;
+        -I|--include)   SHELLFU_PATH="$2:$SHELLFU_PATH"; shift 2 || usage -w "no PTH?" ;;
         -s|--src)       action=src;                 shift; break ;;
         -l|--ls)        action=lsx;                 shift; break ;;
         -L|--lsmod)     action=lsm;                 shift; break ;;
         --which)        action=wch;                 shift; break ;;
-        -o|--only-from) SHELLFU_PATH="$2"; SHELLFU_INCLUDE=""; shift 2 || usage ;;
+        -o|--only-from) SHELLFU_PATH="$2"; SHELLFU_INCLUDE=""; shift 2 || usage -w "no PTH?" ;;
         --lsvar)        action=lsv;                 shift; break ;;
         --lsfun)        action=lsf;                 shift; break ;;
-        -e|--export)    action=exp; format="$2";    shift 2 || usage; break ;;
-        --encoding)     encoding="$2";              shift 2 || usage ;;
-        --name)         RealModuleName="$2";        shift 2 || usage ;;
-        -*)                                         usage ;;
+        -e|--export)    action=exp; format="$2";    shift 2 || usage -w "no FMT?"; break ;;
+        --encoding)     encoding="$2";              shift 2 || usage -w "no ENC?" ;;
+        --name)         RealModuleName="$2";        shift 2 || usage -w "no NAME?" ;;
+        -*)                                         usage -w "unknown argument: $1" ;;
         *)                                          break ;;
     esac done
     mspec="$1"; shift
@@ -121,7 +121,7 @@ main() {
     debug -v action format module RealModuleName
     case $action:$mspec in
         lsx:*|lsm:*|wch:*) true ;;
-        *:)             usage ;;
+        *:)             usage -w "no MODULE?" ;;
     esac
     case $spectype in
         obj) module=$(find_by "$mspec") \

src/include-bash/sfpi.sh

@@ -0,0 +1,231 @@
+#!/bin/bash
+
+shellfu import sfdoc
+shellfu import pretty
+
+#
+# Shellfu plugin interface
+#
+# Discover, query, select and run plugins inside subshells so that they
+# can't interfere too easily.
+#
+#
+# EXAMPLE PLUGIN SETUP
+# ====================
+#
+# Have a Shellfu module 'foo` wanting to support plugins `bar` and
+# `baz`.  We'll need to implement 3 modules: `foo` itself and one
+# for each plugin: `_foop_bar` and `_foop_baz`.
+#
+# For example, the pluging `bar` might look like:
+#
+#     _foop_bar__process() {
+#         #
+#         # Actual "payload" function
+#         #
+#         do_something_meaningful_with "$@"
+#     }
+#
+#     _foop_bar__sfpimeta() {
+#         #
+#         # Get self meta-data key $1
+#         #
+#         local key=$1
+#         case $key in
+#             desc)  echo "We do meaningful thing in terms of bar." ;;
+#         esac
+#     }
+#
+#     _foop_bar__sfpi_compat() {
+#         #
+#         # Check if we can function in this environment
+#         #
+#         test -d /etc/bar
+#     }
+#
+# The useful function is _foop_bar__process(), which does the actual thing
+# that the plugin is supposed to do.  You can have at least one such function,
+# for obvious reasons.
+#
+# There are two optional function helping with the 'sfpi' discovery:
+#
+# The _foop_bar__sfpimeta() function enables parent query plugin meta-data
+# using sfpi__key() function.  Meanings of individual keys are not defined.
+#
+# The _foop_bar__sfpi_compat() function allows parent let plugin decide if
+# it's compatible with current environment and prevent it from being loaded.
+# In other words, if this function returns 1, the plugin would not be listed
+# by sfpi__ls().
+#
+# The minimal foo.sh in this example could look like:
+#
+#     SFPI__PREFIX=_foop        # you NEED to set this ASAP
+#
+#     foo() {
+#         local stuff=$1
+#         for plugin in $(sfpi__ls); do
+#             sfpi__call "$plugin" process "$stuff"
+#         done
+#     }
+#
+
+#
+# Plugin name prefix
+#
+# In order for your plugins to be discoverable, name them with this
+# prefix.  Common naming scheme is '_<APPNAME>p_<PLNAME>', i.e. if
+# your application was named `foo`, final layout could look something
+# like this:
+#
+#     foo
+#     _foop_bar
+#     _foop_baz
+#
+# where you could say that your module has plugins `foo` and `bar`.  In
+# the above example, value of $SFPI__PREFIX would be `_foop` (starting
+# with underscore to remain hidden in normal listings by *sfdoc*.
+#
+SFPI__PREFIX=
+
+sfpi__call() {
+    #
+    # Call plugin $1 function $2 in subshell
+    #
+    __sfpi__ckpfx
+    local plg=$1; shift
+    local fun=$1; shift
+    (
+        shellfu import "${SFPI__PREFIX}_${plg}"
+        type -t "${SFPI__PREFIX}_${plg}__$fun" >/dev/null || {
+            warn "plugin function not implemented: $fun in $plg"
+            exit 3
+        }
+        "${SFPI__PREFIX}_${plg}__$fun" "$@"
+    )
+}
+
+sfpi__import() {
+    #
+    # Import plugin $1 into current namespace
+    #
+    __sfpi__ckpfx
+    local plg=$1
+    local mod"${SFPI__PREFIX}_${plg}"=
+    shellfu try_import "$mod" || {
+        warn "module for plugin not found: $mod"
+        return 3
+    }
+    sfpi__is_compat "$mod" || {
+        warn "module not compatible: $mod"
+        return 3
+    }
+    shellfu import "$mod"
+}
+
+sfpi__get_fun() {
+    #
+    # Print name of plugin $1 function $2
+    #
+    __sfpi__ckpfx
+    local plg=$1
+    local fun=$2
+    echo "${SFPI__PREFIX}_${plg}__$fun"
+}
+
+sfpi__get_mod() {
+    #
+    # Print name of module implementing plugin $1
+    #
+    __sfpi__ckpfx
+    local plg=$1
+    echo "${SFPI__PREFIX}_${plg}"
+}
+
+sfpi__has() {
+    #
+    # True if plugin $1 has function $2
+    #
+    __sfpi__ckpfx
+    local mod="${SFPI__PREFIX}_$1"
+    local fun=$2
+    (
+        shellfu import "$mod"
+        type -t "${mod}__$fun" >/dev/null;
+    )
+}
+
+sfpi__is_compat() {
+    #
+    # True if plugin $1 is compatible
+    #
+    # Load plugin in subshell and look for compatibility function.  If
+    # such function exists, it's called without arguments and 
+    # just to call its compatibility function
+    # and let it decide if it's compatible with this environment.
+    #
+    # If plugin has no compatibility function, it's considered
+    # compatible.
+    #
+    __sfpi__ckpfx
+    local plg=$1
+    local mod="${SFPI__PREFIX}_$plg"
+    local fun=${mod}__sfpi_compat
+    (
+        shellfu import "$mod"        || exit 3
+        sfpi__has "$plg" sfpi_compat || exit 0
+        "$fun"; es=$?
+        test $es -gt 1 && warn "illegal exit status: $es from ${fun}"
+        return $es
+    )
+}
+
+sfpi__key() {
+    #
+    # Safely get meta-data key $2 from plugin for item type $1
+    #
+    __sfpi__ckpfx
+    local plg=$1     # plugin name
+    local key=$2    # meta-data key
+    local value     # ^^ value
+    local fun="${SFPI__PREFIX}_${plg}__sfpimeta" # plg getter function name
+    if type -t "$fun" >/dev/null;
+    then
+        value=$("$fun" "$key")
+        debug -v fun key value
+        test -n "$value" || value="(none)"
+    else
+        value='(undefined)'
+    fi
+    echo "$value"
+}
+
+sfpi__ls_all() {
+    #
+    # List all available plugins
+    #
+    __sfpi__ckpfx
+    SFDOC_SHOW_HIDDEN=true sfdoc__ls_m \
+      | grep "^$SFPI__PREFIX"'_[[:alpha:]][[:alnum:]]*$' \
+      | sed "s/^${SFPI__PREFIX}_//"
+}
+
+sfpi__ls() {
+    #
+    # List compatible plugins
+    #
+    __sfpi__ckpfx
+    local plg
+    for plg in $(sfpi__ls_all); do
+        sfpi__is_compat "$plg" && echo "$plg"
+    done
+    true
+}
+
+__sfpi__ckpfx() {
+    #
+    # Check if $SFPI__PREFIX has been set
+    #
+    debug -v SFPI__PREFIX
+    test -n "$SFPI__PREFIX" \
+     || die "bug: need to set SFPI__PREFIX first"
+}

tests/shellfu_api/TF_RUN

@@ -20,6 +20,7 @@ flt_ours() {
         -e termcolors \
         -e pretty \
         -e sfdoc \
+        -e sfpi \
         -e mdfmt \
     #FIXME: remove the filter when TFKit learns to test in sandbox
 }

tests/shellfu_api/oracle/functions.stdout

@@ -91,3 +91,13 @@ sfdoc:__sfdoc__strip_doc
 sfdoc:sfdoc__export
 sfdoc:sfdoc__ls
 sfdoc:sfdoc__ls_m
+sfpi:__sfpi__ckpfx
+sfpi:sfpi__call
+sfpi:sfpi__get_fun
+sfpi:sfpi__get_mod
+sfpi:sfpi__has
+sfpi:sfpi__import
+sfpi:sfpi__is_compat
+sfpi:sfpi__key
+sfpi:sfpi__ls
+sfpi:sfpi__ls_all

tests/shellfu_api/oracle/modules.stdout

@@ -9,4 +9,5 @@ inigrep
 mdfmt
 pretty
 sfdoc
+sfpi
 termcolors

tests/shellfu_api/oracle/variables.stdout

@@ -17,6 +17,7 @@ pretty:PRETTY_DEBUG_EXCLUDE
 pretty:PRETTY_USAGE
 pretty:PRETTY_VERBOSE
 sfdoc:SFDOC_SHOW_HIDDEN
+sfpi:SFPI__PREFIX
 termcolors:TERMCOLORS_BLACK
 termcolors:TERMCOLORS_BLUE
 termcolors:TERMCOLORS_CYAN