--enum syntax (#28)

The main thrust of this PR is changing the syntax accepted by `--enum`
to be like multi-value options as one can _create_ using this system.
Everything else was in service of that goal.

A follow-on PR will clean things up after all (client) use sites are
updated.

Author: danfuzz

CHANGELOG.md

@@ -7,10 +7,23 @@ versioning principles. Unstable releases do not.
 ### [Unreleased]
 
 Breaking changes:
-* None
+* `bashy-core`:
+  * `arg-processor`:
+    * Tightened up syntax for passing multi-value arguments.
+    * Renamed `--eval=` to `--eval[]=`, to be the same as how options defined by
+      the system work.
 
 Other notable changes:
-* None
+* `bashy-core`:
+  * `arg-processor`:
+    * `--filter` now supports `{...}` to specify a code snippet, just like
+      `--call` already does.
+    * `--eval` values can be specified using the same multi-value syntax used by
+      the rest of the system.
+  * `misc`:
+    * Made `vals` more conservative in its output.
+    * New function `set-array-from-vals`, which is (approximately) the reverse
+      action of `vals`.
 
 ### v2.6 -- 2023-10-24
 

doc/arg-processor.md

@@ -24,16 +24,20 @@ alphanumerics and more dashes, e.g. `--some-option`. In addition:
 
 * Multiple values can be passed to an option by following the option name with
   a pair of square brackets and an equal sign (`[]=`) and then a series of
-  space-separated words, with standard shell rules for quoting and escaping in
-  order to pass special characters, e.g. `--some-option[]='this "and that"'`.
+  space-separated words, with quotes recognized as delimiting words with
+  special characters. Single-quoted (`'...'`) and dollar-quoted (`$'...'`)
+  strings are interpreted in the shell-usual ways. Double-quoted (`"..."`)
+  strings are treated like single-quoted; notably, they do not undergo any shell
+  substitutions or backslash interpretation. E.g. `--some-option[]='this
+  "and that" $'and other' 'things'`.
 
   This multi-value form will also work for options that don't allow values or
   allow only one value (though there are probably few reasons to favor this form
   in those cases).
 
   The helper function `vals` is a convenient way to safely pass multiple values
   without having to worry about quoting hygiene. (That is, the helper handles it
-  for you.) For example, `--some-option[]="$(vals "${myArray[@]}")"`.
+  for you.) For example, `--some-option[]="$(vals -- "${myArray[@]}")"`.
 
 Special cases:
 * A single dash (`-`) is interpreted as a non-option argument.
@@ -61,7 +65,7 @@ my-cmd -34                         # One positional argument.
 my-cmd -- --foo                    # One positional argument, literally `--foo`.
 
 # Passing arbitrary strings safely to a multi-value option.
