-
Notifications
You must be signed in to change notification settings - Fork 168
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Add page for formatting customization #8868
Changes from 1 commit
7b95dcc
3ac67b6
a092cab
f1fe15f
2bdcc91
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,388 @@ | ||
--- | ||
title: Customization of formatting | ||
description: The section on providing custom configurations to the formatter. | ||
keywords: ballerina, programming language, formatting, custom configurations | ||
permalink: /learn/customizing-formatting/ | ||
active: customizing-formatting | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Can you update these also to be consistent with the rest of these pages, please? There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. The |
||
intro: This feature allows developers to customize the formatting of Ballerina projects. This is done with the use of a configuration file. This configuration file can be a local or a remote file, which allows for consistency in code style across projects and simplifies the process of enforcing formatting standards. This is introduced as an experimental feature in Ballerina 2201.9.0. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
--- | ||
|
||
## Configuring | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
Users can provide custom formatting configurations with the use of a separate configuration file of the `toml` format. Users can provide an arbitrary name for the file. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
The formatting configuration file can be specified in two ways: | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* `Ballerina.toml`: Define the path to a configuration file within the Ballerina.toml itself. The path can be absolute, relative to the package root, or a URL (HTTP/HTTPS). This path is specified under the `format` section in `Ballerina.toml` with the use of the `configPath` attribute. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
``` | ||
[format] | ||
configPath = "Format.toml" | ||
``` | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
* Format.bal: If no configuration path is specified in Ballerina.toml, the formatter will look for a file named `Format.toml` in the current package root directory. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* If the `configPath` argument is not provided in the `Ballerina.toml` or the `Format.toml` file does not exist in the project root, default formatting options will be applied. | ||
* If the format config path is an HTTP/HTTPS URL, a cache of the configuration file will be maintained inside the target directory. If the remote configuration file is modified, then make sure to delete the cached `Format.toml` file inside the `target/format/` directory. | ||
|
||
|
||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
## Formatting Options | ||
|
||
### Indent | ||
|
||
#### indentSize | ||
|
||
* Specifies the number of spaces for each level of indentation. | ||
* Value: Integer (e.g., 2, 4) | ||
* Default: 4 | ||
|
||
```ballerina | ||
function main() { | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
if (condition) { | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
io:println("Indented code"); | ||
} | ||
} | ||
``` | ||
|
||
#### continuationIndentSize | ||
|
||
* Determines the indentation size for continuation lines. | ||
* Value: Integer (e.g., 4, 8) | ||
* Default: 8 | ||
|
||
```ballerina | ||
function longFunctionName(int param1, int param2, int param3, | ||
int param4, int param5) { | ||
} | ||
``` | ||
|
||
### Wrapping | ||
|
||
#### maxLineLength | ||
|
||
* Maximum line length before code is wrapped. | ||
* Value: Integer (e.g., 80, 120) | ||
* Default: No line wrapping if maxLineLength not specified. | ||
|
||
#### simpleBlocksInOneLine | ||
|
||
* Preserve single-line blocks in user code. | ||
* Value: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
if x == 1 { return true; } | ||
while i < 5 { i += 1; } | ||
``` | ||
|
||
#### simpleFunctionsInOneLine | ||
|
||
* Preserve single-line methods on a single line. | ||
* Value: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
function getName() returns string { return self.name; } | ||
``` | ||
|
||
### Braces | ||
|
||
#### classBraceStyle: | ||
|
||
* Placement of the opening brace of the class definition. | ||
* Values: NewLine, EndOfLine | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Shouldn't we use backticks for NewLine, EndOfLine etc? @MaryamZi There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more. Yeah, since these are fixed values, we should. |
||
* Default: EndOfLine | ||
* NewLine | ||
```ballerina | ||
class MyClass | ||
{ | ||
// class members | ||
} | ||
``` | ||
|
||
* EndOfLine | ||
```ballerina | ||
class MyClass { | ||
// class members | ||
} | ||
``` | ||
|
||
#### functionBraceStyle | ||
|
||
* Placement of the opening brace of the function definition. | ||
* Values: NewLine, EndOfLine | ||
* Default: EndOfLine | ||
* NewLine | ||
```ballerina | ||
function foo() | ||
{ | ||
// function members | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
} | ||
``` | ||
|
||
* EndOfLine | ||
```ballerina | ||
function foo(){ | ||
// function members | ||
} | ||
``` | ||
|
||
### Function Definition | ||
|
||
#### parametersWrap | ||
|
||
* Formatting of the function parameters when the maxLineLength is exceeded. | ||
* Values: Wrap, NoWrap, ChopDown | ||
* Default: Wrap if maxLineLength specified, else NoWrap | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* Wrap | ||
```ballerina | ||
function foo(int argumentNumberOne, int argumentTwo, | ||
int argumentThree, int argumentFour) { | ||
} | ||
``` | ||
|
||
* NoWrap | ||
```ballerina | ||
function foo(int argumentOne, int argumentTwo, int argumentThree) { | ||
} | ||
``` | ||
|
||
* ChopDown | ||
```ballerina | ||
function foo(int argumentNumberOne, | ||
int argumentTwo, | ||
int argumentThree, | ||
int argumentFour) { | ||
} | ||
``` | ||
|
||
#### alignMultilineParameters | ||
|
||
* Align multiline parameters with the open brace. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
function foo(int argumentNumberOne, int argumentTwo, | ||
int argumentThree, int argumentFour) { | ||
} | ||
``` | ||
|
||
#### newLineAfterLeftParen | ||
|
||
* Newline after the left parenthesis of the function declaration. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
function foo( | ||
int argumentNumberOne, int argumentTwo, int argumentThree, | ||
int argumentFour) { | ||
} | ||
``` | ||
|
||
#### rightParenOnNewLine | ||
|
||
* Right parenthesis of the function declaration on a newline. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
function foo(int argumentNumberOne, int argumentTwo, | ||
int argumentThree, int argumentFour | ||
) { | ||
} | ||
``` | ||
|
||
### Function Call | ||
|
||
#### argumentsWrap | ||
|
||
* Values: Wrap, NoWrap, ChopDown | ||
* Default: Wrap if maxLineLength specified, else NoWrap | ||
* Wrap | ||
```ballerina | ||
myMethod(param1, param2, param3, param4, | ||
param5, param6); | ||
``` | ||
|
||
* NoWrap | ||
```ballerina | ||
myMethod(param1, param2, param3, param4, param5, param6); | ||
``` | ||
|
||
* ChopDown | ||
```ballerina | ||
myMethod(param1, | ||
param2, | ||
param3, | ||
param4, | ||
param5, | ||
param6); | ||
``` | ||
|
||
#### alignMultilineArguments | ||
|
||
* Align multiline arguments with the open brace. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
myMethod(param1, param2, param3, param4 | ||
param5, param6); | ||
``` | ||
|
||
#### newLineAfterLeftParen | ||
|
||
* Newline after the left parenthesis of the function declaration. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
myMethod( | ||
param1, param2, param3, param4, param5, param6); | ||
``` | ||
|
||
#### rightParenOnNewLine | ||
|
||
* Right parenthesis of the function declaration on a newline. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
myMethod(param1, param2, param3, | ||
param4, param5, param6 | ||
); | ||
``` | ||
|
||
### If Statement | ||
|
||
#### elseOnNewLine | ||
|
||
* else and else if keyword on the newline which follows after the } of the previous if or else if statement. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
if (condition) { | ||
// if block | ||
} | ||
else { | ||
// else block | ||
} | ||
``` | ||
|
||
### Spacing | ||
|
||
#### afterTypeCast | ||
|
||
* Space after type casting. | ||
* Values: Boolean | ||
* Default: true | ||
|
||
```ballerina | ||
int x = <int> someValue; | ||
``` | ||
|
||
#### aroundRecordBraces | ||
|
||
* Space after the opening brace and before the closing brace of a mapping constructor. | ||
* Values: Boolean | ||
* Default: true | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
|
||
```ballerina | ||
Student x = { name: “Alex”, age: 15 }; | ||
``` | ||
|
||
#### alignConsecutiveDefinitions | ||
|
||
* Align equals on consecutive definitions. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
```ballerina | ||
const A = "a"; | ||
const AB = "ab"; | ||
const ABC = "ab"; | ||
``` | ||
|
||
### Import | ||
|
||
#### groupImport | ||
|
||
* Group imports by, | ||
* Imports from the same package. | ||
* Imports from the ballerina/ and ballerinax/ organizations. | ||
poorna2152 marked this conversation as resolved.
Show resolved
Hide resolved
|
||
* Imports from third-party organizations. | ||
* Values: Boolean | ||
* defaultValue: true | ||
|
||
#### sortImports | ||
|
||
* Sort imports based on alphabetical order. | ||
* Values: Boolean | ||
* defaultValue: true | ||
|
||
### Query | ||
|
||
#### alignMultiLineQueries | ||
|
||
* Align multiline queries with the equals on the first line. | ||
* Values: Boolean | ||
* Default: false | ||
|
||
* Default behavior | ||
```ballerina | ||
int[] numsReversed = from int i in nums | ||
order by i descending | ||
select i; | ||
``` | ||
|
||
* When `alignMultiLineQueries = true` | ||
```ballerina | ||
int[] numsReversed = from int i in nums | ||
order by i descending | ||
select i; | ||
``` | ||
|
||
## Example Configuration | ||
|
||
```toml | ||
[indent] | ||
indentSize = 4 | ||
continuationIndentSize = 8 | ||
|
||
[wrapping] | ||
maxLineLength = 120 | ||
simpleBlocksInOneLine = true | ||
simpleFunctionsInOneLine = true | ||
|
||
[braces] | ||
classBraceStyle = "NewLine" | ||
functionBraceStyle = "NewLine" | ||
|
||
[functionDefinition] | ||
parametersWrap = "ChopDown" | ||
alignMultilineParameters = true | ||
newLineAfterLeftParen = false | ||
rightParenOnNewLine = false | ||
|
||
[functionCall] | ||
argumentsWrap = "Wrap" | ||
alignMultilineArguments = false | ||
newLineAfterLeftParen = false | ||
rightParenOnNewLine = false | ||
|
||
[ifStatement] | ||
elseOnNewLine = false | ||
|
||
[spacing] | ||
afterTypeCast = true | ||
aroundRecordBraces = true | ||
|
||
[import] | ||
groupImports = true | ||
sortImports = true | ||
|
||
[query] | ||
alignMultiLineQueries = false | ||
``` |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Will this add a new left nav entry as well?
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Yes, decided to have a separate left nav entry under source code and dependencies