Add comments

1 files changed, 76 insertions, 29 deletions

@@ -24,26 +24,26 @@ parameters:
 END
 }
 
-run() {
-        log debug "$@"
+run() { # run COMMAND...
+        log debug "$*"
         "$@"
 }
 
-die() {
+die() { # die EXIT_CODE MESSAGE
         local ec="$1"
         shift
         log error "$*"
         exit "$ec"
 }
 
-# pure bash bible trim_string
-trim() {
+# https://github.com/dylanaraps/pure-bash-bible/
+trim_string() { # trim_string STRING
         : "${1#"${1%%[![:space:]]*}"}"
         : "${_%"${_##*[![:space:]]}"}"
         printf '%s\n' "$_"
 }
 
-log() {
+log() { # log LEVEL MESSAGE
         [[ "$BOLLUX_LOGLEVEL" == QUIET ]] && return
         local fmt
 
@@ -72,9 +72,12 @@ bollux() {
                 run prompt GO BOLLUX_URL
         fi
 
+        log d "BOLLUX_URL='$BOLLUX_URL'"
+
         run blastoff "$BOLLUX_URL"
 }
 
+# process command-line arguments
 bollux_args() {
         while getopts :hvq OPT; do
                 case "$OPT" in
@@ -94,6 +97,7 @@ bollux_args() {
         fi
 }
 
+# process config file and set variables
 bollux_config() {
         : "${BOLLUX_CONFIG:=${XDG_CONFIG_DIR:-$HOME/.config}/bollux/bollux.conf}"
 
@@ -133,15 +137,18 @@ bollux_config() {
         : "${C_PRE:=0}"         # preformatted text formatting
 }
 
+# quit happily
 bollux_quit() {
         log x "$BOLLUX_BYEMSG"
         exit
 }
 
-set_title() {
+# set the terminal title
+set_title() { # set_title STRING
         printf '\e]2;%s\007' "$*"
 }
 
+# prompt for input
 prompt() { # prompt [-u] PROMPT [READ_ARGS...]
         local read_cmd=(read -e -r)
         if [[ "$1" == "-u" ]]; then
@@ -154,7 +161,8 @@ prompt() { # prompt [-u] PROMPT [READ_ARGS...]
         "${read_cmd[@]}" </dev/tty "$@"
 }
 
-blastoff() { # load a url
+# load a URL
+blastoff() { # blastoff [-u] URL
         local well_formed=true
         local proto url
         if [[ "$1" == "-u" ]]; then
@@ -167,7 +175,7 @@ blastoff() { # load a url
                 url="$(run transform_resource "$BOLLUX_URL" "$1")"
         fi
         [[ "$url" != *://* ]] && url="$BOLLUX_PROTO://$url"
-        url="$(trim "$url")"
+        url="$(trim_string "$url")"
         proto="${url%://*}"
 
         log d "PROTO='$proto' URL='$url'"
@@ -190,6 +198,7 @@ blastoff() { # load a url
                 }
 }
 
+# transform a URI according to RFC 3986 sec 5.2.2
 transform_resource() { # transform_resource BASE_URL REFERENCE_URL
         local -A R B T # reference, base url, target
         eval "$(run parse_url B "$1")"
@@ -246,7 +255,8 @@ transform_resource() { # transform_resource BASE_URL REFERENCE_URL
         printf '%s\n' "$r"
 }
 
-merge_paths() { # 5.2.3
+# merge URL paths according to RFC 3986 sec 5.2.3
+merge_paths() { # merge_paths BASE_AUTHORITY BASE_PATH REFERENCE_PATH
         # shellcheck disable=2034
         local B_authority="$1"
         local B_path="$2"
@@ -269,7 +279,8 @@ merge_paths() { # 5.2.3
         fi
 }
 
-remove_dot_segments() { # 5.2.4
+# remove dot segments in paths according to RFC 3986 sec 5.2.4
+remove_dot_segments() { # remove_dot_segments PATH
         local input="$1"
         local output
         while [[ "$input" ]]; do
@@ -292,13 +303,12 @@ remove_dot_segments() { # 5.2.4
         printf '%s\n' "${output//\/\//\//}"
 }
 
+# parse a url using the reference regex in RFC 3986 appendix B
 parse_url() { # eval "$(split_url NAME STRING)" => NAME[...]
         local name="$1"
         local string="$2"
-        # shopt -u extglob # TODO port re ^ to extglob syntax
         local re='^(([^:/?#]+):)?(//([^/?#]*))?([^?#]*)(\?([^#]*))?(#(.*))?'
         [[ $string =~ $re ]] || return $?
-        # shopt -s extglob
 
         local scheme="${BASH_REMATCH[2]}"
         local authority="${BASH_REMATCH[4]}"
@@ -316,18 +326,37 @@ parse_url() { # eval "$(split_url NAME STRING)" => NAME[...]
 
 # is a NAME defined ('set' in bash)?
 isdefined() { [[ "${!1+x}" ]]; } # isdefined NAME
+
 # is a NAME defined AND empty?
 isempty() { [[ ! "${!1-x}" ]]; } # isempty NAME
-# split a string -- see pure bash bible
-split() { # split STRING DELIMITER
-        local -a arr
-        IFS=$'\n' read -d "" -ra arr <<<"${1//$2/$'\n'}"
-        printf '%s\n' "${arr[@]}"
+
+# work with URLs
+# https://github.com/dylanaraps/pure-bash-bible/
+urlencode() { # urlencode STRING
+        local LC_ALL=C
+        for ((i = 0; i < ${#1}; i++)); do
+                : "${1:i:1}"
+                case "$_" in
+                [a-zA-Z0-9.~_-])
+                        printf '%s' "$_"
+                        ;;
+                *)
+                        printf '%%%02X' "'$_"
+                        ;;
+                esac
+        done
+        printf '\n'
+}
+
+# https://github.com/dylanaraps/pure-bash-bible/
+urldecode() { # urldecode STRING
+        : "${1//+/ }"
+        printf '%b\n' "${_//%/\\x}"
 }
 
 # GEMINI
-# https://gemini.circumlunar.space/docs/spec-spec.txt
-gemini_request() {
+# https://gemini.circumlunar.space/docs/specification.html
+gemini_request() { # gemini_request URL
         local url port server
         local ssl_cmd
         url="$1"
@@ -342,7 +371,7 @@ gemini_request() {
         run "${ssl_cmd[@]}" <<<"$url" 2>/dev/null
 }
 
-gemini_response() {
+gemini_response() { # gemini_response URL
         local url code meta
         local title
         url="$1"
@@ -413,7 +442,7 @@ gemini_response() {
 # GOPHER
 # https://tools.ietf.org/html/rfc1436 protocol
 # https://tools.ietf.org/html/rfc4266 url
-gopher_request() {
+gopher_request() { # gopher_request URL
         local url server port type path
         url="$1"
         port=70
@@ -432,7 +461,7 @@ gopher_request() {
         passthru <&9
 }
 
-gopher_response() {
+gopher_response() { # gopher_response URL
         local url pre type cur_server
         pre=false
         url="$1"
@@ -469,12 +498,14 @@ gopher_response() {
         esac
 }
 
+# 'cat' but in pure bash
 passthru() {
         while IFS= read -r; do
                 printf '%s\n' "$REPLY"
         done
 }
 
+# convert gophermap to text/gemini (probably naive)
 gopher_convert() {
         local type label path server port regex
         # cf. https://github.com/jamestomasino/dotfiles-minimal/blob/master/bin/gophermap2gemini.awk
@@ -546,6 +577,7 @@ gopher_convert() {
         exec 9>&-
 }
 
+# display the fetched content
 display() { # display METADATA [TITLE]
         local -a less_cmd
         local i mime charset
@@ -558,7 +590,7 @@ display() { # display METADATA [TITLE]
                 title="$2"
         fi
 
-        mime="$(trim "${hdr[0],,}")"
+        mime="$(trim_string "${hdr[0],,}")"
         for ((i = 1; i <= "${#hdr[@]}"; i++)); do
                 h="${hdr[$i]}"
                 case "$h" in
@@ -601,7 +633,8 @@ display() { # display METADATA [TITLE]
         esac
 }
 
-less_prompt_escape() {
+# escape strings for the less prompt
+less_prompt_escape() { # less_prompt_escape STRING
         local i
         for ((i = 0; i < ${#1}; i++)); do
                 : "${1:i:1}"
@@ -613,7 +646,8 @@ less_prompt_escape() {
         printf '\n'
 }
 
-mklesskey() {
+# generate a lesskey(1) file for custom keybinds
+mklesskey() { # mklesskey FILENAME
         lesskey -o "$1" - <<-END
                 #command
                 o quit 0 # 48 open a link
@@ -631,14 +665,17 @@ mklesskey() {
         END
 }
 
+# normalize files
 normalize() {
         shopt -s extglob
         while IFS= read -r; do
+                # normalize line endings
                 printf '%s\n' "${REPLY//$'\r'?($'\n')/}"
         done
         shopt -u extglob
 }
 
+# typeset a text/gemini document
 typeset_gemini() {
         local pre=false
         local ln=0 # link number
@@ -752,6 +789,7 @@ gemini_pre() {
         printf "\e[${C_PRE}m%s${C_RESET}\n" "$1"
 }
 
+# wrap lines on words to WIDTH
 fold_line() { # fold_line WIDTH TEXT
         local width="$1"
         local margin="${2%%[![:space:]]*}"
@@ -778,7 +816,8 @@ fold_line() { # fold_line WIDTH TEXT
         printf '\n'
 }
 
-handle_keypress() {
+# use the exit code from less (see mklesskey) to do things
+handle_keypress() { # handle_keypress CODE
         case "$1" in
         48) # o - open a link -- show a menu of links on the page
                 run select_url "$BOLLUX_PAGESRC"
@@ -812,7 +851,8 @@ handle_keypress() {
         esac
 }
 
-select_url() {
+# select a URL from a text/gemini file
+select_url() { # select_url FILE
         run mapfile -t < <(extract_links <"$1")
         PS3="OPEN> "
         select u in "${MAPFILE[@]}"; do
@@ -824,6 +864,7 @@ select_url() {
         done </dev/tty
 }
 
+# extract the links from a text/gemini file
 extract_links() {
         local url alt
         while read -r; do
@@ -840,6 +881,7 @@ extract_links() {
         done
 }
 
+# download $BOLLUX_URL
 download() {
         tn="$(mktemp)"
         log x "Downloading: '$BOLLUX_URL' => '$tn'..."
@@ -854,6 +896,7 @@ download() {
         fi
 }
 
+# initialize bollux
 bollux_init() {
         # Trap cleanup
         trap bollux_cleanup INT QUIT EXIT
@@ -866,12 +909,14 @@ bollux_init() {
         run mkdir -p "${BOLLUX_HISTFILE%/*}"
 }
 
+# clean up on exit
 bollux_cleanup() {
         # Stubbed in case of need in future
         :
 }
 
-history_append() { # history_append url TITLE
+# append a URL to history
+history_append() { # history_append URL TITLE
         BOLLUX_URL="$1"
         # date/time, url, title (best guess)
         run printf '%(%FT%T)T\t%s\t%s\n' -1 "$1" "$2" >>"$BOLLUX_HISTFILE"
@@ -879,6 +924,7 @@ history_append() { # history_append url TITLE
         ((HN += 1))
 }
 
+# move back in history (session)
 history_back() {
         log d "HN=$HN"
         ((HN -= 2))
@@ -890,6 +936,7 @@ history_back() {
         run blastoff "${HISTORY[$HN]}"
 }
 
+# move forward in history (session)
 history_forward() {
         log d "HN=$HN"
         if ((HN >= ${#HISTORY[@]})); then