Configuration

Fantomas ships with a limited series of options. These can be stored in an .editorconfig file and will be picked up automatically by the commandline.
Your IDE should respect your settings, however the implementation of that is editor specific. Setting the configuration via UI might be available depending on the IDE.

version: 6.3.16+b7dca797317471654fc693ed5a056cfb90bd73d4

Usage

Inside .editorconfig you can specify the file extension and code location to be use per config:

[*.fs]
fsharp_space_before_uppercase_invocation = true

# Write a comment by starting the line with a '#'
[*.{fs,fsx,fsi}]
fsharp_bar_before_discriminated_union_declaration = true

# Apply specific settings for a targeted subfolder
[src/Elmish/View.fs]
fsharp_multiline_bracket_style = stroustrup

Trying your settings via the online tool

You can quickly try your settings via the online tool.

Settings recommendations

Fantomas ships with a series of settings that you can use freely depending on your case.
However, there are settings that we do not recommend and generally should not be used.

Safe to change: Settings that aren't attached to any guidelines. Depending on your team or your own preferences, feel free to change these as it's been agreed on the codebase, however, you can always use it's defaults.

Use with caution: Settings where it is not recommended to change the default value. They might lead to incomplete results.

Do not use: Settings that don't follow any guidelines.

G-Research: G-Research styling guide. If you use one of these, for consistency reasons you should use all of them.

Copy button: This copies the .editorconfig setting text you need to change the default. ⚠️ The copied text will not contain the default value.

Auxiliary settings

indent_size

indent_size has to be between 1 and 10.

This preference sets the indentation The common values are 2 and 4.
The same indentation is ensured to be consistent in a source file.

# Default
indent_size = 4

formatCode
    """ 
    let inline selectRandom (f: _ []) =
      let r = random 1.0

      let rec find =
          function
          | 0 -> fst f.[0]
          | n when r < snd f.[n] -> fst f.[n]
          | n -> find (n - 1)

      find <| f.Length - 1
    """
    """
indent_size = 2
    """

let inline selectRandom (f: _[]) =
  let r = random 1.0

  let rec find =
    function
    | 0 -> fst f.[0]
    | n when r < snd f.[n] -> fst f.[n]
    | n -> find (n - 1)

  find <| f.Length - 1

max_line_length

max_line_length has to be an integer greater or equal to 60.
This preference sets the column where we break F# constructs into new lines.

# Default
max_line_length = 120

formatCode
    """ 
    match myValue with
    | Some foo -> someLongFunctionNameThatWillTakeFooAndReturnsUnit foo
    | None -> printfn "nothing"
    """
    """
max_line_length = 60
    """

match myValue with
| Some foo ->
    someLongFunctionNameThatWillTakeFooAndReturnsUnit foo
| None -> printfn "nothing"

end_of_line

end_of_line determines the newline character, lf will add \n where crlf will add \r\n.
cr is not supported by the F# language spec.
If not set by the user, the default value is determined by System.Environment.NewLine.

insert_final_newline

Adds a final newline character at the end of the file.
Why should text files end with a newline?

# Default
insert_final_newline = true

formatCode
    """ 
    let a = 42
    """
    """
insert_final_newline = false
    """

let a = 42

fsharp_space_before_parameter

Add a space after the name of a function and before the opening parenthesis of the first parameter.
This setting influences function definitions.

# Default
fsharp_space_before_parameter = true

formatCode
    """ 
   let value (a: int) = x
   let DumpTrace() = ()
    """
    """
fsharp_space_before_parameter = false
    """

let value(a: int) = x
let DumpTrace() = ()

fsharp_space_before_lowercase_invocation

Add a space after the name of a lowercased function and before the opening parenthesis of the first argument.
This setting influences function invocation in expressions and patterns.

# Default
fsharp_space_before_lowercase_invocation = true

formatCode
    """ 
value (a, b)
startTimer ()

match x with
| value (a, b) -> ()
    """
    """
fsharp_space_before_lowercase_invocation = false
    """

value(a, b)
startTimer()

match x with
| value(a, b) -> ()

fsharp_space_before_uppercase_invocation

Add a space after the name of a uppercase function and before the opening parenthesis of the first argument.
This setting influences function invocation in expressions and patterns.

