<div class="gmail_quote">On Fri, May 11, 2012 at 7:26 PM, Chris Lattner <span dir="ltr"><<a href="mailto:clattner@apple.com" target="_blank">clattner@apple.com</a>></span> wrote:<br><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word"><br><div><div class="im"><div>On May 11, 2012, at 9:27 AM, Manuel Klimek wrote:</div><br><blockquote type="cite">Hi,<br><br>we're working on the design of clang-format; there are quite a few open questions, but I'd rather get some early feedback to see whether we're completely off track somewhere.<br>
</blockquote><div><br></div></div><div>Wow, having something like this would be great!</div><div class="im"><br><blockquote type="cite">For those of you who prefer good old email, here is a copy of the current state.</blockquote>
<div><br></div></div>+1 thanks :)</div><div><br></div><div><div class="im"><blockquote type="cite"><div><b style="font-family:'Times New Roman';font-size:medium"><h2 dir="ltr" style="display:inline!important"><span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Context</span></h2>
</b><b><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">While many other languages have auto-formatters available, C++ is still lacking a tool that fits the needs of the majority of C++ programmers. Note that when we talk about </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">formatting</span><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap"> as part of this document, we mean both the problem of </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">indentation</span><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap"> (which has been largely solved independently by regexp-based implementations in editors / IDEs) and </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">line breaking</span><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">, which proves to be a harder problem.</span><br>
</b></div></blockquote><div><br></div></div><div>Also variable naming, use of #includes, etc?  How much of <a href="http://llvm.org/docs/CodingStandards.html" target="_blank">http://llvm.org/docs/CodingStandards.html</a> is realistically enforcable/detectable?</div>
</div></div></blockquote><div><br></div><div>I think we want 2 tools:</div><div>1. The one proposed here, which deals with formatting; ordering includes is a corner case, doing static analysis to figure out iwyu or reverse-iwyu style rules is a clear non-gloal</div>
<div>2. What I call a "lint-style" tool, which will start right where clang-format leaves off and go deep into static analysis; the input format here I'd imagine to be more like "patterns" or "rules", whereas for clang-format I'm basically imagining a lot of bool values and some numbers for the configuration.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div class="im"><br><blockquote type="cite"><div><b><h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium">
<span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Goals</span></h2>

<ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt"><li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline"><span style="vertical-align:baseline;white-space:pre-wrap">Format a whole file according to a configuration</span></li>


<li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline"><span style="vertical-align:baseline;white-space:pre-wrap">Format a part of a file according to a configuration</span></li>


<li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline"><span style="vertical-align:baseline;white-space:pre-wrap">Format a part of a file while being consistent as best as possible with the rest of the file, while falling back to a configuration for options that cannot be deduced from the current file</span></li>


<li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline"><span style="vertical-align:baseline;white-space:pre-wrap">Integrating with editors so that you can just type away until you’re far past the column limit, and then hit a key and have the editor layout the code for you, including placing the right line breaks</span></li>
</ul></b></div></blockquote><div><br></div></div><div>Some wishlist items from me:</div><div>  - A "enforcer" mode that could be used in a post-commit script to find violations of the style.</div></div></div></blockquote>
<div><br></div><div>That should fall out naturally.</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div>  - A "scanner" mode that could be used to scan a corpus of existing code to find the dominant style, instead of having to manually configure a thousand arguments like indent.</div>
</div></div></blockquote><div><br></div><div>Definitely an interesting idea, and something to keep in mind - I don't know whether that would be one of the highest prio goals, but we should make it possible architecture-wise.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div class="im"><br><blockquote type="cite"><div><b><ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt">


</ul><h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium"><span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Non-goals</span></h2><ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt">
<li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline">

<span style="vertical-align:baseline;white-space:pre-wrap">Indenting code while you type; this is a much simpler problem, but has even stronger performance requirements - the current editors should be good enough, and we’ll allow new workflows that don’t ever require the user to break lines</span></li>
</ul></b></div></blockquote><div><br></div></div><div>Make sense, this is a different problem.</div><div class="im"><br><blockquote type="cite"><div><b><ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt">


