Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Clarify whitespace handling #46

Merged
merged 3 commits into from
Sep 23, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions conf.py
Original file line number Diff line number Diff line change
Expand Up @@ -21,8 +21,8 @@
copyright = '2019--2024, EditorConfig Team'
author = 'EditorConfig Team'

version = '0.17.1'
release = '0.17.1'
version = '0.17.2'
release = '0.17.2'

# -- General configuration ---------------------------------------------------

Expand Down
38 changes: 26 additions & 12 deletions index.rst
Original file line number Diff line number Diff line change
@@ -1,4 +1,4 @@
.. Copyright (c) 2019--2020 EditorConfig Team
.. Copyright (c) 2019--2024 EditorConfig Team
All rights reserved.

Redistribution and use in source and binary forms, with or without
Expand Down Expand Up @@ -73,25 +73,35 @@ EditorConfig organization.
File Format
===========

.. versionchanged:: 0.17.0
.. versionchanged:: 0.17.2

EditorConfig files are in an INI-like file format.
In an EditorConfig file, all beginning whitespace on each line is considered
irrelevant. Each line must be one of the following:
To read an EditorConfig file, take one line at a time, from beginning to end.
For each line:

#. Remove all leading and trailing whitespace.
#. Process the remaining text as specified for its type below.

The types of lines are:

- Blank: Contains nothing. Blank lines are ignored.

- Comment: starts with a ``;`` or a ``#``. Comment lines are ignored.

- Blank: contains only whitespace characters.
- Comment: starts with a ``;`` or a ``#``.
- Section Header: starts with a ``[`` and ends with a ``]``.
- May not use any non-whitespace characters outside of the surrounding
brackets.
These lines define globs; see :ref:`glob-expressions`.

- May contain any characters between the square brackets (e.g.,
``[`` and ``]`` and even spaces and tabs are allowed).
- Forward slashes (``/``) are used as path separators.
- Backslashes (``\\``) are not allowed as path separators (even on Windows).
- Key-Value Pair (or Pair): contains a key and a value, separated by an `=`.
- Key: The part before the first `=` (trimmed of whitespace, but including

- Key-Value Pair (or Pair): contains a key and a value, separated by an ``=``.
See :ref:`supported-pairs`.

- Key: The part before the first ``=`` (trimmed of whitespace, but including
any whitespace in the middle).
- Value: The part after the first `=` (trimmed of whitespace, but including
- Value: The part after the first ``=`` (trimmed of whitespace, but including
any whitespace in the middle).

Any line that is not one of the above is invalid.
Expand All @@ -117,7 +127,7 @@ This specification does not define any "escaping" mechanism for

.. admonition :: Compatibility

The EditorConfig file format formerly allowed the use of `;` and `#` after the
The EditorConfig file format formerly allowed the use of ``;`` and ``#`` after the
beginning of the line to mark the rest of a line as comment. This led to
confusion how to parse values containing those characters. Old EditorConfig
parsers may still allow inline comments.
Expand All @@ -133,6 +143,8 @@ The parts of an EditorConfig file are:
- Section: the lines starting from a Section Header until the beginning of
the next Section Header or the end of the file.

.. _glob-expressions:

Glob Expressions
================

Expand Down Expand Up @@ -194,6 +206,8 @@ precedence. If multiple EditorConfig files have matching sections, the rules
from the closer EditorConfig file are read last, so pairs in closer
files take precedence.

.. _supported-pairs:

Supported Pairs
===============

Expand Down