Add options to control list formatting (#753)

Add the `--list-heading` option, to override the heading text printed before a list, defaulting to `Available recipes:\n`, and `--list-prefix`, to override the indentation before each list item.
2021-02-09 01:00:04 -08:00 · 2021-02-09 01:00:04 -08:00 · bac851ff68
commit bac851ff68
parent 6305114024
8 changed files with 122 additions and 19 deletions
--- a/README.adoc
+++ b/README.adoc
@ -233,10 +233,10 @@ Recipes can be listed in alphabetical order with `just --list`:
 ```sh
 $ just --list
 Available recipes:
-  build
-  test
-  deploy
-  lint
+    build
+    test
+    deploy
+    lint
 ```

 `just --summary` is more concise:
@ -259,8 +259,8 @@ build:
 ```sh
 $ just --list --unsorted
 Available recipes:
-  test
-  build
+    test
+    build
 ```

 ```sh
@ -276,6 +276,24 @@ default:
  @just --list
 ```

+The heading text can be customized with `--list-heading`:
+
+```
+$ just --list --list-heading 'Cool stuff…\n'
+Cool stuff…
+    test
+    build
+```
+
+And the indentation can be customized with `--list-prefix`:
+
+```
+$ just --list --list-prefix ····
+Available recipes:
+····test
+····build
+```
+
 === Aliases

 Aliases allow recipes to be invoked with alternative names:
@ -1077,7 +1095,7 @@ _test-helper:
 ```sh
 $ just --list
 Available recipes:
-  test
+    test
 ```

 And from `just --summary`:
--- a/completions/just.bash
+++ b/completions/just.bash
@ -20,7 +20,7 @@ _just() {

    case "${cmd}" in
        just)
-            opts=" -q -u -v -e -l -h -V -f -d -s  --dry-run --highlight --no-dotenv --no-highlight --quiet --clear-shell-args --unsorted --verbose --choose --dump --edit --evaluate --init --list --summary --variables --help --version --chooser --color --justfile --set --shell --shell-arg --working-directory --completions --show  <ARGUMENTS>... "
+            opts=" -q -u -v -e -l -h -V -f -d -s  --dry-run --highlight --no-dotenv --no-highlight --quiet --clear-shell-args --unsorted --verbose --choose --dump --edit --evaluate --init --list --summary --variables --help --version --chooser --color --list-heading --list-prefix --justfile --set --shell --shell-arg --working-directory --completions --show  <ARGUMENTS>... "
                if [[ ${cur} == -* ]] ; then
                    COMPREPLY=( $(compgen -W "${opts}" -- "${cur}") )
                    return 0
@ -41,6 +41,14 @@ _just() {
                    COMPREPLY=($(compgen -W "auto always never" -- "${cur}"))
                    return 0
                    ;;
+                --list-heading)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
+                --list-prefix)
+                    COMPREPLY=($(compgen -f "${cur}"))
+                    return 0
+                    ;;
                --justfile)
                    COMPREPLY=($(compgen -f "${cur}"))
                    return 0
