More documentation

bollux

@@ -38,8 +38,8 @@
 # Code:
 
 # Program information
-PRGN="${0##*/}"			# Easiest way to get the script name
-VRSN=0.4.1			# I /try/ to follow semver?  IDK.
+PRGN="${0##*/}" # Easiest way to get the script name
+VRSN=0.4.1      # I /try/ to follow semver?  IDK.
 
 # Print a useful help message (`bollux -h').
 bollux_usage() {
@@ -238,12 +238,12 @@ bollux_config() {
 	: "${BOLLUX_URL:=}"                            # start url
 	: "${BOLLUX_BYEMSG:=See You Space Cowboy ...}" # bye message
 	## lesskeys
-	: "${KEY_OPEN:=o}"	# prompt for a link to open
-	: "${KEY_GOTO:=g}"	# prompt for a page to 'goto'
-	: "${KEY_GOTO_FROM:=G}"	# goto a page with current prefilled
-	: "${KEY_BACK:='['}"	# go back in the history
+	: "${KEY_OPEN:=o}"      # prompt for a link to open
+	: "${KEY_GOTO:=g}"      # prompt for a page to 'goto'
+	: "${KEY_GOTO_FROM:=G}" # goto a page with current prefilled
+	: "${KEY_BACK:='['}"    # go back in the history
 	: "${KEY_FORWARD:=']'}" # go forward in the history
-	: "${KEY_REFRESH:=r}"	# refresh the page
+	: "${KEY_REFRESH:=r}"   # refresh the page
 	: "${KEY_CYCLE_PRE:=p}" # cycle T_PRE_DISPLAY
 	: "${BOLLUX_CUSTOM_LESSKEY:=$BOLLUX_CONF_DIR/bollux.lesskey}"
 	## files
@@ -253,9 +253,9 @@ bollux_config() {
 	: "${BOLLUX_PAGESRC:=$BOLLUX_DATADIR/pagesrc}" # where to save source
 	BOLLUX_HISTFILE="$BOLLUX_DATADIR/history"      # where to save history
 	## typesetting
-	: "${T_MARGIN:=4}"                 # left and right margin
-	: "${T_WIDTH:=0}"                  # width of the view port
-					   # 0 = get term width
+	: "${T_MARGIN:=4}" # left and right margin
+	: "${T_WIDTH:=0}"  # width of the view port
+	# 0 = get term width
 	: "${T_PRE_DISPLAY:=both,pre,alt}" # how to view PRE blocks
 	# colors -- these will be wrapped in \e[ __ m
 	C_RESET='\e[0m'         # reset
@@ -270,10 +270,9 @@ bollux_config() {
 	: "${C_QUOTE:=3}"       # quote formatting
 	: "${C_PRE:=0}"         # preformatted text formatting
 	## state
-	UC_BLANK=':?:'		# internal use only, should be non-URL chars
+	UC_BLANK=':?:' # internal use only, should be non-URL chars
 }
 
-
 # Load a URL.
 #
 # I was feeling fancy when I named this function -- a more descriptive name
@@ -388,11 +387,11 @@ usplit() { # usplit NAME:ARRAY URL:STRING
 	# below performs a reverse lookup on the name to get the actual data.
 	# shellcheck disable=2034
 	local url="${BASH_REMATCH[0]}" \
-	      scheme="${BASH_REMATCH[2]}" \
-	      authority="${BASH_REMATCH[4]}" \
-	      path="${BASH_REMATCH[5]}" \
-	      query="${BASH_REMATCH[7]}" \
-	      fragment="${BASH_REMATCH[9]}"
+		scheme="${BASH_REMATCH[2]}" \
+		authority="${BASH_REMATCH[4]}" \
+		path="${BASH_REMATCH[5]}" \
+		query="${BASH_REMATCH[7]}" \
+		fragment="${BASH_REMATCH[9]}"
 
 	# 0=url 1=scheme 2=authority 3=path 4=query 5=fragment
 	local i=1 c
@@ -407,6 +406,7 @@ usplit() { # usplit NAME:ARRAY URL:STRING
 	printf -v "$1[0]" '%s' "$url"
 }
 
+# Join a URL array (NAME) back into a string.
 ujoin() { # ujoin NAME:ARRAY
 	local -n U="$1"
 
@@ -431,9 +431,28 @@ ujoin() { # ujoin NAME:ARRAY
 	log d "${U[0]}"
 }
 
-ucdef() { [[ "${!1}" != "$UC_BLANK" ]]; } # ucdef NAME
-ucblank() { [[ -z "${!1}" ]]; }           # ucblank NAME
-ucset() {                                 # ucset NAME VALUE
+# Three small utility functions for dealing with URL components.
+#
+# `ucdef' checks whether a URL component is blank or not -- if a component
+# doesn't exist, `usplit' writes $UC_BLANK there instead (which is :?: by
+# default, though it really doesn't matter much *what* it is, as long as it's
+# not going to really be in a URL).  I tried really hard to differentiate an
+# unset array element from a simply empty one, but like, as far as I could tell,
+# you can't do that in Bash.
+ucdef() { # ucdef NAME
+	[[ "${!1}" != "$UC_BLANK" ]]
+}
+
+# `ucblank' determines whether a URL component is blank (""), as opposed to
+# undefined.
+ucblank() { # ucblank NAME
+	[[ -z "${!1}" ]]
+}
+
+# `ucset' sets one component of a URL array and setting the 0th element to the
+# new full URL.  Use it instead of directly setting the array element with U[x],
+# because U[0] will fall out of sync with the rest of the contents.
+ucset() { # ucset NAME VALUE
 	run eval "${1}='$2'"
 	run ujoin "${1/\[*\]/}"
 }