Add debug option. Plugins!

Author: apathor

README.md

@@ -7,13 +7,12 @@ selection tools.
 
 What is an "interactive line selection tool"? It's a kind of program
 that reads text input then presents an interactive menu for the user to
-select one line.
+select one line. Some line selection tools run only in the terminal and
+others are graphical - cz uses a tool appropriate for the situation.
 
-Some line selection tools run only in the terminal and others are
-graphical - cz uses a tool appropriate for the situation.
-
-Cz implements a plugin system. Each plugin defines a set of lines which
-to select and templates to use the selection.
+Cz implements a plugin system. Each plugin defines lines from which to
+select, an output template, and a command template. Creating new plugins
+is quick and painless in any programming language.
 
 Included are over 250 plugins covering a variety of use cases. For
 example with some of the included plugins you can select from:

cz

@@ -661,7 +661,7 @@ EOF
 
 cz() {
     # version
-    local ver="0.8.4"
+    local ver="0.8.5"
     # usage
     local hows="" use=""
     read -r -d '' use <<EOF
@@ -701,14 +701,17 @@ OPTIONS
   -y            : Use a terminal line selection tool.
   -z TOOL       : Use the given line selection tool.
 
+ These options control debugging features:
+  -m            : Print some debygging information.
+
 TOOLS
  The following interactive line selection tools are supported:
   choose, dmenu, fzf, fzy, iselect, pick, pipedial, rofi, selecta, sentaku,
-  slmenu, and vis-menu.
+  slmenu, vis-menu, and zenity.
 
 PLUGINS
  Plugins use cz for an application specific task. Each plugin defines input
-  lines and delimiter or template options.
+  lines, delimiter, and template options.
  Run 'cz -l' to list plugins and 'cz -h PLUGIN' or 'cz help' for help text.
  All commands starting with 'cz_' are considered plugins.
 
@@ -786,15 +789,16 @@ EOF
     local mode="${_CZ_MODE}"       # string | indicator for program mode
     local help="${_CZ_HELP}"       # string | indicator for help requested
     local dlm="${_CZ_DELIM:-$IFS}" # string | delimeter to split selected line
+    local dbg="${_CZ_DEBUG}"       # boolean | whether or not write debug info
     # set option defaults
-    local inp="/dev/stdin"     # string  | file from which to select a line
-    local buf=0                # boolean | require buffered stdin for command
-    local run=""               # string  | program mode implied by another option
-    local nul=0                # boolean | whether to read null separated lines
-    local clr=0                # boolean | whether to refresh cached input lines
+    local inp="/dev/stdin"         # string  | file from which to select a line
+    local buf=0                    # boolean | require buffered stdin for command
+    local run=""                   # string  | program mode implied by another option
+    local nul=0                    # boolean | whether to read null separated lines
+    local clr=0                    # boolean | whether to refresh cached input lines
     # accept options
     local opt OPTIND OPTARG
-    while getopts ":cd:e:f:ghHi:lkopqrstuvxyz:0" opt; do
+    while getopts ":cd:e:f:ghHi:klmopqrstuvxyz:0" opt; do
         case "$opt" in
             c) # clear hold caches
                 clr=1
@@ -831,6 +835,10 @@ EOF
                     return 2
                 fi
                 ;;
+            k) # list supported tools
+                printf "%s\\n" "$exes"
+                return 0
+                ;;
             l) # list available plugins
                 while read -r f; do
                     if [[ "$f" == cz_* ]]; then
@@ -839,9 +847,8 @@ EOF
                 done < <(compgen -c) | sort
                 return 0
                 ;;
-            k) # list supported tools
-                printf "%s\\n" "$exes"
-                return 0
+            m) # mention some debugging information
+                dbg=1
                 ;;
             o) # just print lines without interactive selection
                 mode=-1
@@ -940,6 +947,7 @@ EOF
         shift "$word"
         # run the plugin with override environment variables
         _CZ_DELIM="$dlm" \
+                 _CZ_DEBUG="$dbg" \
                  _CZ_FIELDS="$fld" \
                  CZ_GUI="${gfx}:${app}" \
                  _CZ_HELP="$help" \
@@ -1053,6 +1061,10 @@ EOF
     if ((nul)); then
         out=$(eval printf "%s" "$out")
     fi
+    # maybe print the selection
+    if ((dbg)); then
+        printf "> %s\\n" "$out" >&2
+    fi
     # tokenize selected line for use in templates
     local cmd=""
     local toks=()
@@ -1074,20 +1086,29 @@ EOF
                 printf "Failed to render template: %s\\n" "$fld" >&2
                 return 5
             fi
+            if ((dbg)); then
+                printf "# %s ==> %s\\n" "$fld" "$out" >&2
+            fi
             printf "%s\\n" "$out"
             ;;
         5) # print some fields extracted from the line
             if ! out="$(nth -p -- "$fld" "${toks[@]}" 2>/dev/null)"; then
                 printf "Failed to render template: %s\\n" "$fld" >&2
                 return 5
             fi
+            if ((dbg)); then
+                printf "# %s ==> %s\\n" "$fld" "$out" >&2
+            fi
             printf "%s\\n" "$out"
             ;;
         2) # template the command string then run it
             if ! cmd="$(nth -q -- "$tpl" "${toks[@]}" 2>/dev/null)"; then
                 printf "Failed to parse template: %s\\n" "$tpl" >&2
                 return 5
             fi
