korp-lib-call

#! /bin/bash
# -*- coding: utf-8 -*-

# Call a function in korp-lib.sh with given arguments.
#
# For usage, see below or run 'korp-lib-call --help'

# TODO:
# - An option to read multiple functions and their arguments from
#   stdin, to be called in sequence.


progname=$(basename $0)
progdir=$(dirname $0)


usage_header="Usage: $progname [options] function_name [arguments ...]
       $progname -l | --list-functions

Call function function_name in the korp-lib.sh (shlib/*.sh) library
with the given arguments. Dashes in function_name are replaced with
underscores.

The exit code is the return value of the function."

optspecs='
v|verbose
    Show verbose information: the called function and its return
    value (unless the function exits with the exit command).
t|trace
    Trace the function execution by setting the shell v and x options.
l|list-functions
    List the available functions. Please note that some functions are
    not designed to be run in isolation.
u|usage
    Show usage information for function_name. With --verbose, show the
    whole usage comment, otherwise only the synopsis. Please note that
    not all functions have a usage comment.
'


. $progdir/korp-lib.sh

# Process options
eval "$optinfo_opt_handler"


if [ "x$list_functions" != x ]; then
    # Omit internal functions whose names begin with an underscore
    grep -h '^[^_#][^ ]* () {' $_shlibdir/*.sh |
    sed -e 's/ ().*//' |
    sort
    exit
fi

func=${1//-/_}
shift
if [ "x$func" = x ]; then
    error "Please specify function name"
fi
if [ "${func#*[!a-z0-9_-]}" != "$func" ]; then
    error "Invalid function name: $func"
fi

if [ "x$usage" != x ]; then
    if [ "x$verbose" = x ]; then
        verbose=0
    fi
    # Assume that a function usage comment immediately precedes the
    # function definition, is preceded by a blank line and is of the
    # following form:
    #
    # # function_name [args]
    # #
    # # Function description
    # function_name () {
    # ...
    #
    # The synopsis "function_name [args]" may span multiple lines, but
    # it ends in the first line with only a # or a non-comment line.
    # Function description may contain multiple paragraphs but each
    # line must begin with a #. The usage comment may be separated
    # from the function definition by blank lines.
    awk '
        # Blank line (or spaces or tabs only)
        /^[ \t]*$/ {
            empty = 1
            next
        }
        # If a comment beginning with the function name follows an
        # empty line, begin collecting a usage comment
        empty && /^# '"$func"'( |$)/ {
            collect = 1
            comment = $0
            next
        }
        # Collect the usage comment until a line with only a comment
        # character (possibly followed by spaces) if not verbose, or
        # until a non-comment line if verbose
        collect && (/^[^#]/ || (/^#[ \t]*$/ && ! '"$verbose"')) {
            collect = 0
        }
        # Add the line to the comment
        collect {
            comment = comment "\n" $0
            next
        }
        # The definition of the specified function follows, so print
        # the comment and exit
        comment && /^'"$func"' \(\)/ {
            print comment
            exit
        }
        # A collected comment is followed by something else than the
        # definition of the specified function, so discard the comment
        comment && /^[ \t]*[^# \t]/ {
            comment = ""
        }
        # Non-empty line
        empty && /^[^ \t]/ {
            empty = 0
        }
    ' $_shlibdir/*.sh |
        cut -c3- |
        tee $tmp_prefix.out
    if [ ! -s $tmp_prefix.out ]; then
        warn "No usage information found for function \"$func\""
    fi
    exit
fi


echo_verb "Calling korp-lib.sh function: $func $(echo_quoted "$@")"
echo_verb "Output:"
if [ "x$trace" != x ]; then
    set -vx
fi
$func "$@"
return_value=$?
set +vx
echo_verb "Return value: $return_value"
exit $return_value