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
allshared all all
crlfshared crlf crlf
lfshared lf lf
osshared os os
unlimitedshared unlimited unlimited
Functions
combinedOptionsshared 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));
        // ...
    }));
commandLineOptionsshared [FormattingOptions, String[]] commandLineOptions(String[] arguments = ...)
Parameters:
  • arguments = process.arguments
configProfileNameshared String? configProfileName()

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

See also loadProfile()
formattingFileshared 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

loadProfileshared 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!)

parseIndentModeshared 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))
parseIntegerRangeshared Range<Integer>? parseIntegerRange(String string)
parseLineBreakStrategyshared LineBreakStrategy? parseLineBreakStrategy(String string)
saveProfileshared 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
Allshared abstract All
FormattingOptionsshared 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
}
IndentModeshared abstract IndentMode

A mode to indent code based on levels of indentation.

LineBreakshared abstract LineBreak
LineBreakStrategyshared abstract LineBreakStrategy

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

Mixedshared 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;
    };
};
Spacesshared Spaces

Indent using spaces.

SparseFormattingOptionsshared 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.

Tabsshared Tabs

Indent using tabs.

Unlimitedshared abstract Unlimited
VariableOptionsshared VariableOptions

A subclass of SparseFormattingOptions that makes its attributes variable.

allshared all
crlfshared crlf
lfshared lf
osshared os
unlimitedshared unlimited
Exceptions
ParseOptionExceptionshared ParseOptionException
UnknownOptionExceptionshared UnknownOptionException