Merge remote-tracking branch 'origin/master' into source-path

README.md

@@ -167,7 +167,7 @@ most Windows users.)
     <tr>
       <td><a href=https://www.npmjs.com/>npm</a></td>
       <td><a href=https://www.npmjs.com/package/rust-just>rust-just</a></td>
-      <td><code>npm install rust-just</code></td>
+      <td><code>npm install -g rust-just</code></td>
     </tr>
     <tr>
       <td><a href=https://pypi.org/>PyPI</a></td>
@@ -1851,6 +1851,24 @@ for details.
   `requirement`, e.g., `">=0.1.0"`, returning `"true"` if so and `"false"`
   otherwise.
 
+#### Style
+
+- `style(name)`<sup>master</sup> - Return a named terminal display attribute
+  escape sequence used by `just`. Unlike terminal display attribute escape
+  sequence constants, which contain standard colors and styles, `style(name)`
+  returns an escape sequence used by `just` itself, and can be used to make
+  recipe output match `just`'s own output.
+
+  Recognized values for `name` are `'command'`, for echoed recipe lines,
+  `error`, and `warning`.
+
+  For example, to style an error message:
+
+  ```just
+  scary:
+    @echo '{{ style("error") }}OH NO{{ NORMAL }}'
+  ```
+
 ##### XDG Directories<sup>1.23.0</sup>
 
 These functions return paths to user-specific directories for things like
@@ -2755,8 +2773,9 @@ scripts interpreted by `COMMAND`. This avoids some of the issues with shebang
 recipes, such as the use of `cygpath` on Windows, the need to use
 `/usr/bin/env`, and inconsistences in shebang line splitting across Unix OSs.
 
-Recipes with an empty `[script]` attribute are executed with the value of
-`set script-interpreter := […]`<sup>1.33.0</sup>, defaulting to `sh -eu`.
+Recipes with an empty `[script]` attribute are executed with the value of `set
+script-interpreter := […]`<sup>1.33.0</sup>, defaulting to `sh -eu`, and *not*
+the value of `set shell`.
 
 The body of the recipe is evaluated, written to disk in the temporary
 directory, and run by passing its path as an argument to `COMMAND`.

README.中文.md

@@ -220,6 +220,22 @@ list:
       <code>asdf install just &lt;version&gt;</code>
     </td>
   </tr>
+  <tr>
+    <td><a href="https://packaging.python.org/tutorials/installing-packages">Various</a></td>
+    <td><a href="https://pypi.org">PyPI</a></td>
+    <td><a href="https://pypi.org/project/rust-just">rust-just</a></td>
+    <td>
+      <code>pipx install rust-just</code><br>
+    </td>
+  </tr>
+  <tr>
+    <td><a href="https://docs.npmjs.com/packages-and-modules/getting-packages-from-the-registry">Various</a></td>
+    <td><a href="https://www.npmjs.com">npm</a></td>
+    <td><a href="https://www.npmjs.com/package/rust-just">rust-just</a></td>
+    <td>
+      <code>npm install -g rust-just</code><br>
+    </td>
+  </tr>
   <tr>
     <td><a href="https://debian.org">Debian</a> and <a href="https://ubuntu.com">Ubuntu</a> derivatives</td>
     <td><a href="https://mpr.makedeb.org">MPR</a></td>

src/color.rs

@@ -35,7 +35,6 @@ impl Color {
     Self::default()
   }
 
