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.

README.adoc

@@ -233,10 +233,10 @@ Recipes can be listed in alphabetical order with `just --list`:
 ```sh
 $ just --list
 Available recipes:
-  build
+    build
-  test
+    test
-  deploy
+    deploy
-  lint
+    lint
 ```
 
 `just --summary` is more concise:
@@ -259,8 +259,8 @@ build:
 ```sh
 $ just --list --unsorted
 Available recipes:
-  test
+    test
-  build
+    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`:

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

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 --list-heading 'Print <TEXT> before list'
-            cand --justfile 'Use <JUSTFILE> as justfile.'
+            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'

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'

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('--list-heading', 'list-heading', [CompletionResultType]::ParameterName, 'Print <TEXT> before list')
-            [CompletionResult]::new('--justfile', 'justfile', [CompletionResultType]::ParameterName, 'Use <JUSTFILE> as justfile.')
+            [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')

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.]' \
+'--list-heading=[Print <TEXT> before list]' \
-'--justfile=[Use <JUSTFILE> as justfile.]' \
+'--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]' \

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 \

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#"