shellfu/src/bin/sfdoc

#!/bin/bash
#shellcheck disable=SC1090

. "$(sfpath)" || exit 3

shellfu import pretty
shellfu import sfdoc


usage() {
    mkusage \
        "[options] MODULE"                                              \
        "[options] --ls [MODULE]"                                       \
        "[options] --ls{var|fun} MODULE"                                \
        "[options] --which"                                             \
        "[options] --lsmod"                                             \
        "[options] --export FMT MODULE"                                 \
        -c                                                              \
            "-l, --ls [MODULE]  list contents of MODULE if specified,"  \
            "                   otherwise of all modules"               \
            "-L, --lsmod        show list of modules"                   \
            " --lsfun MODULE    show list of functions in MODULE"       \
            " --lsvar MODULE    show list of variables in MODULE"       \
            " --which MODULE    show path to MODULE file"               \
            "-e, --export FMT MODULE   export MODULE documentation in"  \
            "                   format FMT: 'markdown', 'manpage' and"  \
            "                   'pod' are supported"                    \
        -o                                                              \
            "-d, --debug        Turn on debugging"                      \
            "-a, --all          Don't ignore hidden (starting with"     \
            "                   underscore) modules or objects"         \
            "--encoding         Override encoding of the source text"   \
            "                   (default: utf8)"                        \
            "--name             Override module name (useful when"      \
            "                   exporting from a file and the filename" \
            "                   is not helpful)"                        \
            "-I PTH, --include PTH  Include path PTH when searching"    \
            "                   for modules; can be specified multiple" \
            "                   times."                                 \
            "-o PTH, --only-from PTH  Search only under path PTH."      \
        --                                                              \
        "Without command specified, will try to display documentation"  \
        "in man(1) pager."
}

select_mfile() {
    #
    # Find and/or verify file that holds module $1
    #
    local module=$1
    local mfile
    case $module in
        */*)    mfile="$module" ;;
        *)      mfile=$(shellfu _select_mfile "$module") ;;
    esac
    debug -v mfile
    test -n "$mfile" || { warn "no such module found: $module"; return 3; }
    test -f "$mfile" || { warn "no such file found: $mfile"; return 3; }
    echo "$mfile"
}

main() {
    local action            # what to do
    local format            # export format
    local module            # module name or path/to/module.sh
    local m                 # module helper var
    local RealModuleName    # name to override eg. if accessing via filename
    local encoding          # encoding
    local mpath             # path to module file
    action=man
    format=markdown
    encoding=utf8
    #shellcheck disable=SC2034
    while true; do case "$1" in
        -d|--debug)     PRETTY_DEBUG=true;          shift ;;
        -a|--all)       SFDOC_SHOW_HIDDEN=true;     shift ;;
        -I|--include)   SHELLFU_PATH="$2:$SHELLFU_PATH"; shift 2 || usage ;;
        -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 ;;
        --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 ;;
        *)                                          break ;;
    esac done
    module="$1"; shift
    debug -v SHELLFU_INCLUDE SHELLFU_PATH SFDOC_SHOW_HIDDEN
    debug -v action format module RealModuleName
    case $action:$module in
        lsx:*|lsm:*|wch:*) true ;;
        *:)             usage ;;
    esac
    case $action in
        lsm|wch) : ;;
        *)      mpath=$(select_mfile "$module") || die ;;
    esac
    case $action in
        exp)    # --export
            grep -qw "$format" <<<manpage,markdown,pod \
             || die "unknown format: $format"
            sfdoc__export "$format" "${RealModuleName:-$module}" "$mpath" "$encoding"
            ;;
        lsm)    # --lsmod
            sfdoc__ls_m | LC_ALL=C sort
            ;;
        lsv)    # --lsvar MODULE
            sfdoc__ls v "$mpath" | LC_ALL=C sort
            ;;
        lsf)    # --lsfun MODULE
            sfdoc__ls f "$mpath" | LC_ALL=C sort
            ;;
        lsx)    # --ls [MODULE]
            case $module in
                "") shellfu _list_mfiles ;;
                *)  echo "$mpath" ;;
            esac \
              | while read -r m;
                do
                    sfdoc__ls v "$m"
                    sfdoc__ls f "$m"
                done \
              | LC_ALL=C sort
            ;;
        man)
            which pod2man &>/dev/null \
             || die "pod2man is missing cannot use man page mode"
            sfdoc__export manpage "${RealModuleName:-$module}" "$mpath" "$encoding" \
              | man -l -
            ;;
        wch)
            select_mfile "$module"
            ;;
    esac
}

main "$@"