-  #[cfg(test)]
   pub(crate) fn always() -> Self {
     Self {
       use_color: UseColor::Always,
@@ -67,7 +66,7 @@ impl Color {
   }
 
   pub(crate) fn doc_backtick(self) -> Self {
-    self.restyle(Style::new().fg(White).on(Black))
+    self.restyle(Style::new().fg(Cyan))
   }
 
   pub(crate) fn error(self) -> Self {

src/function.rs

@@ -98,6 +98,7 @@ pub(crate) fn get(name: &str) -> Option<Function> {
     "snakecase" => Unary(snakecase),
     "source_directory" => Nullary(source_directory),
     "source_file" => Nullary(source_file),
+    "style" => Unary(style),
     "titlecase" => Unary(titlecase),
     "trim" => Unary(trim),
     "trim_end" => Unary(trim_end),
@@ -623,6 +624,20 @@ fn source_file(context: Context) -> FunctionResult {
     })
 }
 
+fn style(context: Context, s: &str) -> FunctionResult {
+  match s {
+    "command" => Ok(
+      Color::always()
+        .command(context.evaluator.context.config.command_color)
+        .prefix()
+        .to_string(),
+    ),
+    "error" => Ok(Color::always().error().prefix().to_string()),
+    "warning" => Ok(Color::always().warning().prefix().to_string()),
+    _ => Err(format!("unknown style: `{s}`")),
+  }
+}
+
 fn titlecase(_context: Context, s: &str) -> FunctionResult {
   Ok(s.to_title_case())
 }

src/node.rs

@@ -197,7 +197,7 @@ impl<'src> Node<'src> for UnresolvedRecipe<'src> {
       t.push_mut("quiet");
     }
 
-    if let Some(doc) = self.doc {
+    if let Some(doc) = &self.doc {
       t.push_mut(Tree::string(doc));
     }
 

src/parser.rs

@@ -936,6 +936,14 @@ impl<'run, 'src> Parser<'run, 'src> {
 
     let private = name.lexeme().starts_with('_') || attributes.contains(&Attribute::Private);
 
+    let mut doc = doc.map(ToOwned::to_owned);
+
+    for attribute in &attributes {
+      if let Attribute::Doc(attribute_doc) = attribute {
+        doc = attribute_doc.as_ref().map(|doc| doc.cooked.clone());
+      }
+    }
+
     Ok(Recipe {
       shebang: shebang || script,
       attributes,

src/recipe.rs

@@ -22,7 +22,7 @@ pub(crate) struct Recipe<'src, D = Dependency<'src>> {
   pub(crate) attributes: BTreeSet<Attribute<'src>>,
   pub(crate) body: Vec<Line<'src>>,
   pub(crate) dependencies: Vec<D>,
-  pub(crate) doc: Option<&'src str>,
+  pub(crate) doc: Option<String>,
   #[serde(skip)]
   pub(crate) file_depth: u32,
   #[serde(skip)]
@@ -465,7 +465,8 @@ impl<'src, D> Recipe<'src, D> {
         return doc.as_ref().map(|s| s.cooked.as_ref());
       }
     }
-    self.doc
+
+    self.doc.as_deref()
   }
 
   pub(crate) fn subsequents(&self) -> impl Iterator<Item = &D> {
@@ -475,8 +476,14 @@ impl<'src, D> Recipe<'src, D> {
 
 impl<'src, D: Display> ColorDisplay for Recipe<'src, D> {
   fn fmt(&self, f: &mut Formatter, color: Color) -> fmt::Result {
-    if let Some(doc) = self.doc {
-      writeln!(f, "# {doc}")?;
+    if !self
+      .attributes
+      .iter()
+      .any(|attribute| matches!(attribute, Attribute::Doc(_)))
+    {
+      if let Some(doc) = &self.doc {
+        writeln!(f, "# {doc}")?;
+      }
     }
 
     for attribute in &self.attributes {

tests/fmt.rs

@@ -1096,3 +1096,27 @@ fn multi_argument_attribute() {
     )
     .run();
 }
+
+#[test]
+fn doc_attribute_suppresses_comment() {
+  Test::new()
+    .justfile(
+      "
+        set unstable
+
+        # COMMENT
+        [doc('ATTRIBUTE')]
+        foo:
+      ",
+    )
+    .arg("--dump")
+    .stdout(
+      "
+        set unstable := true
+
+        [doc('ATTRIBUTE')]
+        foo:
+      ",
+    )
+    .run();
+}

tests/functions.rs

@@ -1183,3 +1183,78 @@ bar:
     .args(["foo", "bar"])
     .run();
 }
+
+#[test]
+fn style_command_default() {
+  Test::new()
+    .justfile(
+      r#"
+        foo:
+          @echo '{{ style("command") }}foo{{NORMAL}}'
+      "#,
+    )
+    .stdout("\x1b[1mfoo\x1b[0m\n")
+    .run();
+}
+
+#[test]
+fn style_command_non_default() {
+  Test::new()
+    .justfile(
+      r#"
+        foo:
+          @echo '{{ style("command") }}foo{{NORMAL}}'
+      "#,
+    )
+    .args(["--command-color", "red"])
+    .stdout("\x1b[1;31mfoo\x1b[0m\n")
+    .run();
+}
+
+#[test]
+fn style_error() {
+  Test::new()
+    .justfile(
+      r#"
+        foo:
+          @echo '{{ style("error") }}foo{{NORMAL}}'
+      "#,
+    )
+    .stdout("\x1b[1;31mfoo\x1b[0m\n")
+    .run();
+}
+
+#[test]
+fn style_warning() {
+  Test::new()
+    .justfile(
+      r#"
+        foo:
+          @echo '{{ style("warning") }}foo{{NORMAL}}'
+      "#,
+    )
+    .stdout("\x1b[1;33mfoo\x1b[0m\n")
+    .run();
+}
+
+#[test]
+fn style_unknown() {
+  Test::new()
+    .justfile(
+      r#"
+        foo:
+          @echo '{{ style("hippo") }}foo{{NORMAL}}'
+      "#,
+    )
+    .stderr(
+      r#"
+        error: Call to function `style` failed: unknown style: `hippo`
+         ——▶ justfile:2:13
+          │
+        2 │   @echo '{{ style("hippo") }}foo{{NORMAL}}'
+          │             ^^^^^
+      "#,
+    )
+    .status(EXIT_FAILURE)
+    .run();
+}

tests/json.rs

@@ -1507,3 +1507,58 @@ fn recipes_with_private_attribute_are_private() {
     },
   );
 }
+
+#[test]
+fn doc_attribute_overrides_comment() {
+  case(
+    "
+      # COMMENT
+      [doc('ATTRIBUTE')]
+      foo:
+    ",
+    json!({
+      "aliases": {},
+      "assignments": {},
+      "first": "foo",
+      "doc": null,
+      "groups": [],
+      "modules": {},
+      "recipes": {
+        "foo": {
+          "attributes": [{"doc": "ATTRIBUTE"}],
+          "body": [],
+          "dependencies": [],
+          "doc": "ATTRIBUTE",
+          "name": "foo",
+          "namepath": "foo",
+          "parameters": [],
+          "priors": 0,
+          "private": false,
+          "quiet": false,
+          "shebang": false,
+        }
+      },
+      "settings": {
+        "allow_duplicate_recipes": false,
+        "allow_duplicate_variables": false,
+        "dotenv_filename": null,
+        "dotenv_load": false,
+        "dotenv_path": null,
+        "dotenv_required": false,
+        "export": false,
+        "fallback": false,
+        "ignore_comments": false,
+        "positional_arguments": false,
+        "quiet": false,
+        "shell": null,
+        "tempdir" : null,
+        "unstable": false,
+        "windows_powershell": false,
+        "windows_shell": null,
+        "working_directory" : null,
+      },
+      "unexports": [],
+      "warnings": [],
+    }),
+  );
+}

tests/list.rs

@@ -452,7 +452,7 @@ fn backticks_highlighted() {
     .stdout(
       "
         Available recipes:
-            recipe \u{1b}[34m#\u{1b}[0m \u{1b}[34mComment \u{1b}[0m\u{1b}[40;37m``\u{1b}[0m\u{1b}[34m \u{1b}[0m\u{1b}[40;37m`with backticks`\u{1b}[0m\u{1b}[34m and trailing text\u{1b}[0m
+            recipe \u{1b}[34m#\u{1b}[0m \u{1b}[34mComment \u{1b}[0m\u{1b}[36m``\u{1b}[0m\u{1b}[34m \u{1b}[0m\u{1b}[36m`with backticks`\u{1b}[0m\u{1b}[34m and trailing text\u{1b}[0m
       ")
     .run();
 }
@@ -470,7 +470,7 @@ fn unclosed_backticks() {
     .stdout(
       "
         Available recipes:
-            recipe \u{1b}[34m#\u{1b}[0m \u{1b}[34mComment \u{1b}[0m\u{1b}[40;37m`with unclosed backick\u{1b}[0m
+            recipe \u{1b}[34m#\u{1b}[0m \u{1b}[34mComment \u{1b}[0m\u{1b}[36m`with unclosed backick\u{1b}[0m
       ")
     .run();
 }