on master help sign in
Update design notes for CPP.
commit5bffeffa05eae8014bc52e06c547ea5cc49c84a2 authorFacundo Domínguez <facundo.dominguez@tweag.io> dateFri 24 Apr 2020, 17:34 (6 years ago) parentfc64ead
2 files changed+15−14
DESIGN.md+11−11 README.md+4−3
DESIGN.md+11−11
@@ -24,7 +24,7 @@ It also includes recommendations for future implementers.
2424
2525We set for the following goals (mostly taken from
2626[brittany](https://github.com/lspitzner/brittany)):
27−* Preserve the meaning of the formatted functions;
27+* Preserve the meaning of the formatted functions when no CPP is used;
2828* Make reasonable use of screen space;
2929* Use linear space and computation time on the size of the input;
3030* Preserve comments;
@@ -140,8 +140,10 @@ impossible to guess what they'll be called on.
140140
141141### CPP
142142
143−Formatting a module which uses CPP directives won't be supported. Instead,
144−we hope for a solution to replace CPP to do conditional compilation.
143+We allow CPP directives in the input, but we forgo the goal to preserve the
144+meaning of the formatted functions in that case.
145+Instead of supporting CPP better, we hope for a solution to replace CPP to
146+do conditional compilation.
145147
146148There are the following challenges when formatting a module with CPP:
147149
@@ -180,14 +182,15 @@ True
180182```
181183
182184At the time of this writing, formatting this program with Hindent
183−produces the same output we would get if the CPP directives were
184−considered comments:
185+or Ormolu produces the same output we would get if the CPP directives
186+were considered comments:
185187
186188```
187−$ hindent --version
188−hindent 5.2.7
189+$ ormolu --version
190+ormolu 0.0.5.0 HEAD fc64eada5c4da7a5b07d2872e253671b48aec115
191+using ghc-lib-parser 8.10.1.20200412
189192
190−$ hindent test.hs
193+$ ormolu --mode inplace test.hs
191194
192195$ cat test.hs
193196{-# LANGUAGE CPP #-}
@@ -227,9 +230,6 @@ to parse Haskell modules. If CPP is replaced with some language
227230extension or mechanism to do conditional compilation, all tools
228231will benefit from it.
229232
230−Therefore, CPP won't be supported. If the CPP extension
231−is enabled, we should signal an error right away.
232−
233233### Printing
234234
235235Just pretty-printing code (following the approach of Hindent) seems sane. It
README.md+4−3
@@ -116,8 +116,9 @@ independent top-level definitions.
116116
117117* CPP support is experimental. CPP is virtually impossible to handle
118118 correctly, so we process them as a sort of unchangeable snippets. This
119− works only in simple cases when CPP conditionals are self-contained. Use
120− Ormolu with CPP at your own risk.
119+ works only in simple cases when CPP conditionals surround top-level
120+ declarations. See the [CPP][design-cpp] section in the design notes for
121+ a discussion of the dangers.
121122* Input modules should be parsable by Haddock, which is a bit stricter
122123 criterion than just being valid Haskell modules.
123124* Various minor idempotence issues, most of them are related to comments.
@@ -154,7 +155,7 @@ See [LICENSE.md][license].
154155
155156Copyright © 2018–present Tweag I/O
156157
157−[design]: https://github.com/tweag/ormolu/blob/master/DESIGN.md#cpp
158+[design-cpp]: https://github.com/tweag/ormolu/blob/master/DESIGN.md#cpp
158159[contributing]: https://github.com/tweag/ormolu/blob/master/CONTRIBUTING.md
159160[license]: https://github.com/tweag/ormolu/blob/master/LICENSE.md
160161[haskell-src-exts]: https://hackage.haskell.org/package/haskell-src-exts