Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documenting the configuration file

  • Loading branch information...
commit 50c755bd8da9e3e29b9289c06fb783bdaa849501 1 parent d63ab6f
@AltGr AltGr authored
Showing with 97 additions and 30 deletions.
  1. +58 −9 .ocp-indent
  2. +39 −21 README.md
View
67 .ocp-indent
@@ -1,10 +1,59 @@
-# This is an example of configuration file; any file below this directory will
-# inherit from it, unless another conf-file is found.
-base = 2
-type = 2
-in = 0
-with = 0
-strict_with = never
-match_clause = 4 # this is non-default
+# This is an example of configuration file
+#
+# Copy to the root of your project, customise, and transparently get consistent
+# indentation on all your ocaml source files.
+
+# Number of spaces used in all base cases, for example:
+# let foo =
+# ^^bar
+base = 2
+
+# Indent for type definitions:
+# type t =
+# ^^int
+type = 2
+
+# Indent after `let in` (unless followed by another `let`):
+# let foo = () in
+# ^^bar
+in = 0
+
+# Indent after `match/try with` or `function`:
+# match foo with
+# ^^| _ -> bar
+with = 0
+
+# Wether the `with` parameter should be applied even when in a sub-block.
+# Can be `always`, `never` or `auto`.
+# if `always`, there are no exceptions
+# if `auto`, the `with` parameter is superseded when seen fit (most of the time,
+# but not after `begin match` for example)
+# if `never`, `with` is only applied if the match block starts a line.
+# For example, the following is not indented if set to `never`:
+# let f = function
+# ^^| Foo -> bar
+strict_with = never
+
+# Indent for clauses inside a pattern-match (after the arrow):
+# match foo with
+# | _ ->
+# ^^^^bar
+# the default is 2, which aligns the pattern and the expression
+match_clause = 4 # this is non-default
+
+# Ocp-indent will normally try to preserve your in-comment indentation, as long
+# as it respects the left-margin or starts with `(*\n`. Setting this to `true`
+# forces alignment within comments.
strict_comments = false
-align_params = auto
+
+# Function parameters are normally indented one level from the line containing
+# the function. This option can be used to have them align relative to the
+# column of the function body instead.
+# if set to `always`, always align below the function
+# if `auto`, only do that when seen fit (mainly, after arrows)
+# if `never`, no alignment whatsoever
+# for example (left: `never`; right: `always or `auto)
+# match foo with # match foo with
+# | _ -> some_fun # | _ -> some_fun
+# ^^parameter # ^^parameter
+align_params = auto
View
60 README.md
@@ -66,6 +66,45 @@ You can also tell it to indent only a subsets of lines, and to output only the i
ocp-indent <src-file> --lines <l1>-<l2> --numeric
```
+## Configuration options
+
+By default, `ocp-indent` comes with sensible default parameters. However,
+you can customize some of the indentation options using command-line
+arguments. For more details, see:
+
+```bash
+ocp-indent --config help
+```
+
+### Configuration file
+The same parameters can be defined in a configuration file, allowing for user
+defaults and per-project parameters. The latter is particularly convenient to
+transparently ensure consistency in projects with many contributors, without
+requiring them to change their settings in any way (except that, obviously, they
+need to use ocp-indent !).
+
+`ocp-indent` will look for `~/.ocp/ocp-indent.conf` to setup its default, then
+search for a `.ocp-indent` file in the current directory and its parents,
+stopping if one if found. These parameters can still, of course, be overridden
+by the environment variable `OCP_INDENT_CONFIG` or the command-line options, in
+this order.
+
+Have a look at ocp-indent's own [`.ocp-indent`](.ocp-indent) file for an
+example.
+
+### In-file configuration
+There is no built-in support for in-file configuration directives. Yet, some
+editors already provide that features, and with emacs, starting your file with a
+line like:
+
+```
+(* -*- ocp-indent-config: in=2 -*- *)
+```
+
+will enable you to have the indentation after `in` setup to 2 locally on this
+file.
+
+
## How does it compare to tuareg ?
We've run some benchmarks on real code-bases and the result is quite
@@ -103,24 +142,3 @@ The tests are organized as follows:
Please make sure tu run `make && tests/test.sh --git-update` before any commit,
so that the repo always reflects the state of the program.
-
-## Configuration options
-
-By default, `ocp-indent` comes with sensible default options. However,
-you can customize some of the indentation options using command-line
-options. For more details, see:
-
-```bash
-ocp-indent --config help
-```
-
-There is no built-in support for in-file configuration directives. Yet, some
-editors already provide that features, and with emacs, starting your file with a
-line like:
-
-```
-(* -*- ocp-indent-config: in=2 -*- *)
-```
-
-will enable you to have the indentation after `in` setup to 2 locally on this
-file.
Please sign in to comment.
Something went wrong with that request. Please try again.