path: root/tools/shman.sh

#!/bin/sh
#
# Shell command language manual generator
#
# Copyright (C) 2018  Patrick McDermott
#
# This program is free software: you can redistribute it and/or modify
# it under the terms of the GNU General Public License as published by
# the Free Software Foundation, either version 3 of the License, or
# (at your option) any later version.
#
# This program is distributed in the hope that it will be useful,
# but WITHOUT ANY WARRANTY; without even the implied warranty of
# MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
# GNU General Public License for more details.
#
# You should have received a copy of the GNU General Public License
# along with this program.  If not, see <http://www.gnu.org/licenses/>.

# Man, shman!

set -u

VERSION='0.1.0'
LF='
'
FUNC_CMDS='brief option operand details return'

warn()
{
	local fmt="${1}"
	shift 1

	printf "shman: Warning: ${fmt}\n" "${@}" >&2
}

get_mtime()
{
	local file="${1}"
	shift 1
	local m=
	local d=
	local y=
	local now_m=
	local now_y=

	read m d y <<-EOF
		$(LC_ALL=POSIX ls -l "${file}" | cut -d ' ' -f 6-8)
		EOF
	case "${m}" in
		'Jan')  m=1;; 'Feb')  m=2;; 'Mar')  m=3;; 'Apr')  m=4;;
		'May')  m=5;; 'Jun')  m=6;; 'Jul')  m=7;; 'Aug')  m=8;;
		'Sep')  m=9;; 'Oct') m=10;; 'Nov') m=11;; 'Dec') m=12;;
	esac
	case "${y}" in *':'*)
		read now_m now_y <<-EOF
			$(date '+%m %Y')
			EOF
		now_m="${now_m#'0'}"
		if [ ${now_m} -ge ${m} ]; then
			y=${now_y}
		else
			y=$((${now_y} - 1))
		fi
	esac

	printf '%d-%02d-%02d' ${y} ${m} ${d}
}

gen_doc_func()
{
	local sym="${1}"
	local doc="${2}"
	shift 2
	local cmd=
	local args=
	local sect_name=
	local sect_desc=
	local sect_ret=

	sect_name=".SH NAME${LF}${sym}"
	while read -r cmd args; do
		case "${cmd}" in
			'brief')
				sect_name="${sect_name} - ${args}"
				;;
			'details')
				sect_desc=".SH DESCRIPTION${LF}${args}"
				;;
			'return')
				sect_ret=".SH RETURN VALUE${LF}${args}"
				;;
		esac
	done <<-EOF
		${doc}
		EOF

	printf '%s\n\n' "${sect_name}" "${sect_desc}" "${sect_ret}"
}

gen_doc()
{
	local date="${1}"
	local source="${2}"
	local manual="${3}"
	local sym="${4}"
	local is_func="${5}"
	local doc="${6}"
	local out_dir="${7}"
	shift 7
	local doc_joined=''
	local sym_upper=

	# Join command lines
	while read -r line; do
		case "${line}" in
			'@'*)
				doc_joined="${doc_joined}${LF}${line#'@'}"
				;;
			*)
				doc_joined="${doc_joined} ${line}"
				;;
		esac
	done <<-EOF
		${doc}
		EOF
	doc="${doc_joined#${LF}}"
	# Now each line in ${doc} should begin with a command name and thus be
	# easier to parse.

	sym_upper="$(printf '%s\n' "${sym}" | tr '[:lower:]' '[:upper:]')"
	{
		if ${is_func}; then
			printf '.TH %s 3 "%s" "%s" "%s"\n\n' \
				"${sym_upper}" "${date}" "${source}" "${manual}"
			gen_doc_func "${sym}" "${doc}"
		fi
	} >"${out_dir}/${sym}.3"
}

parse_docs()
{
	local file="${1}"
	local source="${2}"
	local manual="${3}"
	local out_dir="${4}"
	local tags="${5}"
	shift 5
	local date=
	local line=
	local doc=''
	local got_doc=false
	local is_func=false

	date="$(get_mtime "${file}")"

	while IFS='' read -r line; do
		case "${line}" in
			'##'*)
				## Strip "##" and leading and trailing whitespace
				#read -r line <<-EOF
				#	${line#'##'}
				#	EOF
				doc="${doc}${line#'##'}${LF}"
				got_doc=true
				continue
				;;
			'')
				continue
				;;
			*'()') line="${line%'()'}"  is_func=true;;
			*'='*) line="${line%%'='*}" is_func=false;;
			*)
				doc=''
				got_doc=false
				continue
				;;
		esac
		case "${line}" in [!a-zA-Z]*|*[!a-zA-Z0-9_]*) continue;; esac
		if ${got_doc}; then
			gen_doc "${date}" "${source}" "${manual}" \
				"${line}" ${is_func} "${doc}" "${out_dir}"
			doc=''
			got_doc=false
		elif ${is_func}; then
			warn 'Undocumented function "%s"' "${line}"
		fi
	done <"${file}"
}

usage()
{
	printf 'Usage: %s [option ...] <file>...\n' "${0}"
}

help()
{
	usage
	cat <<EOF
Options:
  -h            Display this information
  -V            Display version information
  -s <source>   The source of the manual pages, e.g. a package name and version
                [default: "Shell"]
  -m <manual>   The title of the manual [default: "Shell Functions"]
  -d <out_dir>  The directory in which to write manual pages [default: the
                current working directory]
  -t <tags>     A file in which to list all documented symbols
EOF
}

version()
{
	cat <<EOF
shman ${VERSION}
Copyright (C) 2018  Patrick McDermott
License GPLv3+: GNU GPL version 3 or later <http://gnu.org/licenses/gpl.html>.
This is free software: you are free to change and redistribute it.
There is NO WARRANTY, to the extent permitted by law.
EOF
}

main()
{
	local opt=
	local source='Shell'
	local manual='Shell Functions'
	local out_dir='.'
	local tags=''
	local f=

	while getopts 'hVs:m:d:t:' opt; do
		case "${opt}" in
			'h')
				help
				exit
				;;
			'V')
				version
				exit
				;;
			's')
				source="${OPTARG}"
				;;
			'm')
				manual="${OPTARG}"
				;;
			'd')
				out_dir="${OPTARG}"
				;;
			't')
				tags="${OPTARG}"
				;;
		esac
	done
	shift $(($OPTIND - 1))

	if [ ${#} -lt 1 ]; then
		usage >&2
		exit 1
	fi

	for f in "${@}"; do
		parse_docs "${f}" "${source}" "${manual}" "${out_dir}" "${tags}"
	done
}

main "${@}"