Skip to content

Configuration.md

Latest commit

 

History

History
313 lines (242 loc) · 8.76 KB

Configuration.md

File metadata and controls

313 lines (242 loc) · 8.76 KB
hide_table_of_contents true

CSharpier has support for a configuration file. You can use any of the following files

  • A .csharpierrc file in JSON or YAML.
  • A .csharpierrc.json or .csharpierrc.yaml file.
  • A .editorconfig file. See EditorConfig section below.

The configuration file will be resolved based on the location of the file being formatted.

  • If a .csharpierrc file exists somewhere at or above the given file, that will be used.
  • Otherwise if an .editorconfig file exists somewhere at or above the given file, that will be used. Respecting editorconfig inheritance.

In csharpier-config we added some C# formatting options. For now

An other implementation is:

  • UsePrettierStyleTrailingCommas: Omit trailing comma for anonymous object/collection/initializer/switch expressions, list patterns and enum declarations in the case a line break occurs.

Configuration Options

JSON

{
    "printWidth": 100,
    "useTabs": false,
    "tabWidth": 4,
    "endOfLine": "auto",

    "newLineBeforeOpenBrace": "Accessors,AnonymousMethods",
    "newLineBeforeOpenBrace_Alternative": "None",
    "newLineBeforeElse": true,
    "newLineBeforeCatch": true,
    "newLineBeforeFinally": true,
    "newLineBeforeMembersInObjectInitializers": null,
    "newLineBeforeMembersInAnonymousTypes": null,
    "newLineBetweenQueryExpressionClauses": true,
    "usePrettierStyleTrailingCommas": true
}

YAML

printWidth: 100
useTabs: false
tabWidth: 4
endOfLine: auto

newLineBeforeOpenBrace: accessors, AnonymousMethods
newLineBeforeElse: true
newLineBeforeCatch: true
newLineBeforeFinally: true
newLineBeforeMembersInObjectInitializers: null
newLineBeforeMembersInAnonymousTypes: null
newLineBetweenQueryExpressionClauses: true
usePrettierStyleTrailingCommas: true

Print Width

Specify at what point the printer will wrap content. This is not a hard limit. Some lines will be shorter or longer.

Default 100

Use Tabs

First available in 0.17.0

Indent lines with tabs instead of spaces.

Default false

Tab Width

First available in 0.17.0

Specify the number of spaces used per indentation level.

Default 4

End of Line

First available in 0.26.0

