From 49edc8b445a06b6decea28e9f2966df6b726e14d Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 8 Aug 2023 21:53:09 +0200 Subject: [PATCH 01/39] 166: Nix formatting Create 0101-nix-formatting.md WIP Go through a large part and agree on it Co-Authored-By: @piegamesde Update 0101-nix-formatting.md Rework a lot of things Update 0101-nix-formatting.md Move around some sections Reword the detailed section Minor updates Slight header changes again Updates Update 0101-nix-formatting.md Update after today's meeting Update 0101-nix-formatting.md Further updates in the meeting Update 0101-nix-formatting.md After todays meeting Update after meeting Rename to probably the right number Only use anchor links Improvements and additions - The sub-expression rule is now reworded and its own section with examples and rationale - Line length limit is now specified as we agreed-upon in the meeting - The operator section is rewritten to align more with the consensus Redo and explain operator special case Also remove the special case for non-chainable operators, barely any benefit in Nixpkgs --- rfcs/0166-nix-formatting.md | 1063 +++++++++++++++++++++++++++++++++++ 1 file changed, 1063 insertions(+) create mode 100644 rfcs/0166-nix-formatting.md diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md new file mode 100644 index 000000000..5c2196d7d --- /dev/null +++ b/rfcs/0166-nix-formatting.md @@ -0,0 +1,1063 @@ +--- +feature: nix_formatting +start-date: 2021-08-17 +author: piegamesde +co-authors: infinisil +pre-RFC reviewers: tomberek, 0x4A6F +shepherd-team: +shepherd-leader: +related-issues: https://github.com/serokell/nixfmt/pull/118, https://github.com/piegamesde/nixpkgs/pull/4 +--- + +# Nix formatting + +## Summary + +The RFC consist of these main parts, see the [detailed design section](#detailed-design) for more information: + +- Define the initial _standard Nix format_ +- Establish the _Nix format team_ +- Create the _official Nix formatter_ implementation +- Reformat Nixpkgs with the official Nix formatter +- Require that any default formatting in the Nix CLI must use the official Nix formatter + +## Motivation + +Currently, there is no authoritative formatting style guide for Nix code, including in Nixpkgs. +The current code style in Nixpkgs has evolved organically over time, leading to inconsistencies both across files and language features. +Things are occasionally improved as people touch old files, at the cost of muddying the diff with cosmetic changes. +There are several auto-formatters for Nix code, each with their own style, and none currently used for Nixpkgs. + +The goals of this RFC are: + +- We want to prevent future debate around how things should be formatted. +- We want to make it as easy as possible for contributors (especially new ones) to make changes without having to worry about formatting. +- Conversely, reviewers should not be bothered with poorly formatted contributions. +- We want a unified Nix code style that's consistent with itself, easily readable, accessible and results in readable diffs. + +Non-goals of this RFC: + +- Code style aspects that are not purely syntactic (e.g. optional/redundant parentheses, adding `inherit` statements, swapping argument order with `flip`, …) +- Nixpkgs-specific tweaks to the format (e.g. using attribute names and other context for heuristics about how to best format the contents) +- Extended Nixpkgs-specific linting like nixpkgs-hammering +- Formatting non-Nix files in Nixpkgs (that's for [treefmt](https://github.com/numtide/treefmt)) +- Applying the format to other repositories within the NixOS organization containing Nix code. + It is up to their respective maintainers to make the transition. + +## Goals and approach + +There are several goals that the formatting style should match. +These are inherently at conflict with each other, requiring priorisation and making trade-offs. +The resulting choice is always a compromise. + +In general, we want the code to be (in no particular order): + +- **Short and concise.** Code should not be spread across too many lines, but also without being crammed +- **Readable.** The output format should reflect the semantic flow of the program. + It should be clear where expressions start and end. + The amount of information per line should be limited. +- **Consistent.** Similar syntax constructs should be formatted similarly. + - The number of special cases in the formatting rules should be minimized. +- **Diffable and stable.** Small changes to the code should not result in excessive changes in the output. + +The general approach taken here is to liberally expand expressions by default, with the goal of being stable, diffable and consistent. +Then, special cases with more compact output for the most common patterns are introduced as needed, +sacrificing those properties in favor of conciseness. +The idea is that this results in a format that is spread-out by default but compact where it matters. + +The interactions between different language features are complex and producing a style that matches the expectations involves a lot of special cases. +Any attempt at creating an exhaustive rule set would be futile. +Therefore, the formatting rules are intentionally under-specified, leaving room for the formatter implementation. +However, the most important or potentially controversial rules are included, as well as some general meta-rules. + +When deciding between two *equally good* options, currently prevalent formatting style in Nixpkgs should be followed. +The emphasis here is on "equally good". +We should not fear of making radical changes to the current style if there are sufficient arguments in favor of it. + +*Bad code does not deserve good formatting.* + +## Detailed design + +### Standard Nix format + +The _standard nix format_ defines the officially recommended way how Nix code should be formatted. + +The initial version of the standard Nix format is defined in a section towards the end: + +[Initial standard Nix format](#initial-standard-nix-format). + +Significant changes to the standard Nix format must go through another RFC. + +The latest version of the standard Nix format must be in a file on the main branch of the [official Nix formatter](#official-nix-formatter). + +### Nix format team + +The _Nix format team_ is established, it has the responsibility to +- Maintain the [official Nix formatter](#official-nix-formatter) +- Regularly [reformat Nixpkgs](#reformat-nixpkgs) with it + +See the linked sections for more information. + +Initially the team consists of these members: +- @piegames (author of this RFC, shepherd of the original formatting RFC) +- @infinisil (from Tweag, co-author of this RFC, shepherd of the original formatting RFC) +- @tomberek (from Flox, shepherd of the original formatting RFC) +- @0x4A6F (shepherd of the original formatting RFC) +- @Sereja313 (from Serokell, original sponsors of nixfmt) + +Team member updates are left for the team itself to decide. + +### Official Nix formatter + +The Nix format team is given the authority and responsibility of +creating and maintaining the _official Nix formatter_ implementation. +This is a repository in the NixOS GitHub organisation. +The repository will initially be based on [this nixfmt pull request](https://github.com/serokell/nixfmt/pull/118). +This pull request has been developed along with this RFC and is already reasonably close to the proposed initial standard format. + +Any release of the official Nix formatter must conform to the latest version of the [standard Nix format](#standard-nix-format). + +The latest release of the official Nix formatter should support the Nix language syntax of the latest Nix release. +The Nix format team should be consulted before the Nix language syntax is changed. + +### Reformat Nixpkgs + +For formatting Nixpkgs itself, a pinned release version of the official Nix formatter must be used. +CI must generally enforce all files in Nixpkgs to be formatted with this version at all times. +Automatically generated files may be handled differently, see [the next section](#automatically-generated-files). + +For every bump of the pinned formatter, +the files of Nixpkgs must thus be re-formatted accordingly. +Commits that reformat Nixpkgs will be added to `.git-blame-ignore-revs`, +which can then be [ignored in tooling](#git-blames). +The Nix format team is responsible for this task. + +In order to minimize conflicts especially when back-porting, +the pinned formatter should preferably only be updated shortly before the release branch-off. +This should be done in coordination with the NixOS release managers. + +#### Automatically generated files + +There are automatically generated files in Nixpkgs, with a potentially different format. +This RFC makes no decisions on how to handle such cases, but there are some options: +- Exclude them from the CI via some tooling (e.g. treefmt if that is being used) +- Format them anyway, either after-the-fact or ideally already in the generator tooling itself + +#### Contributor doc updates + +The [Nixpkgs contributor documentation](https://github.com/NixOS/nixpkgs/blob/master/CONTRIBUTING.md) should be updated to contain all relevant information. +All formatting-specific guidance is removed and replaced with instructions on how to automatically format Nixpkgs instead. + +### Default Nix CLI formatting + +In case the Nix CLI ever gets support for running a default Nix formatter, +the official Nix formatter must be used. + +## Examples and Interactions + +### Git blames + +Reformatting commits that get added to `.git-ignore-revs` [won't get shown](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view) in blames on GitHub, +and can be ignored in the `git blame` command using [`--ignore-revs-file`](https://www.git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt). + +### Formatting gotchas requiring manual intervention + +Some code patterns in Nixpkgs will result in a sub-optimal format, +because an auto-formatter cannot do exceptions based on context. +A lot of the times though, the same program can be equivalently expressed in a prettier way. + +#### CLI argument flags + +It is common to pass in CLI flags (e.g. to builders) like this: + +```nix +[ + "--some-flag" "some-value" +] +``` + +However, this will be formatted sub-optimally: + +```nix +[ + "--some-flag" + "some-value" +] +``` + +If the CLI also accepts GNU-style flags, a more structured helper can be used instead: + +```nix +lib.cli.toGNUCommandLine { } { + some-flag = "some-value"; +} +``` + +#### Singleton lists + +Sometimes a list only needs a single element +and there's no expectation to add more in the future. +This would be formatted like this: + +```nix +{ + list = [ + { + foo = 10; + bar = 20; + } + ]; +} +``` + +In this case one level of indentation can be saved using [`lib.singleton`](https://nixos.org/manual/nixpkgs/stable#function-library-lib.lists.singleton): + +```nix +{ + list = lib.singleton { + foo = 10; + bar = 20; + }; +} +``` + +## Drawbacks + +- No automatic code format can be as pretty as a carefully crafted manual one. There will always be "ugly" edge cases. + - However, we argue that on average the new format will be an improvement, + and that contributors should not waste their time making the code slightly more pretty. +- Every formatter will have bugs, but the Nix format team will be able to make fixes. +- Having a commit that changes the formatting, can make git blame harder to use. + - This can be [worked around in interfaces](#git-blames). + +## Alternatives + +- Keep the status quo of not having an official formatter. + The danger is that this creates discord within the Nix community. + The current friction and maintainer churn due to bad formatting may arguably be small, but not negligible. +- Specify a different format. +- Specify a format, but don't enforce it in CI, to allow manually tweaking the output if necessary. +- Apply the format incrementally, i.e. only changed files get formatted, to make a more graceful transition. + However, such an approach would not reduce the amount of merge conflicts, + and increase the workload for contributors during that time significantly. + +## Unresolved questions + +- Should the line length limit be specified? + +## Future work + +- General style guidelines beyond AST reformatting +- Making widespread use of linters like Nixpkgs-hammering +- Enforcing the format to other official repositories + +----- + +## Initial standard Nix format + +Terms and definitions: +- Brackets: `[]` +- Braces: `{}` +- Parentheses: `()` + +- Newlines are not guaranteed to be preserved, but empty lines are. + - This allows the formatter to compact down multi-line expressions if necessary, while still allowing to structure the code appropriately. +- Expressions of the same kind that can be treated as a sequence of expressions on the same level should be treated as such, even though they are technically parsed as a nested tree. + - This applies to else-if chains, functions with multiple arguments, some operators, etc. + - Example: + ```nix + # This is treated as a sequence of if-then-elsa's chains + if cond1 then + foo + else if cond2 then + bar + else + baz + ``` + +### Single-line common ancestor expression rule + +For any two (sub-)expressions that are fully on a common single line, their smallest common ancestor expression must also be on the same line. + +**Example** + +```nix +# Bad, expressions cond and bar are fully on the same line, +# but their smallest common ancestor expression is the entire if-then-else, which spans multiple lines +if cond then foo +else bar + +# Okay, cond, foo and bar have the if-then-else as a common ancestor expression, +# which is also fully on the same line +if cond then foo else bar + +# Bad, due to function application precedence, the smallest common ancestor expression +# of foo and bar is `foo || bar baz`, which spans two lines +foo || bar + baz +``` + +**Rationale** + +This rule has turned out to be very practical at catching code that could be potentially hard to understand or edit. + +### Line length + +Lines have a soft length limit that doesn't count indentation. +There may also be a hard length limit that includes indentation. +String-like values such as strings, paths, comments, urls, etc. may go over the hard length limit. +These limits should be configurable, and the soft length limit should default to 100 characters. + +### Indentation + +- Two spaces are used for each indentation level. + - This may be revisited should Nix get proper support for [using tabs for indentation](https://github.com/NixOS/nix/issues/7834) in the future. +- Vertical alignment may not be persisted, neither at the start of the line nor within lines. + - Examples: + ```nix + { + # Bad, vertical alignment Within lines + linux = { execFormat = elf; families = { }; }; + netbsd = { execFormat = elf; families = { inherit bsd; }; }; + none = { execFormat = unknown; families = { }; }; + openbsd = { execFormat = elf; families = { inherit bsd; }; }; + + # Bad, vertical alignment at the start of line + optExecFormat = + lib.optionalString (kernel.name == "netbsd" && + gnuNetBSDDefaultExecFormat cpu != kernel.execFormat + ) + kernel.execFormat.name; + } + ``` +- Indentation levels *must not* be "skipped", i.e. on subsequent lines, indentation can only increase by at most one level, but may decrease arbitrarily many levels. + - In other words: a line on indentation level 6 could be followed by a line on indentation level 1, but not the other way around. + - Examples: + ```nix + buildInputs = [ + foo # <-- + ] // lib.optionals cond [ + bar + ]; + + attribute = { args }: let + foo = "bar" # <-- + in + foo; + + (callFunction { + foo = "bar"; # <-- + } + arg + ) + + # This is okay, indentation increases only one level per line + let + x = { + a = foo + bar + baz; + }; # <-- The decrease by two levels here is okay though + in + null + ``` + +### Expansion of expressions + +**Description** + +Unless stated otherwise, any expression that fits onto one single line will be trivially formatted as such. + +For sequences of items in expressions, like elements in a list, key-value pairs in attribute sets, or function arguments, the following applies: + +- If expanded into with multiple lines, each item should be on its own line. + - Grouping similar items together can be done by adding blank lines or comments between the groups instead. + - This also applies to the first item, so e.g. `[ firstElement` in a multi line list is not allowed. +- Long sequences of items may be liberally expanded, even if they would fit onto one line character-wise. + - The motivation is to keep the information per line manageable. Usually "number of elements" is a better metric for that than "line length". + - The cutoff is usually determined empirically based on common usage patterns. + +**Examples:** + +```nix +{ + #1 + buildInputs = [ + foo + bar + baz + + somethingElse + ]; + + #2 + systemd.services = { + foo = { }; + bar = { }; + }; + + #3 + inherit + lib + foo + bar + baz + ; +} +``` + +### Function application + +**Description:** + +- In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". +- The last argument receives special treatment, to better represent common coding patterns. +- As much arguments as possible are fit onto the first line. + - If all but the last argument do fit, then the last argument may start on the same line. + - If an earlier argument does not fit onto the first line, then itself and all the following ones start on a new line. This is called the expanded form. + - All arguments that are not on the same line as the function are indented by one level. + +**Examples:** + +```nix +#1 +function arg1 arg2 + +#2 +function arg1 arg2 { + more = "things"; +} + +#3 +function arg1 arg2 arg3 # reached line limit here + arg4 + arg5 + [ + 1 + 2 + ] + arg7 + +#4 All arguments that don't fit on the same line, start indented on a new line +function arg1 + { + # items that don't fit on same line + } + arg3 + +#5 +function + { + a = 1; + b = 2; + } + { + c = 1; + d = 2; + } + +#6 (with "--width=20") +function arg1 ( + function2 args +) +``` + +**Drawbacks** + +- This style sometimes forces lists or attribute sets to start on a new line, with additional indentation of their items. + +**Rationale and alternatives** + +- Not indenting the arguments, to save some indentation depth. This would be consistent with other constructs like function declarations and let bindings. +- Compacting multiline arguments like this: + ```nix + #4b + function arg1 { + # stuff + } arg3 + + #5b + function { + # … + } { + # … + } + ``` + - This violates the guideline of the indentation representing the expression structure, and thus reduces readability. + - This does not work well with line length limits on short arguments like in example #3. + +### Function declaration + +**Description** + +- The body of the function is not indented relative to its arguments. +- Multiple ("simple") identifier arguments are written onto the same line if possible. +- Attribute set arguments always start on a new line; they are not mixed with identifier arguments. + - If they have few attributes, the argument may be written on a single line, otherwise the expanded form is used. +- Attribute set arguments have their attributes on a new line each with indentation, followed by a trailing comma. + +**Examples** + +```nix +#1 +name: value: name ++ value + +#2 +name: value: +{ + "${name}-foo" = value; +} + +#3 +{ pkgs }: pkgs.hello + +#4 +args@{ + some, + argument, + default ? value, + ... +}: +{ + # body +} + +#5 +{ pkgs }: +name: value: +{ + # body +} +``` + +**Rationale and alternatives** + +- Have leading commas for parameters in attribute set arguments, like currently done in Nixpkgs + ```nix + #6 + { some + , arg + }: + #7 + args@{ + some + , argument + # Single line comment + , commentedArgument + , # Comment on the value + # multiline comment + default ? value + , ... + }: + # … + ``` + - This leads to problems with the first argument, as leading commas are not allowed. `{ some` is discouraged by the the style guidelines; `some` should start on a new line instead. Also, this does not work well with `@` bindings. + - The currently suggested style for commenting items in the Nixpkgs manual (depicted here in `#7`) is not great. However, there are no other good solutions with leading comma style that don't run into other problems. + - The leading comma style was a lesser-evil workaround for the lack of trailing commas in the Nix language. Now that the language has this feature, there is no reason to keep it that way anymore. + + +### Operators + +**Description** + +Chained binary associative [operators](https://nixos.org/manual/nix/stable/language/operators.html#operators) (except [function application](#function-application)) with the same or monotonically decreasing precedence are treated as one. + +If an operator chain does not fit onto one line, it is expanded such that every operator starts a new line: +- If the operand can also fit on the same line as the operator, it's put there +- Otherwise, the operand usually starts indented on a new line, with special handling for parenthesis, brackets, braces, function applications + +Operator chains in bindings may be compacted as long as all lines between the first and last one are indented. + +**Examples** + +```nix +# These chained associative operators have increasing precedence, so they're _not_ treated the same +foo +-> # <- The operator starts on a new line, but right operand is all of the below lines, they don't fit here, so indent + bar + || + baz + && qux # <- The operand fits on this line + +# These chained associative operators have decreasing precedence, so they're treated the same +foo +&& bar # <- All of these operands are just identifiers, they fit on the same line +|| baz # <- We shouldn't indent these lines, because it misleads into thinking that || binds stronger than && +-> qux + +[ + some + flags +] +++ ( # <- The operator is on a new line, but parenthesis/brackets/braces can start on the same line + foo +) +++ optionals condition [ # <- As are multiline functions applications + more + items +] +++ + runCommand name # <- But only functions whose last argument can start on the same line + '' + echo hi + '' + test + +{ + # In a binding, we can use a more compact form as long as all inbetween lines are indented + foo = bar // { + x = 10; + y = 20; + } // baz; +} + +{ + # Bad, we can't use the more compact form because an intermediate line is not indented. + foo = { + x = 10; + y = 20; + } // foo // { + z = 30; + w = 40; + }; +} +``` + +### if + +**Desciption** + +- `if` and `else` keywords always start a line, the if and else bodies are indented. +- If the condition does not fit onto one line, then it will start on the next line with indentation, and `then` will be on the start of the line following the condition. +- `else if` chains are treated as one long sequence, with no indentation creep on each step. +- Only simple `if` statement can be single-line, no `else if` chains. + +**Examples** + +```nix +#1 +if builtins.length matches != 0 then + { inherit path matches; } +else if path == /. then + [ + 1 + 2 + ] +else + go (dirOf path); + +#2 +if + matches != null + && builtins.length matches != 0 +then + { inherit path matches; } +else if path == /. then + null +else + go (dirOf path); +``` + +**Rationale and alternatives** + +- Attribute sets and lists could start on the same line as the if keywords, saving an indentation level on their body: + ```nix + #1a + if builtins.length matches != 0 then { + inherit path matches; + } else if path == /. then [ + 1 + 2 + ] else + go (dirOf path); + ``` + - This results in inconsistent vertical start of the keywords, making the structure harder to follow +- Have the `then` on the start of the next line, directly followed by the if body: + ```nix + #1b + if builtins.length matches != 0 + then { inherit path matches; } + else if path == /. + then [ + 1 + 2 + ] + else go (dirOf path); + + #1c + if builtins.length matches != 0 + then { inherit path matches; } + else if path == /. + then [ + 1 + 2 + ] + else go (dirOf path); + ``` + +### with, assert + +**Description** + +- The body after the statement starts on a new line, without indentation. +- There may be exceptions for common idioms, in which the body already starts on the same line. + +**Examples** + +```nix +with pkgs; +assert foo == bar; { + meta.maintainers = + with lib.maintainers; [ + some + people + ]; +} +``` + +### let + +**Description** + +- Let bindings are *always* multiline. +- The "let" part is indented one level, but not the "in" part. +- Each item in the "let" part is indented and starts on its own line. + For more details, see the [binders section](#binders). +- The "in" part starts on a new line. + +**Examples** + +```nix +let + foo = "bar"; +in +if foo == "bar" then + "hello" +else + "world" +``` + +### Attribute sets and lists + +**Description** + +- Brackets and braces are generally written with a space on the inside, like `[ `, ` ]`, `{ ` and ` }`. + - Empty lists and attribute sets are written as`[ ]` and`{ }`, respectively. +- Lists and attribute sets with multiple items are liberally expanded. + - They can only be on a single line if: + - They contain at most one element + - Fit on the line + - As described under [Binders](#binders) below, nested attribute sets are always expanded. + +**Examples** + +```nix +#1 +[ + { } + { foo = "bar"; } + { + foo = { + bar = "baz"; + }; + } + { foo.bar = "baz"; } +] + +#2 +[ + [ 1 ] + [ + 2 + 3 + ] +] + +#3 +[ + [ + 1 + 2 + 3 + ] +] + +#4 +[ + { + mySingletons = [ + [ + ({ + # stuff in there + }) + ] + ]; + + mySingletons' = [ + [ + (function call) + ] + ]; + } +] +``` + +**Drawbacks** + +- Singleton lists may use a lot of indentation + +**Rationale and alternatives** + +- Have a special compact form for singleton lists, to reduce the indentation level and remove two additional lines + ```nix + foo = [ { + # content + } ]; + ``` +- Be a bit less eager about expanding lists and attribute sets (for example by allowing up to n elements on a single line). + ```nix + [ x y ] + ``` + +### Binders and inherit + +Let bindings and attribute sets share the same syntax for their items, which is discussed here together. + +#### Binders + +**Description** + +Binders have the most special cases to accommodate for many common Nixpkgs idioms. +Generally, the following styles exist, which are used depending on the kind and size of the value: + +```nix +#1 single line +foo = "bar"; + +#2 single line, on a new line +very.long.foo = + function arg1 arg2 arg3; + +#3 multi line, starting on the same line +foo = function { + # args +}; + +#4 multi line, starting on a new line +foo = + function + arg1 + arg2 + arg3 +; + +#5 simple function arguments (<=2) start on the same line +add = x: y: { + result = x + y; +}; + +#6 attribute bindings always start on a new line +# If we add more attributes, the indentation stays the same, see #7 +split = + { x, ... }: + { + inc = x + 1; + dec = x - 1; + }; + +#7 with enough attribute bindings, they will start on a new line and become multline +# it is common to expand input arguments in a way that does not change the number of function applications necessary +outputs = + { + x, + y, + z, + ... + }: + { + result = x + y; + }; +``` + +Notable special cases are: + +- Single line values that would not benefit from style #2 keep using #1, even if this makes it go above the line limit. This mostly applies to simple strings and paths. +- Attribute set values are *always* expanded. This has the consequence of always forcing nested attribute sets to be multiline (even if they would be single line otherwise because they only contain a single item), which usually is desired. + ```nix + { + foo.bar.baz = "qux"; + foo' = { + bar.baz = "qux"; + }; + } + ``` +- "statement-like" expressions like "let", "if" and "assert" always use #4 (or #1). +- If the value is a `with` followed by a function application or list or attribute set, try to use #3. + ```nix + buildInputs = with pkgs; [ + some + dependencies + ]; + ``` + +**Alternatives** + +One could eliminate style #2 by having #4 always start on the first line. This would even reduce indentation in some cases. However, this may look really weird in other cases, especially when the binder is very long: + +```nix +some.very.long.attr = callFunction + arg1 + arg2 + arg3; +``` + +#### inherit + +**Description** + +The items are either all on the same line, or all on a new line each (with indentation). + +**Examples** + +```nix +inherit foo bar baz; +inherit + foo' + bar' + baz' +; +``` + +#### inherit from + +**Description** + +- If the inherit target is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. +- Otherwise, it starts on a new line with indentation, like the others. + - In that case, the remaining items are force-expanded too, even if they would have fit onto one line in the first place. + +**Examples** + +```nix +inherit (pkgs) ap1 ap2 ap3; +inherit (pkgs) + app1 + app2 + # … + app42 +; +inherit + (pkgs.callPackage ./foo.nix { + arg = "val"; + }) + attr1 + attr2 +; +``` + +#### Semicolon placement + +**Description** + +The semicolon is always placed on the same line as the expression it concludes. + +**Examples** + +```nix +{ + attr1 = bar; + attr2 = function call { + # stuff + }; + attr3 = + function call + many + arguments; + attr4 = + let + foo = "bar"; + in + some statement; + attr5 = + if foo then + "bar" + else + "baz"; + attr6 = + let + foo = false; + in + if foo then "bar" else "baz"; + attr7 = function ( + if foo then + "bar" + else + "baz" + ); + attr8 = + cond1 + || cond2 + || + some function call + && cond3; +} +``` + +**Rationale and alternatives** + + +There are four considered semicolon styles: +1. On a new line without indentation. + - This clearly marks a separation between attributes, however it is wasteful of space. + ```nix + attr3 = + function call + many + arguments; + attr3 = + let + foo = "bar"; + in + some statemens; + ``` +2. On a new line with one indentation level. + - Just as wasteful on space as (1), but a bit less clear about signaling the end of the binding. + ```nix + inherit (pkgs) + app1 + app2 + # … + app42; + + attr3 = + function call + many + arguments; + ``` +3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binder. + But with exceptions in which the semicolon is placed onto the following line instead in cases where the value is a multiline `if` expression or nested operator. + These are the only syntax elements which may result in the semicolon being placed on a line with arbitrarily deep indentation. + + ```nix + attr4 = + if foo then + "bar" + else + "baz"; + + attr5 = + let + foo = false; + in + if foo then + "bar" + else + "baz"; + + attr7 = + cond1 + || cond2 + || + some function call + && cond3; + ``` From f4f382dfc9409619ed416199f768a15bc949b554 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Wed, 15 Nov 2023 21:39:04 +0100 Subject: [PATCH 02/39] Operator chains outside bindings can also have a compact form --- rfcs/0166-nix-formatting.md | 28 ++++++++++++---------------- 1 file changed, 12 insertions(+), 16 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 5c2196d7d..c5e8b35ee 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -566,7 +566,7 @@ If an operator chain does not fit onto one line, it is expanded such that every - If the operand can also fit on the same line as the operator, it's put there - Otherwise, the operand usually starts indented on a new line, with special handling for parenthesis, brackets, braces, function applications -Operator chains in bindings may be compacted as long as all lines between the first and last one are indented. +Operator chains may be compacted as long as all lines between the first and last one are indented. **Examples** @@ -603,23 +603,19 @@ foo '' test -{ - # In a binding, we can use a more compact form as long as all inbetween lines are indented - foo = bar // { - x = 10; - y = 20; - } // baz; -} +# We can use a more compact form as long as all inbetween lines are indented +bar // { + x = 10; + y = 20; +} // baz +# Bad, we can't use the more compact form because an intermediate line is not indented. { - # Bad, we can't use the more compact form because an intermediate line is not indented. - foo = { - x = 10; - y = 20; - } // foo // { - z = 30; - w = 40; - }; + x = 10; + y = 20; +} // foo // { + z = 30; + w = 40; } ``` From 940312fbdf41a89e4fdd3756f3724bc9cabd1d6f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Wed, 15 Nov 2023 23:48:45 +0100 Subject: [PATCH 03/39] Make the operator compact form specific to binders --- rfcs/0166-nix-formatting.md | 40 +++++++++++++++++++++++++++---------- 1 file changed, 29 insertions(+), 11 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index c5e8b35ee..9deb395e5 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -566,7 +566,7 @@ If an operator chain does not fit onto one line, it is expanded such that every - If the operand can also fit on the same line as the operator, it's put there - Otherwise, the operand usually starts indented on a new line, with special handling for parenthesis, brackets, braces, function applications -Operator chains may be compacted as long as all lines between the first and last one are indented. +Operator chains in binders may be compacted as long as all lines between the first and last one are indented. **Examples** @@ -603,19 +603,37 @@ foo '' test -# We can use a more compact form as long as all inbetween lines are indented -bar // { - x = 10; - y = 20; -} // baz +# In binders we can use a more compact form as long as all inbetween lines are indented. +{ + foo = bar // { + x = 10; + y = 20; + } // baz; +} # Bad, we can't use the more compact form because an intermediate line is not indented. { - x = 10; - y = 20; -} // foo // { - z = 30; - w = 40; + foo = { + x = 10; + y = 20; + } // bar // { + z = 30; + w = 40; + }; +} + +# Good, this is the non-compact operator form +{ + foo = + { + x = 10; + y = 20; + } + // bar + // { + z = 30; + w = 40; + }; } ``` From 63a2fa906bbf5929e9b4d82b7047619e39ea718f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 16 Nov 2023 00:22:17 +0100 Subject: [PATCH 04/39] Fix accidentally formatted semicolons in alternatives --- rfcs/0166-nix-formatting.md | 23 +++++++++++++---------- 1 file changed, 13 insertions(+), 10 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 9deb395e5..8f234f089 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -1027,12 +1027,14 @@ There are four considered semicolon styles: attr3 = function call many - arguments; + arguments + ; attr3 = let foo = "bar"; in - some statemens; + some statemens + ; ``` 2. On a new line with one indentation level. - Just as wasteful on space as (1), but a bit less clear about signaling the end of the binding. @@ -1041,12 +1043,14 @@ There are four considered semicolon styles: app1 app2 # … - app42; + app42 + ; attr3 = function call many - arguments; + arguments + ; ``` 3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binder. But with exceptions in which the semicolon is placed onto the following line instead in cases where the value is a multiline `if` expression or nested operator. @@ -1057,21 +1061,20 @@ There are four considered semicolon styles: if foo then "bar" else - "baz"; + "baz" + ; attr5 = let foo = false; in - if foo then - "bar" - else - "baz"; + foo || bar; attr7 = cond1 || cond2 || some function call - && cond3; + && cond3 + ; ``` From 9a466299e9aefd307a9793a5d1149807b55438e7 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Thu, 16 Nov 2023 00:37:52 +0100 Subject: [PATCH 05/39] Minor changes --- rfcs/0166-nix-formatting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 8f234f089..00f4fc968 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -551,7 +551,7 @@ name: value: }: # … ``` - - This leads to problems with the first argument, as leading commas are not allowed. `{ some` is discouraged by the the style guidelines; `some` should start on a new line instead. Also, this does not work well with `@` bindings. + - This leads to problems with the first argument, as leading commas are not allowed. `{ some` is discouraged by the style guidelines; `some` should start on a new line instead. Also, this does not work well with `@` bindings. - The currently suggested style for commenting items in the Nixpkgs manual (depicted here in `#7`) is not great. However, there are no other good solutions with leading comma style that don't run into other problems. - The leading comma style was a lesser-evil workaround for the lack of trailing commas in the Nix language. Now that the language has this feature, there is no reason to keep it that way anymore. @@ -597,7 +597,7 @@ foo items ] ++ - runCommand name # <- But only functions whose last argument can start on the same line + runCommand name # <- ... but only for functions whose last argument starts on the same line '' echo hi '' @@ -946,7 +946,7 @@ inherit **Description** -- If the inherit target is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. +- If the inherit source is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. - Otherwise, it starts on a new line with indentation, like the others. - In that case, the remaining items are force-expanded too, even if they would have fit onto one line in the first place. From 1ef40c5a7a073e94992e72a4c3095de762733487 Mon Sep 17 00:00:00 2001 From: Ryan Hendrickson Date: Wed, 15 Nov 2023 19:18:01 -0500 Subject: [PATCH 06/39] Light copy editing --- rfcs/0166-nix-formatting.md | 20 ++++++++++---------- 1 file changed, 10 insertions(+), 10 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 00f4fc968..60b40f26c 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -13,7 +13,7 @@ related-issues: https://github.com/serokell/nixfmt/pull/118, https://github.com/ ## Summary -The RFC consist of these main parts, see the [detailed design section](#detailed-design) for more information: +The RFC consists of these main parts, see the [detailed design section](#detailed-design) for more information: - Define the initial _standard Nix format_ - Establish the _Nix format team_ @@ -47,7 +47,7 @@ Non-goals of this RFC: ## Goals and approach There are several goals that the formatting style should match. -These are inherently at conflict with each other, requiring priorisation and making trade-offs. +These are inherently in conflict with each other, requiring prioritisation and making trade-offs. The resulting choice is always a compromise. In general, we want the code to be (in no particular order): @@ -72,7 +72,7 @@ However, the most important or potentially controversial rules are included, as When deciding between two *equally good* options, currently prevalent formatting style in Nixpkgs should be followed. The emphasis here is on "equally good". -We should not fear of making radical changes to the current style if there are sufficient arguments in favor of it. +We should not fear making radical changes to the current style if there are sufficient arguments in favor of it. *Bad code does not deserve good formatting.* @@ -80,7 +80,7 @@ We should not fear of making radical changes to the current style if there are s ### Standard Nix format -The _standard nix format_ defines the officially recommended way how Nix code should be formatted. +The _standard Nix format_ defines the officially recommended way that Nix code should be formatted. The initial version of the standard Nix format is defined in a section towards the end: @@ -412,7 +412,7 @@ For sequences of items in expressions, like elements in a list, key-value pairs - In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". - The last argument receives special treatment, to better represent common coding patterns. -- As much arguments as possible are fit onto the first line. +- As many arguments as possible are fit onto the first line. - If all but the last argument do fit, then the last argument may start on the same line. - If an earlier argument does not fit onto the first line, then itself and all the following ones start on a new line. This is called the expanded form. - All arguments that are not on the same line as the function are indented by one level. @@ -592,7 +592,7 @@ foo ++ ( # <- The operator is on a new line, but parenthesis/brackets/braces can start on the same line foo ) -++ optionals condition [ # <- As are multiline functions applications +++ optionals condition [ # <- As are multiline function applications more items ] @@ -603,7 +603,7 @@ foo '' test -# In binders we can use a more compact form as long as all inbetween lines are indented. +# In binders we can use a more compact form as long as all in-between lines are indented. { foo = bar // { x = 10; @@ -639,7 +639,7 @@ foo ### if -**Desciption** +**Description** - `if` and `else` keywords always start a line, the if and else bodies are indented. - If the condition does not fit onto one line, then it will start on the next line with indentation, and `then` will be on the start of the line following the condition. @@ -1033,7 +1033,7 @@ There are four considered semicolon styles: let foo = "bar"; in - some statemens + some statements ; ``` 2. On a new line with one indentation level. @@ -1054,7 +1054,7 @@ There are four considered semicolon styles: ``` 3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binder. But with exceptions in which the semicolon is placed onto the following line instead in cases where the value is a multiline `if` expression or nested operator. - These are the only syntax elements which may result in the semicolon being placed on a line with arbitrarily deep indentation. + These are the only syntax elements that may result in the semicolon being placed on a line with arbitrarily deep indentation. ```nix attr4 = From 1da46792a9f893a802e392b5c69f73db5a452c6d Mon Sep 17 00:00:00 2001 From: Yuriy Taraday Date: Thu, 16 Nov 2023 15:03:36 +0100 Subject: [PATCH 07/39] Fix .git-blame-ignore-revs --- rfcs/0166-nix-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 60b40f26c..353326091 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -157,7 +157,7 @@ the official Nix formatter must be used. ### Git blames -Reformatting commits that get added to `.git-ignore-revs` [won't get shown](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view) in blames on GitHub, +Reformatting commits that get added to `.git-blame-ignore-revs` [won't get shown](https://docs.github.com/en/repositories/working-with-files/using-files/viewing-a-file#ignore-commits-in-the-blame-view) in blames on GitHub, and can be ignored in the `git blame` command using [`--ignore-revs-file`](https://www.git-scm.com/docs/git-blame#Documentation/git-blame.txt---ignore-revs-fileltfilegt). ### Formatting gotchas requiring manual intervention From 0513bdae04b917b5b46dccba36dabb904b6435e2 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 28 Nov 2023 21:08:28 +0100 Subject: [PATCH 08/39] Improve assert/with wording --- rfcs/0166-nix-formatting.md | 79 +++++++++++++++++++++++++++++++++++-- 1 file changed, 75 insertions(+), 4 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 353326091..18c355429 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -713,16 +713,87 @@ else **Description** -- The body after the statement starts on a new line, without indentation. -- There may be exceptions for common idioms, in which the body already starts on the same line. +- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, and the `with attrs;`/`assert cond;` does _not_ start on a new line (e.g. `foo = with; …`), then the body will start on that same line too. +- Otherwise, the body of `with attrs;`/`assert cond;` starts on a new line (and without any additional indentation). + +``` +{ + # Good + foo = + assert foo == bar; + with bar; + [ + # multiline + baz + ] + + # Good + foo = with bar; [ + # multiline + baz + ]; + + # Good + foo = + with bar; + baz foo { + # multiline + qux = 10; + } + + # Good + foo = with bar; ( + baz + ); + + # Good + foo = + with bar; + if cond then + foo + else + bar; + + # Bad + foo = assert qux; with bar; [ + # multiline + baz + ]; + + # Bad + foo = with bar; + [ + # multiline + baz + ]; + + # Bad + foo = + with bar; [ + # multiline + baz + ]; +} +``` **Examples** ```nix with pkgs; -assert foo == bar; { +assert foo == bar; +{ + meta.maintainers = with lib.maintainers; [ + some + people + ]; +} + +with pkgs; +assert foo == bar; +{ meta.maintainers = - with lib.maintainers; [ + with lib.maintainers; + [ some people ]; From 385a914e9a506b6b24506a770d71f29e3cd65fdb Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 28 Nov 2023 21:32:37 +0100 Subject: [PATCH 09/39] Be more flexible with single-line element count --- rfcs/0166-nix-formatting.md | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 18c355429..6ed1ad549 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -829,9 +829,7 @@ else - Brackets and braces are generally written with a space on the inside, like `[ `, ` ]`, `{ ` and ` }`. - Empty lists and attribute sets are written as`[ ]` and`{ }`, respectively. - Lists and attribute sets with multiple items are liberally expanded. - - They can only be on a single line if: - - They contain at most one element - - Fit on the line + - They can only be on a single line if they fit on the line and contain few enough elements. - As described under [Binders](#binders) below, nested attribute sets are always expanded. **Examples** From 9ac50f80ab4aafa6fe773a54a8549e3e01ad7fec Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 28 Nov 2023 21:38:37 +0100 Subject: [PATCH 10/39] binder -> binding --- rfcs/0166-nix-formatting.md | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 6ed1ad549..ee203437f 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -566,7 +566,7 @@ If an operator chain does not fit onto one line, it is expanded such that every - If the operand can also fit on the same line as the operator, it's put there - Otherwise, the operand usually starts indented on a new line, with special handling for parenthesis, brackets, braces, function applications -Operator chains in binders may be compacted as long as all lines between the first and last one are indented. +Operator chains in bindings may be compacted as long as all lines between the first and last one are indented. **Examples** @@ -603,7 +603,7 @@ foo '' test -# In binders we can use a more compact form as long as all in-between lines are indented. +# In bindings we can use a more compact form as long as all in-between lines are indented. { foo = bar // { x = 10; @@ -807,7 +807,7 @@ assert foo == bar; - Let bindings are *always* multiline. - The "let" part is indented one level, but not the "in" part. - Each item in the "let" part is indented and starts on its own line. - For more details, see the [binders section](#binders). + For more details, see the [bindings section](#bindings). - The "in" part starts on a new line. **Examples** @@ -830,7 +830,7 @@ else - Empty lists and attribute sets are written as`[ ]` and`{ }`, respectively. - Lists and attribute sets with multiple items are liberally expanded. - They can only be on a single line if they fit on the line and contain few enough elements. - - As described under [Binders](#binders) below, nested attribute sets are always expanded. + - As described under [bindings](#bindings) below, nested attribute sets are always expanded. **Examples** @@ -902,15 +902,15 @@ else [ x y ] ``` -### Binders and inherit +### Bindings and inherit Let bindings and attribute sets share the same syntax for their items, which is discussed here together. -#### Binders +#### Bindings **Description** -Binders have the most special cases to accommodate for many common Nixpkgs idioms. +Bindings have the most special cases to accommodate for many common Nixpkgs idioms. Generally, the following styles exist, which are used depending on the kind and size of the value: ```nix @@ -985,7 +985,7 @@ Notable special cases are: **Alternatives** -One could eliminate style #2 by having #4 always start on the first line. This would even reduce indentation in some cases. However, this may look really weird in other cases, especially when the binder is very long: +One could eliminate style #2 by having #4 always start on the first line. This would even reduce indentation in some cases. However, this may look really weird in other cases, especially when the binding is very long: ```nix some.very.long.attr = callFunction @@ -1121,7 +1121,7 @@ There are four considered semicolon styles: arguments ; ``` -3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binder. +3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binding. But with exceptions in which the semicolon is placed onto the following line instead in cases where the value is a multiline `if` expression or nested operator. These are the only syntax elements that may result in the semicolon being placed on a line with arbitrarily deep indentation. From 299c16f9c7ff96e28c5314bc9de0b1e72656d795 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 28 Nov 2023 21:55:46 +0100 Subject: [PATCH 11/39] unindent inherit semicolon, reshuffle binding/inherit sections (#14) * unindent inherit semicolon, reshuffle binding/inherit sections * fixup! Stuff --- rfcs/0166-nix-formatting.md | 107 +++++++++++++++++------------------- 1 file changed, 49 insertions(+), 58 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index ee203437f..bfa0900a7 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -402,7 +402,7 @@ For sequences of items in expressions, like elements in a list, key-value pairs foo bar baz - ; + ; } ``` @@ -902,12 +902,10 @@ else [ x y ] ``` -### Bindings and inherit +### Bindings Let bindings and attribute sets share the same syntax for their items, which is discussed here together. -#### Bindings - **Description** Bindings have the most special cases to accommodate for many common Nixpkgs idioms. @@ -931,8 +929,7 @@ foo = function arg1 arg2 - arg3 -; + arg3; #5 simple function arguments (<=2) start on the same line add = x: y: { @@ -994,51 +991,7 @@ some.very.long.attr = callFunction arg3; ``` -#### inherit - -**Description** - -The items are either all on the same line, or all on a new line each (with indentation). - -**Examples** - -```nix -inherit foo bar baz; -inherit - foo' - bar' - baz' -; -``` - -#### inherit from - -**Description** - -- If the inherit source is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. -- Otherwise, it starts on a new line with indentation, like the others. - - In that case, the remaining items are force-expanded too, even if they would have fit onto one line in the first place. - -**Examples** - -```nix -inherit (pkgs) ap1 ap2 ap3; -inherit (pkgs) - app1 - app2 - # … - app42 -; -inherit - (pkgs.callPackage ./foo.nix { - arg = "val"; - }) - attr1 - attr2 -; -``` - -#### Semicolon placement +#### Bindings semicolon placement **Description** @@ -1108,13 +1061,6 @@ There are four considered semicolon styles: 2. On a new line with one indentation level. - Just as wasteful on space as (1), but a bit less clear about signaling the end of the binding. ```nix - inherit (pkgs) - app1 - app2 - # … - app42 - ; - attr3 = function call many @@ -1147,3 +1093,48 @@ There are four considered semicolon styles: && cond3 ; ``` + +### inherit + +**Description** + +- The items are either all on the same line, or all on a new line each (with indentation). +- The semicolon is on its own line with indentation. + +**Examples** + +```nix +inherit foo bar baz; +inherit + foo' + bar' + baz' + ; +``` + +#### inherit from + +**Description** + +- If the inherit source is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. +- Otherwise, it starts on a new line with indentation, like the others. + - In that case, the remaining items are force-expanded too, even if they would have fit onto one line in the first place. + +**Examples** + +```nix +inherit (pkgs) ap1 ap2 ap3; +inherit (pkgs) + app1 + app2 + # … + app42 + ; +inherit + (pkgs.callPackage ./foo.nix { + arg = "val"; + }) + attr1 + attr2 + ; +``` From 6a6efcd2b5588ba662004b48314204628487f551 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Dec 2023 21:01:12 +0100 Subject: [PATCH 12/39] Give alternatives to `in` formatting --- rfcs/0166-nix-formatting.md | 48 ++++++++++++++++++++++++++++++++++--- 1 file changed, 45 insertions(+), 3 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index bfa0900a7..0e355cc9c 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -804,11 +804,20 @@ assert foo == bar; **Description** +Let bindings always have this form: +``` +let + = ; + = ; + ... +in + +``` + - Let bindings are *always* multiline. -- The "let" part is indented one level, but not the "in" part. -- Each item in the "let" part is indented and starts on its own line. +- Each binding is indented and starts on its own line. For more details, see the [bindings section](#bindings). -- The "in" part starts on a new line. +- The `` always starts on a new line and is not indented. **Examples** @@ -822,6 +831,39 @@ else "world" ``` +**Alternatives** + +- To allow having the `` be on the same line as the `in`: + ``` + let + = ; + = ; + ... + in + ``` + + In particular when `` is an identifier, list, attribute set and/or others. + + Problems with this alternative: + - It leads to larger diffs when inserting something after the `in` + - The formatting can change when `` is updated + - It's less consistent, since the formatting depends on the `` + +- The body could be indented by a level + ``` + let + = ; + = ; + ... + in + + ``` + + Problems with this alternative: + - Leads to indentation creeps + - Inconsistent with other expressions that have a `` that is "returned" + - Favors a style where the body starts on the same line as the in for some values (e.g. attribute sets) to reduce an indentation level, see above. + ### Attribute sets and lists **Description** From ff2f08aa077639058711f49146e618e0dbca9057 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Dec 2023 21:51:59 +0100 Subject: [PATCH 13/39] Expand on line break preservation --- rfcs/0166-nix-formatting.md | 30 +++++++++++++++++++++++++++++- 1 file changed, 29 insertions(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 0e355cc9c..51f1be10a 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -30,6 +30,7 @@ There are several auto-formatters for Nix code, each with their own style, and n The goals of this RFC are: +- People should not be bothered with formatting. - We want to prevent future debate around how things should be formatted. - We want to make it as easy as possible for contributors (especially new ones) to make changes without having to worry about formatting. - Conversely, reviewers should not be bothered with poorly formatted contributions. @@ -260,8 +261,35 @@ Terms and definitions: - Braces: `{}` - Parentheses: `()` -- Newlines are not guaranteed to be preserved, but empty lines are. +- Line breaks may not be preserved, but empty lines must always be preserved. - This allows the formatter to compact down multi-line expressions if necessary, while still allowing to structure the code appropriately. + - Multiple subsequent empty lines must get collapsed into a single one. + + For example, formatting this code: + ```nix + [ + 0 + 10 + + 20 + + + 30 + ] + ``` + + turns into this: + ```nix + [ + 0 + 10 + + 20 + + 30 + ] + ``` + - Expressions of the same kind that can be treated as a sequence of expressions on the same level should be treated as such, even though they are technically parsed as a nested tree. - This applies to else-if chains, functions with multiple arguments, some operators, etc. - Example: From 5fd936505c25533875cb23ae32ce69a018516e09 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Dec 2023 21:56:48 +0100 Subject: [PATCH 14/39] Add editorconfig --- rfcs/0166-nix-formatting.md | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 51f1be10a..ca300a55c 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -303,6 +303,18 @@ Terms and definitions: baz ``` +### Editor Config + +This [editor config](https://editorconfig.org/) specifies the basic details about Nix files: + +```toml +end_of_line = lf +insert_final_newline = true +trim_trailing_whitespace = true +charset = utf-8 +indent_style = space +``` + ### Single-line common ancestor expression rule For any two (sub-)expressions that are fully on a common single line, their smallest common ancestor expression must also be on the same line. From 4f3b3ce5d704755d6527a9eaae9d01b9b430104d Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Dec 2023 22:35:02 +0100 Subject: [PATCH 15/39] Expand argumentation against leading commas --- rfcs/0166-nix-formatting.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index ca300a55c..4553c75a9 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -410,7 +410,7 @@ Unless stated otherwise, any expression that fits onto one single line will be t For sequences of items in expressions, like elements in a list, key-value pairs in attribute sets, or function arguments, the following applies: -- If expanded into with multiple lines, each item should be on its own line. +- If expanded into multiple lines, each item should be on its own line. - Grouping similar items together can be done by adding blank lines or comments between the groups instead. - This also applies to the first item, so e.g. `[ firstElement` in a multi line list is not allowed. - Long sequences of items may be liberally expanded, even if they would fit onto one line character-wise. @@ -572,7 +572,10 @@ name: value: **Rationale and alternatives** -- Have leading commas for parameters in attribute set arguments, like currently done in Nixpkgs +- Have leading commas for parameters in attribute set arguments, like currently done in Nixpkgs. + + - This makes attribute set arguments less likely to be confused with lists. + - It's easier to see where arguments start and end. ```nix #6 { some @@ -591,11 +594,14 @@ name: value: }: # … ``` - - This leads to problems with the first argument, as leading commas are not allowed. `{ some` is discouraged by the style guidelines; `some` should start on a new line instead. Also, this does not work well with `@` bindings. + + Problems with this alternative: + - Moving items around with this style may require editing lines. + - Inconsistent with the [expression expansion guidelines](#expansion-of-expressions), which disallows forms like `{ some`; `some` should start on a new line instead. + - This does not work well with leading `@` bindings. - The currently suggested style for commenting items in the Nixpkgs manual (depicted here in `#7`) is not great. However, there are no other good solutions with leading comma style that don't run into other problems. - The leading comma style was a lesser-evil workaround for the lack of trailing commas in the Nix language. Now that the language has this feature, there is no reason to keep it that way anymore. - ### Operators **Description** From b717f6e60bf49ca40b3ec7ecc03ebb84593ffd05 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 12 Dec 2023 22:50:31 +0100 Subject: [PATCH 16/39] Add @dasJ to the formatter team --- rfcs/0166-nix-formatting.md | 15 ++++++++------- 1 file changed, 8 insertions(+), 7 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 4553c75a9..8211cdce2 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -16,7 +16,7 @@ related-issues: https://github.com/serokell/nixfmt/pull/118, https://github.com/ The RFC consists of these main parts, see the [detailed design section](#detailed-design) for more information: - Define the initial _standard Nix format_ -- Establish the _Nix format team_ +- Establish the _Nix formatter team_ - Create the _official Nix formatter_ implementation - Reformat Nixpkgs with the official Nix formatter - Require that any default formatting in the Nix CLI must use the official Nix formatter @@ -91,9 +91,9 @@ Significant changes to the standard Nix format must go through another RFC. The latest version of the standard Nix format must be in a file on the main branch of the [official Nix formatter](#official-nix-formatter). -### Nix format team +### Nix formatter team -The _Nix format team_ is established, it has the responsibility to +The _Nix formatter team_ is established, it has the responsibility to - Maintain the [official Nix formatter](#official-nix-formatter) - Regularly [reformat Nixpkgs](#reformat-nixpkgs) with it @@ -105,12 +105,13 @@ Initially the team consists of these members: - @tomberek (from Flox, shepherd of the original formatting RFC) - @0x4A6F (shepherd of the original formatting RFC) - @Sereja313 (from Serokell, original sponsors of nixfmt) +- @dasJ (from Helsinki Systems, writes Nix) Team member updates are left for the team itself to decide. ### Official Nix formatter -The Nix format team is given the authority and responsibility of +The Nix formatter team is given the authority and responsibility of creating and maintaining the _official Nix formatter_ implementation. This is a repository in the NixOS GitHub organisation. The repository will initially be based on [this nixfmt pull request](https://github.com/serokell/nixfmt/pull/118). @@ -119,7 +120,7 @@ This pull request has been developed along with this RFC and is already reasonab Any release of the official Nix formatter must conform to the latest version of the [standard Nix format](#standard-nix-format). The latest release of the official Nix formatter should support the Nix language syntax of the latest Nix release. -The Nix format team should be consulted before the Nix language syntax is changed. +The Nix formatter team should be consulted before the Nix language syntax is changed. ### Reformat Nixpkgs @@ -131,7 +132,7 @@ For every bump of the pinned formatter, the files of Nixpkgs must thus be re-formatted accordingly. Commits that reformat Nixpkgs will be added to `.git-blame-ignore-revs`, which can then be [ignored in tooling](#git-blames). -The Nix format team is responsible for this task. +The Nix formatter team is responsible for this task. In order to minimize conflicts especially when back-porting, the pinned formatter should preferably only be updated shortly before the release branch-off. @@ -227,7 +228,7 @@ In this case one level of indentation can be saved using [`lib.singleton`](https - No automatic code format can be as pretty as a carefully crafted manual one. There will always be "ugly" edge cases. - However, we argue that on average the new format will be an improvement, and that contributors should not waste their time making the code slightly more pretty. -- Every formatter will have bugs, but the Nix format team will be able to make fixes. +- Every formatter will have bugs, but the Nix formatter team will be able to make fixes. - Having a commit that changes the formatting, can make git blame harder to use. - This can be [worked around in interfaces](#git-blames). From 734deb163b8178932d11944c1ea1002970ae546f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Wed, 20 Dec 2023 21:56:25 +0100 Subject: [PATCH 17/39] Add shepherd team Co-authored-by: Linus Heckemann --- rfcs/0166-nix-formatting.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 8211cdce2..7f50a485f 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -4,8 +4,8 @@ start-date: 2021-08-17 author: piegamesde co-authors: infinisil pre-RFC reviewers: tomberek, 0x4A6F -shepherd-team: -shepherd-leader: +shepherd-team: das_j, tomberek, 0x4A6F, infinisil +shepherd-leader: infinisil related-issues: https://github.com/serokell/nixfmt/pull/118, https://github.com/piegamesde/nixpkgs/pull/4 --- From ac863af209585d3134e8b8f33fa23b0f7f8fe1bc Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Wed, 3 Jan 2024 17:16:36 +0100 Subject: [PATCH 18/39] Various improvements (#15) * Various improvements - Remove unnecessary **Description** headers - Rename **Rationale and Alternatives** to just **Alternatives** - Insert must/may/should more diligently - Add some TODOs where things are unclear - Remove numberings from examples when not needed - Minor clarity improvements and simplifications throughout * Apply suggestions from code review Co-authored-by: Ryan Hendrickson --------- Co-authored-by: Ryan Hendrickson --- rfcs/0166-nix-formatting.md | 281 +++++++++++++++++------------------- 1 file changed, 131 insertions(+), 150 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 7f50a485f..3a5098c98 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -262,34 +262,34 @@ Terms and definitions: - Braces: `{}` - Parentheses: `()` -- Line breaks may not be preserved, but empty lines must always be preserved. - - This allows the formatter to compact down multi-line expressions if necessary, while still allowing to structure the code appropriately. - - Multiple subsequent empty lines must get collapsed into a single one. +- Line breaks may be added or removed, but empty lines must not be created. Single empty lines must be preserved, and consecutive empty lines must be turned into a single empty line. + This allows the formatter to expand or compact multi-line expressions, while still allowing grouping of code. - For example, formatting this code: - ```nix - [ - 0 - 10 - - 20 - - - 30 - ] - ``` + For example, formatting this code: + ```nix + [ + 0 10 - turns into this: - ```nix - [ - 0 - 10 - - 20 - - 30 - ] - ``` + ( + 20 + 1 + ) + + + 30 + ] + ``` + + turns into this: + ```nix + [ + 0 # Line break added + 10 + + (20 + 1) # Line breaks removed + # Consecutive empty lines turned into a single empty line + 30 + ] + ``` - Expressions of the same kind that can be treated as a sequence of expressions on the same level should be treated as such, even though they are technically parsed as a nested tree. - This applies to else-if chains, functions with multiple arguments, some operators, etc. @@ -304,6 +304,30 @@ Terms and definitions: baz ``` +- Indentation should reflect the expression structure. + Example: + ```nix + # Bad, the indentation misleads the user + { + foo = { + bar = if + baz == null then 10 + else 20 + ; + }; } + + # Good + { + foo = { + bar = + if baz == null then + 10 + else + 20; + }; + } + ``` + ### Editor Config This [editor config](https://editorconfig.org/) specifies the basic details about Nix files: @@ -344,16 +368,16 @@ This rule has turned out to be very practical at catching code that could be pot ### Line length -Lines have a soft length limit that doesn't count indentation. -There may also be a hard length limit that includes indentation. -String-like values such as strings, paths, comments, urls, etc. may go over the hard length limit. -These limits should be configurable, and the soft length limit should default to 100 characters. +- There should be a configurable _soft_ line length limit, limiting the number of characters on one line without counting the leading indentation. + The default should be 100 characters. +- There may also be a configurable _hard_ line length limit, which includes the leading indentation. +- String-like values such as strings, paths, comments, urls, etc. may go over the hard line length limit. ### Indentation -- Two spaces are used for each indentation level. +- Two spaces must be used for each indentation level. - This may be revisited should Nix get proper support for [using tabs for indentation](https://github.com/NixOS/nix/issues/7834) in the future. -- Vertical alignment may not be persisted, neither at the start of the line nor within lines. +- Vertical alignment must be ignored, both at the start of the line and within lines. - Examples: ```nix { @@ -371,23 +395,22 @@ These limits should be configurable, and the soft length limit should default to kernel.execFormat.name; } ``` -- Indentation levels *must not* be "skipped", i.e. on subsequent lines, indentation can only increase by at most one level, but may decrease arbitrarily many levels. - - In other words: a line on indentation level 6 could be followed by a line on indentation level 1, but not the other way around. +- Increasing indentation levels must not be "skipped": On subsequent lines, indentation can only increase by at most one level, but may decrease arbitrarily many levels. - Examples: ```nix buildInputs = [ - foo # <-- + foo # <-- Bad, indentation increases by 2 levels ] // lib.optionals cond [ bar ]; attribute = { args }: let - foo = "bar" # <-- + foo = "bar" # <-- Bad, indentation increases by 2 levels in foo; (callFunction { - foo = "bar"; # <-- + foo = "bar"; # <-- Bad, indentation increases by 2 levels } arg ) @@ -398,23 +421,21 @@ These limits should be configurable, and the soft length limit should default to a = foo bar baz; - }; # <-- The decrease by two levels here is okay though + }; # <-- The decrease by two levels here is okay in null ``` ### Expansion of expressions -**Description** - -Unless stated otherwise, any expression that fits onto one single line will be trivially formatted as such. +Unless stated otherwise, any expression that fits onto one single line must be trivially formatted as such. -For sequences of items in expressions, like elements in a list, key-value pairs in attribute sets, or function arguments, the following applies: +For list elements, attributes, and function arguments, the following applies: -- If expanded into multiple lines, each item should be on its own line. +- If expanded into multiple lines, each item must be on its own line. - Grouping similar items together can be done by adding blank lines or comments between the groups instead. - This also applies to the first item, so e.g. `[ firstElement` in a multi line list is not allowed. -- Long sequences of items may be liberally expanded, even if they would fit onto one line character-wise. +- Long sequences of items should be liberally expanded, even if they would fit onto one line character-wise. - The motivation is to keep the information per line manageable. Usually "number of elements" is a better metric for that than "line length". - The cutoff is usually determined empirically based on common usage patterns. @@ -422,7 +443,6 @@ For sequences of items in expressions, like elements in a list, key-value pairs ```nix { - #1 buildInputs = [ foo bar @@ -431,13 +451,11 @@ For sequences of items in expressions, like elements in a list, key-value pairs somethingElse ]; - #2 systemd.services = { foo = { }; bar = { }; }; - #3 inherit lib foo @@ -449,44 +467,38 @@ For sequences of items in expressions, like elements in a list, key-value pairs ### Function application -**Description:** - - In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". -- The last argument receives special treatment, to better represent common coding patterns. -- As many arguments as possible are fit onto the first line. - - If all but the last argument do fit, then the last argument may start on the same line. - - If an earlier argument does not fit onto the first line, then itself and all the following ones start on a new line. This is called the expanded form. - - All arguments that are not on the same line as the function are indented by one level. +- As many arguments as possible must be fit onto the first line. + - If all but the last argument do fit, then the last argument may also start on the first line. + - If an earlier argument does not fit onto the first line, then that argument and all the following ones must start on their own line. + - All arguments that are not on the same line as the function must be indented by one level. **Examples:** ```nix -#1 +# All arguments fit onto the first line function arg1 arg2 -#2 +# The line length limit is reached, so the remaining arguments need to be on their own lines +function arg1 arg2 arg3 + arg4 + arg5 + +# The last argument is a multiline expression, so it doesn't fit on the first line, +# but it can still start on the first line function arg1 arg2 { more = "things"; } -#3 -function arg1 arg2 arg3 # reached line limit here - arg4 - arg5 - [ - 1 - 2 - ] - arg7 - -#4 All arguments that don't fit on the same line, start indented on a new line -function arg1 +# The second argument doesn't fit on the first line, but it's not the last argument, +# so it needs to start on a new line +function arg1 arg2 { - # items that don't fit on same line + more = "things"; } arg3 -#5 +# Same with more multiline arguments function { a = 1; @@ -496,28 +508,21 @@ function c = 1; d = 2; } - -#6 (with "--width=20") -function arg1 ( - function2 args -) ``` **Drawbacks** - This style sometimes forces lists or attribute sets to start on a new line, with additional indentation of their items. -**Rationale and alternatives** +**Alternatives** - Not indenting the arguments, to save some indentation depth. This would be consistent with other constructs like function declarations and let bindings. - Compacting multiline arguments like this: ```nix - #4b function arg1 { # stuff } arg3 - #5b function { # … } { @@ -525,17 +530,15 @@ function arg1 ( } ``` - This violates the guideline of the indentation representing the expression structure, and thus reduces readability. - - This does not work well with line length limits on short arguments like in example #3. + - This does not work well with line length limits on short arguments (TODO: What does this mean?) ### Function declaration -**Description** - -- The body of the function is not indented relative to its arguments. -- Multiple ("simple") identifier arguments are written onto the same line if possible. -- Attribute set arguments always start on a new line; they are not mixed with identifier arguments. - - If they have few attributes, the argument may be written on a single line, otherwise the expanded form is used. -- Attribute set arguments have their attributes on a new line each with indentation, followed by a trailing comma. +- The body of the function must not be indented relative to its first arguments. +- Multiple ("simple") identifier arguments are written onto the same line if possible. TODO: What if it's not possible? +- Attribute set arguments must always start on a new line and they must not be mixed with identifier arguments. + - If they have few attributes, the argument may be written on a single line + - Otherwise each attribute must be on its own line with indentation, followed by a trailing comma. **Examples** @@ -571,22 +574,21 @@ name: value: } ``` -**Rationale and alternatives** +**Alternatives** - Have leading commas for parameters in attribute set arguments, like currently done in Nixpkgs. - This makes attribute set arguments less likely to be confused with lists. - It's easier to see where arguments start and end. ```nix - #6 { some , arg }: - #7 + args@{ some , argument - # Single line comment + # Single line comment , commentedArgument , # Comment on the value # multiline comment @@ -600,18 +602,16 @@ name: value: - Moving items around with this style may require editing lines. - Inconsistent with the [expression expansion guidelines](#expansion-of-expressions), which disallows forms like `{ some`; `some` should start on a new line instead. - This does not work well with leading `@` bindings. - - The currently suggested style for commenting items in the Nixpkgs manual (depicted here in `#7`) is not great. However, there are no other good solutions with leading comma style that don't run into other problems. + - It's unclear whether comments belong to the next or the previous argument. - The leading comma style was a lesser-evil workaround for the lack of trailing commas in the Nix language. Now that the language has this feature, there is no reason to keep it that way anymore. ### Operators -**Description** +Chained binary associative [operators](https://nixos.org/manual/nix/stable/language/operators.html#operators) (except [function application](#function-application)) with the same or monotonically decreasing precedence must be treated together as a single operator chain. -Chained binary associative [operators](https://nixos.org/manual/nix/stable/language/operators.html#operators) (except [function application](#function-application)) with the same or monotonically decreasing precedence are treated as one. - -If an operator chain does not fit onto one line, it is expanded such that every operator starts a new line: -- If the operand can also fit on the same line as the operator, it's put there -- Otherwise, the operand usually starts indented on a new line, with special handling for parenthesis, brackets, braces, function applications +If an operator chain does not fit onto one line, it must be expanded such that every operator starts a new line: +- If the operand can also fit on the same line as the operator, it must be put there +- Otherwise, the operand must start indented on a new line, with exceptions for parenthesis, brackets, braces and function applications Operator chains in bindings may be compacted as long as all lines between the first and last one are indented. @@ -684,19 +684,18 @@ foo } ``` -### if - -**Description** +### if-then-else -- `if` and `else` keywords always start a line, the if and else bodies are indented. +- `if` and `else` keywords must always start a line. +- The `if` and `else` bodies must always be indented. - If the condition does not fit onto one line, then it will start on the next line with indentation, and `then` will be on the start of the line following the condition. - `else if` chains are treated as one long sequence, with no indentation creep on each step. -- Only simple `if` statement can be single-line, no `else if` chains. +- `else if` chains must not be on a single line. **Examples** ```nix -#1 +# Condition fits on one line if builtins.length matches != 0 then { inherit path matches; } else if path == /. then @@ -707,7 +706,7 @@ else if path == /. then else go (dirOf path); -#2 +# Condition doesn't fit onto one line if matches != null && builtins.length matches != 0 @@ -719,9 +718,9 @@ else go (dirOf path); ``` -**Rationale and alternatives** +**Alternatives** -- Attribute sets and lists could start on the same line as the if keywords, saving an indentation level on their body: +- Attribute sets and lists could start on the same line as the `if` keywords, saving an indentation level on their body: ```nix #1a if builtins.length matches != 0 then { @@ -758,12 +757,11 @@ else ### with, assert -**Description** +- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, and the `with attrs;`/`assert cond;` does _not_ start on a new line (e.g. `foo = with; …`), then the body must start on that same line too. + TODO: What does it mean for it to "not start on a new line"? This really depends on what the surrounding expression is. Notably bindings yes, anything else? +- Otherwise, the body of `with attrs;`/`assert cond;` must start on a new line without any additional indentation. -- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, and the `with attrs;`/`assert cond;` does _not_ start on a new line (e.g. `foo = with; …`), then the body will start on that same line too. -- Otherwise, the body of `with attrs;`/`assert cond;` starts on a new line (and without any additional indentation). - -``` +```nix { # Good foo = @@ -787,11 +785,6 @@ else # multiline qux = 10; } - - # Good - foo = with bar; ( - baz - ); # Good foo = @@ -847,11 +840,9 @@ assert foo == bar; } ``` -### let - -**Description** +### let-in -Let bindings always have this form: +Let bindings must always have this form: ``` let = ; @@ -913,18 +904,15 @@ else ### Attribute sets and lists -**Description** - -- Brackets and braces are generally written with a space on the inside, like `[ `, ` ]`, `{ ` and ` }`. - - Empty lists and attribute sets are written as`[ ]` and`{ }`, respectively. -- Lists and attribute sets with multiple items are liberally expanded. +- Brackets and braces must always have a space (or line break) on the inside, like `[ `, ` ]`, `{ ` and ` }`. + - Empty lists and attribute sets are written as `[ ]` and `{ }`, respectively. +- Lists and attribute sets with multiple items should be liberally expanded. - They can only be on a single line if they fit on the line and contain few enough elements. - As described under [bindings](#bindings) below, nested attribute sets are always expanded. **Examples** ```nix -#1 [ { } { foo = "bar"; } @@ -936,7 +924,6 @@ else { foo.bar = "baz"; } ] -#2 [ [ 1 ] [ @@ -945,7 +932,6 @@ else ] ] -#3 [ [ 1 @@ -954,7 +940,6 @@ else ] ] -#4 [ { mySingletons = [ @@ -978,7 +963,7 @@ else - Singleton lists may use a lot of indentation -**Rationale and alternatives** +**Alternatives** - Have a special compact form for singleton lists, to reduce the indentation level and remove two additional lines ```nix @@ -986,20 +971,16 @@ else # content } ]; ``` -- Be a bit less eager about expanding lists and attribute sets (for example by allowing up to n elements on a single line). - ```nix - [ x y ] - ``` ### Bindings Let bindings and attribute sets share the same syntax for their items, which is discussed here together. -**Description** - Bindings have the most special cases to accommodate for many common Nixpkgs idioms. Generally, the following styles exist, which are used depending on the kind and size of the value: +TODO: This entire section doesn't have any real specification and is rather unclear on details + ```nix #1 single line foo = "bar"; @@ -1051,7 +1032,7 @@ outputs = Notable special cases are: - Single line values that would not benefit from style #2 keep using #1, even if this makes it go above the line limit. This mostly applies to simple strings and paths. -- Attribute set values are *always* expanded. This has the consequence of always forcing nested attribute sets to be multiline (even if they would be single line otherwise because they only contain a single item), which usually is desired. +- Attribute set values must always be expanded. This has the consequence of always forcing nested attribute sets to be multiline (even if they would be single line otherwise because they only contain a single item), which usually is desired. ```nix { foo.bar.baz = "qux"; @@ -1082,9 +1063,7 @@ some.very.long.attr = callFunction #### Bindings semicolon placement -**Description** - -The semicolon is always placed on the same line as the expression it concludes. +The semicolon in bindings must always be placed on the same line as the expression it concludes. **Examples** @@ -1128,10 +1107,9 @@ The semicolon is always placed on the same line as the expression it concludes. } ``` -**Rationale and alternatives** +**Alternatives** -There are four considered semicolon styles: 1. On a new line without indentation. - This clearly marks a separation between attributes, however it is wasteful of space. ```nix @@ -1185,10 +1163,8 @@ There are four considered semicolon styles: ### inherit -**Description** - -- The items are either all on the same line, or all on a new line each (with indentation). -- The semicolon is on its own line with indentation. +The items must either be all on the same line, or all on a new line each (with indentation), +in which case the semicolon must be on its own line with indentation. **Examples** @@ -1203,11 +1179,16 @@ inherit #### inherit from -**Description** -- If the inherit source is single-line, it is placed on the same line as the `inherit`, even if the following items do not fit onto one line. -- Otherwise, it starts on a new line with indentation, like the others. - - In that case, the remaining items are force-expanded too, even if they would have fit onto one line in the first place. +For a fragment like this: +``` +inherit () ... ; +``` + +- If the entire fragment fits in the first line, it must be formatted as such. +- Otherwise if only `inherit ()` fits into the first line, it must be formatted as such, + with the same style as the normal `inherit` for the attributes. +- Otherwise the `()` must also be on its own line. **Examples** From b42842df5b721af0467cff461bf4c13beacb7fdd Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 9 Jan 2024 21:34:22 +0100 Subject: [PATCH 19/39] Address TODOs and rework with/assert --- rfcs/0166-nix-formatting.md | 120 ++++++++++++++++++++++++------------ 1 file changed, 82 insertions(+), 38 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 3a5098c98..7bed8d865 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -530,12 +530,12 @@ function } ``` - This violates the guideline of the indentation representing the expression structure, and thus reduces readability. - - This does not work well with line length limits on short arguments (TODO: What does this mean?) ### Function declaration - The body of the function must not be indented relative to its first arguments. -- Multiple ("simple") identifier arguments are written onto the same line if possible. TODO: What if it's not possible? +- Multiple ("simple") identifier arguments must be written onto the same line if admitted from on the line length limit. + - Otherwise they're each on their own line. - Attribute set arguments must always start on a new line and they must not be mixed with identifier arguments. - If they have few attributes, the argument may be written on a single line - Otherwise each attribute must be on its own line with indentation, followed by a trailing comma. @@ -572,6 +572,14 @@ name: value: { # body } + +#6: These would be over the line length limit on a single line +aaaa: +bbbb: +cccc: +dddd: +eeee: +null ``` **Alternatives** @@ -755,36 +763,86 @@ else else go (dirOf path); ``` -### with, assert +### assert -- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, and the `with attrs;`/`assert cond;` does _not_ start on a new line (e.g. `foo = with; …`), then the body must start on that same line too. - TODO: What does it mean for it to "not start on a new line"? This really depends on what the surrounding expression is. Notably bindings yes, anything else? -- Otherwise, the body of `with attrs;`/`assert cond;` must start on a new line without any additional indentation. +- `assert`s must always start on their own line and the body also starts on its own line without any additional indentation. ```nix +# Good +assert foo; +[ + bar + baz +] + +# Bad +assert foo; [ + bar + baz +] + +# Good { + vendor ? + assert false; + null, + + vendor ? null, +}: +null + +let # Good - foo = - assert foo == bar; - with bar; - [ - # multiline - baz - ] + x = + assert foo; + bar; + + # Bad + y = assert foo; + bar; +in +x +``` + +**Alternatives** +- Treat it the [same as `with`](#with). The reasons not to do that: + - `assert`'s stand on their own and could be removed without breaking anything. Comparatively, `with`'s can't be removed without breaking the code + - `assert`'s are a bit like `if-then-else` statements, which are also spread out over multiple lines + +### with + +- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, then the body must start on that same line too. + - Otherwise, the body of `with attrs;` must start on a new line without any additional indentation. +- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''` + and `with attrs; …` is parenthesised or to the right side of a binding (e.g. `(with; [ …` or `foo = with; [ …`), + then `with` must start on the same line. + - Otherwise it must start on a new line. + +**Examples** +```nix +{ # Good foo = with bar; [ # multiline baz ]; + # Good + foo = + with foo; + with bar; [ + # multiline + baz + ]; + # Good foo = with bar; baz foo { # multiline qux = 10; - } + }; # Good foo = @@ -813,30 +871,16 @@ else # multiline baz ]; -} -``` - -**Examples** - -```nix -with pkgs; -assert foo == bar; -{ - meta.maintainers = with lib.maintainers; [ - some - people - ]; -} - -with pkgs; -assert foo == bar; -{ - meta.maintainers = - with lib.maintainers; - [ - some - people - ]; + + # Good + [ + qux + quux + ] + ++ (with pkgs; [ + baz + blorp + ]); } ``` From e94e1e3d4c3368c4c4aead1c9fde7a6e1c53197f Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 9 Jan 2024 22:17:44 +0100 Subject: [PATCH 20/39] Minor adjustments --- rfcs/0166-nix-formatting.md | 28 +++++++++++++++++++++------- 1 file changed, 21 insertions(+), 7 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 7bed8d865..a4fbb0452 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -136,7 +136,8 @@ The Nix formatter team is responsible for this task. In order to minimize conflicts especially when back-porting, the pinned formatter should preferably only be updated shortly before the release branch-off. -This should be done in coordination with the NixOS release managers. +This should be done in coordination with the NixOS release managers, +so this information must be added to the [NixOS release wiki](https://nixos.github.io/release-wiki/). #### Automatically generated files @@ -245,8 +246,6 @@ In this case one level of indentation can be saved using [`lib.singleton`](https ## Unresolved questions -- Should the line length limit be specified? - ## Future work - General style guidelines beyond AST reformatting @@ -295,7 +294,7 @@ Terms and definitions: - This applies to else-if chains, functions with multiple arguments, some operators, etc. - Example: ```nix - # This is treated as a sequence of if-then-elsa's chains + # This is treated as a sequence of if-then-else's chains if cond1 then foo else if cond2 then @@ -332,7 +331,7 @@ Terms and definitions: This [editor config](https://editorconfig.org/) specifies the basic details about Nix files: -```toml +```editorconfig end_of_line = lf insert_final_newline = true trim_trailing_whitespace = true @@ -347,7 +346,7 @@ For any two (sub-)expressions that are fully on a common single line, their smal **Example** ```nix -# Bad, expressions cond and bar are fully on the same line, +# Bad, expressions cond and foo are fully on the same line, # but their smallest common ancestor expression is the entire if-then-else, which spans multiple lines if cond then foo else bar @@ -516,7 +515,6 @@ function **Alternatives** -- Not indenting the arguments, to save some indentation depth. This would be consistent with other constructs like function declarations and let bindings. - Compacting multiline arguments like this: ```nix function arg1 { @@ -580,6 +578,9 @@ cccc: dddd: eeee: null + +#7: @ patterns can also come afterwards +{ pkgs }@args: pkgs.hello ``` **Alternatives** @@ -904,6 +905,19 @@ in **Examples** ```nix +let + foo = "bar"; +in +func foo; + +let + foo = "bar"; +in +{ + inherit foo; + baz = "smth"; +} + let foo = "bar"; in From 4f99905ed2b4af7360afa4cd4046c74a68396afa Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 23 Jan 2024 18:45:11 +0100 Subject: [PATCH 21/39] Mention formatting Nix code in documentation --- rfcs/0166-nix-formatting.md | 8 ++++++-- 1 file changed, 6 insertions(+), 2 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index a4fbb0452..f7062e983 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -125,8 +125,8 @@ The Nix formatter team should be consulted before the Nix language syntax is cha ### Reformat Nixpkgs For formatting Nixpkgs itself, a pinned release version of the official Nix formatter must be used. -CI must generally enforce all files in Nixpkgs to be formatted with this version at all times. -Automatically generated files may be handled differently, see [the next section](#automatically-generated-files). +CI must generally enforce all Nix files in Nixpkgs to be formatted with this version at all times. +Automatically generated files may be handled differently, see [this sub-section](#automatically-generated-files). For every bump of the pinned formatter, the files of Nixpkgs must thus be re-formatted accordingly. @@ -139,6 +139,10 @@ the pinned formatter should preferably only be updated shortly before the releas This should be done in coordination with the NixOS release managers, so this information must be added to the [NixOS release wiki](https://nixos.github.io/release-wiki/). +#### Nix code in documentation + +Nix code in Nixpkgs documentation, such as the Nixpkgs manual, the NixOS manual, NixOS options, `CONTRIBUTING.md` and co. should also be formatted with the pinned release version of the official Nix formatter. + #### Automatically generated files There are automatically generated files in Nixpkgs, with a potentially different format. From 6b430d7f7efd04e454c54be215ef8c7195695f36 Mon Sep 17 00:00:00 2001 From: piegames Date: Tue, 6 Feb 2024 21:21:28 +0100 Subject: [PATCH 22/39] Working towards finalization (#16) - Defined absorption and absorbable terms - Adapted the existing RFC text to make use of these definitions, resulting in simplications of the text in many cases. - Updated `with` section to match the implementation - Updated the function declaration section to match the implementation - Sometimes, the function body may get absorbed - This used to be a special case scoped to bindings only, so it got removed there - Updated the operators section to match the implementation - Specify the format of non-chainable operators (somehow those got lost in the past) - Reworked bindings section. It should now be clear and specific enough. - Minor wording fixes --- rfcs/0166-nix-formatting.md | 238 ++++++++++++++++++++++++------------ 1 file changed, 160 insertions(+), 78 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index f7062e983..ecc5b08ec 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -38,7 +38,7 @@ The goals of this RFC are: Non-goals of this RFC: -- Code style aspects that are not purely syntactic (e.g. optional/redundant parentheses, adding `inherit` statements, swapping argument order with `flip`, …) +- Code style aspects that are not purely syntactic (e.g. optional/redundant parentheses, adding `inherit` statements, swapping argument order with `flip`, ...) - Nixpkgs-specific tweaks to the format (e.g. using attribute names and other context for heuristics about how to best format the contents) - Extended Nixpkgs-specific linting like nixpkgs-hammering - Formatting non-Nix files in Nixpkgs (that's for [treefmt](https://github.com/numtide/treefmt)) @@ -258,14 +258,65 @@ In this case one level of indentation can be saved using [`lib.singleton`](https ----- -## Initial standard Nix format +## Terms and definitions: + +- **Brackets:** `[]` +- **Braces:** `{}` +- **Parentheses**: `()` +- **Expressions:** + All syntax nodes that would be a syntactically correct Nix program on their own. +- **Terms:** The follwoing expressions are called terms + - Variables, int, float, string, path, list, set, selection, all parenthesised expressions + - As a rule of thumb: Expressions which can be used as list items (without parentheses) +- **Absorption:** + A multiline expression can have an alternative layout depending on the context. + In that case, it will start on the end of the current line instead of a new line, + potentially saving a level of indentation of its content. + ```nix + { + # The right-hand side of bindings is an example of a situation where absorption improves the style. + absorbed = with bar; [ + 1 + 2 + 3 + ]; + notAbsorbed = + with bar; # Placing a comment here will force the non-absorbed, multiline layout. + [ + 1 + 2 + 3 + ]; -Terms and definitions: -- Brackets: `[]` -- Braces: `{}` -- Parentheses: `()` + # In this case, absorption does not reduce the indentation level of the set. + absorbed' = + let + qux = 1; + in + # { is absorbed + bar: baz: { + # <-- same level + }; + + notAbsorbed' = + let + qux = 1; + in + way: + too: + many: + arguments: + { + # <-- same level + }; + } + ``` +- **Absorbable Terms:** + Attribute sets, lists, and multiline `''` strings are called absorbable terms. Parenthesized absorbable terms are absorbable terms again too. + +## Initial standard Nix format -- Line breaks may be added or removed, but empty lines must not be created. Single empty lines must be preserved, and consecutive empty lines must be turned into a single empty line. +- Line breaks may be added or removed, but empty lines must not be created. Single empty lines must be preserved, and consecutive empty lines must be collapsed into a single empty line. This allows the formatter to expand or compact multi-line expressions, while still allowing grouping of code. For example, formatting this code: @@ -298,7 +349,7 @@ Terms and definitions: - This applies to else-if chains, functions with multiple arguments, some operators, etc. - Example: ```nix - # This is treated as a sequence of if-then-else's chains + # This is treated as a sequence of if-then-else chains, instead of indenting the second if as part of the else body if cond1 then foo else if cond2 then @@ -472,7 +523,7 @@ For list elements, attributes, and function arguments, the following applies: - In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". - As many arguments as possible must be fit onto the first line. - - If all but the last argument do fit, then the last argument may also start on the first line. + - If all but the last argument do fit, then the last argument may get absorbed, i.e. also start on the first line. - If an earlier argument does not fit onto the first line, then that argument and all the following ones must start on their own line. - All arguments that are not on the same line as the function must be indented by one level. @@ -526,9 +577,9 @@ function } arg3 function { - # … + # ... } { - # … + # ... } ``` - This violates the guideline of the indentation representing the expression structure, and thus reduces readability. @@ -536,11 +587,13 @@ function ### Function declaration - The body of the function must not be indented relative to its first arguments. -- Multiple ("simple") identifier arguments must be written onto the same line if admitted from on the line length limit. +- A small number of ("simple") identifier arguments can be written onto the same line. - Otherwise they're each on their own line. + - The body may get absorbed here - Attribute set arguments must always start on a new line and they must not be mixed with identifier arguments. - If they have few attributes, the argument may be written on a single line - Otherwise each attribute must be on its own line with indentation, followed by a trailing comma. +- Due to structural similarity and for consistency reasons, attribute set arguments with a default value follow the same rules as [bindings](#bindings). **Examples** @@ -548,16 +601,21 @@ function #1 name: value: name ++ value -#2 -name: value: -{ - "${name}-foo" = value; -} +#2 absorption +name: value: '' + ${name} = ${value}; +'' #3 -{ pkgs }: pkgs.hello +name: value: +name +++ value +++ more stuff making the line too long #4 +{ pkgs }: pkgs.hello + +#5 args@{ some, argument, @@ -568,14 +626,14 @@ args@{ # body } -#5 +#6 { pkgs }: name: value: { # body } -#6: These would be over the line length limit on a single line +#7: These would be over the line length limit on a single line aaaa: bbbb: cccc: @@ -583,7 +641,7 @@ dddd: eeee: null -#7: @ patterns can also come afterwards +#8: @ patterns can also come afterwards { pkgs }@args: pkgs.hello ``` @@ -608,7 +666,7 @@ null default ? value , ... }: - # … + # ... ``` Problems with this alternative: @@ -620,11 +678,42 @@ null ### Operators -Chained binary associative [operators](https://nixos.org/manual/nix/stable/language/operators.html#operators) (except [function application](#function-application)) with the same or monotonically decreasing precedence must be treated together as a single operator chain. +From the [list of operators](https://nixos.org/manual/nix/stable/language/operators.html#operators), this section focuses on binary operators. +Function application and attribute selection are not treated as an "operator" in the sense of this section, see [function application](#function-application) instead. + +#### Non-chainable operators + +Operators with no associativity are non-chainable. +Each invokation will always have exactly one left-hand side and one right-hand side. + +The right-hand side must always be attached to the operator on the same line. +The operator must either be attached to the left-hand side as well, or start on a new line. + +```nix +shortVariable == 42 + +stringLength (drvName (toString oldDependency)) +== stringLength (drvName (toString newDependency)) + +some complicated calculation { + # arguments +} == other stuff { + # which may be multiline +} + +some complicated calculation { + # arguments +} +== "some very long string" +``` + +#### Chainable operators + +Chained binary associative [operators](https://nixos.org/manual/nix/stable/language/operators.html#operators) with the same or monotonically decreasing precedence must be treated together as a single operator chain. If an operator chain does not fit onto one line, it must be expanded such that every operator starts a new line: - If the operand can also fit on the same line as the operator, it must be put there -- Otherwise, the operand must start indented on a new line, with exceptions for parenthesis, brackets, braces and function applications +- Otherwise, the operand must either be absorbed or start a new line with indentation Operator chains in bindings may be compacted as long as all lines between the first and last one are indented. @@ -649,15 +738,15 @@ foo some flags ] -++ ( # <- The operator is on a new line, but parenthesis/brackets/braces can start on the same line +++ ( # <- Parenthesized expressions get absorbed foo ) -++ optionals condition [ # <- As are multiline function applications +++ optionals condition [ # <- As are some multiline function applications more items ] ++ - runCommand name # <- ... but only for functions whose last argument starts on the same line + runCommand name # <- Function application which cannot be absorbed start on a new line with indentation '' echo hi '' @@ -699,7 +788,7 @@ foo ### if-then-else -- `if` and `else` keywords must always start a line. +- `if` and `else` keywords must always start on a new line. - The `if` and `else` bodies must always be indented. - If the condition does not fit onto one line, then it will start on the next line with indentation, and `then` will be on the start of the line following the condition. - `else if` chains are treated as one long sequence, with no indentation creep on each step. @@ -733,7 +822,7 @@ else **Alternatives** -- Attribute sets and lists could start on the same line as the `if` keywords, saving an indentation level on their body: +- The bodies could be absorbed in some cases, saving an indentation level: ```nix #1a if builtins.length matches != 0 then { @@ -816,12 +905,8 @@ x ### with -- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''`, then the body must start on that same line too. - - Otherwise, the body of `with attrs;` must start on a new line without any additional indentation. -- If the body is `{ ... }`, `[ ... ]`, `( ... )` or `'' ... ''` - and `with attrs; …` is parenthesised or to the right side of a binding (e.g. `(with; [ …` or `foo = with; [ …`), - then `with` must start on the same line. - - Otherwise it must start on a new line. +- In any situation where a term would get absorbed, the term with a `with` prepended to it may get absorbed as well. +- Otherwise, the body of `with attrs;` must start on a new line without any additional indentation. **Examples** @@ -836,7 +921,8 @@ x # Good foo = with foo; - with bar; [ + with bar; + [ # multiline baz ]; @@ -933,7 +1019,7 @@ else **Alternatives** -- To allow having the `` be on the same line as the `in`: +- To allow having the `` be absorbed after the `in`: ``` let = ; @@ -1036,59 +1122,37 @@ else ### Bindings -Let bindings and attribute sets share the same syntax for their items, which is discussed here together. +Let bindings, attribute sets and default function arguments share the same syntax for their items, which is discussed here together. + +Within bindings, if the first and last line are not indented, the absorbed style is used, otherwise newline and indent Bindings have the most special cases to accommodate for many common Nixpkgs idioms. Generally, the following styles exist, which are used depending on the kind and size of the value: -TODO: This entire section doesn't have any real specification and is rather unclear on details - ```nix -#1 single line +#1 The entire binding fits onto a single line foo = "bar"; -#2 single line, on a new line +#2 The body fits onto a single line, but the binding is too long +length limit very.long.foo = function arg1 arg2 arg3; -#3 multi line, starting on the same line +#3 Where possible, the body should be absorbed foo = function { # args }; +add = x: y: { + result = x + y; +}; -#4 multi line, starting on a new line +#4 If neither single-line nor absorbable, start on a new line with indentation foo = function arg1 arg2 arg3; -#5 simple function arguments (<=2) start on the same line -add = x: y: { - result = x + y; -}; - -#6 attribute bindings always start on a new line -# If we add more attributes, the indentation stays the same, see #7 -split = - { x, ... }: - { - inc = x + 1; - dec = x - 1; - }; - -#7 with enough attribute bindings, they will start on a new line and become multline -# it is common to expand input arguments in a way that does not change the number of function applications necessary -outputs = - { - x, - y, - z, - ... - }: - { - result = x + y; - }; ``` Notable special cases are: @@ -1103,18 +1167,27 @@ Notable special cases are: }; } ``` -- "statement-like" expressions like "let", "if" and "assert" always use #4 (or #1). -- If the value is a `with` followed by a function application or list or attribute set, try to use #3. +- As described in the [`with` section](#with), `with` expressions of absorbable terms should be treated the same way as absorbable terms. + - This means that the attribute set force-expansion also applies to them here. + - This also means that (multi-line) `with` expressions will use style #3 or #4, depending on their body. ```nix - buildInputs = with pkgs; [ - some - dependencies - ]; + # Force-expand short attrset + meta = with lib; { + maintainers = []; + }; + # Don't absorb since the body of `with pkgs;` is `with pyPkgs; ...`, which is not absorbable. + buildInputs = + with pkgs; + with pyPkgs; + [ + some + dependencies + ]; ``` **Alternatives** -One could eliminate style #2 by having #4 always start on the first line. This would even reduce indentation in some cases. However, this may look really weird in other cases, especially when the binding is very long: +Function calls could always be absorbed. This would reduce indentation of their arguments in some cases. However, this may look really weird in other cases, especially when the binding is very long: ```nix some.very.long.attr = callFunction @@ -1123,6 +1196,15 @@ some.very.long.attr = callFunction arg3; ``` +Consistent with this would be to also absorb `let` bindings and other expressions, however this might result in double indentation. + +```nix +suff = let + foo = "bar"; # <-- double-indentation + in + foo; +``` + #### Bindings semicolon placement The semicolon in bindings must always be placed on the same line as the expression it concludes. @@ -1259,7 +1341,7 @@ inherit (pkgs) ap1 ap2 ap3; inherit (pkgs) app1 app2 - # … + # ... app42 ; inherit From 8cb46fd96dc650b81b28f0d28f08805458d27951 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 6 Feb 2024 22:05:03 +0100 Subject: [PATCH 23/39] String section --- rfcs/0166-nix-formatting.md | 60 +++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index ecc5b08ec..ba9756abb 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -519,6 +519,66 @@ For list elements, attributes, and function arguments, the following applies: } ``` +### Strings + +- The kind of quotes used in strings (`"` vs `''`) must be preserved from the input. +- The non-interpolated string parts must be preserved from the input + - E.g. changing `\t` to a tab character must not be done automatically + +**Examples:** +```nix +# Kept as is +"foo \n\t ${bar} baz" +# This one too +'' + foo \n\t ${bar} baz +'' +``` + +#### Interpolations + +- "Simple" interpolations must be rendered using the single-line format, regardless of the line's length. + - Otherwise, the multiline formatting must be used + - "simple" is implementation-defined and generally includes short expressions of low complexity. + Multiline expressions are never "simple". +- If the interpolation is the first thing on the string line, then its contents may be absorbed. + - Otherwise, the interpolation code must start on a new line + +**Examples**: +```nix +# Short and simple +"foo \n\t ${bar} baz" + +# Interpolation of simple or short code +# Good +throw ''Some very long error messages containing ${variables} and stuff'' +# Bad +throw ''Some very long error messages containing ${ + variables +} and stuff'' + +'' + # Don't absorb interpolations if they don't start the line + # Good + some longer line ${ + some function [ + 1 + 2 + ] + } baz + # Bad + some longer line ${some function [ + 1 + 2 + ]} baz + + # However, absorption is allowed here, since the interpolation starts a line + ${other function ( + # with stuff + )} +'' +``` + ### Function application - In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". From 8d3cd5b769772e1e4cf7139166fe61809dbad1d2 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 6 Feb 2024 22:22:14 +0100 Subject: [PATCH 24/39] Specify assert conditions --- rfcs/0166-nix-formatting.md | 17 ++++++++++++++++- 1 file changed, 16 insertions(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index ba9756abb..0fcb19493 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -919,7 +919,8 @@ else ### assert -- `assert`s must always start on their own line and the body also starts on its own line without any additional indentation. +- `assert ;` mirrors the formatting for [bindings](#bindings). +- `assert`s `` must always start on their own line and the body also starts on its own line without any additional indentation. ```nix # Good @@ -956,6 +957,20 @@ let bar; in x + +# Multiline condition +assert + let + x = true; + in x; + true + +# Function call condition with absorbed last argument, same formatting as bindings +assert assertMsg (isPath path) '' + lib.path.append: + The first argument is of type ${builtins.typeOf path}, but a path was expected +''; +true ``` **Alternatives** From 1e83c6db2a4ae73061924ac7f3efeb58809f3957 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 6 Feb 2024 22:43:47 +0100 Subject: [PATCH 25/39] More absorption for multi-line arguments --- rfcs/0166-nix-formatting.md | 32 ++++++++++++++++++++++++++------ 1 file changed, 26 insertions(+), 6 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 0fcb19493..4e1f1715b 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -265,7 +265,7 @@ In this case one level of indentation can be saved using [`lib.singleton`](https - **Parentheses**: `()` - **Expressions:** All syntax nodes that would be a syntactically correct Nix program on their own. -- **Terms:** The follwoing expressions are called terms +- **Terms:** The follwoing expressions are called terms - Variables, int, float, string, path, list, set, selection, all parenthesised expressions - As a rule of thumb: Expressions which can be used as list items (without parentheses) - **Absorption:** @@ -581,10 +581,11 @@ throw ''Some very long error messages containing ${ ### Function application -- In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". +In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". + - As many arguments as possible must be fit onto the first line. - - If all but the last argument do fit, then the last argument may get absorbed, i.e. also start on the first line. - - If an earlier argument does not fit onto the first line, then that argument and all the following ones must start on their own line. +- If there is at most one multi-line argument that can be absorbed and all other arguments before/after fit onto a single line respectively, then that multi-line argument is absorbed. +- Otherwise, the first argument not fitting onto the first line will start a new line with indentation, and all subsequent arguments will start on their own line as well. - All arguments that are not on the same line as the function must be indented by one level. **Examples:** @@ -606,13 +607,21 @@ function arg1 arg2 { # The second argument doesn't fit on the first line, but it's not the last argument, # so it needs to start on a new line -function arg1 arg2 +function arg1 { + more = "things"; +} arg3 + +# In this case, the remaining arguments after the second one woulnd't fit onto the line anymore, therefore start all of them on a new line +function arg1 { more = "things"; } arg3 + many + long + args -# Same with more multiline arguments +# Same with multiple multiline arguments function { a = 1; @@ -622,6 +631,17 @@ function c = 1; d = 2; } + +# Assume that the line lenght limit is here ↓ +# Good +concatMapString (s: "short string: ${s}") ( + attrsToList foo +) + +# Bad: The first argument would have fit onto the first line +concatMapString ( + s: "short string: ${s}" +) (attrsToList foo) ``` **Drawbacks** From 2c90b3071264fd1b22c24834f31b1cdcbc8f5a78 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 6 Feb 2024 23:00:03 +0100 Subject: [PATCH 26/39] How to update the standard format --- rfcs/0166-nix-formatting.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 4e1f1715b..c0d803c1b 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -87,7 +87,8 @@ The initial version of the standard Nix format is defined in a section towards t [Initial standard Nix format](#initial-standard-nix-format). -Significant changes to the standard Nix format must go through another RFC. +Controversial changes to the standard Nix format must go through another RFC. +It is up to the Nix formatter team to decide when an RFC is necessary. The latest version of the standard Nix format must be in a file on the main branch of the [official Nix formatter](#official-nix-formatter). From 1e5914d2a214f5b3bf1e3a1279fd683cb7b18c2b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Janne=20He=C3=9F?= Date: Wed, 14 Feb 2024 10:55:57 +0100 Subject: [PATCH 27/39] Fix minor typos --- rfcs/0166-nix-formatting.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index c0d803c1b..a36e309f1 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -266,7 +266,7 @@ In this case one level of indentation can be saved using [`lib.singleton`](https - **Parentheses**: `()` - **Expressions:** All syntax nodes that would be a syntactically correct Nix program on their own. -- **Terms:** The follwoing expressions are called terms +- **Terms:** The following expressions are called terms - Variables, int, float, string, path, list, set, selection, all parenthesised expressions - As a rule of thumb: Expressions which can be used as list items (without parentheses) - **Absorption:** @@ -633,7 +633,7 @@ function d = 2; } -# Assume that the line lenght limit is here ↓ +# Assume that the line length limit is here ↓ # Good concatMapString (s: "short string: ${s}") ( attrsToList foo @@ -765,7 +765,7 @@ Function application and attribute selection are not treated as an "operator" in #### Non-chainable operators Operators with no associativity are non-chainable. -Each invokation will always have exactly one left-hand side and one right-hand side. +Each invocation will always have exactly one left-hand side and one right-hand side. The right-hand side must always be attached to the operator on the same line. The operator must either be attached to the left-hand side as well, or start on a new line. From c617b9f26d7c9f6201e04d91cf2ad0f47427d854 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 20 Feb 2024 20:59:53 +0100 Subject: [PATCH 28/39] Less lines for common function call patterns --- rfcs/0166-nix-formatting.md | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index a36e309f1..269a6cda5 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -588,6 +588,10 @@ In a function application chain, the first element is treated as the "function" - If there is at most one multi-line argument that can be absorbed and all other arguments before/after fit onto a single line respectively, then that multi-line argument is absorbed. - Otherwise, the first argument not fitting onto the first line will start a new line with indentation, and all subsequent arguments will start on their own line as well. - All arguments that are not on the same line as the function must be indented by one level. +- If the last argument is parenthesized, the parentheses get absorbed while its body is put on a new line with indentation. + - Exception: If the last argument is parenthesized and its body contains an absorbable term, an alternative and more compact layout may be used instead: The body gets compacted and its term absorbed. + - In this case, the inner term may be force-expanded. + - This results in less indentation for many common Nix idioms. **Examples:** @@ -643,6 +647,19 @@ concatMapString (s: "short string: ${s}") ( concatMapString ( s: "short string: ${s}" ) (attrsToList foo) + +# Good: The body of the last argument starts on a new line with indentation +pkgs.nixosTest ( + { pkgs }: + { + config = { }; + } +) + +# Good: The last argument is parenthesised and contains a function declaration, the exception makes this have less lines +stdenv.mkDerivation (finalAttrs: { + name = "..."; +}) ``` **Drawbacks** From 6b2f19aea5d53b17390131bc9b723d8ed7a941d5 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 20 Feb 2024 22:34:09 +0100 Subject: [PATCH 29/39] Specify comments --- rfcs/0166-nix-formatting.md | 145 ++++++++++++++++++++++++++++++++++++ 1 file changed, 145 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 269a6cda5..2011f7b1e 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -534,6 +534,11 @@ For list elements, attributes, and function arguments, the following applies: '' foo \n\t ${bar} baz '' + +# Even if strings exceed the line length limit, no attempt to make it smaller is made +'' + This is a really long string that would not fit within the line length limit +'' ``` #### Interpolations @@ -580,6 +585,146 @@ throw ''Some very long error messages containing ${ '' ``` +### Comments + +- `/**` comments must be handled according to [RFC 0145: Doc comments](https://github.com/NixOS/rfcs/pull/145). + - Specifically, the expression that the comment is attached to must be maintained by the formatter, as well as the resulting doc string. +- Empty comments may be deleted. + - Often their only purpose is to vertically align lines, which is not allowed. +- Single-line `/*` comments must be converted to `#` comments. +- Single-line comments may be moved up or down a line to improve the layout. +- Anything after the first `#` of single-line comments must be preserved. + - This allows the common pattern of prefixing many lines with `#` to comment them out, without the formatter trying to change anything. +- For multiline `/*` and `/**` comments: + - Both `/*`/`/**` and `*/` start on a new line each, and are vertically aligned (i.e. have the same level of indentation). + - The left-most line in between have one extra level of indentation (relative to the starting `/*`/`/**`). + - Inner-comment indentation is preserved, in a similar way as for multiline strings. + - Whitespace immediately after `/*`/`/**` and whitespace before `*/` may not be preserved. + - Content after `/*`/`/**` on the same line may get shifted the next line. + - Comments where all intermittent lines start with a `*` may have it stripped. + - Otherwise, the non-whitespace content of each comment line must be preserved. + +**Examples:** + +Note that these examples show *allowed* transformations, which may or may not be applied by the formatter. + +```nix +/* foo */ +↓ +# foo + +/*bar */ +# bar + +function call ( # trailing comment + body +) +↓ +function call ( + # trailing comment + body +) + +if /* inline comment */ cond then + true +else + false +↓ +# inline comment +if cond then + true +else + false + +if cond /* inline comment */ then + true +then + false +↓ +if + cond # inline comment +then + true +else + false + +/* foo */ '' + bar +'' +↓ +# foo +'' + bar +'' + +/* Foo + bar + baz */ +↓ +/* + Foo + bar + baz +*/ + +/* Foo + bar + baz + +*/ +↓ +/* + Foo + bar + baz +*/ + +/* Foo + * bar + */ +↓ +/* + Foo + bar +*/ + +# Some comment +# Some preserved indentation +#This also stays as is +``` + +**Alternatives:** +- There are some ways of using multi-line comments to comment parts of strings that wouldn't otherwise support comments. + For example in bash + ```bash + some-command \ # Some comment + some-arg \ # Some comment + another-arg + ``` + is not valid. + In Nix we have the ability to use string concatenation and inline comments to add comments between the arguments: + ```nix + '' + some-command \ + '' + /* Some comment */ '' + some-arg \ + '' + /* Some comment */ '' + another-arg + '' + ``` + + This style of the `+` operator for one isn't consistent with the rest of the formatting rules. + + Alternatively: + ```nix + some-command \ ${""/* Some comment */} + some-arg \ ${"" /* Some comment */} + another-arg + ``` + + But this is considered too hacky. + + ### Function application In a function application chain, the first element is treated as the "function" and the remaining ones as "arguments". From 463a858e57e4d68f4bfb1d38f20d8ac852ac4574 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Tue, 20 Feb 2024 23:44:32 +0100 Subject: [PATCH 30/39] Specify that the formatter should be as pure as possible With some exceptions --- rfcs/0166-nix-formatting.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 2011f7b1e..4e1fa9652 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -317,6 +317,8 @@ In this case one level of indentation can be saved using [`lib.singleton`](https ## Initial standard Nix format +- The formatter should be as "pure" as possible, i.e. different input formats of the "same" code (same AST with comments) should result in the same output format. + - The formatter may take the input formatting into account in some cases in order to preserve multi-line syntax elements (which would otherwise have been contracted by the rules). - Line breaks may be added or removed, but empty lines must not be created. Single empty lines must be preserved, and consecutive empty lines must be collapsed into a single empty line. This allows the formatter to expand or compact multi-line expressions, while still allowing grouping of code. @@ -1312,9 +1314,9 @@ else - Brackets and braces must always have a space (or line break) on the inside, like `[ `, ` ]`, `{ ` and ` }`. - Empty lists and attribute sets are written as `[ ]` and `{ }`, respectively. -- Lists and attribute sets with multiple items should be liberally expanded. - - They can only be on a single line if they fit on the line and contain few enough elements. - - As described under [bindings](#bindings) below, nested attribute sets are always expanded. +- Lists and attribute sets can only be on a single line if they fit on the line and contain few enough items. +- Lists and attribute sets with more items should be liberally expanded. +- As described under [bindings](#bindings) below, nested attribute sets are always expanded. **Examples** From e92f5ab8da1704da9ff8903cbd84a8fbe2c314fa Mon Sep 17 00:00:00 2001 From: Linus Heckemann Date: Tue, 27 Feb 2024 19:26:17 +0100 Subject: [PATCH 31/39] nit: fix list concatenation example (#17) --- rfcs/0166-nix-formatting.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 4e1fa9652..e9bd213a1 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -457,7 +457,7 @@ This rule has turned out to be very practical at catching code that could be pot ```nix buildInputs = [ foo # <-- Bad, indentation increases by 2 levels - ] // lib.optionals cond [ + ] ++ lib.optionals cond [ bar ]; From 6e63b6b617e486655560713b92347481158248a3 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 19:23:34 +0100 Subject: [PATCH 32/39] Update rfcs/0166-nix-formatting.md Co-authored-by: Doron Behar --- rfcs/0166-nix-formatting.md | 1 + 1 file changed, 1 insertion(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index e9bd213a1..28fcebc8d 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -616,6 +616,7 @@ Note that these examples show *allowed* transformations, which may or may not be # foo /*bar */ +↓ # bar function call ( # trailing comment From dec17975ac771f18ba7085c0af387481436a7aac Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 20:07:04 +0100 Subject: [PATCH 33/39] Add good indentation examples (#18) --- rfcs/0166-nix-formatting.md | 35 ++++++++++++++++++++++++++++++----- 1 file changed, 30 insertions(+), 5 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 28fcebc8d..310001e65 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -455,30 +455,55 @@ This rule has turned out to be very practical at catching code that could be pot - Increasing indentation levels must not be "skipped": On subsequent lines, indentation can only increase by at most one level, but may decrease arbitrarily many levels. - Examples: ```nix + # Bad indentation buildInputs = [ - foo # <-- Bad, indentation increases by 2 levels + foo # <-- Not okay, increase by 2 levels ] ++ lib.optionals cond [ bar ]; + # Okay indentation, subsequent lines at most one more level + buildInputs = + [ + foo + ] ++ lib.optionals cond [ + bar + ]; + + # Bad indentation attribute = { args }: let - foo = "bar" # <-- Bad, indentation increases by 2 levels + foo = "bar"; # <-- Not okay, increase by 2 levels in foo; + # Okay indentation + attribute = { args }: + let + foo = "bar"; + in + foo; + + # Bad indentation (callFunction { - foo = "bar"; # <-- Bad, indentation increases by 2 levels + foo = "bar"; # <-- Not okay, increase by 2 levels + } + arg + ) + # Okay indentation + (callFunction + { + foo = "bar"; } arg ) - # This is okay, indentation increases only one level per line + # Okay indentation let x = { a = foo bar baz; - }; # <-- The decrease by two levels here is okay + }; # <-- The decrease by two levels here is okay, only increases are limited to one level in null ``` From 3a91c378bee4f275629a2a347fe25e4ac1b5d6c5 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 20:14:37 +0100 Subject: [PATCH 34/39] Add another chainable operators example --- rfcs/0166-nix-formatting.md | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 310001e65..1b92b629e 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -1055,6 +1055,32 @@ foo w = 40; }; } + +# Good +{ + postPatch = + '' + patchShebangs . + '' + + lib.optionalString withFrei0r '' + substituteInPlace libavfilter/vf_frei0r.c \ + --replace /usr/local/lib/frei0r-1 ${frei0r}/lib/frei0r-1 + substituteInPlace doc/filters.texi \ + --replace /usr/local/lib/frei0r-1 ${frei0r}/lib/frei0r-1 + ''; + + configureFlags = + [ + # * Program flags + (enableFeature buildFfmpeg "ffmpeg") + (enableFeature buildFfplay "ffplay") + (enableFeature buildFfprobe "ffprobe") + ] + ++ optionals withBin [ "--bindir=${placeholder "bin"}/bin" ] + ++ [ + # ... + ]; +} ``` ### if-then-else From f33b211ed60d0f12acad54bdfeecc0ca677a41fe Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 20:21:16 +0100 Subject: [PATCH 35/39] justify difference in semicolon placement --- rfcs/0166-nix-formatting.md | 3 +++ 1 file changed, 3 insertions(+) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 1b92b629e..058e71a0f 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -1621,6 +1621,9 @@ The semicolon in bindings must always be placed on the same line as the expressi The items must either be all on the same line, or all on a new line each (with indentation), in which case the semicolon must be on its own line with indentation. +- The semicolon placement seems inconsistent between bindings and `inherit`s: For bindings it's on the last line of the expression, while for `inherit`s it's on a new line. + + This is because it's much more common to change items in an `inherit` than other expressions. By placing the semicolon on a new line, items can easily be added and removed at the end. **Examples** From aa2141a9cad9a3e784c160913b042e3d27a15bbc Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 20:38:50 +0100 Subject: [PATCH 36/39] Allow different parenthesized argument style --- rfcs/0166-nix-formatting.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 058e71a0f..ab816bae2 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -761,7 +761,7 @@ In a function application chain, the first element is treated as the "function" - If there is at most one multi-line argument that can be absorbed and all other arguments before/after fit onto a single line respectively, then that multi-line argument is absorbed. - Otherwise, the first argument not fitting onto the first line will start a new line with indentation, and all subsequent arguments will start on their own line as well. - All arguments that are not on the same line as the function must be indented by one level. -- If the last argument is parenthesized, the parentheses get absorbed while its body is put on a new line with indentation. +- If the last argument is parenthesized, the parentheses should get absorbed while its body is put on a new line with indentation. - Exception: If the last argument is parenthesized and its body contains an absorbable term, an alternative and more compact layout may be used instead: The body gets compacted and its term absorbed. - In this case, the inner term may be force-expanded. - This results in less indentation for many common Nix idioms. @@ -815,6 +815,9 @@ function concatMapString (s: "short string: ${s}") ( attrsToList foo ) +# Good, this is also allowed +concatMapString (s: "short string: ${s}") + (attrsToList foo) # Bad: The first argument would have fit onto the first line concatMapString ( From 26b444b58db94baa2636d3b940a90768745e8692 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 21:00:29 +0100 Subject: [PATCH 37/39] Clarify non-vertical alignment rule --- rfcs/0166-nix-formatting.md | 41 ++++++++++++++++++++++++++++++++----- 1 file changed, 36 insertions(+), 5 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index ab816bae2..0508019f1 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -434,22 +434,53 @@ This rule has turned out to be very practical at catching code that could be pot - Two spaces must be used for each indentation level. - This may be revisited should Nix get proper support for [using tabs for indentation](https://github.com/NixOS/nix/issues/7834) in the future. -- Vertical alignment must be ignored, both at the start of the line and within lines. +- No special care is taken to preserve vertical alignment in the AST or comments. + - It is non-trivial to specify a rule for preserving vertical alignment, so this is out of scope for now, but could be reconsidered in the future. - Examples: ```nix { - # Bad, vertical alignment Within lines - linux = { execFormat = elf; families = { }; }; + # Vertically aligned input like this.. + foo = 10; # Foo + b = 10; # - b + baz = 10; # - baz + more = 10; # - more + + # ..will get formatted like this. + # The vertical alignment is not preserved. + foo = 10; # Foo + b = 10; # - b + baz = 10; # - baz + more = 10; # - more + + + # Vertically aligned input like this.. netbsd = { execFormat = elf; families = { inherit bsd; }; }; none = { execFormat = unknown; families = { }; }; - openbsd = { execFormat = elf; families = { inherit bsd; }; }; - # Bad, vertical alignment at the start of line + # ..will get formatted like this. + netbsd = { + execFormat = elf; + families = { + inherit bsd; + }; + }; + none = { + execFormat = unknown; + families = { }; + }; + + + # Vertically aligned input like this.. optExecFormat = lib.optionalString (kernel.name == "netbsd" && gnuNetBSDDefaultExecFormat cpu != kernel.execFormat ) kernel.execFormat.name; + + # ..will get formatted like this. + optExecFormat = lib.optionalString ( + kernel.name == "netbsd" && gnuNetBSDDefaultExecFormat cpu != kernel.execFormat + ) kernel.execFormat.name; } ``` - Increasing indentation levels must not be "skipped": On subsequent lines, indentation can only increase by at most one level, but may decrease arbitrarily many levels. From 685ee9bf80abdfaceffe1e423f9c0a0609b82890 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 21:10:35 +0100 Subject: [PATCH 38/39] Improved clarity of bindings rule --- rfcs/0166-nix-formatting.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 0508019f1..4bb906792 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -1470,7 +1470,7 @@ else Let bindings, attribute sets and default function arguments share the same syntax for their items, which is discussed here together. -Within bindings, if the first and last line are not indented, the absorbed style is used, otherwise newline and indent +For each binding value, if only the first and last line are not indented, the absorbed style is used, otherwise newline and indent. Bindings have the most special cases to accommodate for many common Nixpkgs idioms. Generally, the following styles exist, which are used depending on the kind and size of the value: @@ -1499,6 +1499,12 @@ foo = arg2 arg3; +# There is non-indented line between the first and last line, so this can't use the absorbed style +bar = + if baz == null then + 10 + else + 20; ``` Notable special cases are: From aaf1613f51abb97be149a5f429634a25277c2327 Mon Sep 17 00:00:00 2001 From: Silvan Mosberger Date: Mon, 4 Mar 2024 21:30:10 +0100 Subject: [PATCH 39/39] Improve bindings semicolon alternatives section --- rfcs/0166-nix-formatting.md | 70 +++++++++++++++++++++++++------------ 1 file changed, 48 insertions(+), 22 deletions(-) diff --git a/rfcs/0166-nix-formatting.md b/rfcs/0166-nix-formatting.md index 4bb906792..24ff61e27 100644 --- a/rfcs/0166-nix-formatting.md +++ b/rfcs/0166-nix-formatting.md @@ -1607,29 +1607,30 @@ The semicolon in bindings must always be placed on the same line as the expressi 1. On a new line without indentation. - - This clearly marks a separation between attributes, however it is wasteful of space. - ```nix - attr3 = - function call - many - arguments - ; - attr3 = - let - foo = "bar"; - in - some statements - ; - ``` + - This clearly marks a separation between attributes, however it is wasteful of space. + - The lonely semicolon looks odd, and it's not a commonly used style. + ```nix + attr3 = + function call + many + arguments + ; + attr3 = + let + foo = "bar"; + in + some statements + ; + ``` 2. On a new line with one indentation level. - - Just as wasteful on space as (1), but a bit less clear about signaling the end of the binding. - ```nix - attr3 = - function call - many - arguments - ; - ``` + - Just as wasteful on space as (1), but a bit less clear about signaling the end of the binding. + ```nix + attr3 = + function call + many + arguments + ; + ``` 3. A mix of (1) and (2), where usually the semicolon is placed directly at the end of the binding. But with exceptions in which the semicolon is placed onto the following line instead in cases where the value is a multiline `if` expression or nested operator. These are the only syntax elements that may result in the semicolon being placed on a line with arbitrarily deep indentation. @@ -1656,6 +1657,31 @@ The semicolon in bindings must always be placed on the same line as the expressi && cond3 ; ``` +4. Always wrapping multi-line expressions with parenthesis. + - The parenthesis help "ground" the bindings on the top-level and don't look anywhere near as odd as the lonely semicolon. + - However this is a style not commonly used. + + ```nix + { + attr3 = ( + function call + many + arguments + ); + attr3 = ( + let + foo = "bar"; + in + some statements + ); + attr3 = ( + if foo == "bar" then + function call + else + some statements + ); + } + ``` ### inherit