A bundle of options for the formatter that control how the code should be formatted.

The default arguments are modeled after the ceylon.language module and the Ceylon SDK. You can refine them using named arguments:

FormattingOptions {
    indentMode = Tabs(4);
    // modify some others
    // keep the rest
}

no subtypes hierarchy

Initializer
FormattingOptions(IndentMode indentMode = ..., Integer|Unlimited maxLineLength = ..., LineBreakStrategy lineBreakStrategy = ..., Boolean braceOnOwnLine = false, Boolean spaceBeforeParamListOpeningParen = false, Boolean spaceAfterParamListOpeningParen = false, Boolean spaceBeforeParamListClosingParen = false, Boolean spaceAfterParamListClosingParen = true, All|{String*} inlineAnnotations = ..., Boolean spaceBeforeMethodOrClassPositionalArgumentList = false, Boolean spaceBeforeAnnotationPositionalArgumentList = true, Range<Integer> lineBreaksBetweenImportElements = ..., Boolean spaceAroundImportAliasEqualsSign = false, Range<Integer> lineBreaksBeforeLineComment = ..., Range<Integer> lineBreaksAfterLineComment = ..., Range<Integer> lineBreaksBeforeSingleComment = ..., Range<Integer> lineBreaksAfterSingleComment = ..., Range<Integer> lineBreaksBeforeMultiComment = ..., Range<Integer> lineBreaksAfterMultiComment = ..., Range<Integer> lineBreaksInTypeParameterList = ..., Boolean spaceAfterSequenceEnumerationOpeningBrace = true, Boolean spaceBeforeSequenceEnumerationClosingBrace = true, Boolean spaceAfterValueIteratorOpeningParenthesis = false, Boolean spaceBeforeValueIteratorClosingParenthesis = false, Boolean failFast = true, Boolean spaceAfterTypeArgListComma = false, Boolean spaceAfterTypeParamListComma = true, Boolean spaceAroundTypeParamListEqualsSign = false, Integer indentBeforeTypeInfo = ..., Boolean indentBlankLines = true, LineBreak lineBreak = ..., Boolean elseOnOwnLine = false, Boolean spaceAroundSatisfiesOf = true, Boolean spaceAfterControlStructureKeyword = true, Integer spaceOptionalAroundOperatorLevel = ..., Boolean indentComprehensionClauses = true)
Parameters:
  • indentMode = Spaces(4)

    The indentation mode.

  • maxLineLength = unlimited

    The maximum line length, or unlimited.

  • lineBreakStrategy = DefaultLineBreaks()

    The strategy to determine where lines should be broken to accomodate SparseFormattingOptions.maxLineLength.

  • braceOnOwnLine = false

    Decide whether to keep an opening brace ('{') on the same line (One True Style) or put them on the next line (Allman Style).

  • spaceBeforeParamListOpeningParen = false

    Decide whether to put a space before the opening parenthesis ('(') of a method definition’s parameter list or not.

    For example: void foo(String bar) vs void foo (String bar)

  • spaceAfterParamListOpeningParen = false

    Decide whether to put a space after the opening parenthesis ('(') of a method definition’s parameter list or not.

    For example: void foo(String bar) vs void foo( String bar)

  • spaceBeforeParamListClosingParen = false

    Decide whether to put a space before the closing parenthesis (')') of a method definition’s parameter list or not.

    For example: void foo(String bar) vs void foo (String bar )

  • spaceAfterParamListClosingParen = true

    Decide whether to put a space after the closing parenthesis (')') of a method definition’s parameter list or not.

    This only applies when the parameter list is followed by a brace (as is the case for simple functions and classes). If it is instead followed by a fat arrow, a space is always added; if it’s followed by a semicolon (formal), or a comma or closing paren (parameter list of functional parameter), no space is be added.

    For example: void foo(String bar) {} vs void foo(String bar){}

  • inlineAnnotations = { "abstract", "actual", "annotation", "default", "final", "formal", "late", "native", "optional", "sealed", "shared", "variable" }

    Decide which annotations should be on the same line as their declaration.

    all means that all annotations should be on the same line, in other words, that line breaking will only occur according to SparseFormattingOptions.lineBreakStrategy.

    If you give an Iterable instead, a line break will be appended after any annotation that it doesn’t contain. For example, the default value will produce:

    by ("John Doe")
    throws (`class Anything`)
    shared formal void foo();
    

    where by and throws are each on a separate line because they are not elements of the default value, but shared and formal are elements of the default value and therefore on the same line as the declaration.

    If the value of this option is empty, line breaks will be inserted after every annotation (no “inline” annotations).

    It should be noted that the annotations can look weird if you put “inline” annotations before or between “own-line” annotations:

    shared by ("John Doe")
    formal throws (`class Anything`)
    void foo();
    

    Don’t do that. (You can already see in this small example how the combination “shared by” can be potentially confusing.)

  • spaceBeforeMethodOrClassPositionalArgumentList = false

    Decide if there should be a space in front of a positional argument list for a method or class.

    A positional argument list is the complement of a named argument list, i. e. what you’d probably know as simply an argument list:

    process.arguments.filter("--help --usage --version".split().contains);
    //                      '----------positional argument list---------'
    
  • spaceBeforeAnnotationPositionalArgumentList = true

    Decide if there should be a space in front of a positional argument list for an annotation.

    A positional argument list is the complement of a named argument list, i. e. what you’d probably know as simply an argument list:

    process.arguments.filter("--help --usage --version".split().contains);
    //                      '----------positional argument list---------'
    
  • lineBreaksBetweenImportElements = 1..1

    The range of line breaks allowed between import elements.

    0..0 is a “forced single-line” style:

    import java.lang { Thread, JString=String, Runtime { runtime } }
    

    0..1 is “freeform” style:

    import java.lang {
        Thread, JString=String,
        Runtime {
            runtime
        }
    }
    

    1..1 is “forced multi-line” style:

    import java.lang {
        Thread,
        JString=String,
        Runtime {
            runtime
        }
    }
    

    (Of course, wider ranges like 0..3 are also permitted.)

  • spaceAroundImportAliasEqualsSign = false

    Decide if there should be spaces around the equals sign ('=') of an import alias, that is

    import java.lang { JString=String }
    // vs
    import java.lang { JString = String }
    
  • lineBreaksBeforeLineComment = 0..3

    The range of line breaks allowed before a line comment (// comment).

  • lineBreaksAfterLineComment = 1..3

    The range of line breaks allowed after a line comment (// comment).

    Note that the minimum value of the range must be > 0; allowing having no line breaks after a line comment would obviously produce syntactically invalid code.

  • lineBreaksBeforeSingleComment = 0..3

    The range of line breaks allowed before a single-line multi comment (/* comment */).

  • lineBreaksAfterSingleComment = 0..3

    The range of line breaks allowed after a single-line multi comment (/* comment */).

  • lineBreaksBeforeMultiComment = 0..3

    The range of line breaks allowed before a multi-line comment (/* comment... \n ... \n comment */).

  • lineBreaksAfterMultiComment = 0..3

    The range of line breaks allowed after a multi-line comment (/* comment... \n ... \n comment */).

  • lineBreaksInTypeParameterList = 0..1

    The range of line breaks allowed in a type parameter list.

  • spaceAfterSequenceEnumerationOpeningBrace = true

    Decide whether there should be a space after the opening brace of a sequence enumeration.

    For example: { 1, 2, 3 } vs {1, 2, 3}

  • spaceBeforeSequenceEnumerationClosingBrace = true

    Decide whether there should be a space before the closing brace of a sequence enumeration.

    For example: { 1, 2, 3 } vs {1, 2, 3}

  • spaceAfterValueIteratorOpeningParenthesis = false

    Decide whether there should be a space after the opening parenthesis of a value iterator.

    For example: for ( c in "text" ) { ... } vs for (c in "text") { ... }

  • spaceBeforeValueIteratorClosingParenthesis = false

    Decide whether there should be a space before the closing parenthesis of a value iterator.

    For example: for ( c in "text" ) { ... } vs for (c in "text") { ... }

  • failFast = true

    Decide whether, in the case of an error, the formatter should attempt to recover and continue or immediately exit.

    This is mostly for internal use; in the finished formatter, there shouldn’t be any errors when formatting syntactically valid code.

  • spaceAfterTypeArgListComma = false

    Decide whether there should be a space after commas in a type argument list.

    For example: Map<Key,Value> vs Map<Key, Value>

  • spaceAfterTypeParamListComma = true

    Decide whether there should be a space after commas in a type parameter list.

    For example: Map<out Key=Object,out Item=Anything> vs Map<out Key=Object, out Item=Anything>

  • spaceAroundTypeParamListEqualsSign = false

    Decide whether there should be a space around equals signs in a type parameter list.

    For example: Map<out Key=Object, out Item=Anything> vs Map<out Key = Object, out Item = Anything>

  • indentBeforeTypeInfo = 2

    By how many levels extends, satisfies, of, given, and abstracts should be indented.

    For example:

    // 2
    class Foo()
            extends Bar()
            satisfies Baz {}
    // vs
    // 1
    class Foo()
        extends Bar()
        satisfies Baz {}
    
  • indentBlankLines = true

    Decide whether blank lines should be indented or not.

  • lineBreak = lf

    The character(s) used to break lines, or os to use the operating system’s line breaks.

  • elseOnOwnLine = false

    Decide whether else and catch should be on its own line. For example:

    if (something) {
        // ...
    } else {
        // ...
    }
    

    vs.

    if (something) {
        // ...
    }
    else {
        // ...
    }
    
  • spaceAroundSatisfiesOf = true

    Decide whether there should be spaces around satisfied interfaces and case types. For example:

    class MyClass()
            satisfies MyInterface&MyOtherInterface
            of CaseType1|CaseType2 { ... }
    

    vs.

    class MyClass()
            satisfies MyInterface & MyOtherInterface
            of CaseType1 | CaseType2 { ... }
    
  • spaceAfterControlStructureKeyword = true

    Decide whether there should be a space between a control structure keyword and its opening parenthesis.

    This applies to the following keywords:

    • if
    • for
    • while
    • try, when followed by a resource list
    • catch
    • switch
    • case
  • spaceOptionalAroundOperatorLevel = 3

    The maximum operator layer for which spaces are optional.

    If the spaces around an operator are optional, then the formatter omits them when the operator is nested within other operators, for instance:

    value hollowCubeVolume = w*h*d - iW*iH*iD; // (inner) width/height/depth
    

    The operator layers are listed in the Ceylon Language Specification, table 6.1; a brief summary is:

    1. arithmetic, invocation, and access operators
    2. comparison and type test operators
    3. logical operators
    4. conditional and assignment operators

    Spaces are optional around all operators of level up to the value of this option. The default value is 3, resulting in code like this:

    value sum = 1 + 2 + 3;
    value hollowCubeVolume = w*h*d - iW*iH*iD; // (inner) width/height/depth
    value allEqual = a==b && b==c && c==d;
    value regular = start..end;
    value shifted = start+offset .. end+offset;
    

    If you don’t like the look of a==b, consider setting this option to a lower level, like 1. You can also turn it off completely, enforcing spaces around all operators, with the value 0.

  • indentComprehensionClauses = true

    Decide whether comprehension clauses should be indented by one level or not. For example:

    Integer.sum {
        for (employee in employees)
            if (employee.level < manager)
                employee.salary
    }
    

    vs.

    Integer.sum {
        for (employee in employees)
        if (employee.level < manager)
        employee.salary
    }
    
Attributes
braceOnOwnLineSource Codeshared actual Boolean braceOnOwnLine

Decide whether to keep an opening brace ('{') on the same line (One True Style) or put them on the next line (Allman Style).

elseOnOwnLineSource Codeshared actual Boolean elseOnOwnLine

Decide whether else and catch should be on its own line. For example:

if (something) {
    // ...
} else {
    // ...
}

vs.

if (something) {
    // ...
}
else {
    // ...
}
failFastSource Codeshared actual Boolean failFast

Decide whether, in the case of an error, the formatter should attempt to recover and continue or immediately exit.

This is mostly for internal use; in the finished formatter, there shouldn’t be any errors when formatting syntactically valid code.

indentBeforeTypeInfoSource Codeshared actual Integer indentBeforeTypeInfo

By how many levels extends, satisfies, of, given, and abstracts should be indented.

For example:

// 2
class Foo()
        extends Bar()
        satisfies Baz {}
// vs
// 1
class Foo()
    extends Bar()
    satisfies Baz {}
indentBlankLinesSource Codeshared actual Boolean indentBlankLines

Decide whether blank lines should be indented or not.

indentComprehensionClausesSource Codeshared actual Boolean indentComprehensionClauses

Decide whether comprehension clauses should be indented by one level or not. For example:

Integer.sum {
    for (employee in employees)
        if (employee.level < manager)
            employee.salary
}

vs.

Integer.sum {
    for (employee in employees)
    if (employee.level < manager)
    employee.salary
}
indentModeSource Codeshared actual IndentMode indentMode

The indentation mode.

inlineAnnotationsSource Codeshared actual All|{String*} inlineAnnotations

Decide which annotations should be on the same line as their declaration.

all means that all annotations should be on the same line, in other words, that line breaking will only occur according to SparseFormattingOptions.lineBreakStrategy.

If you give an Iterable instead, a line break will be appended after any annotation that it doesn’t contain. For example, the default value will produce:

by ("John Doe")
throws (`class Anything`)
shared formal void foo();

where by and throws are each on a separate line because they are not elements of the default value, but shared and formal are elements of the default value and therefore on the same line as the declaration.

If the value of this option is empty, line breaks will be inserted after every annotation (no “inline” annotations).

It should be noted that the annotations can look weird if you put “inline” annotations before or between “own-line” annotations:

shared by ("John Doe")
formal throws (`class Anything`)
void foo();

Don’t do that. (You can already see in this small example how the combination “shared by” can be potentially confusing.)

lineBreakSource Codeshared actual LineBreak lineBreak

The character(s) used to break lines, or os to use the operating system’s line breaks.

lineBreakStrategySource Codeshared actual LineBreakStrategy lineBreakStrategy

The strategy to determine where lines should be broken to accomodate SparseFormattingOptions.maxLineLength.

lineBreaksAfterLineCommentSource Codeshared actual Range<Integer> lineBreaksAfterLineComment

The range of line breaks allowed after a line comment (// comment).

Note that the minimum value of the range must be > 0; allowing having no line breaks after a line comment would obviously produce syntactically invalid code.

lineBreaksAfterMultiCommentSource Codeshared actual Range<Integer> lineBreaksAfterMultiComment

The range of line breaks allowed after a multi-line comment (/* comment... \n ... \n comment */).

lineBreaksAfterSingleCommentSource Codeshared actual Range<Integer> lineBreaksAfterSingleComment

The range of line breaks allowed after a single-line multi comment (/* comment */).

lineBreaksBeforeLineCommentSource Codeshared actual Range<Integer> lineBreaksBeforeLineComment

The range of line breaks allowed before a line comment (// comment).

lineBreaksBeforeMultiCommentSource Codeshared actual Range<Integer> lineBreaksBeforeMultiComment

The range of line breaks allowed before a multi-line comment (/* comment... \n ... \n comment */).

lineBreaksBeforeSingleCommentSource Codeshared actual Range<Integer> lineBreaksBeforeSingleComment

The range of line breaks allowed before a single-line multi comment (/* comment */).

lineBreaksBetweenImportElementsSource Codeshared actual Range<Integer> lineBreaksBetweenImportElements

The range of line breaks allowed between import elements.

0..0 is a “forced single-line” style:

import java.lang { Thread, JString=String, Runtime { runtime } }

0..1 is “freeform” style:

import java.lang {
    Thread, JString=String,
    Runtime {
        runtime
    }
}

1..1 is “forced multi-line” style:

import java.lang {
    Thread,
    JString=String,
    Runtime {
        runtime
    }
}

(Of course, wider ranges like 0..3 are also permitted.)

lineBreaksInTypeParameterListSource Codeshared actual Range<Integer> lineBreaksInTypeParameterList

The range of line breaks allowed in a type parameter list.

maxLineLengthSource Codeshared actual Integer|Unlimited maxLineLength

The maximum line length, or unlimited.

spaceAfterControlStructureKeywordSource Codeshared actual Boolean spaceAfterControlStructureKeyword

Decide whether there should be a space between a control structure keyword and its opening parenthesis.

This applies to the following keywords:

  • if
  • for
  • while
  • try, when followed by a resource list
  • catch
  • switch
  • case
spaceAfterParamListClosingParenSource Codeshared actual Boolean spaceAfterParamListClosingParen

Decide whether to put a space after the closing parenthesis (')') of a method definition’s parameter list or not.

This only applies when the parameter list is followed by a brace (as is the case for simple functions and classes). If it is instead followed by a fat arrow, a space is always added; if it’s followed by a semicolon (formal), or a comma or closing paren (parameter list of functional parameter), no space is be added.

For example: void foo(String bar) {} vs void foo(String bar){}

spaceAfterParamListOpeningParenSource Codeshared actual Boolean spaceAfterParamListOpeningParen

Decide whether to put a space after the opening parenthesis ('(') of a method definition’s parameter list or not.

For example: void foo(String bar) vs void foo( String bar)

spaceAfterSequenceEnumerationOpeningBraceSource Codeshared actual Boolean spaceAfterSequenceEnumerationOpeningBrace

Decide whether there should be a space after the opening brace of a sequence enumeration.

For example: { 1, 2, 3 } vs {1, 2, 3}

spaceAfterTypeArgListCommaSource Codeshared actual Boolean spaceAfterTypeArgListComma

Decide whether there should be a space after commas in a type argument list.

For example: Map<Key,Value> vs Map<Key, Value>

spaceAfterTypeParamListCommaSource Codeshared actual Boolean spaceAfterTypeParamListComma

Decide whether there should be a space after commas in a type parameter list.

For example: Map<out Key=Object,out Item=Anything> vs Map<out Key=Object, out Item=Anything>

spaceAfterValueIteratorOpeningParenthesisSource Codeshared actual Boolean spaceAfterValueIteratorOpeningParenthesis

Decide whether there should be a space after the opening parenthesis of a value iterator.

For example: for ( c in "text" ) { ... } vs for (c in "text") { ... }

spaceAroundImportAliasEqualsSignSource Codeshared actual Boolean spaceAroundImportAliasEqualsSign

Decide if there should be spaces around the equals sign ('=') of an import alias, that is

import java.lang { JString=String }
// vs
import java.lang { JString = String }
spaceAroundSatisfiesOfSource Codeshared actual Boolean spaceAroundSatisfiesOf

Decide whether there should be spaces around satisfied interfaces and case types. For example:

class MyClass()
        satisfies MyInterface&MyOtherInterface
        of CaseType1|CaseType2 { ... }

vs.

class MyClass()
        satisfies MyInterface & MyOtherInterface
        of CaseType1 | CaseType2 { ... }
spaceAroundTypeParamListEqualsSignSource Codeshared actual Boolean spaceAroundTypeParamListEqualsSign

Decide whether there should be a space around equals signs in a type parameter list.

For example: Map<out Key=Object, out Item=Anything> vs Map<out Key = Object, out Item = Anything>

spaceBeforeAnnotationPositionalArgumentListSource Codeshared actual Boolean spaceBeforeAnnotationPositionalArgumentList

Decide if there should be a space in front of a positional argument list for an annotation.

A positional argument list is the complement of a named argument list, i. e. what you’d probably know as simply an argument list:

process.arguments.filter("--help --usage --version".split().contains);
//                      '----------positional argument list---------'
spaceBeforeMethodOrClassPositionalArgumentListSource Codeshared actual Boolean spaceBeforeMethodOrClassPositionalArgumentList

Decide if there should be a space in front of a positional argument list for a method or class.

A positional argument list is the complement of a named argument list, i. e. what you’d probably know as simply an argument list:

process.arguments.filter("--help --usage --version".split().contains);
//                      '----------positional argument list---------'
spaceBeforeParamListClosingParenSource Codeshared actual Boolean spaceBeforeParamListClosingParen

Decide whether to put a space before the closing parenthesis (')') of a method definition’s parameter list or not.

For example: void foo(String bar) vs void foo (String bar )

spaceBeforeParamListOpeningParenSource Codeshared actual Boolean spaceBeforeParamListOpeningParen

Decide whether to put a space before the opening parenthesis ('(') of a method definition’s parameter list or not.

For example: void foo(String bar) vs void foo (String bar)

spaceBeforeSequenceEnumerationClosingBraceSource Codeshared actual Boolean spaceBeforeSequenceEnumerationClosingBrace

Decide whether there should be a space before the closing brace of a sequence enumeration.

For example: { 1, 2, 3 } vs {1, 2, 3}

spaceBeforeValueIteratorClosingParenthesisSource Codeshared actual Boolean spaceBeforeValueIteratorClosingParenthesis

Decide whether there should be a space before the closing parenthesis of a value iterator.

For example: for ( c in "text" ) { ... } vs for (c in "text") { ... }

spaceOptionalAroundOperatorLevelSource Codeshared actual Integer spaceOptionalAroundOperatorLevel

The maximum operator layer for which spaces are optional.

If the spaces around an operator are optional, then the formatter omits them when the operator is nested within other operators, for instance:

value hollowCubeVolume = w*h*d - iW*iH*iD; // (inner) width/height/depth

The operator layers are listed in the Ceylon Language Specification, table 6.1; a brief summary is:

  1. arithmetic, invocation, and access operators
  2. comparison and type test operators
  3. logical operators
  4. conditional and assignment operators

Spaces are optional around all operators of level up to the value of this option. The default value is 3, resulting in code like this:

value sum = 1 + 2 + 3;
value hollowCubeVolume = w*h*d - iW*iH*iD; // (inner) width/height/depth
value allEqual = a==b && b==c && c==d;
value regular = start..end;
value shifted = start+offset .. end+offset;

If you don’t like the look of a==b, consider setting this option to a lower level, like 1. You can also turn it off completely, enforcing spaces around all operators, with the value 0.

Inherited Attributes
Attributes inherited from: Object
hash, string
Attributes inherited from: SparseFormattingOptions
Inherited Methods
Methods inherited from: Object
equals