Polish README and --help output

.gitignore

@@ -3,3 +3,5 @@
 .Rdata
 .httr-oauth
 .DS_Store
+/.quarto/
+**/*.quarto_ipynb

NEWS.md

@@ -1,18 +1,21 @@
 # Rapp (development version)
 
-* Added support for commands in Rapp applications (#8, #11).
-* Added support for short opts (#4, #5).
-* New `install_pkg_cli_apps()` installs Rapps and R scripts
-  in a package's `exec/` directory on the users `PATH` (#7, #3).
-* Declaring `c()` or `list()` defaults now creates repeatable CLI options.
+-   New `install_pkg_cli_apps()` installs Rapps and R scripts in a
+    package's `exec/` directory onto the users `PATH` (#7, #3).
+-   Added support for commands in Rapp applications (#8, #11).
+-   Added support for short opts (#4, #5).
+-   Simple assignment of `c()` or `list()` now creates a repeatable CLI
+    option.
+-   Positional arguments are now required by default, unless annotation
+    `#| required: false` is supplied (#13).
 
 # Rapp 0.2.0
 
-* Updated default `--help` output.
-* Added a package logo.
-* Moved repository to 'r-lib' on Github
-* Added a `NEWS.md` file to track changes to the package.
+-   Updated default `--help` output.
+-   Added a package logo.
+-   Moved repository to 'r-lib' on Github
+-   Added a `NEWS.md` file to track changes to the package.
 
 # Rapp 0.1.0
 
-* Initial release
+-   Initial release

R/app.R

@@ -236,6 +236,13 @@ get_app_inputs <- function(app, exprs = app$exprs, pos = integer()) {
       arg[names(anno)] <- anno
     }
 
+    # By default, positional arguments are required unless explicitly
+    # annotated otherwise. This applies both to NULL-initialized
+    # positionals and those explicitly marked via `#| arg-type: positional`.
+    if (identical(arg$arg_type, "positional") && is.null(arg$required)) {
+      arg$required <- TRUE
+    }
+
     if (arg$arg_type == "positional") {
       args[[name]] <- arg
     } else {
@@ -266,8 +273,7 @@ parse_expr_anno <- function(lineno, lines, is_hashpipe) {
     anno_start <- anno_start - 1L
   }
   normalize_anno_keys(parse_hashpipe_yaml(
-    lines[anno_start:anno_end],
-    handlers = list("bool#yes" = identity, "bool#no" = identity)
+    lines[anno_start:anno_end]
   ))
 }
 

R/args.R

@@ -177,7 +177,7 @@ process_args <- function(args, app) {
     app$exprs[[spec$.val_pos_in_exprs]] <- val
   }
 
-  if (length(positional_args)) {
+  if (length(positional_args) || length(app_args)) {
     # we've parsed all the command line args,
     # we can now match positional args
     specs <- app_args %||% structure(list(), names = character())
@@ -189,15 +189,20 @@ process_args <- function(args, app) {
     if (length(collector) > 1) {
       stop(
         "Only one collector positional arg permitted, encountered:",
-        paste(names(specs)[collector], collapse = ", ")
+        paste(names(specs)[collector], collapse = ", "),
+        call. = FALSE
       )
     }
 
     if (length(collector)) {
       specs[[collector]]$variadic <- TRUE
       n_short <- length(positional_args) - length(specs)
       if (n_short < 0) {
-        specs[[collector]] <- NULL
+        # If a collector is present but there aren't enough positional args,
+        # drop the collector slot only when it's not explicitly required.
+        if (!isTRUE(specs[[collector]]$required)) {
+          specs[[collector]] <- NULL
+        }
       } else if (n_short > 0) {
         collector_spec <- specs[collector]
         collector_spec[[1]]$action <- "append"
@@ -213,6 +218,23 @@ process_args <- function(args, app) {
       )
     }
 
+    if (length(specs) != length(positional_args)) {
+      for (i in rev(seq_along(specs))) {
+        if (isFALSE(specs[[i]]$required)) {
+          specs[[i]] <- NULL
+        }
+        if (length(specs) == length(positional_args)) break
+      }
+      if (length(specs) != length(positional_args)) {
+        n_missing <- length(specs) - length(positional_args)
+        noun <- if (length(n_missing) == 1L) "argument" else "arguments"
+        nms <- names(specs[seq(to = length(specs), length.out = n_missing)])
+        nms <- toupper(gsub("_", "-", nms, fixed = TRUE))
+        nms <- paste0(nms, collapse = ", ")
+        stop(sprintf("Missing required %s: %s", noun, nms), call. = FALSE)
+      }
+    }
+
     for (i in seq_along(positional_args)) {
       spec <- specs[[i]]
       if (identical(spec$action, "append")) {

R/help.R

@@ -381,47 +381,34 @@ print_app_help <- function(app, yaml = TRUE, scope = NULL) {
   usage_components <- c(usage_components, build_usage_args(current_args))
   usage_line <- paste("Usage:", paste(usage_components, collapse = " "))
 
-  header_lines <- character()
+  title <- current_meta$title
+  description <- current_meta$description
+
   if (length(scope) == 1L) {
-    title <- current_meta$title
-    desc <- current_meta$description
-    if (length(title)) {
-      header_lines <- wrap_lines(title)
-      if (length(desc)) {
-        header_lines <- c(
-          header_lines,
-          "",
-          wrap_lines(sprintf("%s: %s", app_name, desc))
-        )
-      }
-    } else if (length(desc)) {
-      header_lines <- wrap_lines(sprintf("%s: %s", app_name, desc))
-    } else {
-      header_lines <- app_name
+    if (is.null(description) && is.null(title)) {
+      description <- app_name
     }
+  } else if (is.null(description) && is.null(title)) {
+    description <- sprintf("%s command", utils::tail(full_command, 1L))
+  }
+
+  title_lines <- if (!is.null(title)) wrap_lines(title) else character()
+  description_lines <- if (!is.null(description)) {
+    wrap_lines(description)
   } else {
-    title <- current_meta$title
-    description <- current_meta$description
-    if (length(title)) {
-      header_lines <- wrap_lines(title)
-      if (length(description)) {
-        header_lines <- c(header_lines, "", wrap_lines(description))
-      }
-    } else if (length(description)) {
-      header_lines <- wrap_lines(description)
-    }
-    if (!length(header_lines)) {
-      header_lines <- wrap_lines(
-        sprintf("%s command", utils::tail(full_command, 1L))
-      )
-    }
+    character()
   }
 
-  sections <- list(
-    header_lines,
-    "",
-    usage_line
-  )
+  intro_lines <- character()
+  if (length(title_lines)) {
+    intro_lines <- c(intro_lines, title_lines, "")
+  }
+  intro_lines <- c(intro_lines, usage_line)
+  if (length(description_lines)) {
+    intro_lines <- c(intro_lines, "", description_lines)
+  }
+
+  sections <- list(intro_lines)
 
   command_block <- format_command_block(current_commands)
   if (length(command_block)) {

R/install.R

@@ -405,15 +405,15 @@ install_rapp_launcher <- function(destdir, overwrite = NA) {
       paste("::", sentinel),
       "setlocal",
       sprintf(
-        r"("%s/Rscript.exe" --default-packages=base -e Rapp::run() %%*)",
+        r"("%s/Rscript.exe" -e Rapp::run() %%*)",
         R.home("bin")
       )
     ),
     unix = c(
       "#!/bin/sh",
       paste("#", sentinel),
       sprintf(
-        r"(exec %s/Rscript --default-packages=base -e 'Rapp::run()' "$@")",
+        r"(exec %s/Rscript -e 'Rapp::run()' "$@")",
         R.home("bin")
       )
     )