Documentation request: include_str and format_args combination

[jkelleyrtp]

I noticed some weird behavior today and couldn't find any documentation on how it works. It seems that format_args! and include_str!can actually work together to do compile-time validation of file inputs. Like so:

let html = format_args!(include_str!("./index.html"), title="test");

Both of these are compiler builtins so their sources aren't easily accessible. However, in neither of their documentation did I see any mention of this behavior. Contrast this with a proc/decl macro that tries to parse the inners as a LitStr/literal:

macro_rules! parse_args {
    ($a:literal) => {};
}

fn test() {
    let nodes = parse_args!(include_str!("./htmlexample.html"));
}

with error:

   |
12 | macro_rules! parse_args {
   | ----------------------- when calling this macro
...
17 |     let nodes = parse_args!(include_str!("./htmlexample.html"));
   |                             ^^^^^^^^^^^ no rules expected this token in macro call

Is there any documentation for this behavior? Is there any way for macro developers to also leverage this mechanic for parse a str literal returned by include_str!?

[ehuss]

This is called "eager expansion" and is unfortunately not well documented at this time (the only thing I can find is this). It is only done for some internal macros. There is no mechanism for doing this as a macro developer. There were efforts in the past such as RFC 2320 to make it more generally available, but it is a very tricky topic that would take a lot of work to design.

[inquisitivecrystal]

@rustbot label +A-macros +C-enhancement +T-compiler +T-doc