swrup/mte
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity

Browse source
This commit is contained in:
swrup 2025-10-06 21:52:32 +02:00
parent b1fbebfcfa
commit 748d199b9c
8 changed files with 721 additions and 51 deletions
Download patch file Download diff file Expand all files Collapse all files

673
fmt Normal file
View file

@ -0,0 +1,673 @@
OCAMLFORMAT(1) Ocamlformat Manual OCAMLFORMAT(1)
NAME
ocamlformat - A tool to format OCaml code.
SYNOPSIS
ocamlformat [OPTION]… [SRC]…
DESCRIPTION
ocamlformat automatically formats OCaml code.
OPTIONS (CODE FORMATTING STYLE)
Unless otherwise noted, any option --option=VAL detailed in this
section can be set in many ways, its value is determined in the
following order (of increasing priority): the default value is used if
no other value is specified. The value of a boolean option --foo or
--no-foo can be modified in an .ocamlformat configuration file with
'foo = {true,false}', it can be done for any other option with an
'option = VAL' line (*), or using the OCAMLFORMAT environment variable:
OCAMLFORMAT=option=VAL,...,option=VAL, or as an optional parameter on
the command line, or with a global [@@@ocamlformat "option=VAL"]
attribute in the processed file, or with an [@@ocamlformat
"option=VAL"] attribute on expression in the processed file.
(*) .ocamlformat files in current and all ancestor directories for each
input file are used, applied from top to bottom, overriding the
settings each time a file is applied, stopping at the project root. If
no project root and no ocamlformat file has been found, and if the
option enable-outside-detected-project is set, the global ocamlformat
file defined in $XDG_CONFIG_HOME (or in $HOME/.config if
$XDG_CONFIG_HOME is undefined) is used.
If the disable option is not set, an .ocamlformat-ignore file specifies
files that OCamlFormat should ignore. Each line in an
.ocamlformat-ignore file specifies a filename relative to the directory
containing the .ocamlformat-ignore file. Shell-style regular
expressions are supported. Lines starting with # are ignored and can be
used as comments.
If the disable option is set, an .ocamlformat-enable file specifies
files that OCamlFormat should format even when the disable option is
set. Each line in an .ocamlformat-enable file specifies a filename
relative to the directory containing the .ocamlformat-enable file.
Shell-style regular expressions are supported. Lines starting with #
are ignored and can be used as comments.
--assignment-operator={end-line|begin-line}
Position of the assignment operator. end-line positions assignment
operators (‘:=‘ and ‘<-‘) at the end of the line and breaks after
it if the whole assignment expression does not fit on a single
line. begin-line positions assignment operators (‘:=‘ and ‘<-‘) at
the beginning of the line and breaks before it if the whole
assignment expression does not fit on a single line. The default
value is end-line.
--break-before-in={fit-or-vertical|auto}
Whether the line should break before the in keyword of a let
binding. fit-or-vertical will always break the line before the in
keyword if the whole let binding does not fit on a single line.
auto will only break the line if the in keyword does not fit on the
previous line. The default value is fit-or-vertical.
--break-cases={fit|nested|toplevel|fit-or-vertical|vertical|all}
Break pattern match cases. Specifying fit lets pattern matches
break at the margin naturally. nested forces a break after nested
or-patterns to highlight the case body. Note that with nested, the
indicate-nested-or-patterns option is not needed, and so ignored.
toplevel forces top-level cases (i.e. not nested or-patterns) to
break across lines, otherwise break naturally at the margin.
fit-or-vertical tries to fit all or-patterns on the same line,
otherwise breaks. vertical vertically breaks branches. all forces
all pattern matches to break across lines. The default value is
fit.
--break-collection-expressions={fit-or-vertical|wrap}
Break collection expressions (lists and arrays) elements by
elements. fit-or-vertical vertically breaks expressions if they do
not fit on a single line. wrap will group simple expressions and
try to format them in a single line. The default value is
fit-or-vertical.
--break-colon={after|before}
Break before or after colon in value binding declarations and type
constraints. after breaks after the colon. before breaks before the
colon. The default value is after.
--break-fun-decl={wrap|fit-or-vertical|smart}
Style for function declarations and types. wrap breaks only if
necessary. fit-or-vertical vertically breaks arguments if they do
not fit on a single line. smart is like fit-or-vertical but try to
fit arguments on their line if they fit. The default value is wrap.
--break-fun-sig={wrap|fit-or-vertical|smart}
Style for function signatures. wrap breaks only if necessary.
fit-or-vertical vertically breaks arguments if they do not fit on a
single line. smart is like fit-or-vertical but try to fit arguments
on their line if they fit. The default value is wrap.
--break-infix={wrap|fit-or-vertical|wrap-or-vertical}
Break sequence of infix operators. wrap will group simple
expressions and try to format them in a single line.
fit-or-vertical vertically breaks expressions if they do not fit on
a single line. wrap-or-vertical behaves like wrap for high
precedence operators and behaves like fit-or-vertical for low
precedence operators. The default value is wrap.
--break-infix-before-func
Break infix operators whose right arguments are anonymous functions
specially: do not break after the operator so that the first line
of the function appears docked at the end of line after the
operator. The flag is unset by default.
--break-separators={after|before}
Break before or after separators such as ‘;‘ in list or record
expressions. after breaks the expressions after the separator.
before breaks the expressions before the separator. The default
value is after.
--break-sequences
Force sequence expressions to break irrespective of margin. The
flag is set by default.
--break-string-literals={auto|never}
Break string literals. auto mode breaks lines at newlines and wraps
string literals at the margin. never mode formats string literals
as they are parsed, in particular, with escape sequences expanded.
The default value is auto.
--break-struct={force|natural}
Break struct-end module items. force will break struct-end phrases
unconditionally. natural will break struct-end phrases naturally at
the margin. The default value is force.
--cases-exp-indent=COLS
Indentation of cases expressions (COLS columns). See also the
cases-matching-exp-indent and nested-match options. The default
value is 4. Cannot be set in attributes.
--cases-matching-exp-indent={normal|compact}
Indentation of cases right-hand sides which are ‘match‘ or ‘try‘
expressions. normal indents as it would any other expression.
compact forces an indentation of 2, unless nested-match is set to
align and we're on the last case. The default value is normal.
--disambiguate-non-breaking-match
Add parentheses around matching constructs that fit on a single
line. The flag is unset by default.
--doc-comments={after-when-possible|before-except-val|before}
Doc comments position. after-when-possible puts doc comments after
the corresponding code. This option has no effect on variant
declarations because that would change their meaning and on
structures, signatures and objects for readability.
before-except-val puts doc comments before the corresponding code,
but puts doc comments of val and external declarations after the
corresponding declarations. before puts comments before the
corresponding code. The default value is after-when-possible.
--doc-comments-padding=PADDING
Add PADDING spaces before doc comments in type declarations. The
default value is 2.
--doc-comments-tag-only={default|fit}
Position of doc comments with only tags. default means no special
treatment. fit puts doc comments on the same line. The default
value is default.
--dock-collection-brackets
Dock the brackets of lists, arrays and records, so that when the
collection does not fit on a single line the brackets are opened on
the preceding line and closed on the following line. The flag is
set by default.
--exp-grouping={parens|preserve}
Style of expression grouping. parens groups expressions using
parentheses. preserve preserves the original grouping syntax
(parentheses or begin/end). The default value is parens. Cannot be
set in attributes.
--extension-indent=COLS
Indentation of items inside extension nodes (COLS columns). The
default value is 2.
--field-space={loose|tight|tight-decl}
Whether or not to use a space between a field name and the
punctuation symbol (‘:‘ or ‘=‘) preceding the rhs. This option
affects records and objects. loose uses a space. tight does not use
a space. tight-decl is tight for declarations and loose for
instantiations. The default value is loose.
--function-indent=COLS
Indentation of function cases (COLS columns). The default value is
2.
--function-indent-nested={never|always|auto}
Whether the function-indent parameter should be applied even when
in a sub-block. never only applies function-indent if the function
block starts a line. always always apply function-indent. auto
applies function-indent when seen fit. The default value is never.
--if-then-else={compact|fit-or-vertical|vertical|keyword-first|k-r}
If-then-else formatting. compact tries to format an if-then-else
expression on a single line. fit-or-vertical vertically breaks
branches if they do not fit on a single line. vertical always
vertically breaks branches. keyword-first formats if-then-else
expressions such that the if-then-else keywords are the first on
the line. k-r formats if-then-else expressions with parentheses
that match the K&R style. The default value is compact.
--indent-after-in=COLS
Indentation (COLS columns) after ‘let ... in‘, unless followed by
another ‘let‘. The default value is 0. Cannot be set in attributes.
--indicate-multiline-delimiters={no|space|closing-on-separate-line}
How to indicate that two matching delimiters live on different
lines. no doesn't do anything special to indicate the closing
delimiter. space prints a space inside the delimiter to indicate
the matching one is on a different line. closing-on-separate-line
makes sure that the closing delimiter is on its own line. The
default value is no.
--indicate-nested-or-patterns={unsafe-no|space}
Control whether or not to indicate nested or-pattern using
indentation. unsafe-no does not indicate nested or-patterns.
Warning: this can produce confusing code where a short body of a
match case is visually hidden by surrounding long patterns, leading
to misassociation between patterns and body expressions. space
starts lines of nested or-patterns with " |" rather than "| ". The
default value is unsafe-no.
--infix-precedence={indent|parens}
Use indentation or also discretionary parentheses to explicitly
disambiguate precedences of infix operators. indent uses
indentation to explicitly disambiguate precedences of infix
operators. parens uses parentheses to explicitly disambiguate
precedences of infix operators. The default value is indent.
--leading-nested-match-parens
Nested match parens formatting. The flag is unset by default.
Cannot be set in attributes.
--let-and={compact|sparse}
Style of let_and. compact will try to format ‘let p = e and p = e‘
in a single line. sparse will always break between them. The
default value is compact.
--let-binding-deindent-fun
Deindent a line beginning with ‘fun‘. The flag is set by default.
--let-binding-indent=COLS
Indentation of let binding expressions (COLS columns) if they do
not fit on a single line. The default value is 2. Cannot be set in
attributes.
--let-binding-spacing={compact|sparse|double-semicolon}
Spacing between let binding. compact spacing separates adjacent let
bindings in a module according to module-item-spacing. sparse
places two open lines between a multi-line module-level let binding
and the next. double-semicolon places double semicolons and an open
line between a multi-line module-level let binding and the next.
The default value is compact.
--let-module={compact|sparse}
Module binding formatting. compact does not break a line after the
let module ... = and before the in if the module declaration does
not fit on a single line. sparse breaks a line after let module ...
= and before the in if the module declaration does not fit on a
single line. The default value is compact.
--line-endings={lf|crlf}
Line endings used. lf uses Unix line endings. crlf uses Windows
line endings. The default value is lf. Cannot be set in attributes.
-m COLS, --margin=COLS
Format code to fit within COLS columns. The default value is 80.
Cannot be set in attributes.
--match-indent=COLS
Indentation of match/try cases (COLS columns). The default value is
0.
--match-indent-nested={never|always|auto}
Whether the match-indent parameter should be applied even when in a
sub-block. never only applies match-indent if the match block
starts a line. always always apply match-indent. auto applies
match-indent when seen fit. The default value is never.
--max-indent=COLS
Maximum offset (COLS columns) added to a new line in addition to
the offset of the previous line. The default value is 68. Cannot be
set in attributes.
--module-item-spacing={compact|sparse|preserve}
Spacing between items of structures and signatures. compact will
not leave open lines between one-liners of similar sorts. sparse
will always break a line between two items. preserve will not leave
open lines between one-liners of similar sorts unless there is an
open line in the input. The default value is compact.
--nested-match={wrap|align}
Style of a pattern-matching nested in the last case of another
pattern-matching. wrap wraps the nested pattern-matching with
parentheses and adds indentation. align vertically aligns the
nested pattern-matching under the encompassing pattern-matching.
The default value is wrap.
--no-break-infix-before-func
Unset break-infix-before-func.
--no-break-sequences
Unset break-sequences.
--no-disambiguate-non-breaking-match
Unset disambiguate-non-breaking-match.
--no-dock-collection-brackets
Unset dock-collection-brackets.
--no-leading-nested-match-parens
Unset leading-nested-match-parens.
--no-let-binding-deindent-fun
Unset let-binding-deindent-fun.
--no-ocp-indent-compat
Unset ocp-indent-compat.
--no-parens-ite
Unset parens-ite.
--no-parse-docstrings
Unset parse-docstrings.
--no-parse-toplevel-phrases
Unset parse-toplevel-phrases.
--no-space-around-arrays
Unset space-around-arrays.
--no-space-around-lists
Unset space-around-lists.
--no-space-around-records
Unset space-around-records.
--no-space-around-variants
Unset space-around-variants.
--no-wrap-comments
Unset wrap-comments.
--no-wrap-fun-args
Unset wrap-fun-args.
--ocp-indent-compat
Attempt to generate output which does not change (much) when
post-processing with ocp-indent. The flag is unset by default.
-p {default|conventional|ocamlformat|janestreet},
--profile={default|conventional|ocamlformat|janestreet}
Select a preset profile which sets all options, overriding lower
priority configuration. default is an alias for the conventional
profile. The conventional profile aims to be as familiar and
"conventional" appearing as the available options allow. The
ocamlformat profile aims to take advantage of the strengths of a
parsetree-based auto-formatter, and to limit the consequences of
the weaknesses imposed by the current implementation. This is a
style which optimizes for what the formatter can do best, rather
than to match the style of any existing code. General guidelines
that have directed the design include: Legibility, in the sense of
making it as hard as possible for quick visual parsing to give the
wrong interpretation, is of highest priority; Whenever possible the
high-level structure of the code should be obvious by looking only
at the left margin, in particular, it should not be necessary to
visually jump from left to right hunting for critical keywords,
tokens, etc; All else equal compact code is preferred as reading
without scrolling is easier, so indentation or white space is
avoided unless it helps legibility; Attention has been given to
making some syntactic gotchas visually obvious. The janestreet
profile is used at Jane Street. The default value is default.
--parens-ite
Uses parentheses around if-then-else branches that spread across
multiple lines. The flag is unset by default.
--parens-tuple={always|multi-line-only}
Parens tuple expressions. always always uses parentheses around
tuples. multi-line-only mode will try to skip parens for
single-line tuples. The default value is always.
--parens-tuple-patterns={multi-line-only|always}
Parens tuple patterns. multi-line-only mode will try to skip parens
for single-line tuple patterns. always always uses parentheses
around tuples patterns. The default value is multi-line-only.
--parse-docstrings
Parse and format docstrings. The flag is set by default.
--parse-toplevel-phrases
Parse and format toplevel phrases and their output. The flag is
unset by default.
--sequence-blank-line={preserve-one|compact}
Blank line between expressions of a sequence. preserve will keep a
blank line between two expressions of a sequence if the input
contains at least one. compact will not keep any blank line between
expressions of a sequence. The default value is preserve-one.
--sequence-style={terminator|separator|before}
Style of sequence. terminator only puts spaces after semicolons.
separator puts spaces before and after semicolons. before breaks
the sequence before semicolons. The default value is terminator.
--single-case={compact|sparse}
Style of pattern matching expressions with only a single case.
compact will try to format a single case on a single line. sparse
will always break the line before a single case. The default value
is compact.
--space-around-arrays
Add a space inside the delimiters of arrays. The flag is set by
default.
--space-around-lists
Add a space inside the delimiters of lists. The flag is set by
default.
--space-around-records
Add a space inside the delimiters of records. The flag is set by
default.
--space-around-variants
Add a space inside the delimiters of variants. The flag is set by
default.
--stritem-extension-indent=COLS
Indentation of structure items inside extension nodes (COLS
columns). The default value is 0.
--type-decl={compact|sparse}
Style of type declaration. compact will try to format constructors
and records definition in a single line. sparse will always break
between constructors and record fields. The default value is
compact.
--type-decl-indent=COLS
Indentation of type declarations (COLS columns) if they do not fit
on a single line. The default value is 2. Cannot be set in
attributes.
--wrap-comments
Comments are divided into paragraphs by open lines (two or more
consecutive newlines), and each paragraph is wrapped at the margin.
Multi-line comments with vertically-aligned asterisks on the left
margin are not wrapped. Consecutive comments with both left and
right margin aligned are not wrapped either. The flag is unset by
default.
--wrap-fun-args
Style for function call. The flag is set by default.
OPTIONS (REMOVED)
--align-cases=VAL
This option has been removed in version 0.22.
--align-constructors-decl=VAL
This option has been removed in version 0.22.
--align-variants-decl=VAL
This option has been removed in version 0.22.
--doc-comments-val=VAL
This option has been removed in version 0.16. If you are using
‘doc-comments-val=before‘ in combination with ‘doc-comments=before‘
then only ‘doc-comments=before‘ is now required to achive the same
behavior. If you are using ‘doc-comments-val=before‘ in combination
with ‘doc-comments=after‘ this behavior is not available anymore.
If you are using ‘doc-comments-val=after‘ in combination with
‘doc-comments=before‘ please now use
‘doc-comments=before-except-val‘. If you are using
‘doc-comments-val=after‘ in combination with ‘doc-comments=after‘
then only ‘doc-comments=after-when-possible‘ is now required to
achieve the same behavior. If you are using
‘doc-comments-val=unset‘ the same behavior can now be achieved by
setting ‘doc-comments‘ only.
--escape-chars=VAL
This option has been removed in version 0.16. Concrete syntax will
now always be preserved.
--escape-strings=VAL
This option has been removed in version 0.16. Concrete syntax will
now always be preserved.
--extension-sugar=VAL
This option has been removed in version 0.17. Concrete syntax will
now always be preserved.
--let-open=VAL
This option has been removed in version 0.17. Concrete syntax will
now always be preserved.
OPTIONS
Unless mentioned otherwise non-formatting options cannot be set in
attributes or .ocamlformat files.
-c VAL, --config=VAL (absent OCAMLFORMAT env)
Aggregate options. Options are specified as a comma-separated list
of pairs: option=VAL,...,option=VAL.
--check
Check whether the input files already are formatted. Mutually
exclusive with --inplace and --output.
--comment-check
Control whether to check comments and documentation comments.
Unsafe to turn off. May be set in .ocamlformat. The flag is set by
default.
--disable
Disable ocamlformat. This is used in attributes to locally disable
automatic code formatting. One can also use [@@@ocamlformat
"enable"] instead of [@@@ocamlformat "disable=false"]. The flag is
unset by default.
--disable-conf-attrs
Disable configuration in attributes. The flag is unset by default.
--disable-conf-files
Disable .ocamlformat configuration files.
--disable-outside-detected-project
If no .ocamlformat config files have been detected, disable the
formatting. OCamlFormat is disabled outside of a detected project
by default, to enable the opposite behavior use
--enable-outside-detected-project.
--doc
Parse input as an odoc documentation.
--enable-outside-detected-project
Read .ocamlformat config files outside the current project when no
project root has been detected for the input file. The project root
of an input file is taken to be the nearest ancestor directory that
contains a .git or .hg or dune-project file. If .ocamlformat config
files are located in the same directory or parents they are
applied, if no .ocamlformat file is found then the global
configuration defined in $XDG_CONFIG_HOME/.ocamlformat (or in
$HOME/.config/.ocamlformat if $XDG_CONFIG_HOME is undefined) is
applied.
-g, --debug
Generate debugging output. The flag is unset by default.
-i, --inplace
Format in-place, overwriting input file(s).
--ignore-invalid-option
Ignore invalid options (e.g. in .ocamlformat).
--impl
Parse input as an implementation.
--intf
Parse input as an interface.
--margin-check
Emit a warning if the formatted output exceeds the margin. The flag
is unset by default.
-n N, --max-iters=N
Fail if output of formatting does not stabilize within N
iterations. May be set in .ocamlformat. The default value is 10.
--name=NAME
Name of input file for use in error reporting and starting point
when searching for '.ocamlformat' files. Defaults to the input file
name. Some options can be specified in configuration files named
'.ocamlformat' in the same or a parent directory of NAME, see
documentation of other options for details.
--no-comment-check
Unset comment-check.
--no-debug
Unset debug.
--no-disable
Unset disable.
--no-disable-conf-attrs
Unset disable-conf-attrs.
--no-margin-check
Unset margin-check.
--no-quiet
Unset quiet.
--no-version-check
Unset version-check.
-o DST, --output=DST
Output file. Mutually exclusive with --inplace. Write to stdout if
omitted.
--ocaml-version=V
Version of OCaml syntax of the output. The default value is 4.04.0.
--ocp-indent-config
Read .ocp-indent configuration files. base is an alias for
let-binding-indent. type is an alias for type-decl-indent. in is an
alias for indent-after-in. with sets function-indent and
match-indent. match_clause is an alias for cases-exp-indent.
ppx_stritem_ext is an alias for stritem-extension-indent.
max_indent is an alias for max-indent. strict_with sets
function-indent-nested and match-indent-nested.
--print-config
Print the configuration determined by the environment variable, the
configuration files, preset profiles and command line. Attributes
are not considered. If many input files are specified, only print
the configuration for the first file. If no input file is
specified, print the configuration for the root directory if
specified, or for the current working directory otherwise.
-q, --quiet
Quiet. May be set in .ocamlformat. The flag is unset by default.
--repl-file
Parse input as toplevel phrases with their output.
--root=DIR
Root of the project. If specified, only take into account
.ocamlformat configuration files inside DIR and its subdirectories.
--use-file
Deprecated. Same as impl.
--version-check
Check that the version matches the one specified in .ocamlformat.
The flag is set by default.
SRC Input files. At least one is required, and exactly one without
--inplace. If - is passed, will read from stdin.
COMMON OPTIONS
--help[=FMT] (default=auto)
Show this help in format FMT. The value FMT must be one of auto,
pager, groff or plain. With auto, the format is pager or plain
whenever the TERM env var is dumb or undefined.
--version
Show version information.
EXIT STATUS
ocamlformat exits with:
0 on success.
123 on indiscriminate errors reported on standard error.
124 on command line parsing errors.
125 on unexpected internal errors (bugs).
ENVIRONMENT
These environment variables affect the execution of ocamlformat:
OCAMLFORMAT
See option --config.
Ocamlformat 0.27.0 OCAMLFORMAT(1)