Relax boolean switch parsing

Author: t-kalinowski

NEWS.md

@@ -2,10 +2,10 @@
 
 ## Breaking changes
 
--   Boolean switch aliases now follow logical defaults: `FALSE` exposes the
-    positive flag and `TRUE` exposes the generated `--no-*` flag. `NA` remains
-    a value-taking boolean option, so it can still indicate that an option was
-    not supplied.
+-   Boolean switch aliases now follow logical defaults in help output: `FALSE`
+    exposes the positive flag, `TRUE` exposes the generated `--no-*` flag, and
+    `NA` exposes both as a tri-state switch. Boolean switches also accept
+    explicit values such as `--foo=false`.
 -   Rapp now parses YAML with YAML 1.2 semantics. Bare `yes` and `no`
     non-bool option values are strings, not boolean aliases. Declared
     bool options still accept YAML 1.1 bool aliases such as `yes`, `no`,

R/app.R

@@ -228,7 +228,7 @@ get_app_inputs <- function(app, exprs = app$exprs, pos = integer()) {
         "NULL" = "string"
       ),
 
-      arg_type = if (is_auto_bool_switch_default(default)) {
+      arg_type = if (is_bool_switch_default(default)) {
         "switch"
       } else if (is.null(default)) {
         "positional"

R/args.R

@@ -19,12 +19,13 @@ process_args <- function(args, app) {
     for (i in seq_along(app_opts)) {
       if (identical(short, app_opts[[i]][["short"]])) {
         if (identical(app_opts[[i]][["arg_type"]], "switch")) {
-          if (has_positive_alias(app_opts[[i]])) {
+          if (show_positive_alias(app_opts[[i]])) {
             return(paste0("--", names(app_opts)[[i]]))
           }
-          if (has_negative_alias(app_opts[[i]])) {
+          if (show_negative_alias(app_opts[[i]])) {
             return(paste0("--no-", names(app_opts)[[i]]))
           }
+          return(paste0("--", names(app_opts)[[i]]))
         } else {
           return(paste0("--", names(app_opts)[[i]]))
         }
@@ -86,6 +87,7 @@ process_args <- function(args, app) {
 
     # resolve these values in this block
     name <- val <- spec <- NULL
+    positive_switch <- FALSE
 
     # --name=val
     equals_idx <- regexpr("=", a)
@@ -101,13 +103,15 @@ process_args <- function(args, app) {
       ) {
         stop_unrecognized_arg(a)
       }
+      if (!is.null(spec) && identical(spec$arg_type, "switch")) {
+        positive_switch <- TRUE
+      }
       if (is.null(spec) && startsWith(a, "--no-")) {
         alt_name <- str_drop_prefix(name, "no_")
         alt_spec <- app_opts[[alt_name]]
         if (
           !is.null(alt_spec) &&
-            identical(alt_spec$arg_type, "switch") &&
-            !has_negative_alias(alt_spec)
+            identical(alt_spec$arg_type, "switch")
         ) {
           stop_unrecognized_arg(a)
         }
@@ -125,6 +129,9 @@ process_args <- function(args, app) {
       ) {
         stop_unrecognized_arg(a)
       }
+      if (!is.null(spec) && identical(spec$arg_type, "switch")) {
+        positive_switch <- TRUE
+      }
 
       # if flag not known, maybe this is a switch flag
       if (is.null(spec) && startsWith(a, "--no-")) {
@@ -154,10 +161,28 @@ process_args <- function(args, app) {
 
     if (is.null(val)) {
       if (identical(spec$arg_type, "switch")) {
-        val <- "true"
+        if (positive_switch) {
+          next_arg <- readLines(args, 1L)
+          if (length(next_arg)) {
+            if (is_bool_cli_value(next_arg)) {
+              val <- next_arg
+            } else {
+              pushBack(next_arg, args)
+            }
+          }
+        }
+        if (is.null(val)) {
+          val <- "true"
+        }
       } else {
         # arg_type == "option"
         val <- readLines(args, 1L)
+        if (!length(val)) {
+          stop(
+            sprintf("Missing value for --%s.", to_kebab_case(name)),
+            call. = FALSE
+          )
+        }
       }
     }
 
@@ -328,5 +353,11 @@ normalize_bool_cli_value <- function(val) {
   )
 }
 
+is_bool_cli_value <- function(val) {
+  is.character(val) &&
+    length(val) == 1L &&
+    normalize_bool_cli_value(val) %in% c("true", "false")
+}
+
 to_snake_case <- function(x) gsub("-", "_", x, fixed = TRUE)
 to_kebab_case <- function(x) gsub("_", "-", x, fixed = TRUE)

R/help.R

@@ -194,38 +194,49 @@ print_app_help <- function(app, yaml = TRUE, command_path = character()) {
       default_value <- format_default_value(opt$default)
       positive_flag <- paste0("--", cli_name)
       negative_flag <- paste0("--no-", cli_name)
-      show_positive <- has_positive_alias(opt)
-      show_negative <- has_negative_alias(opt)
-      flags <- c(
-        if (show_positive) positive_flag,
-        if (show_negative) negative_flag
-      )
-      flag <- paste(flags, collapse = " / ")
-      if (!is.null(short_flag) && nzchar(short_flag)) {
-        flag <- paste0("-", short_flag, ", ", flag)
-      }
-      toggle_note <- if (isTRUE(opt$default)) {
-        if (show_negative) {
-          sprintf("Disable with `%s`.", negative_flag)
-        } else {
-          character()
+      show_positive <- show_positive_alias(opt)
+      show_negative <- show_negative_alias(opt)
+      if (!show_positive && !show_negative) {
+        flag <- paste(positive_flag, format_placeholder(name))
+        if (!is.null(short_flag) && nzchar(short_flag)) {
+          flag <- paste0("-", short_flag, ", ", flag)
         }
-      } else if (isFALSE(opt$default)) {
-        if (show_positive) {
-          sprintf("Enable with `%s`.", positive_flag)
-        } else {
-          character()
+        if (!is.null(default_value)) {
+          details <- c(details, sprintf("[default: %s]", default_value))
         }
+        details <- c(details, "[type: bool]")
       } else {
-        c(
-          if (show_positive) sprintf("Enable with `%s`.", positive_flag),
-          if (show_negative) sprintf("Disable with `%s`.", negative_flag)
+        flags <- c(
+          if (show_positive) positive_flag,
+          if (show_negative) negative_flag
         )
+        flag <- paste(flags, collapse = " / ")
+        if (!is.null(short_flag) && nzchar(short_flag)) {
+          flag <- paste0("-", short_flag, ", ", flag)
+        }
+        toggle_note <- if (isTRUE(opt$default)) {
+          if (show_negative) {
+            sprintf("Disable with `%s`.", negative_flag)
+          } else {
+            character()
+          }
+        } else if (isFALSE(opt$default)) {
+          if (show_positive) {
+            sprintf("Enable with `%s`.", positive_flag)
+          } else {
+            character()
+          }
+        } else {
+          c(
+            if (show_positive) sprintf("Enable with `%s`.", positive_flag),
+            if (show_negative) sprintf("Disable with `%s`.", negative_flag)
+          )
+        }
+        if (!is.null(default_value)) {
+          details <- c(details, sprintf("[default: %s]", default_value))
+        }
+        details <- c(details, toggle_note)
       }
-      if (!is.null(default_value)) {
-        details <- c(details, sprintf("[default: %s]", default_value))
-      }
-      details <- c(details, toggle_note)
     }
 
     if (identical(opt$action, "append")) {

R/utils.R

@@ -68,10 +68,6 @@ compact <- function(x) x[lengths(x) > 0]
 `%||%` <- function(x, y) if (is.null(x)) y else x
 `subtract<-` <- function(x, value) x - value
 
-is_auto_bool_switch_default <- function(x) {
-  identical(x, TRUE) || identical(x, FALSE)
-}
-
 is_bool_switch_default <- function(x) is.logical(x) && length(x) == 1L
 
 check_bool_switch_default <- function(default) {
@@ -89,9 +85,7 @@ has_positive_alias <- function(opt) {
   default <- opt[["default"]]
   check_bool_switch_default(default)
 
-  isFALSE(default) ||
-    isTRUE(is.na(default)) ||
-    isFALSE(opt[["negative_alias"]])
+  TRUE
 }
 
 has_negative_alias <- function(opt) {
@@ -104,7 +98,25 @@ has_negative_alias <- function(opt) {
     return(!isFALSE(opt[["negative_alias"]]))
   }
 
-  isTRUE(default) || isTRUE(is.na(default))
+  TRUE
+}
+
+show_positive_alias <- function(opt) {
+  stopifnot(identical(opt[["arg_type"]], "switch"))
+
+  default <- opt[["default"]]
+  check_bool_switch_default(default)
+
+  isFALSE(default) || isTRUE(is.na(default))
+}
+
+show_negative_alias <- function(opt) {
+  stopifnot(identical(opt[["arg_type"]], "switch"))
+
+  default <- opt[["default"]]
+  check_bool_switch_default(default)
+
+  has_negative_alias(opt) && (isTRUE(default) || isTRUE(is.na(default)))
 }
 
 `append<-` <- function(x, after = NULL, value) {

README.md

@@ -113,7 +113,7 @@ flip-coin --n=1
 flip-coin --n 1
 ```
 
-Assignments of `TRUE` or `FALSE` are a little different from other
+Assignments of `TRUE`, `FALSE`, or `NA` are a little different from other
 options. They support usage as switches or toggles at the command line,
 and the default controls which aliases are exposed. For example in an R
 script:
@@ -129,9 +129,10 @@ my-app --no-echo     # FALSE
 ```
 
 With `echo <- FALSE`, the positive alias `--echo` is supported.
-Assignments of `NA` remain boolean options that take a value, so omitting
-`echo <- NA` leaves `echo` as `NA` and supplying `--echo true` or
-`--echo false` records the caller's choice.
+Assignments of `NA` are tri-state boolean switches: omitting the flag
+leaves the value as `NA`, `--echo` sets it to `TRUE`, and `--no-echo`
+sets it to `FALSE`. Boolean switches also accept explicit values, such
+as `--echo=true`, `--echo=false`, `--echo true`, and `--echo false`.
 
 To omit the generated `--no-*` alias for a boolean switch, add
 `#| negative_alias: false` above the assignment:
@@ -147,6 +148,9 @@ strings rather than boolean aliases for non-bool values. For declared
 bool options, Rapp also accepts YAML 1.1 bool aliases such as `yes`,
 `no`, `y`, `n`, `on`, and `off` for backward compatibility.
 
+See [Boolean option behavior](docs/boolean-options.md) for a full table
+of boolean defaults, annotations, and accepted command-line forms.
+
 Assigning `c()` or `list()` declares an option that can be supplied
 multiple times. Use `c()` when you want to keep the exact strings
 provided on the command line, and `list()` when you want Rapp to attempt
@@ -373,7 +377,7 @@ command line arguments.
 | Assignment of `NULL`<br>`foo <- NULL` | Positional Arg<br>`APP foo-value` |
 | Assignment of `FALSE`<br>`foo <- FALSE` | Boolean switch<br>`APP --foo` |
 | Assignment of `TRUE`<br>`foo <- TRUE` | Boolean switch<br>`APP --no-foo` |
-| Assignment of `NA`<br>`foo <- NA` | Boolean option<br>`APP --foo true` or `APP --foo false` |
+| Assignment of `NA`<br>`foo <- NA` | Tri-state boolean switch<br>`APP --foo` or `APP --no-foo` |
 | Assignment of `c()` or `list()`<br>`foo <- c()` | Repeatable option<br>`APP --foo val1 --foo val2` |
 | Assignment of `NULL` to name with `...`<br>`args... <- NULL` | Positional Arg Collector<br>`APP foo bar baz` |
 | Switch with string literal<br>`switch("", cmd1 = {}, cmd2 = {})` | Required commands<br>`APP --help`<br>`APP cmd1 --help`<br>`APP cmd2 --help` |

docs/boolean-options.md

@@ -0,0 +1,26 @@
+# Boolean Option Behavior
+
+Logical defaults become boolean command-line inputs. Help output shows the
+most useful spelling for changing the default, while parsing also accepts
+explicit boolean values for convenience.
+
+In the table below, `TRUE`, `FALSE`, and `NA` are the resulting R values.
+`reject` means the command-line form is not accepted.
+
+| R definition | Help shows | Omitted | `--foo` | `--no-foo` | `--foo=true` | `--foo=false` | `--foo true` | `--foo false` |
+|---|---|---:|---:|---:|---:|---:|---:|---:|
+| `foo <- FALSE` | `--foo` | `FALSE` | `TRUE` | `FALSE` | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `foo <- TRUE` | `--no-foo` | `TRUE` | `TRUE` | `FALSE` | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `foo <- NA` | `--foo / --no-foo` | `NA` | `TRUE` | `FALSE` | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `#| negative_alias: false`<br>`foo <- FALSE` | `--foo` | `FALSE` | `TRUE` | reject | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `#| negative_alias: false`<br>`foo <- TRUE` | `--foo <FOO>` | `TRUE` | `TRUE` | reject | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `#| negative_alias: false`<br>`foo <- NA` | `--foo` | `NA` | `TRUE` | reject | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+| `#| arg_type: option`<br>`foo <- NA` | `--foo <FOO>` | `NA` | reject | reject | `TRUE` | `FALSE` | `TRUE` | `FALSE` |
+
+Bare `--foo` and `--no-foo` count as supplied values for boolean switches.
+Use `#| arg_type: option` when a boolean input should require an explicit
+value after `--foo`.
+
+`#| negative_alias: false` only disables the generated `--no-foo` spelling.
+It does not disable the positive spelling or explicit value forms such as
+`--foo=false`.