# Default
fsharp_space_before_uppercase_invocation = false

formatCode
    """ 
Value(a, b)
person.ToString()

match x with
| Value(a, b) -> ()
    """
    """
fsharp_space_before_uppercase_invocation = true
    """

Value (a, b)
person.ToString ()

match x with
| Value (a, b) -> ()

fsharp_space_before_class_constructor

Add a space after a type name and before the class constructor.

# Default
fsharp_space_before_class_constructor = false

formatCode
    """ 
    type Person() =
        class
        end
    """
    """
fsharp_space_before_class_constructor = true
    """

type Person () = class end

fsharp_space_before_member

Add a space after a member name and before the opening parenthesis of the first parameter.

# Default
fsharp_space_before_member = false

formatCode
    """ 
    type Person() =
        member this.Walk(distance: int) = ()
        member this.Sleep() = ignore
        member __.singAlong() = ()
        member __.swim(duration: TimeSpan) = ()
    """
    """
fsharp_space_before_member = true
    """

type Person() =
    member this.Walk (distance: int) = ()
    member this.Sleep () = ignore
    member __.singAlong () = ()
    member __.swim (duration: TimeSpan) = ()

fsharp_space_before_colon

Add a space before :. Please note that not every : is controlled by this setting.

# Default
fsharp_space_before_colon = false

formatCode
    """ 
   type Point = { x: int; y: int }
   let myValue: int = 42
   let update (msg: Msg) (model: Model) : Model = model
    """
    """
fsharp_space_before_colon = true
    """

type Point = { x : int; y : int }
let myValue : int = 42
let update (msg : Msg) (model : Model) : Model = model

fsharp_space_after_comma

Adds a space after , in tuples.

# Default
fsharp_space_after_comma = true

formatCode
    """ 
    myValue.SomeFunction(foo, bar, somethingElse)
    (a, b, c)
    """
    """
fsharp_space_after_comma = false
    """

myValue.SomeFunction(foo,bar,somethingElse)
(a,b,c)

fsharp_space_before_semicolon

Adds a space before ; in records, arrays, lists, etc.

# Default
fsharp_space_before_semicolon = false

formatCode
    """ 
    let a = [ 1 ; 2 ; 3 ]
    let b = [| foo ; bar |]
    type C = { X: int ; Y: int }
    """
    """
fsharp_space_before_semicolon = true
    """

let a = [ 1 ; 2 ; 3 ]
let b = [| foo ; bar |]
type C = { X: int ; Y: int }

fsharp_space_after_semicolon

Adds a space after ; in records, arrays, lists, etc.

# Default
fsharp_space_after_semicolon = true

formatCode
    """ 
    let a = [ 1; 2; 3 ]
    let b = [| foo; bar |]
    type C = { X: int; Y: int }
    """
    """
fsharp_space_after_semicolon = false
    """

let a = [ 1;2;3 ]
let b = [| foo;bar |]
type C = { X: int;Y: int }

fsharp_space_around_delimiter

