Add extensible recipe and justfile annotations

[casey]

I think that Just would benefit from syntax for annotations / attributes.

This might be used for:

• Controlling printing of scripts for shebang recipes. (Consider inverting behavior of @ on shebang recipes #603)
• Annotating recipes with the OS/shell they should run with (Cross-platform justfiles #531)
• For use instead of @ for controlling line printing. (#[quiet] instead of @)
• Enabling unstable features in a justfile.

I've been thinking about rust-style (#[foo]) or C# style ([foo]), and I think rust style would be better, since it won't conflict with array notation ([...]), and there's a precedent for attributes that apply to the containing item (#![foo]).

So recipe attributes would look like:

#[quiet]
foo:
  echo foo

and module attributes would look like:

#![feature(modules)]

# rest of justfile

An initial PR need only support recipe or module attributes, not both, and could initially only support a single ident as the attribute contents.

[plus7wist]

Good idea :3

[plus7wist]

I like the Rust style, because just is written in Rust. Rust guys will be happy.

[runeimp]

I think both styles are fine. The C# user base is, I believe, significantly larger than the Rust user base. So the syntax would be more familiar to more people. On the other hand The C# style makes me thing INI file and annotations should not be confused with section headers. The Rust style actually looks more like an annotation to me too.

[casey]

Just to make an arbitrary decision, let's go with Rust-style. I personally think that C# is nicer looking, but I do like that Rust-style makes it clear that they're annotations.

[rjsberry]

I would contend that the C# style is a better choice.

Everywhere else we have # to start comments. I think that the lack of the hash creates strong visual separation between the comment for the recipe and the recipe itself.

When using make syntax for highlighting on GitHub/similar, it also means that the attributes will not be highlighted as comments.

Consider:

# this is an example
#[foo]
#[bar]
baz:
  echo baz

The attributes are obviously highlighted wrong. But also they are not clearly attributes at a glance because of the leading #.

Compare this to:

# this is an example
[foo]
[bar]
baz:
  echo baz

I personally find this much clearer. Visually speaking the lines containing attributes are cleanly separated from the comment as the first character of the line is [.

[casey]

I do think that C# attributes are more attractive, and the syntax highlighting argument is persuasive. C# uses curly braces for arrays (e.g. {1,2,3,4}), so there's no ambiguity there. Using […] for annotations would mean that we couldn't use […] for arrays in Just, which doesn't seem ideal.

[casey]

We have our first annotation, [no-exit-message], implemented in #1354, so I guess we're going with C#-style annotations, which is nice, since they won't be hidden as comments.

[casey]

And we can still use […] for arrays, since annotations and arrays are unlikely to be in the same positions in the grammar.

[mkatychev]

@casey are there any discussions on doing cargo style [not(condition)]/[condition] annotations?:

[not(windows)]
run:
  cc main.c
  ./a.out
  
[windows]
run:
  cl main.c
  main.exe

I imagine my usecase is quite common for some when dealing with doing/avoiding setup specific to CI environments:

[env_var("CI") == "true"]
run:
  ./do_the_ci_setup.sh
  ./run.sh

[not(env_var("CI") == "true")]
run:
  ./run.sh

[casey]

I opened #1895 to track inverted cfg style attributes