Thanks for the PR. I think there's a better way to do this. For one, I want to use @monouser7dig's idea to have a feature equivalent to clang-format where you can turn on and off the formatter for sections.

My original idea, which you coded up, has the problem that if there were ever another reason to put meta-information in a comment like this, which comment is "first" would fight with each other.

So the approach I would want to take on this issue is to have the support be in std.zig.render. It would look for a LineComment token before every top level declaration. If it found one that disabled formatting, then it would scan for the next LineComment that re-enables formatting (or EOF), and then directly copy bytes from the source buffer to the output stream, and then skip over top level declarations until it was after the token that re-enabled formatting.

Thanks for the detailed feedback! I fully agree!
I didn't write this as a comprehensive solution, and I expected your answer.
However, it allows completely skipping over large files and not load them in memory, which seemed to be a concern, seeing that you mentioned file sizes in #1030.

Thanks

However, it allows completely skipping over large files and not load them in memory, which seemed to be a concern, seeing that you mentioned file sizes in #1030.

That's true! And I appreciate the effort. However, here is one of the Zen of Zig items:

• Avoid local maximums.

How that can be applied here is that we can focus our energy on the long-term solution that will solve this use case, rather than a temporary bandage.

That being said, the fact that you put the effort into this pull request means that I will leave it open until the problem is solved. And open pull requests are very motivating to resolve.

One other thing that needs to be considered is that we accept shebangs for zig run so this wouldn't be able to be put on the first line in every case. I think we'd need to handle a zig fmt: off (and maybe zig fmt: on) anywhere in a source file. Andrew seems to have covered this above so that looks fine.

So the approach I would want to take on this issue is to have the support be in std.zig.render. It would look for a LineComment token before every top level declaration. If it found one that disabled formatting, then it would scan for the next LineComment that re-enables formatting (or EOF), and then directly copy bytes from the source buffer to the output stream, and then skip over top level declarations until it was after the token that re-enabled formatting.

That wouldn't give much control over formatting, because formatting could only be turned off for entire top level declarations. clang-format allows enabling and disabling formatting anywhere in a file, not only before top level declarations.

clang-format also keeps track of blocks and indentation even when it is disabled :

$ cat test.c           
int a = 2;
// clang-format off
     if(a == 2){
// clang-format on
a = 3;
}

$ clang-format ./test.c
int a = 2;
// clang-format off
     if(a == 2){
  // clang-format on
  a = 3;
}

Here, it didn't format the if, but it did indent a = 3;

I fear that heavy refactoring will be needed and that simply scanning top level declaratinos isn't enough. (That is, if we want feature parity with clang-format)

We don't need feature parity with clang-format. I don't think the above code looks very good; the ability to produce such code is not something I will miss. I consider this issue resolved now.