Adds a space around delimiters like [,[|,{`.

# Default
fsharp_space_around_delimiter = true

formatCode
    """ 
    let a = [ 1;2;3 ]
    let b = [| 4;5;6 |]
    """
    """
fsharp_space_around_delimiter = false
    """

let a = [1; 2; 3]
let b = [|4; 5; 6|]

Maximum width constraints

Settings that control the max width of certain expressions.

fsharp_max_if_then_short_width

Control the maximum length for which if/then expression without an else expression can be on one line.
The Microsoft F# style guide recommends to never write such an expression in one line.

If the else expression is absent, it is recommended to never to write the entire expression in one line.

# Default
fsharp_max_if_then_short_width = 0

formatCode
    """ 
    if a then 
        ()
    """
    """
fsharp_max_if_then_short_width = 15
    """

if a then ()

fsharp_max_if_then_else_short_width

Fantomas by default follows the if/then/else conventions listed in the Microsoft F# style guide.
This setting facilitates this by determining the maximum character width where the if/then/else expression stays in one line.

# Default
fsharp_max_if_then_else_short_width = 60

formatCode
    """ 
    if myCheck then truth else bogus
    """
    """
fsharp_max_if_then_else_short_width = 10
    """

if myCheck then
    truth
else
    bogus

fsharp_max_infix_operator_expression

Control the maximum length for which infix expression can be on one line.

# Default
fsharp_max_infix_operator_expression = 80

formatCode
    """ 
    let WebApp =
        route "/ping" >=> authorized >=> text "pong"
    """
    """
fsharp_max_infix_operator_expression = 20
    """

let WebApp =
    route "/ping"
    >=> authorized
    >=> text "pong"

fsharp_max_record_width

Control the maximum width for which records should be in one line.

Requires fsharp_record_multiline_formatter to be character_width to take effect.

# Default
fsharp_max_record_width = 40

formatCode
    """ 
    type MyRecord = { X: int; Y: int; Length: int }
    let myInstance = { X = 10; Y = 20; Length = 90 }
    """
    """
fsharp_max_record_width = 20
    """

type MyRecord =
    { X: int
      Y: int
      Length: int }

let myInstance =
    { X = 10
      Y = 20
      Length = 90 }

fsharp_max_record_number_of_items

Control the maximum number of fields for which records should be in one line.

Requires fsharp_record_multiline_formatter to be number_of_items to take effect.

# Default
fsharp_max_record_number_of_items = 1

formatCode
    """ 
    type R = { x: int }

    type S = { x: int; y: string }

    type T = { x: int; y: string; z: float }

    let myRecord = { r = 3 }

    let myRecord' = { r with x = 3 }

    let myRecord'' = { r with x = 3; y = "hello" }

    let myRecord''' = { r with x = 3; y = "hello"; z = 0.0 }
    """
    """
fsharp_record_multiline_formatter = number_of_items
fsharp_max_record_number_of_items = 2
    """

type R = { x: int }

type S = { x: int; y: string }

type T =
    { x: int
      y: string
      z: float }

let myRecord = { r = 3 }

let myRecord' = { r with x = 3 }

let myRecord'' = { r with x = 3; y = "hello" }

let myRecord''' =
    { r with
        x = 3
        y = "hello"
        z = 0.0 }

fsharp_record_multiline_formatter

Split records expressions/statements into multiple lines based on the given condition.
character_width uses character count of the expression, controlled by fsharp_max_record_width.
number_of_items uses the number of fields in the record, controlled by fsharp_max_record_number_of_items.

Note that in either case, record expressions/statements are still governed by max_line_length.

# Default
fsharp_record_multiline_formatter = character_width

formatCode
    """ 
    type R = { x: int }

    type S = { x: int; y: string }

    let myRecord = { r = 3 }

    let myRecord' = { r with x = 3 }

    let myRecord'' = { r with x = 3; y = "hello" }
    """
    """
fsharp_record_multiline_formatter = number_of_items
    """

type R = { x: int }

type S =
    { x: int
      y: string }

let myRecord = { r = 3 }

let myRecord' = { r with x = 3 }

let myRecord'' =
    { r with
        x = 3
        y = "hello" }

fsharp_max_array_or_list_width

Control the maximum width for which lists and arrays can be in one line.

Requires fsharp_array_or_list_multiline_formatter to be character_width to take effect

# Default
fsharp_max_array_or_list_width = 80

formatCode
    """ 
    let myArray = [| one; two; three |]
    """
    """
fsharp_max_array_or_list_width = 20
    """

let myArray =
    [| one
       two
       three |]

fsharp_max_array_or_list_number_of_items

Control the maximum number of elements for which lists and arrays can be in one line.

Requires fsharp_array_or_list_multiline_formatter to be number_of_items to take effect.

# Default
fsharp_max_array_or_list_number_of_items = 1

formatCode
    """ 
    let myList = [ one; two ]
    let myArray = [| one; two; three |]
    """
    """
fsharp_array_or_list_multiline_formatter = number_of_items
fsharp_max_array_or_list_number_of_items = 2
    """

let myList = [ one; two ]

let myArray =
    [| one
       two
       three |]

fsharp_array_or_list_multiline_formatter

Split arrays and lists into multiple lines based on the given condition.
character_width uses character count of the expression, controlled by fsharp_max_array_or_list_width.
number_of_items uses the number of elements in the array or list, controlled by fsharp_max_array_or_list_number_of_items.

Note that in either case, list expressions are still governed by max_line_length.

# Default
fsharp_array_or_list_multiline_formatter = character_width

formatCode
    """ 
    let myArray = [| one; two; three |]
    """
    """
fsharp_array_or_list_multiline_formatter = number_of_items
    """

let myArray =
    [| one
       two
       three |]

fsharp_max_value_binding_width

Control the maximum expression width for which let and member value/property bindings should be in one line.
The width is that of the pattern for the binding plus the right-hand expression but not the keywords (e.g. "let").

# Default
fsharp_max_value_binding_width = 80

formatCode
    """ 
    let title = "Great title of project"
    type MyType() =
        member this.HelpText = "Some help text"
    """
    """
fsharp_max_value_binding_width = 10
    """

let title =
    "Great title of project"

type MyType() =
    member this.HelpText =
        "Some help text"

fsharp_max_function_binding_width

Control the maximum width for which function and member bindings should be in one line.
In contrast to fsharp_max_value_binding_width, only the right-hand side expression of the binding is measured.

# Default
fsharp_max_function_binding_width = 40

formatCode
    """ 
    let title = "Great title of project"
    type MyType() =
        member this.HelpText = "Some help text"
    """
    """
fsharp_max_function_binding_width = 10
    """

let title = "Great title of project"

type MyType() =
    member this.HelpText = "Some help text"

fsharp_max_dot_get_expression_width

Control the maximum width for which (nested) SynExpr.DotGet expressions should be in one line.

# Default
fsharp_max_dot_get_expression_width = 80

formatCode
    """ 
   let job = JobBuilder.UsingJobData(jobDataMap).Create<WrapperJob>().Build()
    """
    """
fsharp_max_dot_get_expression_width = 60
    """

let job =
    JobBuilder
        .UsingJobData(jobDataMap)
        .Create<WrapperJob>()
        .Build()

fsharp_multiline_bracket_style

Cramped The default way in F# to format brackets.
Aligned Alternative way of formatting records, arrays and lists. This will align the braces at the same column level.
Stroustrup Allow for easier reordering of members and keeping the code succinct.

# Default
fsharp_multiline_bracket_style = cramped

formatCode
    """ 
    let myRecord =
        { Level = 1
          Progress = "foo"
          Bar = "bar"
          Street = "Bakerstreet"
          Number = 42 }

    type Range =
        { From: float
          To: float
          FileName: string }

    let a =
        [| (1, 2, 3)
           (4, 5, 6)
           (7, 8, 9)
           (10, 11, 12)
           (13, 14, 15)
           (16, 17,18)
           (19, 20, 21) |]
    """
    """
fsharp_multiline_bracket_style = aligned
    """

let myRecord =
    {
        Level = 1
        Progress = "foo"
        Bar = "bar"
        Street = "Bakerstreet"
        Number = 42
    }

type Range =
    {
        From: float
        To: float
        FileName: string
    }

let a =
    [|
        (1, 2, 3)
        (4, 5, 6)
        (7, 8, 9)
        (10, 11, 12)
        (13, 14, 15)
        (16, 17, 18)
        (19, 20, 21)
    |]

formatCode
    """ 
    let myRecord =
        { Level = 1
          Progress = "foo"
          Bar = "bar"
          Street = "Bakerstreet"
          Number = 42 }

    type Range =
        { From: float
          To: float
          FileName: string }

    let a =
        [| (1, 2, 3)
           (4, 5, 6)
           (7, 8, 9)
           (10, 11, 12)
           (13, 14, 15)
           (16, 17,18)
           (19, 20, 21) |]
    """
    """
fsharp_multiline_bracket_style = stroustrup
    """

let myRecord = {
    Level = 1
    Progress = "foo"
    Bar = "bar"
    Street = "Bakerstreet"
    Number = 42
}

type Range = {
    From: float
    To: float
    FileName: string
}

let a = [|
    (1, 2, 3)
    (4, 5, 6)
    (7, 8, 9)
    (10, 11, 12)
    (13, 14, 15)
    (16, 17, 18)
    (19, 20, 21)
|]

fsharp_newline_before_multiline_computation_expression

Insert a newline before a computation expression that spans multiple lines

# Default
fsharp_newline_before_multiline_computation_expression = true

formatCode
    """ 
    let something =
        task {
            let! thing = otherThing ()
            return 5
        }
    """
    """
fsharp_newline_before_multiline_computation_expression = false
    """

let something = task {
    let! thing = otherThing ()
    return 5
}

G-Research style

A series of settings requicolor="red" to conform with the G-Research style guide.
From a consistency point of view, it is recommend to enable all these settings instead of cherry-picking a few.

fsharp_newline_between_type_definition_and_members

Adds a new line between a type definition and its first member.

# Default
fsharp_newline_between_type_definition_and_members = true

formatCode
    """ 
type Range =
    { From: float
      To: float }

    member this.Length = this.To - this.From
    """
    """
fsharp_newline_between_type_definition_and_members = false
    """

type Range =
    { From: float
      To: float }

    member this.Length = this.To - this.From

fsharp_align_function_signature_to_indentation

When a function signature exceeds the max_line_length, Fantomas will put all parameters on separate lines.
This setting also places the equals sign and return type on a new line.

# Default
fsharp_align_function_signature_to_indentation = false

formatCode
    """ 
[<FunctionName("FormatCode")>]
let run 
    ([<HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "{*any}")>] req: HttpRequest)
    (log: ILogger)
    : HttpResponse =
    Http.main CodeFormatter.GetVersion format FormatConfig.FormatConfig.Default log req
    """
    """
fsharp_align_function_signature_to_indentation = true
    """

[<FunctionName("FormatCode")>]
let run
    ([<HttpTrigger(AuthorizationLevel.Anonymous, "get", "post", Route = "{*any}")>] req: HttpRequest)
    (log: ILogger)
    : HttpResponse
    =
    Http.main CodeFormatter.GetVersion format FormatConfig.FormatConfig.Default log req

fsharp_alternative_long_member_definitions

Provides an alternative way of formatting long member and constructor definitions, where the difference is mainly in the equal sign and returned type placement.

# Default
fsharp_alternative_long_member_definitions = false

formatCode
    """ 
type C
    (
        aVeryLongType: AVeryLongTypeThatYouNeedToUse,
        aSecondVeryLongType: AVeryLongTypeThatYouNeedToUse,
        aThirdVeryLongType: AVeryLongTypeThatYouNeedToUse
    ) =
    class
    end

type D() =
    member _.LongMethodWithLotsOfParameters
        (
            aVeryLongParam: AVeryLongTypeThatYouNeedToUse,
            aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse,
            aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse
        ) : ReturnType =
        42

type E() =
    new
        (
            aVeryLongType: AVeryLongTypeThatYouNeedToUse,
            aSecondVeryLongType: AVeryLongTypeThatYouNeedToUse,
            aThirdVeryLongType: AVeryLongTypeThatYouNeedToUse
        ) = E()
    """
    """
fsharp_alternative_long_member_definitions = true
    """

type C
    (
        aVeryLongType: AVeryLongTypeThatYouNeedToUse,
        aSecondVeryLongType: AVeryLongTypeThatYouNeedToUse,
        aThirdVeryLongType: AVeryLongTypeThatYouNeedToUse
    )
    = class end

type D() =
    member _.LongMethodWithLotsOfParameters
        (
            aVeryLongParam: AVeryLongTypeThatYouNeedToUse,
            aSecondVeryLongParam: AVeryLongTypeThatYouNeedToUse,
            aThirdVeryLongParam: AVeryLongTypeThatYouNeedToUse
        )
        : ReturnType
        =
        42

type E() =
    new
        (
            aVeryLongType: AVeryLongTypeThatYouNeedToUse,
            aSecondVeryLongType: AVeryLongTypeThatYouNeedToUse,
            aThirdVeryLongType: AVeryLongTypeThatYouNeedToUse
        )
        =
        E()

fsharp_multi_line_lambda_closing_newline

Places the closing parenthesis of a multiline lambda argument on the next line.

# Default
fsharp_multi_line_lambda_closing_newline = false

formatCode
    """ 
let printListWithOffset a list1 =
    List.iter
        (fun { ItemOne = a } ->
            // print
            printfn "%s" a)
        list1

let printListWithOffset a list1 =
    list1
    |> List.iter
        (fun elem ->
            // print stuff
            printfn "%d" (a + elem))
    """
    """
fsharp_multi_line_lambda_closing_newline = true
    """

let printListWithOffset a list1 =
    List.iter
        (fun { ItemOne = a } ->
            // print
            printfn "%s" a
        )
        list1

let printListWithOffset a list1 =
    list1
    |> List.iter (fun elem ->
        // print stuff
        printfn "%d" (a + elem)
    )

fsharp_experimental_keep_indent_in_branch

Breaks the normal indentation flow for the last branch of a pattern match or if/then/else expression.
Only when the last pattern match or else branch was already at the same level of the entire match or if expression.

This feature is experimental and is subject to change.

# Default
fsharp_experimental_keep_indent_in_branch = false

formatCode
    """ 
let main argv =
    let args = parse argv

    let instructions = Library.foo args

    if args.DryRun = RunMode.Dry then
        printfn "Would execute actions, but --dry-run was supplied: %+A" instructions
        0
    else

    // proceed with main method
    let output = Library.execute instructions
    // do more stuff
    0
    """
    """
fsharp_experimental_keep_indent_in_branch = true
    """

let main argv =
    let args = parse argv

    let instructions = Library.foo args

    if args.DryRun = RunMode.Dry then
        printfn "Would execute actions, but --dry-run was supplied: %+A" instructions
        0
    else

    // proceed with main method
    let output = Library.execute instructions
    // do more stuff
    0

fsharp_bar_before_discriminated_union_declaration

Always use a | before every case in the declaration of a discriminated union.
If false, a | character is used only in multiple-case discriminated unions, and is omitted in short single-case DUs.

# Default
fsharp_bar_before_discriminated_union_declaration = false

formatCode
    """ 
    type MyDU = Short of int
    """
    """
fsharp_bar_before_discriminated_union_declaration = true
    """

type MyDU = | Short of int

Other

Some additional settings that don't fit into any style guide.

fsharp_blank_lines_around_nested_multiline_expressions

Surround nested multi-line expressions with blank lines.
Existing blank lines are always preserved (via trivia), with exception when fsharp_keep_max_number_of_blank_lines is used.
Top level expressions will always follow the 2020 blank lines revision principle.

# Default
fsharp_blank_lines_around_nested_multiline_expressions = true

formatCode
    """ 
    let topLevelFunction () =
        printfn "Something to print"

        try
                nothing ()
        with
        | ex ->
            splash ()
        ()

    let secondTopLevelFunction () =
        // ...
        ()
    """
    """
fsharp_blank_lines_around_nested_multiline_expressions = false
    """

let topLevelFunction () =
    printfn "Something to print"

    try
        nothing ()
    with ex ->
        splash ()
    ()

let secondTopLevelFunction () =
    // ...
    ()

fsharp_keep_max_number_of_blank_lines

Set maximal number of consecutive blank lines to keep from original source. It doesn't change number of new blank lines generated by Fantomas.

# Default
fsharp_keep_max_number_of_blank_lines = 100

formatCode
    """ 
    open Foo

    let x = 42
    """
    """
fsharp_keep_max_number_of_blank_lines = 1
    """

open Foo

let x = 42

fsharp_experimental_elmish

Applies the Stroustrup style to the final (two) array or list argument(s) in a function application.
Note that this behaviour is also active when fsharp_multiline_bracket_style = stroustrup.

# Default
fsharp_experimental_elmish = false

formatCode
    """ 
let dualList =
    div
        []
        [
            h1 [] [ str "Some title" ]
            ul
                []
                [
                    for p in model.Points do
                        li [] [ str $"%i{p.X}, %i{p.Y}" ]
                ]
            hr []
        ]

let singleList =
    Html.div
        [
            Html.h1 [ str "Some title" ]
            Html.ul
                [
                    for p in model.Points do
                        Html.li [ str $"%i{p.X}, %i{p.Y}" ]
                ]
        ]
    """
    """
fsharp_experimental_elmish = true
    """

let dualList =
    div [] [
        h1 [] [ str "Some title" ]
        ul [] [
            for p in model.Points do
                li [] [ str $"%i{p.X}, %i{p.Y}" ]
        ]
        hr []
    ]

let singleList =
    Html.div [
        Html.h1 [ str "Some title" ]
        Html.ul [
            for p in model.Points do
                Html.li [ str $"%i{p.X}, %i{p.Y}" ]
        ]
    ]