Add new `includes' module for exploring the bsdconfig(8) API.

8 files changed, 342 insertions, 3 deletions

diff --git a/usr.sbin/bsdconfig/Makefile b/usr.sbin/bsdconfig/Makefile
index 13cc1c7..72187de 100644
--- a/usr.sbin/bsdconfig/Makefile
+++ b/usr.sbin/bsdconfig/Makefile
@@ -6,6 +6,7 @@ SUBDIR=	console \
 	dot \
 	examples \
 	include \
+	includes \
 	mouse \
 	networking \
 	packages \
diff --git a/usr.sbin/bsdconfig/includes/INDEX b/usr.sbin/bsdconfig/includes/INDEX
new file mode 100644
index 0000000..6e829be
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/INDEX
@@ -0,0 +1,56 @@
+# Copyright (c) 2013 Devin Teske
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. 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.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+#
+# $FreeBSD$
+
+#
+# Title that will be shown in the bsdconfig menu.
+#
+menu_title=""
+
+#
+# A short descriptive line shown at the bottom of the bsdconfig menu. keep it
+# short because any line longer than the terminal width will be truncated.
+#
+menu_help=""
+
+#
+# Two-part variable that defines an action to take when `keyword' is passed on
+# a bsdconfig command line. Variable takes the form "keyword|command" and
+# multiple occurrences of the variable (with different `keyword's, or different
+# `keyword's AND `command's) are allowed.  If `command' begins with a '/' then
+# the full path to the program is needed. If `command' begins with anything
+# else it is a path relative to the directory this INDEX file is in. `keyword'
+# can be i18n'ed but `command' is the name of a script.
+#
+menu_selection="includes|includes"
+
+#
+# ------------ Items below this line do NOT need i18n translation ------------
+#
+# Name of the program to be run when this menu choice is selected. If it begins
+# with a '/' then the full path to the program is needed. If it begins with
+# anything else it is a path relative to the directory this INDEX file is in.
+#
+menu_program=""
diff --git a/usr.sbin/bsdconfig/includes/Makefile b/usr.sbin/bsdconfig/includes/Makefile
new file mode 100644
index 0000000..f7cbc1e
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/Makefile
@@ -0,0 +1,16 @@
+# $FreeBSD$
+
+NO_OBJ=
+
+SUBDIR= include
+
+FILESDIR=	${LIBEXECDIR}/bsdconfig/includes
+FILES=		INDEX USAGE
+
+SCRIPTSDIR=	${FILESDIR}
+SCRIPTS=	includes
+
+beforeinstall:
+	mkdir -p ${DESTDIR}${FILESDIR}
+
+.include <bsd.prog.mk>
diff --git a/usr.sbin/bsdconfig/includes/USAGE b/usr.sbin/bsdconfig/includes/USAGE
new file mode 100644
index 0000000..48dead2
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/USAGE
@@ -0,0 +1,66 @@
+# Copyright (c) 2013 Devin Teske
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. 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.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+#
+# $FreeBSD$
+
+Usage: bsdconfig @PROGRAM_NAME@ [OPTIONS] [include ...]
+
+OPTIONS:
+	-a    Always use color even when output is not to a terminal.
+	-f    Show functions for selected includes.
+	-F pattern
+	      If `-f', only print functions matching pattern. Without `-f'
+	      print only includes containing functions matching pattern.
+	-h    Print this usage statement and exit.
+	-n    Disable the use of color.
+
+EXAMPLES:
+	View a list of available includes:
+
+		bsdconfig @PROGRAM_NAME@
+
+	View functions for all available includes (function names are
+	highlighted):
+
+		bsdconfig @PROGRAM_NAME@ -f
+
+	View functions with less(1) (function names are not highlighted):
+
+		bsdconfig @PROGRAM_NAME@ -f | less
+
+	View functions with less(1) and color:
+
+		bsdconfig @PROGRAM_NAME@ -af | less -R
+
+	View functions from `common.subr':
+
+		bsdconfig @PROGRAM_NAME@ common.subr
+
+	NB: The `-f' flag is implied when given an include.
+
+	Show only functions containing the word `show' in common.subr:
+
+		bsdconfig @PROGRAM_NAME@ -F show common
+
+	NB: The `.subr' suffix on the end of the include is optional.
diff --git a/usr.sbin/bsdconfig/includes/include/Makefile b/usr.sbin/bsdconfig/includes/include/Makefile
new file mode 100644
index 0000000..79c4481
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/include/Makefile
@@ -0,0 +1,11 @@
+# $FreeBSD$
+
+NO_OBJ=
+
+FILESDIR=	${LIBEXECDIR}/bsdconfig/includes/include
+FILES=		messages.subr
+
+beforeinstall:
+	mkdir -p ${DESTDIR}${FILESDIR}
+
+.include <bsd.prog.mk>
diff --git a/usr.sbin/bsdconfig/includes/include/messages.subr b/usr.sbin/bsdconfig/includes/include/messages.subr
new file mode 100644
index 0000000..8fa881b
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/include/messages.subr
@@ -0,0 +1,28 @@
+# Copyright (c) 2013 Devin Teske
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. 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.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+#
+# $FreeBSD$
+
+msg_functions_in="Functions in %s:"
+msg_functions_in_matching="Functions in %s matching \`%s':"
diff --git a/usr.sbin/bsdconfig/includes/includes b/usr.sbin/bsdconfig/includes/includes
new file mode 100755
index 0000000..cfbfb98
--- /dev/null
+++ b/usr.sbin/bsdconfig/includes/includes
@@ -0,0 +1,161 @@
+#!/bin/sh
+#-
+# Copyright (c) 2013 Devin Teske
+# All rights reserved.
+#
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions
+# are met:
+# 1. Redistributions of source code must retain the above copyright
+#    notice, this list of conditions and the following disclaimer.
+# 2. 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.
+#
+# THIS SOFTWARE IS PROVIDED BY THE AUTHOR 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 AUTHOR 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.
+#
+# $FreeBSD$
+#
+############################################################ INCLUDES
+
+# Prevent common.subr from auto initializing debugging (this is not an inter-
+# active utility that requires debugging).
+#
+DEBUG_SELF_INITIALIZE=NO
+
+BSDCFG_SHARE="/usr/share/bsdconfig"
+. $BSDCFG_SHARE/common.subr || exit 1
+f_dprintf "%s: loading includes..." "$0"
+
+BSDCFG_LIBE="/usr/libexec/bsdconfig" APP_DIR="includes"
+f_include_lang $BSDCFG_LIBE/include/messages.subr
+f_include_lang $BSDCFG_LIBE/$APP_DIR/include/messages.subr
+
+ipgm=$( f_index_menusel_keyword $BSDCFG_LIBE/$APP_DIR/INDEX "$pgm" )
+[ $? -eq $SUCCESS -a "$ipgm" ] && pgm="$ipgm"
+
+############################################################ GLOBALS
+
+#
+# Options
+#
+USE_COLOR=1
+SHOW_FUNCS=
+FUNC_PATTERN=
+
+############################################################ FUNCTIONS
+
+# show_functions $file
+#
+# Show the functions in the given include file.
+#
+show_include()
+{
+	local file="${1#./}"
+
+	local pattern="${FUNC_PATTERN:-.*}"
+	output=$( awk -v use_color=${USE_COLOR:-0} -v re="$pattern" '
+	/^$/,/^#/ {
+		if ($0 ~ /^# f_/) {
+			if (!match($2, re)) next
+			if (use_color)
+				printf " %s%s%s\n",
+				       substr($0, 2, RSTART),
+				       substr($0, 2 + RSTART, RLENGTH),
+				       substr($0, 2 + RSTART + RLENGTH)
+			else
+				print substr($0, 2)
+			print_more = substr($0, length($0)) == "\\"
+		}
+		while (print_more) {
+			getline
+			print substr($0, 2)
+			print_more = substr($0, length($0)) == "\\"
+		}
+	}' "$file" )
+	if [ "$output" ]; then
+		if [ ! "$SHOW_FUNCS" ]; then
+			echo "$file"
+			return $SUCCESS
+		fi
+		if [ "$FUNC_PATTERN" ]; then
+			printf "$msg_functions_in_matching\n" \
+			       "$file" "$FUNC_PATTERN"
+		else
+			printf "$msg_functions_in\n" "$file"
+		fi
+		echo "$output"
+		echo # blank line to simplify awk(1)-based reparse
+	fi
+}
+
+############################################################ MAIN
+
+# Incorporate rc-file if it exists
+[ -f "$HOME/.bsdconfigrc" ] && f_include "$HOME/.bsdconfigrc"
+
+# Are we in a terminal?
+[ -t 1 ] || USE_COLOR=
+
+#
+# Process command-line arguments
+#
+while getopts afF:hn flag; do
+	case "$flag" in
+	a) USE_COLOR=1 ;;
+	f) SHOW_FUNCS=1 ;;
+	F) FUNC_PATTERN="$OPTARG" ;;
+	n) USE_COLOR= ;;
+	h|\?) f_usage $BSDCFG_LIBE/$APP_DIR/USAGE "PROGRAM_NAME" "$pgm" ;;
+	esac
+done
+shift $(( $OPTIND - 1 ))
+
+# cd(1) to `share' dir so relative paths work for find and positional args
+cd $BSDCFG_SHARE || f_die 1 "$msg_directory_not_found" "$BSDCFG_SHARE"
+
+#
+# If given an argument, operate on it specifically (implied `-f') and exit
+#
+[ $# -gt 0 ] && SHOW_FUNCS=1
+for include in "$@"; do
+	# See if they've just omitted the `*.subr' suffix
+	[ -f "$include.subr" -a ! -f "$include" ] && include="$include.subr"
+	if [ ! -f "$include" ]; then
+		f_die 1 "$msg_no_such_file_or_directory" "$0" "$include"
+	elif [ ! -r "$include" ]; then
+		f_die 1 "$msg_permission_denied" "$0" "$include"
+	fi
+	show_include "$include" || f_die
+done
+
+# Exit if we processed some include arguments
+[ $# -gt 0 ] && exit $SUCCESS
+
+#
+# Operate an all known include files
+# NB: If we get this far, we had no include arguments
+#
+find -s . -type f -and -iname '*.subr' | while read file; do
+	if [ "$SHOW_FUNCS" -o "$FUNC_PATTERN" ]; then
+		show_include "$file"
+	else
+		echo "${file#./}"
+	fi
+done
+
+exit $SUCCESS
+
+################################################################################
+# END
+################################################################################
diff --git a/usr.sbin/bsdconfig/share/variable.subr b/usr.sbin/bsdconfig/share/variable.subr
index b947529..55bc850 100644
--- a/usr.sbin/bsdconfig/share/variable.subr
+++ b/usr.sbin/bsdconfig/share/variable.subr
@@ -179,7 +179,7 @@ f_debugging()
 	f_getvar $VAR_DEBUG value && [ "$value" ]
 }
 
-# f_interactive()
+# f_interactive
 #
 # Are we running interactively? Return error if $nonInteractive is set and non-
 # NULL, otherwise return success.
@@ -190,7 +190,7 @@ f_interactive()
 	! f_getvar $VAR_NONINTERACTIVE value || [ ! "$value" ]
 }
 
-# f_netinteractive()
+# f_netinteractive
 #
 # Has the user specifically requested the network-portion of configuration and
 # setup to be performed interactively? Returns success if the user has asked
@@ -205,7 +205,7 @@ f_netinteractive()
 	f_getvar $VAR_NETINTERACTIVE value && [ "$value" ]
 }
 
-# f_zfsinteractive()
+# f_zfsinteractive
 #
 # Has the user specifically requested the ZFS-portion of configuration and
 # setup to be performed interactively? Returns success if the user has asked