editorconfig / specification Goto Github PK
View Code? Open in Web Editor NEWSpecification of EditorConfig file format
Home Page: https://editorconfig-specification.readthedocs.io
License: BSD 2-Clause "Simplified" License
Specification of EditorConfig file format
Home Page: https://editorconfig-specification.readthedocs.io
License: BSD 2-Clause "Simplified" License
What are the plans with this repository. Obviously it will contain the official specifications for EditorConfig file.
But how will they be served to the audience?
Will it contain markdown file that are served as GitHub Pages in the main website like https://editorconfig.org/specification? This seems to me a very handy and logical addition to the website.
Or are there other plans?
The specification contains the following language:
Inserting a
#
or;
after non-whitespace characters in a line (i.e., inline) shall neither be parsed as a comment nor as part of the section name, pair (defined below) key or value in which it was inserted. This may change in the future; thus, is not recommended.
It also contains the following test inputs:
With the following tests:
This has led me to the following questions:
;
or #
character (dotnet/roslyn#44596), what is the supported mechanism?Per #41,
The format [of a
spelling_language
value] isss
orss-TT
.
I intended ss
to stand for exactly two characters and TT
to stand for exactly two characters. However, as @gustaphe commented in editorconfig/editorconfig-vim#210 (comment) , TT
could be read as a variable standing for any ISO 3166 code.
Update the specification to clarify that ss
represents exactly two characters and TT
represents exactly the two characters of an ISO 3166-1 alpha-2 code. Therefore, a spelling_lanugage
string as a whole must be exactly two chars (ss
) or exactly five chars (ss-TT
).
According to the specification, this repository is supposed to have tags corresponding to each version of the specification, but the tags do not exist in:
If the version tags could be published, or otherwise changing the communication structure of versioning, that'd be greatly appreciated.
IMHO, a specification should always have a revision format where application programmers and users alike can see which version of the specification the corresponding programs support.
I recommend SemVer. As a positive example I'd cite the Matrix.org spec.
Since editorconfig is a pretty small specification, the versioning should be pretty easy. Maybe just slap a v1.0 onto the spec if #2 and #8 are resolved? As there are already implementations of the spec which work somewhat this shouldn't be too risky.
max_line_length is used in this repo, in various plugins and core. Is there any reason why this specification doesn't describe it?
POSIX requires non-empty files to feature a final end of line (e.g. \n
line feed) terminator, and in general EditorConfig does a good job of helping users to enforce this.
For blank files, however, POSIX does allow for the omission of final end of line terminators. In the event that EditorConfig encounters a file with absolutely no content, it should not warn (and text editor plugins should not auto-insert) about end of line terminators.
In Atom for example, saving a blank file with EditorConfig and insert_final_newline
rule enabled, does not present an extra end of line terminator. Neither does Vim. That is acceptable and storage-optimal behavior as far as POSIX is concerned. Not sure about how other EditorConfig toolsets behave.
If we ignore backwards compatibility, then EditorConfig should clarify final eol rule behavior. EditorConfig plugins and linters should go ahead and check for empty files before warning or auto-inserting final eol terminators. This could temporarily break some CI configurations, though the end result is that user data is more POSIX compliant.
However, if backwards compatibility is preeminent, then we may want to create a new option for this rule, something like blank_files_skip_eol
, which takes values true
, false
, or none
(not enforced). And encourage the community of EditorConfig tools to update and encourage good form.
According to the spec, whitespaces in keys are not prohibited:
Key: the part before the first = (trimmed of whitespace).
Unfortunately, this behavior is not widely adopted, nor explicitly considered as a legal option. However, JetBrains seems to use this behaviour as an option when exporting .editorconfig
:
[{*.http,*.rest}]
ij_http request_call_parameters_wrap = normal
This feature is documented in IDEA documentation, you can actually see implementation cases searching for code samples: https://github.com/search?q=ij_http+request_call_parameters_wrap&type=code
I'm requesting any clarification on legality and acceptability of this use case. This question was originally raised at
ec4j/ec4j#122 (comment) as this behavior may misleadingly be adopted by parser developers. If spacing is considered as allowed, please implement any tests for this in https://github.com/editorconfig/editorconfig-core-test so any other parser developers may have a chance to adapt too
It is possible on readthedocs to use a custom (sub)domain to host the specification. Something like specifications.editorconfig.org
or just specs.editorconfig.org
would make it clearer that the specifications are officially linked to the project.
Not sure who has access to the DNS of editorconfig.org, but I guess @xuhdev should be able to add the required CNAME record.
I propose that we introduce an AST specification that would represent the intermediate state between parsing and applying EditorConfig-specific rules.
Consider also that EditorConfig, though it only targets supported rules, can technically accept any/all rules you throw at it. This means that the file format and AST are useful outside of the context of EditorConfig.
See the confusion in editorconfig/editorconfig-core-test#37 (comment)
One of the things that need to be clarified is how trim_trailing_whitespace = true
is expected to work.
At the moment almost all implementations I use trim all the trailing whitespaces that exist in a file on save. IMHO that is the expected behavior.
The native Visual Studio implementation only trims whitespaces when enter is pressed at the end of a line. That seems fairly odd and unexpected behavior to me, but "it works as designed" they say: https://developercommunity.visualstudio.com/content/problem/134457/editorconfig-trim-trailing-whitespace-only-applies.html
In their case it even means that when you are at the end of a line, press space or tab followed by any arrow key (or alike) the trailing whitespace remains in the file, despite the setting trim_trailing_whitespace = true
.
By clarifying the expected behavior we can strive for more consistent between the various implementations. Right now on our website it says:
trim_trailing_whitespace
: set to "true" to remove any whitespace characters preceding newline characters and "false" to ensure it doesn't.
I would suggest to add something like "in the file" after "whitespace characters".
Taking the specification literally, the glob *.py
would not match foo/bar.py
since foo/bar
includes the slash character. The C library for editorconfig adds **/
to the start of the glob if it does not have a slash in it (see editorconfig.c:260), but this should really be in the spec.
Within projects there is a lot of generated (e.g. test output) or duplicated data (e.g. symlinks or after build process).
This leads to permanent reindex by the IDE for things we won't ever need to lookup.
Therefor IDEs can mark directories or files as "excluded" which should be a property in editorconfig too.
Notes:
The link to the built version as mentioned in the README.md (https://editorconfig-specification.readthedocs.io/en/latest/) just reads "SORRY - This page does not exist yet."
The text at the aforementioned point reads:
root
: special property that should be specified at the top of the file outside of any sections. Set to "true" to stop .editorconfig files search on current file.
As a L1 english speaker, I cannot read the above point, "to stop .editorconfig files search" lacks a definite article, perhaps the author meant ""to stop the .editorconfig files searching the current file"? What is exactly meant by "current file"?
I'm happy to file a pull request, I just lack the context of what it's referring to, hence why I filed an issue first.
Per the current specification, I don't see how (if possible) to include a key-value pair whose value is a multiline string.
If it's not currently possible, is it possible to update the spec to have a way for that?
Currently there is no mention of what these things should do in neither the simplified nor the formal version of the spec. The example files in official libraries seems to generally avoid doing so, and WebStorm seems to agree that they are in general invalid.
If the current behavior is intended to be kept, I recommend adding this to the spec:
Any property other than
root
MUST be located under a section to take effect. They are not otherwise recognized.
This, however, can feel counterintuitive to some. It could be more intuitive to do this (at a cost of changing quite a few libraries; we will need a versioning scheme for that):
Formatting (non-
root
) properties not found under a section are taken to have a section of[*]
. The normal precedence rules apply.
The example should probably be changed to illustrate the precedence behavior too. Maybe define a indent under [*]
and overwriting it for js will help show the point.
This issue is opened to discuss the table of content for the specification.
Here is a first shot:
Introduction of the specification.
Describes the file format of the .editorconfig
files. Also a subsection on parsing the file.
Describes the glob syntax used in the section headers in the editorconfig file.
Describes the file name, how they are located and the order of processing the content.
Describes the supported properties.
How should the plugin behave in certain situations. (e.g ignore unknown
properties, warn on invalid values for known properties).
Users attempting to quickly toggle on and off code commenting, e.g. for YAML, Python and other whitespace sensitive file formats, will find that the resulting uncommented code may not align with the rest of the file, resulting in errors. EditorConfig could minimize this risk, by allowing for a rule on code comments: How many ASCII space characters to insert between #
and the beginning of the snippet to comment.
Examples:
my:
# car:
# color: "red"
vs.
my:
#car:
# color: "red"
Either style would be fine, as long as our text editors can pick up the fact that a certain number of spaces are treated as leading comment characters, when toggling comments back off.
A declarative, efficient, and flexible JavaScript library for building user interfaces.
๐ Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. ๐๐๐
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google โค๏ธ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.