+            if ((dbg)); then
+                printf "# %s\\n" "$cmd" >&2
+            fi
             unset -v _CZ_DELIM _CZ_FIELDS _CZ_HELP _CZ_MODE _CZ_TEMPLATE HOLD_CLEAR
             # eval the command maybe passing through stdin or the terminal
             if ((${#stdin})); then
@@ -1103,13 +1124,19 @@ EOF
                 printf "Failed to render template.\\n%s\\n" "$tpl" >&2
                 return 4
             fi
+            if ((dbg)); then
+                printf "# %s ==> %s\\n" "$fld" "$out" >&2
+            fi
             printf "%s\\n" "$cmd"
             ;;
         4) # render the command template unquoted
             if ! cmd="$(nth -p "$tpl" "${toks[@]}")"; then
                 printf "Failed to render template.\\n%s\\n" "$tpl" >&2
                 return 4
             fi
+            if ((dbg)); then
+                printf "# %s ==> %s\\n" "$fld" "$out" >&2
+            fi
             printf "%s\\n" "$cmd"
             ;;
     esac
@@ -1125,7 +1152,7 @@ function _cz() {
     # cz has some options
     local opt="" opts
     declare -A opts
-    for opt in -{d,e,f,h,i,l,k,o,p,q,r,s,t,u,v,x,y,z,0}; do opts["$opt"]=0; done
+    for opt in -{d,e,f,h,i,l,k,m,o,p,q,r,s,t,u,v,x,y,z,0}; do opts["$opt"]=0; done
     # scan all previous words
     local base="" last="" word="" i=0
     for ((i=1; i < "$COMP_CWORD"; i++)); do
@@ -1668,13 +1695,23 @@ EOF
     cz -e 'cd {0}' find dir "$d"
 }
 
+cz_dict_database() {
+    { hep "$_CZ_HELP" && return; } <<EOF
+cz dict database [QUERY]
+Select a dict server database.
+EOF
+    req dict sed || return 5
+    local qry="${1}"
+    cz -e "dict -d {0} $qry" -f 0 -i <(dict -D | sed 1d)
+}
+
 cz_dict_strategy() {
     { hep "$_CZ_HELP" && return; } <<EOF
 cz dict strategy [QUERY]
 Select a dict server search strategy.
 EOF
     req dict sed || return 5
-    local qry="${1:-}"
+    local qry="${1}"
     cz -e "dict -s {0} $qry" -f 0 -i <(dict -S | sed 1d)
 }
 
@@ -1684,8 +1721,11 @@ cz dict word [QUERY]
 Select a word from a dict server and print its definition.
 EOF
     req dict || return 5
-    local qry="${1:-.*}"
-    cz -f 3: -e 'dict -- "{3:@P}"' -i <(dict -m -f -s re "$qry")
+    local qry="${1}"
+
+    cz -f 3: -e 'dict -- "{3:@P}"' \
+       -i <( if [ -z "$qry" ]; then hold -ep -t 86400 -- dict -m -f -s re "";
+             else dict -m -f -s re "$qry"; fi)
 }
 
 cz_dir() {
@@ -1836,6 +1876,30 @@ EOF
             done)
 }
 
+cz_radiogarden_place() {
+    { hep "$_CZ_HELP" && return; } <<EOF
+cz radiogarden place
+Select a place known to radio.garden.
+go install github.com/jonasrmichel/radio-garden-go/radio-garden@latest
+EOF
+    req radio-garden || return 5
+    cz -f 0 -i <(hold -ep -t 86400 -- radio-garden places \
+                | jq -r '.data.list[] | [.id, .country, .title] | @tsv')
+}
+
+cz_radiogarden_station() {
+    { hep "$_CZ_HELP" && return; } <<EOF
+cz radiogarden station [PLACE-ID]
+Select a station known to radio.garden near the given place.
+go install github.com/jonasrmichel/radio-garden-go/radio-garden@latest
+EOF
+    req radio-garden || return 5
+    local place="${1:-$(insulate ^_CZ cz -u radiogarden place)}"
+    cz  -e 'radio-garden station stream -i {0}' -f 0 \
+        -i <(radio-garden stations -i "$place" \
+                 | jq -r '.data.content[0].items[] | [(.href | split("/")[-1]), .title] | @tsv')
+}
+
 cz_rofi_theme() {
     { hep "$_CZ_HELP" && return; } <<EOF
 cz rofi theme
@@ -3029,7 +3093,6 @@ EOF
                    | jq -r '.data[] | select(.type == "oracle_cards") | .download_uri'); then
         return 2
     fi
-
     local data="" menu=""
     if ! data=$(hold -e -n scryfalldata -t $((86400 * 7)) curl -sS "$url"); then
         return 2

www/index.org

@@ -6,11 +6,9 @@
 ** About
 Cz is a bash script that provides a common interface to interactive line selection tools.
 
-What is an "interactive line selection tool"? It's a kind of program that reads text input then presents an interactive menu for the user to select one line.
+What is an "interactive line selection tool"? It's a kind of program that reads text input then presents an interactive menu for the user to select one line. Some line selection tools run only in the terminal and others are graphical - cz uses a tool appropriate for the situation.
 
-Some line selection tools run only in the terminal and others are graphical - cz uses a tool appropriate for the situation.
-
-Cz implements a plugin system. Each plugin defines a set of lines  which to select and templates to use the selection.
+Cz implements a plugin system. Each plugin defines lines from which to select, an output template, and a command template. Creating new plugins is quick and painless in any programming language.
 
 Included are over 250 plugins covering a variety of use cases. For example with some of the included plugins you can select from: