Options for the Ceylon formatter.

The formatter requires an object satisfying FormattingOptions. There are several ways in which you can obtain such an object:

  • Manually create one, defining each attribute yourself:

    FormattingVisitor(tokens, writer, FormattingOptions {
        indentMode = Spaces(4);
        // ...
    });
    
  • Read one from a file using formattingFile():

    FormattingVisitor(tokens, writer, formattingFile(filename));
    
  • Use the default options:

    FormattingVisitor(tokens, writer, FormattingOptions());
    
  • Combine existing FormattingOptions with manually created SparseFormattingOptions:

    FormattingVisitor(tokens, writer, combinedOptions(defaultOptions, SparseFormattingOptions {
        indentMode = Mixed(Tabs(8), Spaces(4));
        // ...
    }));
    
Values
allSource Codeshared all all
crlfSource Codeshared crlf crlf
lfSource Codeshared lf lf
osSource Codeshared os os
unlimitedSource Codeshared unlimited unlimited
Functions
combinedOptionsSource Codeshared FormattingOptions combinedOptions(FormattingOptions baseOptions, SparseFormattingOptions* decoration)

A combination of several FormattingOptions, of which some may be Sparse.

Each attribute is first searched in each of the decoration options, in the order of their appearance, and, if it isn't present in any of them, the attribute of baseOptions is used.

In the typical use case, baseOptions will be some default options (e.g. FormattingOptions()), and decoration will be one SparseFormattingOptions object created on the fly:

FormattingVisitor(tokens, writer, combinedOptions(defaultOptions,
    SparseFormattingOptions {
        indentMode = Mixed(Tabs(8), Spaces(4));
        // ...
    }));
commandLineOptionsSource Codeshared [FormattingOptions, String[]] commandLineOptions(String[] arguments = ...)
Parameters:
  • arguments = process.arguments
configProfileNameSource Codeshared String? configProfileName()

Loads the profile name from the Ceylon configuration (key formattool.profile).

See also loadProfile()
formattingFileSource Codeshared FormattingOptions formattingFile(String filename, FormattingOptions baseOptions = ...)

Reads a file with formatting options.

The file consists of lines of key=value pairs or comments, like this:

# Boss Man says the One True Style is evil
blockBraceOnNewLine=true
# 80 characters is not enough
maxLineWidth=120
indentMode=4 spaces

As you can see, comment lines begin with a # (\{0023}), and the value doesn't need to be quoted to contain spaces. Blank lines are also allowed.

The keys are attributes of FormattingOptions. The format of the value depends on the type of the key; to parse it, the function parse<KeyType>(String) is used (e.g parseInteger for Integer values, parseBoolean for Boolean values, etc.).

A special option in this regard is include: It is not an attribute of FormattingOptions, but instead specifies another file to be loaded.

The file is processed in the following order:

  1. First, load baseOptions.
  2. Then, scan the file for any include options, and process any included files.
  3. Lastly, parse all other lines.

Thus, options in the top-level file override options in included files.

Parameters:
  • filename

    The file to read

  • baseOptions = FormattingOptions()

    The options that will be used if the file and its included files don't specify an option

loadProfileSource Codeshared FormattingOptions loadProfile(String profile = ..., Boolean inherit = true, String baseDir = ...)

Loads formatting options from the given profile.

A profile is a file with the name

"``profile``.format"

next to the regular Ceylon config file. It contains formatting options in a formatter section, like this:

[formatter]
indentMode = 4 spaces
braceOnOwnLine = false

If inherit is true, options from the profile file in the current directory take precedence over options from the profile file in the user and system-wide configuration directories (as per the default Ceylon configuration mechanism); otherwise, only the options from the profile file itself are used.

Parameters:
  • profile = "default"

    The profile name.

    The options are loaded from a configuration file with the name

    "``profile``.format"
    

    using the normal configuration file lookup mechanism (that is, options are inherited from the user and system-wide configuration in a file with the same name).

  • inherit = true

    Whether to inherit options from the user and system-wide configuration or not.

    By default, options are inherited; however, certain users (for example, an IDE) might want to disable this.

  • baseDir = "."

    The base directory (e. g., the project directory.)

    (The parent of the .ceylon directory, not that directory itself!)

parseIndentModeSource Codeshared IndentMode? parseIndentMode(String string)

The IndentMode represented by the given String, or null if the string can't be parsed.

The format is like this:

  • n spaces, where n represents an Integer, for Spaces(n)
  • n-wide tabs, where n represents an Integer, for Tabs(n)
  • mix n-wide tabs, m spaces, where m, n represent Integers, for Mixed(Tabs(n), Spaces(m))
parseIntegerRangeSource Codeshared Range<Integer>? parseIntegerRange(String string)
parseLineBreakStrategySource Codeshared LineBreakStrategy? parseLineBreakStrategy(String string)
saveProfileSource Codeshared void saveProfile(SparseFormattingOptions profile, String name = ..., String baseDir = ..., String relativePath = ...)

Saves formatting options to the given profile.

For more informations on profiles, see the loadProfile() documentation.

Parameters:
  • profile

    The formatting options to save.

    (Only non-null options will be saved.)

  • name = "default

    The profile name.

  • baseDir = ".

    The base directory (e. g., the project directory.)

    (The parent of the .ceylon directory, not that directory itself!)

  • relativePath = ".ceylon/``name``.format

    The relative path of the file name.

    (The relative path from baseDir, defaults to .ceylon/{profile}.format)

See also loadProfile()
Classes
AllSource Codeshared abstract All
FormattingOptionsSource Codeshared FormattingOptions

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
}
IndentModeSource Codeshared abstract IndentMode

A mode to indent code based on levels of indentation.

LineBreakSource Codeshared abstract LineBreak
LineBreakStrategySource Codeshared abstract LineBreakStrategy

A strategy to break a series of tokens into multiple lines to accomodate a maximum line length.

MixedSource Codeshared Mixed

Indent using tabs and spaces.

spaces controls the width of one indentation level. To provide the wanted indentation, the line is filled with as many tabs as fit, and then padded with spaces. Typically, the width of a level is 4, while a tab is 8 wide; this would be created with

Mixed(Tabs(8), Spaces(4))

or, more verbosely,

Mixed {
    Tabs {
        width = 8;
    };
    Spaces {
        spacesPerLevel = 4;
    };
};
SpacesSource Codeshared Spaces

Indent using spaces.

SparseFormattingOptionsSource Codeshared SparseFormattingOptions

A superclass of FormattingOptions where attributes are optional.

The intended use is that users take a “default” FormattingOptions object and apply some SparseFormattingOptions on top of it using combinedOptions(); this way, they don't have to specify every option each time that they need to provide FormattingOptions somewhere.

TabsSource Codeshared Tabs

Indent using tabs.

UnlimitedSource Codeshared abstract Unlimited
VariableOptionsSource Codeshared VariableOptions

A subclass of SparseFormattingOptions that makes its attributes variable.

allSource Codeshared all
crlfSource Codeshared crlf
lfSource Codeshared lf
osSource Codeshared os
unlimitedSource Codeshared unlimited
Exceptions
ParseOptionExceptionSource Codeshared ParseOptionException
UnknownOptionExceptionSource Codeshared UnknownOptionException