-my-cmd --strings[]="$(vals "${paths[@]}")"
+my-cmd --strings[]="$(vals -- "${paths[@]}")"
 ```
 
 ## Declaring options

scripts/lib/bashy-basics/_setup.sh

@@ -285,7 +285,7 @@ function usual-json-output-args {
     # Output style.
     if (( doOutput )); then
         opt-value --var=_bashy_jsonOutputStyle --default=json \
-            --enum='array json lines none raw raw0' output
+            --enum[]='array json lines none raw raw0' output
     else
         _bashy_jsonOutputStyle=json
     fi

scripts/lib/bashy-basics/jarray

@@ -25,10 +25,10 @@ define-usage --with-help $'
 '
 
 # Output style.
-opt-value --var=outputStyle --default=json --enum='compact json' output
+opt-value --var=outputStyle --default=json --enum[]='compact json' output
 
 # Input style.
-opt-value --var=inputStyle --default=json --enum='json strings' input
+opt-value --var=inputStyle --default=json --enum[]='json strings' input
 
 # The array elements.
 rest-arg --var=values values

scripts/lib/bashy-basics/jget

@@ -31,7 +31,7 @@ opt-value --var=filePath file
 
 # Output style.
 opt-value --var=outputStyle --default=json \
-    --enum='compact json lines none raw raw:slurp raw0 raw0:slurp' output
+    --enum[]='compact json lines none raw raw:slurp raw0 raw0:slurp' output
 
 # Value to operate on. (Will actually be the first expression if `--file` is
 # used.)

scripts/lib/bashy-basics/jval

@@ -60,12 +60,12 @@ define-usage --with-help $'
 
 # Input style.
 opt-value --var=inputStyle --default=none \
-    --enum='none raw raw:slurp raw0 raw0:slurp read slurp' \
+    --enum[]='none raw raw:slurp raw0 raw0:slurp read slurp' \
     input
 
 # Output style.
 opt-value --var=outputStyle --default=json \
-    --enum='compact json lines none raw raw0' output
+    --enum[]='compact json lines none raw raw0' output
 
 # List of variable assignments, as parallel arrays of type, name, and value.
 varTypes=()

scripts/lib/bashy-basics/timey/print

@@ -27,7 +27,7 @@ define-usage --with-help $'
 '
 
 # Input type.
-opt-value --var=inputType --default='secs' --enum='secs rfc822' input
+opt-value --var=inputType --default='secs' --enum[]='secs rfc822' input
 
 # UTC?
 opt-toggle --var=utc utc

scripts/lib/bashy-basics/timey/secs

@@ -23,7 +23,7 @@ define-usage --with-help $'
 '
 
 # Input type.
-opt-value --var=inputType --default='secs' --enum='secs rfc822' input
+opt-value --var=inputType --default='secs' --enum[]='secs rfc822' input
 
 # Time value to parse.
 positional-arg --required --var=time time

scripts/lib/bashy-core/arg-processor.sh

@@ -29,15 +29,16 @@
 #
 # Value-accepting argument definers allow these additional options to pre-filter
 # a value, before it gets set or passed to a `--call`:
-# * `--filter=<name>` -- Calls the named function passing it a single argument
-#   value; the function must output a replacement value. If the call fails, the
-#   argument is rejected. Note: The filter function runs in a subshell, and as
-#   such it cannot be used to affect the global environment of the main script.
+# * `--filter=<name>` or `filter={code}` -- Calls the named function passing it
+#   a single argument value, or runs the indicated code snippet. The function
+#   or snippet must output a replacement value. If the call fails, the argument
+#   is rejected. Note: The filter runs in a subshell, and as such it cannot be
+#   used to affect the global environment of the main script.
 # * `--filter=/<regex>/` -- Matches each argument value against the regex. If
 #   the regex doesn't match, the argument is rejected.
-# * `--enum=<spec>` -- Matches each argument value against a set of valid names.
-#   `<spec>` must be a space-separated list of names, e.g. `--enum='yes no
-#   maybe'`.
+# * `--enum[]=<spec>` -- Matches each argument value against a set of valid
+#   names. `<spec>` must be a non-empty list of values, in the usual multi-value
+#   form accepted by this system, e.g. `--enum[]='yes no "maybe so"'`.
 #
 # Some argument-definers also accept these options:
 # * `--default=<value>` -- Specifies a default value for an argument or option
