formatter

#!/usr/bin/env bash
# shellcheck disable=SC2016,SC2119


__f_show_help() {
	printf "%s" "
$(f_heading "formatter" | f_fg_yellow)

utilities for shell output formatting.


$(f_subheading "usage")

$(f_code_block \
"sh" \
'[env FORMAT=terminal|markdown|raw ;] source ./formatter')

$(f_code_block \
"sh" \
'./formatter -h')


$(f_subheading "flags")

$(f_code_definition \
"-h" \
"shows this help message. works only when the script is executed (not sourced).")


$(f_subheading "API")
 
when the formatter is sourced, it exposes an API composed of two parts; \
tags and functions.

some tags or functions will only be applied in a certain format, e.g. \
$(f_code 'terminal'). in such cases, the available formats will be  marked in \
the description body, with $(f_bold "available in: <formats...>").
if no available formats are mentioned, the rendering will apply on all formats.


$(f_subheading "tags") 

tags are predefined variables that can be used to format text terms.
wrap the terms with a start tag in the form $(f_code '_f_<name>'), and a close \
tag in the form $(f_code '_f_<name>_off').

the definitions below describe only the start tag, for brevity.

$(f_code_definition '_f_bold' \
"formats the text as bold.")

$(f_code_definition '_f_italics' \
"formats the text as italics.")

$(f_code_definition '_f_strike' \
"formats the text as strike-through.")

$(f_code_definition '_f_under' \
"$(f_sup "available in: $(f_bold "terminal")")
formats the text as underlined.")

$(f_code_definition '_f_code' \
"formats the text as inline code.")

$(f_code_definition '_f_sub' \
"$(f_sup "available in: $(f_bold "markdown")")
formats the text as sub-text.")

$(f_code_definition '_f_sup' \
"$(f_sup "available in: $(f_bold "markdown")")
formats the text as super-text.")

$(f_code_definition '_f_fg_<color>' \
"$(f_sup "available in: $(f_bold "terminal")")
applies foreground color to the text.")

$(f_code_definition '_f_bg_<color>' \
"$(f_sup "available in: $(f_bold "terminal")")
applies background color to the text.")


$(f_subheading "functions") 

most of the tag variables has equivalent functions. they all follow the \
$(f_code 'f_<name>()') convention.

formatter functions can be piped, or accept arguments. those that can do both, 
with no side effects, will be marked with $(f_bold "composeable").

$(f_code_definition 'f_bold(string...)' \
"$(f_sup "composeable" | f_bold)
formats passed arguments as bold text.")

$(f_code_definition 'f_italics(string...)' \
"$(f_sup "composeable" | f_bold)
formats passed arguments as italics text.")

$(f_code_definition 'f_strike(string...)' \
"$(f_sup "composeable" | f_bold)
formats passed arguments as strike-through text.")

$(f_code_definition 'f_under(string...)' \
"$(f_sup "composeable" | f_bold)
$(f_sup "available in: $(f_bold "terminal")")
formats passed arguments as underlined text.")

$(f_code_definition 'f_code(string...)' \
"$(f_sup "composeable" | f_bold)
formats passed arguments as inline code.
note to always pass arguments with $(f_code "'strong quoting'"), \
or properly escape them, to avoid arbitrary code being interpreted by the shell.")

$(f_code_definition 'f_sub(string...)' \
"$(f_sup "composeable" | f_bold)
$(f_sup "available in: $(f_bold "markdown")")
formats passed arguments as sub-text.")

$(f_code_definition 'f_sup(string...)' \
"$(f_sup "composeable" | f_bold)
$(f_sup "available in: $(f_bold "markdown")")
formats passed arguments as super-text.")

$(f_code_definition 'f_link([name], target)' \
"formats passed arguments as an inline link. if $(f_code "name") is passed, \
it will be used in the markdown format to name the link. the target will be \
used as the link ref.")

$(f_code_definition 'f_fg_<color>(string...)' \
"$(f_sup "composeable" | f_bold)
$(f_sup "available in: $(f_bold "terminal")")
applies foreground color to passed arguments. e.g. $(f_code 'f_fg_red("my text")').")

$(f_code_definition 'f_bg_<color>(string...)' \
"$(f_sup "composeable" | f_bold)
$(f_sup "available in: $(f_bold "terminal")")
applies background color to passed arguments. e.g. $(f_code 'f_bg_red("my text")')")

$(f_code_definition 'f_heading(string)' \
"$(f_sup "composeable" | f_bold)
formats the passed $(f_code 'string') as heading.")

$(f_code_definition 'f_subheading(string)' \
"$(f_sup "composeable" | f_bold)
formats the passed $(f_code 'string') as subheading.")

$(f_code_definition 'f_list_item([title], body)' \
"formats passed arguments as a list item. if $(f_code "title") is passed, it will \
appear as the list item's first line, and will be styled as bold.")

$(f_code_definition 'f_definition(term, description)' \
"formats passed arguments as a definition list item. $(f_code "term") is used as \
the item's term, and $(f_code "description") is used as the item's description \
(its body content).
note that only $(f_code 'inline code') and $(f_bold "bold") styles are allowed \
to be nested inside definition list items.")

$(f_code_definition 'f_code_definition(term, description)' \
"same as $(f_code "f_definition()"), except $(f_code "term") is formatted as \
inline code.")

$(f_code_definition 'f_code_block([lang], body)' \
"formats passed arguments as a code block. if $(f_code "lang") is passed, \
it will be used in the markdown format to highlight the code block. \
allowed $(f_code "lang") values are those allowed in github-flavored markdown \
code blocks.
note to always enclose the passed $(f_code 'body') in $(f_code "'strong quotes'"), \
or properly escape it, to avoid arbitrary code being interpreted by the shell.")

$(f_code_definition 'f_output(body)' \
"formats passed arguments as an output block. in markdown this is the same as \
$(f_code 'f_code_block'), and in terminal every line of the body will be \
prefixed with an arrow, to mark code output.")

$(f_code_definition 'f_if(format, content)' \
"only renders the $(f_code 'content') if the current format matches the passed \
$(f_code 'format').")


$(f_subheading "colors")

here are the available color names to be used with the color formatting tags \
and functions:

$(f_code_block \
'red
green
yellow
blue
magenta
cyan
lightred
lightgreen
lightyellow
lightblue
lightmagenta
lightcyan')


$(f_subheading "examples")

$(f_list_item \
"wrapping with tags" \
"$(f_code_block \
"sh" \
'echo "${_f_bold}this text will be bold${_f_bold_off}"
echo "text can be ${_f_under}underlined${_f_under_off} as well"
echo "color me ${_f_fg_yellow}yellow${_f_fg_off}"')")

$(f_list_item \
"using functions" \
"$(f_code_block \
"sh" \
'echo "$(f_heading "foo")"
echo "$(echo "foo" | f_heading)"
echo "$(echo "foo" | f_heading | f_fg_yellow)"')

you can also skip the inner echo, if you're using composeable functions:

$(f_code_block \
"sh" \
'echo "$(f_heading "foo" | f_fg_yellow)"')
$(f_if "terminal" "
$(f_output \
"$(f_heading "yellow heading" | f_fg_yellow)")")

$(f_code_block \
"sh" \
'echo "$(f_fg_yellow "foo" | f_bold | f_under)"')
$(f_if "terminal" "
$(f_output \
"$(f_fg_yellow "yellow bold underlined" | f_bold | f_under)")")

some formatter functions cannot be composed, but can still be used regardless:

$(f_code_block \
"sh" \
'echo "$(f_fg_rainbow "the quick brown fox jumps over the lazy dog")"')
$(f_if "terminal" "
$(f_output \
"$(f_fg_rainbow "the quick brown fox jumps over the lazy dog")")")")

$(f_subheading "gotcha's")

$(f_list_item \
"nesting formats may not behave as expected with the $(f_code 'terminal') format, \
as some closing tags reset all formatting.")
$(f_list_item \
"heavy use of formatter functions will impact performance, so use them wisely.")


$(f_subheading "references")

$(f_list_item \
"the colors used here are based on the $(f_link "SMYCK color scheme" 'http://color.smyck.org/').")
$(f_list_item \
"the hex color values from SMYCK were converted to their xterm-256 ansi approximations with $(f_link "colortrans.py" 'https://gist.github.com/MicahElliott/719710').")

"
	exit 0
}


# parses function input from stdin or passed arguments
# usage:
# local input=$(__f_util_input "$@")
__f_util_input() {
	local input
	if [ ! -p /dev/stdin ]; then
		if [ $# -gt 0 ]; then
			input="$*"
		fi
	else
		input=$(cat -)
	fi
	printf "%s" "$input"
}

__f_util_noop() {
	printf "%s" "$(__f_util_input "$@")"
}

__f_util_resolve_format() {
	local format
	# shellcheck disable=SC2153
	if type "__f_init_api_$FORMAT" >/dev/null 2>&1; then
		format="$FORMAT"
	else
		format="terminal"
	fi
	printf "%s" "$format"
}

__f_util_switch() {
	local match_format="$1"; shift
	local format
	local output
	format=$(__f_util_resolve_format)
	if [[ $format = "$match_format" ]]; then
		output=$(__f_util_input "$@")
	fi
	printf "%s" "$output"
}

__f_util_trim_start() {
	local input
	input=$(__f_util_input "$@")
	printf "%s" "$input" | sed -e '1s,[[:space:]][[:space:]]*\(.*\),\1,'
}

__f_util_repeat() {
	local n
	local str=""
	for (( n=$2; n > 0; n-- )); do
		str="$str$1"
	done
	printf "%s" "$str"	
}

__f_util_wrap() {
	local tag="$1"; shift
	local tagoff="$1"; shift
	local input
	input=$(__f_util_input "$@")
	printf "%s%s%s" "$tag" "$input" "$tagoff"
}

__f_util_prefix() {
	local prefix="$1"; shift
	local input
	input=$(__f_util_input "$@")
	printf "%s%s" "$prefix" "$input"
}

__f_util_suffix() {
	local suffix="$1"; shift
	local input
	input=$(__f_util_input "$@")
	printf "%s%s" "$input" "$suffix"
}

__f_util_prefix_multiline() {
	local prefix=$1; shift
	local input
	input=$(__f_util_input "$@")
	sed -e 's,^\(.*\)$,'"$prefix"'\1,' <<< "$input"
}

__f_util_suffix_multiline() {
	local suffix=$1; shift
	local input
	input=$(__f_util_input "$@")
	sed -e 's,^\(.*\)$,\1'"$suffix"',' <<< "$input"
}

__f_util_char_underline() {
	local char="$1"; shift
	local suffix="$1"; shift
	local input
	local underline
	input=$(__f_util_input "$@")
	underline="$(__f_util_repeat "$char" ${#input})"
	printf "%s%s\n%s" "$input" "$suffix" "$underline"
}

__f_util_replace_tags() {
	local from_tag="$1"
	local from_tag_off="$2"
	local to_tag="$3"
	local to_tag_off="$4"
	sed -e 's,'"$from_tag"'\([^'"$from_tag_off"']*\)'"$from_tag_off"','"$to_tag"'\1'"$to_tag_off"',g'
}

__f_util_escape_entities() {
	sed -e 's,\&,\&amp;,g' -e 's,\<,\&lt;,g' -e 's,\>,\&gt;,g'
}


# declare all api functions, in case some are not declared later. use pipe-through implementation for all
__f_init_api_stubs() {

	f_bold() {              __f_util_noop "$@"; }
	f_italics() {           __f_util_noop "$@"; }
	f_strike() {            __f_util_noop "$@"; }
	f_code() {              __f_util_noop "$@"; }
	f_under() {             __f_util_noop "$@"; }

	f_fg_red() {            __f_util_noop "$@"; }
	f_fg_green() {          __f_util_noop "$@"; }
	f_fg_yellow() {         __f_util_noop "$@"; }
	f_fg_blue() {           __f_util_noop "$@"; }
	f_fg_magenta() {        __f_util_noop "$@"; }
	f_fg_cyan() {           __f_util_noop "$@"; }
	f_fg_lightred() {       __f_util_noop "$@"; }
	f_fg_lightgreen() {     __f_util_noop "$@"; }
	f_fg_lightyellow() {    __f_util_noop "$@"; }
	f_fg_lightblue() {      __f_util_noop "$@"; }
	f_fg_lightmagenta() {   __f_util_noop "$@"; }
	f_fg_lightcyan() {      __f_util_noop "$@"; }
	f_fg_rainbow() {        __f_util_noop "$@"; }

	f_bg_red() {            __f_util_noop "$@"; }
	f_bg_green() {          __f_util_noop "$@"; }
	f_bg_yellow() {         __f_util_noop "$@"; }
	f_bg_blue() {           __f_util_noop "$@"; }
	f_bg_magenta() {        __f_util_noop "$@"; }
	f_bg_cyan() {           __f_util_noop "$@"; }
	f_bg_lightred() {       __f_util_noop "$@"; }
	f_bg_lightgreen() {     __f_util_noop "$@"; }
	f_bg_lightyellow() {    __f_util_noop "$@"; }
	f_bg_lightblue() {      __f_util_noop "$@"; }
	f_bg_lightmagenta() {   __f_util_noop "$@"; }
	f_bg_lightcyan() {      __f_util_noop "$@"; }

	f_heading() {           __f_util_noop "$@"; }
	f_subheading() {        __f_util_noop "$@"; }
	f_list_item() {         __f_util_noop "$@"; }
	f_definition() {        __f_util_noop "$@"; }
	f_code_definition() {   __f_util_noop "$@"; }
	f_code_block() {        __f_util_noop "$@"; }
	f_link() {              __f_util_noop "$@"; }
	f_output() {            __f_util_noop "$@"; }
	f_sub() {               __f_util_noop "$@"; }
	f_sup() {               __f_util_noop "$@"; }

	f_if() {                __f_util_noop "$@"; }
}

# declare base implementations for common functions that all api flavors share
__f_init_api_common() {

	# uncomposeable functions
	f_if() {                __f_util_switch             "$@"; }

	# composeable functions
	f_bold() {              __f_util_wrap     "$_f_bold"            "$_f_bold_off"      "$@"; }
	f_italics() {           __f_util_wrap     "$_f_italics"         "$_f_italics_off"   "$@"; }
	f_strike() {            __f_util_wrap     "$_f_strike"          "$_f_strike_off"    "$@"; }
	f_code() {              __f_util_wrap     "$_f_code"            "$_f_code_off"      "$@"; }
	# shellcheck disable=SC2120
	f_under() {             __f_util_wrap     "$_f_under"           "$_f_under_off"     "$@"; }

}

# declare/override implementations for terminal api functions and tags
__f_init_api_terminal() {
	local tput_colors

	# shellcheck disable=SC2015
	[[ -t 1 && -t 2 ]] && {
	
		_f_off=$(           tput sgr0                   )

		_f_bold=$(          tput bold   || tput md      )
		_f_bold_off=$_f_off
		_f_italics=$(       tput sitm   || tput ZH      )
		_f_italics_off=$(   tput ritm   || tput ZR      )
		_f_under=$(         tput smul   || tput us      )
		_f_under_off=$(     tput rmul   || tput ue      )
		
		tput_colors=$(tput colors)
		if [[ $tput_colors ]]; then
			# `tput setaf 0 || tput AF 0` cannot be used to reset the foreground, as some 
			# terminal emulators (e.g. iterm2) will set it to explicit black. 
			# too bad, nesting tags in terminal mode may misbehave as a consequence.
			_f_fg_off=$_f_off
			_f_bg_off=$_f_off
			if (( tput_colors >= 256 )); then
				_f_fg_red=$(             tput setaf 167     || tput AF 167  )
				_f_fg_green=$(           tput setaf 107     || tput AF 107  )
				_f_fg_yellow=$(          tput setaf 179     || tput AF 179  )
				_f_fg_blue=$(            tput setaf 74      || tput AF 74   )
				_f_fg_magenta=$(         tput setaf 182     || tput AF 182  )
				_f_fg_cyan=$(            tput setaf 30      || tput AF 30   )
				_f_fg_lightred=$(        tput setaf 174     || tput AF 174  )
				_f_fg_lightgreen=$(      tput setaf 191     || tput AF 191  )
				_f_fg_lightyellow=$(     tput setaf 222     || tput AF 222  )
				_f_fg_lightblue=$(       tput setaf 153     || tput AF 153  )
				_f_fg_lightmagenta=$(    tput setaf 219     || tput AF 219  )
				_f_fg_lightcyan=$(       tput setaf 116     || tput AF 116  )
				_f_bg_red=$(             tput setab 167     || tput AB 167  )
				_f_bg_green=$(           tput setab 107     || tput AB 107  )
				_f_bg_yellow=$(          tput setab 179     || tput AB 179  )
				_f_bg_blue=$(            tput setab 74      || tput AB 74   )
				_f_bg_magenta=$(         tput setab 182     || tput AB 182  )
				_f_bg_cyan=$(            tput setab 30      || tput AB 30   )
				_f_bg_lightred=$(        tput setab 174     || tput AB 174  )
				_f_bg_lightgreen=$(      tput setab 191     || tput AB 191  )
				_f_bg_lightyellow=$(     tput setab 222     || tput AB 222  )
				_f_bg_lightblue=$(       tput setab 153     || tput AB 153  )
				_f_bg_lightmagenta=$(    tput setab 219     || tput AB 219  )
				_f_bg_lightcyan=$(       tput setab 116     || tput AB 116  )
			elif (( tput_colors >= 8 )); then
				_f_fg_red=$(             tput setaf 1       || tput AF 1    )
				_f_fg_green=$(           tput setaf 2       || tput AF 2    )
				_f_fg_yellow=$(          tput setaf 3       || tput AF 3    )
				_f_fg_blue=$(            tput setaf 4       || tput AF 4    )
				_f_fg_magenta=$(         tput setaf 5       || tput AF 5    )
				_f_fg_cyan=$(            tput setaf 6       || tput AF 6    )
				_f_fg_lightred=$_f_fg_red
				_f_fg_lightgreen=$_f_fg_green
				_f_fg_lightyellow=$_f_fg_yellow
				_f_fg_lightblue=$_f_fg_blue
				_f_fg_lightmagenta=$_f_fg_magenta
				_f_fg_lightcyan=$_f_fg_cyan
				_f_bg_red=$(             tput setab 1       || tput AB 1    )
				_f_bg_green=$(           tput setab 2       || tput AB 2    )
				_f_bg_yellow=$(          tput setab 3       || tput AB 3    )
				_f_bg_blue=$(            tput setab 4       || tput AB 4    )
				_f_bg_magenta=$(         tput setab 5       || tput AB 5    )
				_f_bg_cyan=$(            tput setab 6       || tput AB 6    )
				_f_bg_lightred=$_f_bg_red
				_f_bg_lightgreen=$_f_bg_green
				_f_bg_lightyellow=$_f_bg_yellow
				_f_bg_lightblue=$_f_bg_blue
				_f_bg_lightmagenta=$_f_bg_magenta
				_f_bg_lightcyan=$_f_bg_cyan
			fi
		fi

	} 2>/dev/null ||: # protect from "unknown terminfo capability" errors

	_f_strike=$'\033[9m'
	_f_strike_off=$'\033[29m'
	_f_code=$_f_bold
	_f_code_off=$_f_bold_off
	_f_list_item=' - '
	_f_new_line='
'

	f_fg_red() {            __f_util_wrap     "$_f_fg_red"            "$_f_fg_off"      "$@"; }
	f_fg_green() {          __f_util_wrap     "$_f_fg_green"          "$_f_fg_off"      "$@"; }
	f_fg_yellow() {         __f_util_wrap     "$_f_fg_yellow"         "$_f_fg_off"      "$@"; }
	f_fg_blue() {           __f_util_wrap     "$_f_fg_blue"           "$_f_fg_off"      "$@"; }
	f_fg_magenta() {        __f_util_wrap     "$_f_fg_magenta"        "$_f_fg_off"      "$@"; }
	f_fg_cyan() {           __f_util_wrap     "$_f_fg_cyan"           "$_f_fg_off"      "$@"; }
	f_fg_lightred() {       __f_util_wrap     "$_f_fg_lightred"       "$_f_fg_off"      "$@"; }
	f_fg_lightgreen() {     __f_util_wrap     "$_f_fg_lightgreen"     "$_f_fg_off"      "$@"; }
	f_fg_lightyellow() {    __f_util_wrap     "$_f_fg_lightyellow"    "$_f_fg_off"      "$@"; }
	f_fg_lightblue() {      __f_util_wrap     "$_f_fg_lightblue"      "$_f_fg_off"      "$@"; }
	f_fg_lightmagenta() {   __f_util_wrap     "$_f_fg_lightmagenta"   "$_f_fg_off"      "$@"; }
	f_fg_lightcyan() {      __f_util_wrap     "$_f_fg_lightcyan"      "$_f_fg_off"      "$@"; }
	
	f_bg_red() {            __f_util_wrap     "$_f_bg_red"            "$_f_bg_off"      "$@"; }
	f_bg_green() {          __f_util_wrap     "$_f_bg_green"          "$_f_bg_off"      "$@"; }
	f_bg_yellow() {         __f_util_wrap     "$_f_bg_yellow"         "$_f_bg_off"      "$@"; }
	f_bg_blue() {           __f_util_wrap     "$_f_bg_blue"           "$_f_bg_off"      "$@"; }
	f_bg_magenta() {        __f_util_wrap     "$_f_bg_magenta"        "$_f_bg_off"      "$@"; }
	f_bg_cyan() {           __f_util_wrap     "$_f_bg_cyan"           "$_f_bg_off"      "$@"; }
	f_bg_lightred() {       __f_util_wrap     "$_f_bg_lightred"       "$_f_bg_off"      "$@"; }
	f_bg_lightgreen() {     __f_util_wrap     "$_f_bg_lightgreen"     "$_f_bg_off"      "$@"; }
	f_bg_lightyellow() {    __f_util_wrap     "$_f_bg_lightyellow"    "$_f_bg_off"      "$@"; }
	f_bg_lightblue() {      __f_util_wrap     "$_f_bg_lightblue"      "$_f_bg_off"      "$@"; }
	f_bg_lightmagenta() {   __f_util_wrap     "$_f_bg_lightmagenta"   "$_f_bg_off"      "$@"; }
	f_bg_lightcyan() {      __f_util_wrap     "$_f_bg_lightcyan"      "$_f_bg_off"      "$@"; }

	f_fg_rainbow() {
		local input
		local chars
		local i=0
		local colors=('red' 'yellow' 'green' 'cyan' 'blue' 'magenta')
		input=$(__f_util_input "$@")
		chars="$(grep -o . --color=never <<< "$input")"
		while read -r; do
			let "pos = $i % ${#colors[@]}"
			let "i++"
			local color="${colors[$pos]}"
			local var_name="_f_fg_$color"
			printf "%s%s%s" "${!var_name}" "$REPLY" "${_f_fg_off}"
		done <<< "$chars"
	}

	f_heading() {
		__f_util_char_underline '-' "$_f_fg_off" "$@" | __f_util_wrap "$_f_bold" "$_f_bold_off"
	}
	f_subheading() {
		__f_util_wrap "$_f_under" "$_f_under_off" "$@"
	}
	f_list_item() {
		local title; local body
		if (( $# > 1 )); then
			title="$1"; shift
		fi
		body="$(__f_util_prefix_multiline '   ' "$1$_f_new_line")"
		if [[ -n $title ]]; then
			__f_util_prefix "$(__f_util_wrap "$_f_list_item$_f_under" "$_f_under_off" "$title")" "$_f_new_line$_f_new_line$body"
		else
			__f_util_trim_start "$body" | __f_util_prefix "$_f_list_item"
		fi
	}
	f_definition() {
		local term="$1"; local desc="$2"
		__f_util_prefix '   ' "$term" | __f_util_wrap "$_f_bold" "$_f_bold_off$_f_new_line"
		__f_util_prefix_multiline '      ' "$desc$_f_new_line"
	}
	f_code_definition() {
		f_definition "$@"
	}
	f_code_block() {
		if (( $# > 1 )); then
			shift # ignore the first arg if there are more than one, it's the language specifier
		fi
		local body="$1"
		__f_util_wrap "$_f_code" "$_f_code_off" "$body" | __f_util_prefix_multiline '    '
	}
	f_link() {
		local name; local target
		if (( $# > 1 )); then
			name="$1"; shift
		fi
		target="$1"
		if [[ -n $name ]]; then
			printf "%s [%s]" "$name" "$target" | __f_util_wrap "$_f_italics" "$_f_italics_off"
		else
			__f_util_wrap "$_f_italics" "$_f_italics_off" "$target"
		fi
	}
	f_output() {
		__f_util_prefix_multiline ' -> ' "$@"
	}

}

# declare/override implementations for markdown api functions and tags
__f_init_api_markdown() {
	
	_f_bold='**'
	_f_bold_off=$_f_bold
	_f_italics='_'
	_f_italics_off=$_f_italics
	_f_strike='~~'
	_f_strike_off=$_f_strike
	_f_code='`'
	_f_code_off=$_f_code
	_f_code_block='```'
	_f_code_block_off=$_f_code_block
	_f_list_item='- '
	_f_def_term='<dl>
	<dt>'
	_f_def_term_off='</dt>
'
	_f_def_desc='	<dd>'
	_f_def_desc_off='</dd>
</dl>
'
	_f_new_line=$'\n'
	_f_line_break="  $_f_new_line"
	_f_sub='<sub>'
	_f_sub_off='</sub>'
	_f_sup='<sup>'
	_f_sup_off='</sup>'

	_f_bold_escaped='\*\*'
	_f_bold_escaped_off=$_f_bold_escaped


	f_sub() {   __f_util_wrap   "$_f_sub"  "$_f_sub_off"    "$@"; }
	f_sup() {   __f_util_wrap   "$_f_sup"  "$_f_sup_off"    "$@"; }


	f_heading() {
		__f_util_prefix '# ' "$1"
	}
	f_subheading() {
		__f_util_prefix '## ' "$1"
	}
	f_list_item() {
		local title; local body
		if (( $# > 1 )); then
			title="$1"; shift
		fi
		body="$(__f_util_prefix_multiline '  ' "$1$_f_new_line")"
		if [[ -n $title ]]; then
			__f_util_prefix "$(__f_util_wrap "$_f_list_item$_f_bold" "$_f_bold_off" "$title")" "$_f_line_break$body"
		else
			__f_util_trim_start "$body" | __f_util_prefix "$_f_list_item"
		fi
	}
	f_definition() {
		local term
		local desc
		term="$(echo "$1" | __f_util_escape_entities)"
		desc="$(echo "$2" | __f_util_suffix_multiline '<br/>')"
		__f_util_wrap "$_f_def_term" "$_f_def_term_off" "$term" | \
			__f_util_replace_tags "$_f_code" "$_f_code_off" '<code>' '</code>'
		__f_util_wrap "$_f_def_desc" "$_f_def_desc_off" "$desc" | \
			__f_util_replace_tags "$_f_code" "$_f_code_off" '<code>' '</code>' | \
			__f_util_replace_tags "$_f_bold_escaped" "$_f_bold_escaped_off" '<strong>' '</strong>'
	}
	f_code_definition() {
		local title
		title="$(__f_util_wrap "$_f_code" "$_f_code_off" "$1")"
		f_definition "$title" "$2"
	}
	f_code_block() {
		local lang
		local body
		if (( $# > 1 )); then
			lang="$1"; shift
		fi
		body="$1"
		__f_util_wrap "$_f_code_block$lang$_f_new_line" "$_f_new_line$_f_code_block_off" "$body"
	}
	f_link() {
		local name; local target
		if (( $# > 1 )); then
			name="$1"; shift
		fi
		target="$1"
		if [[ -n $name ]]; then
			printf "[%s](%s)" "$name" "$target"
		else
			printf "%s" "$target"
		fi
	}
	f_output() {
		f_code_block
	}

}

__f_init_api_raw() {

	f_list_item() {
		local title; local body
		if (( $# > 1 )); then
			title="$1"; shift
		fi
		body="$1"
		if [[ -n $title ]]; then
			__f_util_prefix "$title" "

$body"
		else
			__f_util_noop "$body"
		fi
	}
	f_definition() {
		local term="$1"; local desc="$2"
		__f_util_prefix "$term" "
$desc"
	}
	f_code_definition() {
		f_definition "$@"
	}
	f_code_block() {
		if (( $# > 1 )); then
			shift
		fi
		local body="$1"
		__f_util_noop "$body"
	}

	f_if() {
		shift
		local body="$1"
		__f_util_noop "$body"
	}
}

__f_init_formatter() {
	local format
	format=$(__f_util_resolve_format)
	__f_init_api_stubs
	__f_init_api_common
	__f_init_api_"$format"
}


__f_main() {

	__f_init_formatter

	# test if this script is executed (i.e. not sourced)
	# shellcheck disable=SC2128
	if [[ $BASH_SOURCE = "$0" && $1 = "-h" ]]; then
		__f_show_help
	fi
}

__f_main "$@"