Valid options:

  • "auto" - Maintain existing line endings (mixed values within one file are normalised by looking at what's used after the first line)
  • "lf" – Line Feed only (\n), common on Linux and macOS as well as inside git repos
  • "crlf" - Carriage Return + Line Feed characters (\r\n), common on Windows

Default auto

New line before open brace

Available only in CSharpierConfig from 0.29.1

See editorconfig page to more information. Values are mapped in BraceNewLine and it's a flag value. Valid options: all, none, accessors, anonymous_methods, anonymous_types, control_blocks, events, indexers, lambdas, local_functions, methods, object_collection_array_initializers, properties, types

All values is mapped into BraceNewLine.

Default 65535 all

New line before else

Available only in CSharpierConfig from 0.29.1

Place else statements on a new line.

Default true

New line before catch

Available only in CSharpierConfig from 0.29.1

Place catch statements on a new line.

Default true

New line before finally

Available only in CSharpierConfig from 0.29.1

Place finally statements on a new line.

Default true

New line before members in object initializers

Available only in CSharpierConfig from 0.29.1

Require members of object initializers to be on separate lines or not.

Valid options:

  • true: Require members of object initializers to be on separate lines 
    var objectInitializer = new ObjectName
{
    A = 1,
    B = 2
};
  • false: Require members of object initializers to be on the same line 
    var objectInitializer = new ObjectName 
{
    A = 1, B = 2
};
  • null: Use default behaviour of CSharpier, inline for objects or arrays should be placed on the same line if they contain fewer than three elements or Collections are not complex element.

Default null

New line before members in anonymous types

Available only in CSharpierConfig from 0.29.1

Require members of anonymous types to be on separate lines or not.

Valid options:

  • true: Require members of anonymous types to be on separate lines 
    var z = new
{
    A = 3,
    B = 4
}
  • false: Require members of anonymous types to be on the same line 
    var z = new
{
    A = 3, B = 4
}
  • null: Use default behaviour of CSharpier, inline for objects or arrays should be placed on the same line if they contain fewer than three elements.

Default null

New line between query expression clauses

Available only in CSharpierConfig from 0.29.1

Require elements of query expression clauses to be on separate lines or not.

It's not exactly what we expected because the expression starts on a new line instead of continuing on the same line as the variable declaration. However, it is the best option for now.

Valid options:

  • true: Require elements of query expression clauses to be on separate lines 
    var q =
  from a in e
  from b in e
  select a * b;
  • false: Require elements of query expression clauses to be on the same line 
    var q = from a in e from b in e select a * b;

var queryLong =
    from fieldA in listOrTable from fieldB in listOrTable
    select fieltA * fieldB;
  • null: Use default behaviour of CSharpier.

Default null

Use Prettier style trailing commas

Available only in CSharpierConfig from 0.29.1

Force or no trailing comma for anonymous object/collection/initializer/switch expressions, list patterns and enum declarations in the case a line break occurs.

Valid options:

  • true: Default configuration for csharpier after version 0.28.2 
    var objectInitializerD = new
{
    A = 1,
    B = 2,
    C = 3,
    D = 4,
};
  • false: Doesn't force trailing comma in the case a line break occurs 
    var objectInitializerD = new
{
    A = 1,
    B = 2,
    C = 3,
    D = 4
};

Default true

Preprocessor Symbol Sets

Removed in 0.25.0

Currently CSharpier only has basic support for understanding how to format code inside of #if directives. It will attempt to determine which sets of preprocessor symbols are needed for roslyn to parse all the code in each file.

For example in the following code block, the following symbol sets would be needed ["FIRST", "SECOND,THIRD", ""]

#if FIRST
// some code
#elif SECOND && THIRD
// some code
#else
// some code
#endif

When supplying symbol sets, they will be used for all files being formatted. This will slow down formatting, and determining all symbol sets needed across all files won't be straight forward.

The long term plan is to improve Csharpier's ability to determine the symbol sets itself and to allow specifying them for individual files.

Configuration Overrides

First available in 0.29.0

Overrides allows you to specify different configuration options based on glob patterns. This can be used to format non-standard extensions, or to change options based on file path. Top level options will apply to **/*.{cs,csx}

{
    "overrides": [
        {
           "files": ["*.cst"],
           "formatter": "csharp",
           "tabWidth": 2,
           "useTabs": true,
           "printWidth": 10,
           "endOfLine": "LF"
        }
    ]
}
overrides:
    - files: "*.cst"
      formatter: "csharp"
      tabWidth: 2
      useTabs: true
      printWidth: 10
      endOfLine: "LF"

EditorConfig

First available in 0.26.0

CSharpier supports configuration via an .editorconfig file. A .csharpierrc* file in the same directory will take priority.

[*.{cs|csx}]
# Non-configurable behaviors
charset = utf-8
insert_final_newline = true
trim_trailing_whitespace = true
dotnet_sort_system_directives_first = true
dotnet_separate_import_directive_groups = false

# Configurable behaviors
# end_of_line = lf - there is no 'auto' with an .editorconfig
indent_style = space
indent_size = 4
max_line_length = 100

First available in 0.29.2

Formatting non-standard file extensions using csharpier can be accomplished with the csharpier_formatter option

[*.cst]
csharpier_formatter = csharp
indent_style = space
indent_size = 2
max_line_length = 80