@@ -151,7 +152,7 @@ function opt-multi {
     local optRequired=0
     local optVar=''
     local args=("$@")
-    _argproc_janky-args call enum filter required var \
+    _argproc_janky-args call enum[] filter required var \
     || return 1
 
     local specName=''
@@ -218,7 +219,7 @@ function opt-value {
     local optRequired=0
     local optVar=''
     local args=("$@")
-    _argproc_janky-args call default enum filter required var \
+    _argproc_janky-args call default enum[] filter required var \
     || return 1
 
     local specName=''
@@ -252,7 +253,7 @@ function positional-arg {
     local optRequired=0
     local optVar=''
     local args=("$@")
-    _argproc_janky-args call default enum filter required var \
+    _argproc_janky-args call default enum[] filter required var \
     || return 1
 
     local specName=''
@@ -361,7 +362,7 @@ function rest-arg {
     local optFilter=''
     local optVar=''
     local args=("$@")
-    _argproc_janky-args call enum filter var \
+    _argproc_janky-args call enum[] filter var \
     || return 1
 
     local specName=''
@@ -658,6 +659,31 @@ function _argproc_error-coda {
     fi
 }
 
+# Helper (called by code produced by `_argproc_handler-body`) which performs
+# a filter call. Upon success, prints all the filtered values.
+function _argproc_filter-call {
+    local desc="$1"
+    local filter="$2"
+    shift 2
+
+    if [[ ${filter} =~ ^\{(.*)\}$ ]]; then
+        # Kinda gross, but this makes it easy to call the filter code block.
+        eval "function _argproc_filter-call:inner {
+            ${BASH_REMATCH[1]}
+        }"
+        filter='_argproc_filter-call:inner'
+    fi
+
+    local arg result
+    for arg in "$@"; do
+        if ! result=("$("${filter}" "${arg}")"); then
+            error-msg "Invalid value for ${desc}: ${arg}"
+            return 1
+        fi
+        vals -- "${result}"
+    done
+}
+
 # Produces an argument handler body, from the given components.
 function _argproc_handler-body {
     local specName="$1"
@@ -675,16 +701,20 @@ function _argproc_handler-body {
             "${desc}" "${filter}"
         )")
     elif [[ ${filter} != '' ]]; then
-        # Add a loop to call the filter function on each argument.
-        result+=(
-            "$(printf '
-                local _argproc_value _argproc_args=()
-                for _argproc_value in "$@"; do
-                    _argproc_args+=("$(%s "${_argproc_value}")") || return 1
-                done
-                set -- "${_argproc_args[@]}"' \
-                "${filter}")"
-        )
+        # Add a call to perform the filtering.
+        local desc="$(_argproc_arg-description "${specName}")"
+        result+=("$(printf '
+            local _argproc_args
+            _argproc_args="$(_argproc_filter-call %q %q "$@")" \
+            && set-array-from-vals _argproc_args "${_argproc_args}" \
+            || {
+                local error="$?"
+                error-msg --suppress-cmd
+                return "${error}"
+            }
+            set -- "${_argproc_args[@]}"' \
+            "${desc}" "${filter}"
+        )")
     fi
 
     if [[ ${callFunc} =~ ^\{(.*)\}$ ]]; then
@@ -733,14 +763,19 @@ function _argproc_janky-args {
     local gotDefault=0
     local a
 
+    # TEMP: Remove spec mod once use sites are migrated.
+    if [[ ${argSpecs} =~ ' enum[] ' ]]; then
+        argSpecs+='enum '
+    fi
+
     for a in "${args[@]}"; do
         if (( optsDone )); then
             args+=("${a}")
             continue
         fi
 
         if [[ ${a} =~ ^--. ]]; then
-            if ! [[ ${a} =~ ^--([a-z][-a-z]+)(=.*)?$ ]]; then
+            if ! [[ ${a} =~ ^--([a-z][-a-z]+\[?\]?)(=.*)?$ ]]; then
                 error-msg --file-line=2 "Invalid option syntax: ${a}"
                 _argproc_declarationError=1
                 return 1
@@ -767,25 +802,14 @@ function _argproc_janky-args {
                     && optDefault="${BASH_REMATCH[1]}" \
                     || argError=1
                     ;;
-                enum)
-                    if [[ ${value} =~ ^=(' '*([-_:.a-zA-Z0-9]+' '*)+)$ ]]; then
-                        # Re-form as a filter expression.
-                        value="${BASH_REMATCH[1]}"
-                        optFilter=''
-                        while [[ ${value} =~ ^' '*([^ ]+)' '*(.*)$ ]]; do
-                            optFilter+="|${BASH_REMATCH[1]}"
-                            value="${BASH_REMATCH[2]}"
-                        done
-                        # `:1` to drop the initial `|`.
-                        optFilter="/^(${optFilter:1})\$/"
-                        # "Escape" `.` so it's not treated as regex syntax.
-                        optFilter="${optFilter//./[.]}"
-                    else
+                # TEMP: Remove plain `enum` once use sites are migrated.
+                enum|enum[])
+                    if ! _argproc_parse-enum "${value#=}"; then
                         argError=1
                     fi
                     ;;
                 filter)
-                    [[ ${value} =~ ^=(/.*/|[_a-zA-Z][-_:a-zA-Z0-9]*)$ ]] \
+                    [[ ${value} =~ ^=(/.*/|\{.*\}|[_a-zA-Z][-_:a-zA-Z0-9]*)$ ]] \
                     && optFilter="${BASH_REMATCH[1]}" \
                     || argError=1
                     ;;
@@ -858,6 +882,32 @@ function _argproc_janky-args {
     fi
 }
 
+# Parses a single enumeration-set value. Upon success sets a `optFilter`
+# (presumed local in the calling scope) to "return" a filter expression that
+# matches the specified enumeration.
+function _argproc_parse-enum {
+    local value="$1"
+    local values
+
+    set-array-from-vals values "${value}" \
+    || return "$?"
+
+    if (( ${#values[@]} == 0 )); then
+        # Error: Must have at least one value.
+        return 1
+    fi
+
+    optFilter="$(
+        printf '{ [[ "$1" =~ ^('
+        local or='' print
+        for value in "${values[@]}"; do
+            printf '%s%s' "${or}" "$(vals --dollar -- "${value}")"
+            or='|'
+        done
+        printf $')$ ]] && printf \'%%s\' "$1" }'
+    )"
+}
+
 # Parses a single argument / option spec. `--short` to accept a <short>
 # (short-option) character. `--value` to accept a value. `--value-eq` to accept
 # a value and leave the `=` in the result (to distinguish unset and
@@ -1022,12 +1072,12 @@ function _argproc_statements-from-args {
                         ;;
                     '[]=')
                         # Multi-value option. Parse the value into elements.
-                        if eval 2>/dev/null "values=(${value})"; then
+                        if set-array-from-vals values "${value}"; then
                             _argproc_statements+=(
                                 "${handler} $(_argproc_quote "${values[@]}")")
                         else
                             error-msg "Invalid multi-value syntax for option --${name}:"
-                            error-msg "  ${value}"
+                            error-msg "  $(vals -- "${value}")"
                             argError=1
                         fi
                         ;;