<li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline"><span style="vertical-align:baseline;white-space:pre-wrap">The only lexical elements clang-format should touch are: whitespaces, string-literals and comments. Any other changes ranging from ordering includes to removing superfluous paranthesis are not in the scope of this tool.</span></li>
</ul></b></div></blockquote><blockquote type="cite"><div><b><ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt"><li style="list-style-type:disc;font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline">
<span style="vertical-align:baseline;white-space:pre-wrap">Per-file configuration: be able to annotate a file with a style which it adheres to (?)</span></li></ul></b></div></blockquote><div><br></div></div><div>If successful, the tool will probably be feature crept to support these.  I think it is completely sensible to subset these out from any initial implementation though: best to solve some small problems well (and then grow in scope) than to try to solve all problems and never got to a point where it is useful.</div>
</div></div></blockquote><div><br></div><div>I also think we can give sensible alternatives to some...</div><div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex">
<div style="word-wrap:break-word"><div><div class="im"><br><blockquote type="cite"><div><b><ul style="font-family:'Times New Roman';font-size:medium;margin-top:0pt;margin-bottom:0pt">

</ul><h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium"><span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Code location</span></h2><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">Clang-format is a very basic tool, so it might warrant living in clang mainstream. On the other hand it would also fit nicely with other clang refactoring tools. </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">TODO: Where do we want clang-format to live?</span><br>
</b></div></blockquote><div><br></div></div><div>No strong feeling.</div><div class="im"><br><blockquote type="cite"><div><b>

<h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium"><span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Parsing approach</span></h2><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">The key consideration is whether clang-format can be based </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">purely on a lexer</span><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">, or whether it needs type information, and we need the full </span><span style="font-size:15px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">AST</span><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">. </span><br>


<span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap"></span><br><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">We believe that we will need the full AST information to correctly indent code, break lines, and fix whitespace within a line.</span><br>
</b></div></blockquote><div><br></div></div><div>The major tradeoff here is that requiring an AST "requires" valid code and information on how to simulate the build.  If you can use just the lexer, then you can run on a random header file in isolation.</div>
<div><br></div><div>Perhaps it is possible to subset and layer things so that some stuff works with just the lexer (e.g. 80 column detection) but other stuff requires more integration with AST and build info?</div></div></div>
</blockquote><div><br></div><div>The very first draft I had that I didn't send to the list actually had this one question at its core: how much can we do with the lexer only?</div><div>The problem is that I think we'll not be able to do sufficiently better than standard-regexp-based solutions that it's worth the effort. Even indenting needs types (as Richard pointed out) when templates are involved.</div>
<div> </div><blockquote class="gmail_quote" style="margin:0 0 0 .8ex;border-left:1px #ccc solid;padding-left:1ex"><div style="word-wrap:break-word"><div><div class="im"><br><blockquote type="cite"><div><b><h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium">
<span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Configuration</span></h2><span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">To support a majority of developers, being able to configure the desired style is key. We propose using a YAML configuration file, as there’s already a YAML parser readily available in LLVM. Proposals for more specific ideas welcome.</span><br>
</b></div></blockquote><div><br></div></div>Makes sense to me.</div><div><div class="im"><br><blockquote type="cite"><div><b><h2 dir="ltr" style="font-family:'Times New Roman';font-size:medium"><span style="font-size:19px;font-family:Arial;vertical-align:baseline;white-space:pre-wrap">Style deduction</span></h2>
<span style="font-size:15px;font-family:Arial;font-weight:normal;vertical-align:baseline;white-space:pre-wrap">When changing the format of code that does not conform to a given style configuration, we will optionally try to deduce style options from the file first, and fall back to the configured layout when there was no clear style deducible from the context.</span><br>
</b></div></blockquote><div><br></div></div><div>+100 :)</div></div></div></blockquote><div><br></div><div>Thanks for you input!</div><div>/Manuel </div></div><br>