More documentation

1 files changed, 39 insertions, 20 deletions

@@ -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/\[*\]/}"
 }