#! /bin/sh

# Copyright 2014 The Kyua Authors.

# All rights reserved.

#

# Redistribution and use in source and binary forms, with or without

# modification, are permitted provided that the following conditions are

# met:

#

# * Redistributions of source code must retain the above copyright

#   notice, this list of conditions and the following disclaimer.

# * Redistributions in binary form must reproduce the above copyright

#   notice, this list of conditions and the following disclaimer in the

#   documentation and/or other materials provided with the distribution.

# * Neither the name of Google Inc. nor the names of its contributors

#   may be used to endorse or promote products derived from this software

#   without specific prior written permission.

#

# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

# "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

# LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

# A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

# OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

# SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT

# LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,

# DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY

# THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT

# (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE

# OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

# \file doc/manbuild.sh

# Generates a manual page from a source file.

#

# Input files can have __VAR__-style patterns in them that are replaced

# with the values provided by the caller via the -v VAR=VALUE flag.

#

# Input files can also include other files using the __include__ directive,

# which takes a relative path to the file to include plus an optional

# collection of additional variables to replace in the included file.

# Name of the running program for error reporting purposes.

Prog_Name="${0##*/}"

# Prints an error message and exits.

#

# Args:

#   ...: The error message to print.  Multiple arguments are joined with a

#       single space separator.

err() {

    echo "${Prog_Name}: ${*}" 1>&2

    exit 1

}

# Invokes sed(1) translating input variables to expressions.

#

# Args:

#   ...: List of var=value pairs to replace.

#

# Returns:

#   True if the operation succeeds; false otherwise.

sed_with_vars() {

    local vars="${*}"

    set --

    for pair in ${vars}; do

        local var="$(echo "${pair}" | cut -d = -f 1)"

        local value="$(echo "${pair}" | cut -d = -f 2-)"

        set -- "${@}" -e"s&__${var}__&${value}&g"

    done

    if [ "${#}" -gt 0 ]; then

        sed "${@}"

    else

        cat

    fi

}

# Generates the manual page reading from stdin and dumping to stdout.

#

# Args:

#   include_dir: Path to the directory containing the include files.

#   ...: List of var=value pairs to replace in the manpage.

#

# Returns:

#   True if the generation succeeds; false otherwise.

generate() {

    local include_dir="${1}"; shift

    while :; do

        local read_ok=yes

        local oldifs="${IFS}"

        IFS=

        read -r line || read_ok=no

        IFS="${oldifs}"

        [ "${read_ok}" = yes ] || break

        case "${line}" in

            __include__*)

                local file="$(echo "${line}" | cut -d ' ' -f 2)"

                local extra_vars="$(echo "${line}" | cut -d ' ' -f 3-)"

                # If we fail to output the included file, just leave the line as

                # is.  validate_file() will later error out.

                [ -f "${include_dir}/${file}" ] || echo "${line}"

                generate <"${include_dir}/${file}" "${include_dir}" \

                    "${@}" ${extra_vars} || echo "${line}"

                ;;

            *)

                echo "${line}"

                ;;

        esac

    done | sed_with_vars "${@}"

}

# Validates that the manual page has been properly generated.

#

# In particular, this checks if any directives or common replacement patterns

# have been left in place.

#

# Returns:

#   True if the manual page is valid; false otherwise.

validate_file() {

    local filename="${1}"

    if grep '__[A-Za-z0-9]*__' "${filename}" >/dev/null; then

        return 1

    else

        return 0

    fi

}

# Program entry point.

main() {

    local vars=

    while getopts :v: arg; do

        case "${arg}" in

            v)

                vars="${vars} ${OPTARG}"

                ;;

            \?)

                err "Unknown option -${OPTARG}"

                ;;

        esac

    done

    shift $((${OPTIND} - 1))

    [ ${#} -eq 2 ] || err "Must provide input and output names as arguments"

    local input="${1}"; shift

    local output="${1}"; shift

    trap "rm -f '${output}.tmp'" EXIT HUP INT TERM

    generate "$(dirname "${input}")" ${vars} \

        <"${input}" >"${output}.tmp" \

        || err "Failed to generate ${output}"

    if validate_file "${output}.tmp"; then

        :

    else

        err "Failed to generate ${output}; some patterns were left unreplaced"

    fi

    mv "${output}.tmp" "${output}"

}

main "${@}"