--- a/completions/just.elvish
+++ b/completions/just.elvish
@ -16,8 +16,10 @@ edit:completion:arg-completer[just] = [@words]{
        &'just'= {
            cand --chooser 'Override binary invoked by `--choose`'
            cand --color 'Print colorful output'
-            cand -f 'Use <JUSTFILE> as justfile.'
-            cand --justfile 'Use <JUSTFILE> as justfile.'
+            cand --list-heading 'Print <TEXT> before list'
+            cand --list-prefix 'Print <TEXT> before each list item'
+            cand -f 'Use <JUSTFILE> as justfile'
+            cand --justfile 'Use <JUSTFILE> as justfile'
            cand --set 'Override <VARIABLE> with <VALUE>'
            cand --shell 'Invoke <SHELL> to run recipes'
            cand --shell-arg 'Invoke shell with <SHELL-ARG> as an argument'
--- a/completions/just.fish
+++ b/completions/just.fish
@ -11,7 +11,9 @@ complete -c just -a '(__fish_just_complete_recipes)'
 # autogenerated completions
 complete -c just -n "__fish_use_subcommand" -l chooser -d 'Override binary invoked by `--choose`'
 complete -c just -n "__fish_use_subcommand" -l color -d 'Print colorful output' -r -f -a "auto always never"
-complete -c just -n "__fish_use_subcommand" -s f -l justfile -d 'Use <JUSTFILE> as justfile.'
+complete -c just -n "__fish_use_subcommand" -l list-heading -d 'Print <TEXT> before list'
+complete -c just -n "__fish_use_subcommand" -l list-prefix -d 'Print <TEXT> before each list item'
+complete -c just -n "__fish_use_subcommand" -s f -l justfile -d 'Use <JUSTFILE> as justfile'
 complete -c just -n "__fish_use_subcommand" -l set -d 'Override <VARIABLE> with <VALUE>'
 complete -c just -n "__fish_use_subcommand" -l shell -d 'Invoke <SHELL> to run recipes'
 complete -c just -n "__fish_use_subcommand" -l shell-arg -d 'Invoke shell with <SHELL-ARG> as an argument'
--- a/completions/just.powershell
+++ b/completions/just.powershell
@ -21,8 +21,10 @@ Register-ArgumentCompleter -Native -CommandName 'just' -ScriptBlock {
        'just' {
            [CompletionResult]::new('--chooser', 'chooser', [CompletionResultType]::ParameterName, 'Override binary invoked by `--choose`')
            [CompletionResult]::new('--color', 'color', [CompletionResultType]::ParameterName, 'Print colorful output')
-            [CompletionResult]::new('-f', 'f', [CompletionResultType]::ParameterName, 'Use <JUSTFILE> as justfile.')
-            [CompletionResult]::new('--justfile', 'justfile', [CompletionResultType]::ParameterName, 'Use <JUSTFILE> as justfile.')
+            [CompletionResult]::new('--list-heading', 'list-heading', [CompletionResultType]::ParameterName, 'Print <TEXT> before list')
+            [CompletionResult]::new('--list-prefix', 'list-prefix', [CompletionResultType]::ParameterName, 'Print <TEXT> before each list item')
+            [CompletionResult]::new('-f', 'f', [CompletionResultType]::ParameterName, 'Use <JUSTFILE> as justfile')
+            [CompletionResult]::new('--justfile', 'justfile', [CompletionResultType]::ParameterName, 'Use <JUSTFILE> as justfile')
            [CompletionResult]::new('--set', 'set', [CompletionResultType]::ParameterName, 'Override <VARIABLE> with <VALUE>')
            [CompletionResult]::new('--shell', 'shell', [CompletionResultType]::ParameterName, 'Invoke <SHELL> to run recipes')
            [CompletionResult]::new('--shell-arg', 'shell-arg', [CompletionResultType]::ParameterName, 'Invoke shell with <SHELL-ARG> as an argument')
--- a/completions/just.zsh
+++ b/completions/just.zsh
@ -17,8 +17,10 @@ _just() {
    local common=(
 '--chooser=[Override binary invoked by `--choose`]' \
 '--color=[Print colorful output]: :(auto always never)' \
-'-f+[Use <JUSTFILE> as justfile.]' \
-'--justfile=[Use <JUSTFILE> as justfile.]' \
+'--list-heading=[Print <TEXT> before list]' \
+'--list-prefix=[Print <TEXT> before each list item]' \
+'-f+[Use <JUSTFILE> as justfile]' \
+'--justfile=[Use <JUSTFILE> as justfile]' \
 '*--set[Override <VARIABLE> with <VALUE>]: :_just_variables' \
 '--shell=[Invoke <SHELL> to run recipes]' \
 '*--shell-arg=[Invoke shell with <SHELL-ARG> as an argument]' \
--- a/src/config.rs
+++ b/src/config.rs
@ -19,6 +19,8 @@ pub(crate) struct Config {
  pub(crate) dry_run:              bool,
  pub(crate) highlight:            bool,
  pub(crate) invocation_directory: PathBuf,
+  pub(crate) list_heading:         String,
+  pub(crate) list_prefix:          String,
  pub(crate) load_dotenv:          bool,
  pub(crate) search_config:        SearchConfig,
  pub(crate) shell:                String,
@ -73,6 +75,8 @@ mod arg {
  pub(crate) const COLOR: &str = "COLOR";
  pub(crate) const DRY_RUN: &str = "DRY-RUN";
  pub(crate) const HIGHLIGHT: &str = "HIGHLIGHT";
+  pub(crate) const LIST_HEADING: &str = "LIST-HEADING";
+  pub(crate) const LIST_PREFIX: &str = "LIST-PREFIX";
  pub(crate) const JUSTFILE: &str = "JUSTFILE";
  pub(crate) const NO_DOTENV: &str = "NO-DOTENV";
  pub(crate) const NO_HIGHLIGHT: &str = "NO-HIGHLIGHT";
@ -123,6 +127,20 @@ impl Config {
          .help("Highlight echoed recipe lines in bold")
          .overrides_with(arg::NO_HIGHLIGHT),
      )
+      .arg(
+        Arg::with_name(arg::LIST_HEADING)
+          .long("list-heading")
+          .help("Print <TEXT> before list")
+          .value_name("TEXT")
+          .takes_value(true),
+      )
+      .arg(
+        Arg::with_name(arg::LIST_PREFIX)
+          .long("list-prefix")
+          .help("Print <TEXT> before each list item")
+          .value_name("TEXT")
+          .takes_value(true),
+      )
      .arg(
        Arg::with_name(arg::NO_DOTENV)
          .long("no-dotenv")
@ -139,7 +157,7 @@ impl Config {
          .short("f")
          .long("justfile")
          .takes_value(true)
-          .help("Use <JUSTFILE> as justfile."),
+          .help("Use <JUSTFILE> as justfile"),
      )
      .arg(
        Arg::with_name(arg::QUIET)
@ -439,6 +457,14 @@ impl Config {
      shell: matches.value_of(arg::SHELL).unwrap().to_owned(),
      load_dotenv: !matches.is_present(arg::NO_DOTENV),
      unsorted: matches.is_present(arg::UNSORTED),
+      list_heading: matches
+        .value_of(arg::LIST_HEADING)
+        .unwrap_or("Available recipes:\n")
+        .to_owned(),
+      list_prefix: matches
+        .value_of(arg::LIST_PREFIX)
+        .unwrap_or("    ")
+        .to_owned(),
      color,
      invocation_directory,
      search_config,
@ -687,7 +713,7 @@ impl Config {
    let max_line_width = cmp::min(line_widths.values().cloned().max().unwrap_or(0), 30);

    let doc_color = self.color.stdout().doc();
-    println!("Available recipes:");
+    print!("{}", self.list_heading);

    for recipe in justfile.public_recipes(self.unsorted) {
      let name = recipe.name();
@ -696,7 +722,7 @@ impl Config {
        .chain(recipe_aliases.get(name).unwrap_or(&Vec::new()))
        .enumerate()
      {
-        print!("    {}", name);
+        print!("{}{}", self.list_prefix, name);
        for parameter in &recipe.parameters {
          if self.color.stdout().active() {
            print!(" {:#}", parameter);
@ -847,7 +873,9 @@ OPTIONS:
            Print shell completion script for <SHELL> [possible values: zsh, bash, fish, \
                                 powershell, elvish]

-    -f, --justfile <JUSTFILE>                      Use <JUSTFILE> as justfile.
+    -f, --justfile <JUSTFILE>                      Use <JUSTFILE> as justfile
+        --list-heading <TEXT>                      Print <TEXT> before list
+        --list-prefix <TEXT>                       Print <TEXT> before each list item
        --set <VARIABLE> <VALUE>                   Override <VARIABLE> with <VALUE>
        --shell <SHELL>                            Invoke <SHELL> to run recipes [default: sh]
        --shell-arg <SHELL-ARG>...                 Invoke shell with <SHELL-ARG> as an argument \
--- a/tests/misc.rs
+++ b/tests/misc.rs
@ -1108,6 +1108,47 @@ a:
  "#,
 }

+test! {
+  name:     list_heading,
+  justfile: r#"
+a:
+b:
+"#,
+  args:     ("--list", "--list-heading", "Cool stuff…\n"),
+  stdout:   r#"
+    Cool stuff…
+        a
+        b
+  "#,
+}
+
+test! {
+  name:     list_prefix,
+  justfile: r#"
+a:
+b:
+"#,
+  args:     ("--list", "--list-prefix", "····"),
+  stdout:   r#"
+    Available recipes:
+    ····a
+    ····b
+  "#,
+}
+
+test! {
+  name:     list_empty_prefix_and_heading,
+  justfile: r#"
+a:
+b:
+"#,
+  args:     ("--list", "--list-heading", "", "--list-prefix", ""),
+  stdout:   r#"
+    a
+    b
+  "#,
+}
+
 test! {
  name:     show_suggestion,
  justfile: r#"