From 0fe2995e08495d12b54c0d39c6b5bfdf5da395c4 Mon Sep 17 00:00:00 2001 From: Lennart Spitzner Date: Sat, 30 Jul 2016 23:12:46 +0200 Subject: [PATCH] Create README.md --- README.md | 46 ++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 46 insertions(+) create mode 100644 README.md diff --git a/README.md b/README.md new file mode 100644 index 0000000..28b1006 --- /dev/null +++ b/README.md @@ -0,0 +1,46 @@ +# brittany +haskell source code formatter + +This project's goals roughly are to: + +- Be idempotent (this also directly ensures that only valid haskell is + produced); +- Support the full ghc-haskell syntax including syntactic extensions; +- Retain newlines and comments unmodified; +- Be clever about using the available horizontal space while not overflowing + it if it cannot be avoided; +- Have linear complexity in the size of the input. + +At this point, these goals are completed to different degrees. It is not +ensured that only syntactically valid haskell is produced (yet), and coverage +of the project's testsuite is rather limited. By using ghc-exactprint as the +parser, brittany supports full ghc syntax including extensions, but many of the +more obscure cases are not handled yet. More importantly, only type-signatures +and function/value bindings are processed; other module elements (data-decls, +classes, instances, imports/exports etc.) are not +transformed in any way; this extends to e.g. bindings inside class instance +definitions - they won't be touched (yet). + +The current algorithm is rather clever about horizontal space while still being +linear in the size of the input (although the constant factor is not small). + +# Important notes + +- `-XCPP` is not officially supported (yet). +- Some commandline flags mentioned in the help don't work yet (and won't even + be parsed correctly.) +- Creates a `brittany.yaml` config file _in the current directory_. I am aware + that this behaviour is not optimal. +- Currently some unhandled syntactical constructs don't raise errors; in such + cases the output will contain ghc-exactprint'ed code and some debugging + comment. This could easily make the output invalid haskell. +- There are cases where comments are not copied to the output (this will + be detected and the user will get an error); there are other cases where + comments are moved slightly; there are also cases where comments result in + wonky newline insertion (although this should be a purely aesthetic issue.) + +# Usage + +- Currently one mode of operation: Transform a single module. By default read + from `stdin` and written to `stdout`, but commandline arguments allow to + read/write from/to files.