Styling of Rust Frontmatter

[epage]

RFC 3503 adds the concept of a frontmatter to rust for the sake of RFC 3502: cargo-script.

Ideally, before stabilization, we decide on the style and get support for it.

PR:

• docs(style): Specify the frontmatter style rust#145617

Tracking:

• Tracking Issue for cargo-script RFC 3424 cargo#12207

[epage]

Question 1: Should Style Guide recommend blank lines before frontmatter? If so, no blank lines or one?

Compare:

#!/usr/bin/env cargo
---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

#!/usr/bin/env cargo

---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

[epage]

Question 2: Should the style guide specify the blank lines after a frontmatter? If so, no blank lines or one?

Compare:

#!/usr/bin/env cargo
---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---
use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

#!/usr/bin/env cargo
---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

#!/usr/bin/env cargo
---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---




use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

[epage]

Question 3: Should Style Guide specify spacing between code fence and infostring? If so, no spaces or 1 space?

Compare:

#!/usr/bin/env cargo
---cargo
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

#!/usr/bin/env cargo
---    cargo     
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

[epage]

Question 4: Should Style Guide specify the number of dashes to use? If so, should it be the minimum necessary?

Compare:

#!/usr/bin/env cargo
---
[dependencies]
clap = { version = "4.2", features = ["derive"] }
---

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

#!/usr/bin/env cargo
-----------------------
[dependencies]
clap = { version = "4.2", features = ["derive"] }
-----------------------

use clap::Parser;

#[derive(Parser, Debug)]
#[clap(version)]
struct Args {
    #[clap(short, long, help = "Path to config")]
    config: Option<std::path::PathBuf>,
}

fn main() {
    let args = Args::parse();
    println!("{:?}", args);
}

[epage]

There is also the question of whether this issue, rust-lang/rustfmt#4091, or another issue should be responsible for processing the embedded Cargo.toml.

[epage]

Also, are there any expectations from rustc's lexer that need to be kept in mind for rustfmt? My initial assumption is to eat the frontmatter like we eat shebangs but I'm assuming rustfmt uses the lexer and that that might not work for you.

[ytmimi]

Also, are there any expectations from rustc's lexer that need to be kept in mind for rustfmt? My initial assumption is to eat the frontmatter like we eat shebangs but I'm assuming rustfmt uses the lexer and that that might not work for you.

rustfmt uses the rustc parser. Is it possible to represent the frontmatter in the AST? That would be ideal for formatting.

[alanwsmith]

Would punting on the front matter be an acceptable first step? Meaning, don't make an attempt to format it. Just leave it as is and format the rest of the file as if the frontmatter didn't exist.

(POV: I use scripts all the time and don't really care about the formatting of the frontmatter, but my goodness would it be nice to have the rest of the file formatted automatically. If not worrying about the frontmatter's format gets there faster, I'm all in.)

[epage]

This was discussed on #t-compiler/help > Pointers for implementing cargo scrpt support @ 💬

No concerns about that from me. If we eventually want to format the frontmatter it might be useful to represent it in the AST, but after looking into this a little more we could probably get away with not creating a designated AST node for it.

If the only thing we care about right now is that rustfmt leaves the frontmatter unchanged, including leading and trailing whitespace, then I think we should be good to go as long as the parser knows to ignore the frontmatter when generating the AST.

[epage]

If T-style agrees that frontmatter can remain neutral for the initial release, does that need to be represented in the style guide somehow?

[ytmimi]

@epage is frontmatter nightly-only? If so then I don't think the guide needs to be updated