editorconfig.txt

*editorconfig.txt*  For Vim version 8.1.  Last change: 2019 Aug 23

                  EDITOR CONFIG FOR VIM   by Ralf Schandl

Plugin to add editorconfig support to Vim.                      *editorconfig*


1. Introduction                              |editorconfig-intro|
2. Supported Properties                      |editorconfig-props|
3. Commands                                  |editorconfig-cmd|
4. Customization                             |editorconfig-customization|
5. Extending Editorconfig                    |editorconfig-extending|
6. Integrating with the Editorconfig Plugin  |editorconfig-integrating|

==============================================================================
1. Introduction                                           *editorconfig-intro*

Editorconfig provides a simple way to configure some basic settings. It is in
no way comparable with what you can do with your vimrc, but it helps to bring
some consistency into a code base handled by different programmers with
different editors.


You can read more about editorconfig on http://editorconfig.org and in the
wiki at https://github.com/editorconfig/editorconfig/wiki.

1.1 How does it work?
---------------------

A file named `.editorconfig` is created in the root directory of a source
project. Whenever Vim opens a file in or below that directory, the file
`.editorconfig` is parsed and the appropriate settings are applied for the
file to edit. Typical settings are `tabstop` or `shiftwidth`.

The editorconfig file is a simple init file with sections named by glob
pattern and settings. Like:
>
    root = true

    [*]
    charset = utf-8
    indent_size = 4
    insert_final_newline = true
    trim_trailing_whitespace = true

    [*.js]
    indent_style = space

    [*.{yml,yaml}]
    indent_style = space
    indent_size = 2
<

The `root = true` defines this file as the top-level editorconfig file. If
this setting would not be there, parent directories would be searched for
further files named `.editorconfig`.

The rest of the file is pretty self explanatory. It is read from top to bottom
and the properties from matching sections are applied. A property from a later
section will override those from an earlier section. E.g. all files use UTF-8
encoding. For Javascript the indent (shiftwidth) is 4 (inherited from `[*]`),
for yaml files 2.

Comments
--------
Comment characters in editorconfig files are `#` and `;`. They define the rest
of the line as comment.
It is highly recommended to put comments on their own line.
The behavior of end-of-lines comments and the escaping of comments characters
is not clearly defined. So you should avoid them.
>
    [*]
    prop1 = value  # this is a comment
    prop2 = value#   this is NOT a comment
    prop3 = value \# this is NOT a comment, but \ is also returned
<

1.2 Editorconfig vs. Modeline
-----------------------------

If the file has a |modeline|, this settings take precedence over the
editorconfig settings.


==============================================================================
2. Supported Properties                                   *editorconfig-props*

Note, that all properties support the special value `unset`. This makes it a
'no-op', even when it was set in a parent `.editorconfig` or a parent section
like `[*]`.

If a property has a invalid value, that property is silently ignored. Use the
command |:EditorConfigStatus| to display warning messages.

`indent_style`            Value: `tab`, `space`
                        Defines whether tabs or spaces should be used for
                        indenting.
                        In Vim it switches the option |expandtab|.

`indent_size`             Value: `tab` or a positive number
                        Sets the |'shiftwidth'|. If the value is `tab`, the
                        |'shiftwidth'| is set to `0`, then the value of
                        |'tabstop'| is used.

`tab_width`               Value: a positive number
                        Sets the option |'tabstop'|.

`end_of_line`             Value: `lf`, `cr` or `crlf`.
                        Sets the |'fileformat'|.
                        `lf`:   fileformat = unix
                        `cr`:   fileformat = mac
                        `crlf`: fileformat = dos

`trim_trailing_whitespace`
                        Value: `true` or `false`
                        If true, installs a buffer-local `autocmd` to remove
                        trailing spaces before writing the buffer.

`insert_final_newline`    Value: `true` or `false`
                        Toggles the option |'fixendofline'|.

`charset`                 Value: any charset supported by Vim (see
                        |encoding-values|)
                        Sets the |'fileencoding'| for the file.
                        If the charset is `utf-8-bom` the option |'bomb'| is
                        set.
                        Editorconfig only requires support for a limited set
                        of encodings:
                          - latin1
                          - utf-8
                          - utf-16be
                          - utf-16le
                          - utf-8-bom
                        Note that "utf-16be" is not listed as a
                        |encoding-values| in Vim help, but work (at least on
                        Linux).

`max_line_length`         Value: `off` or a positive number
                        Sets the option |'textwidth'|.
                        If the value is `off`, |'textwidth'| is untouched
                        (whatever it was set before)`.


Vim extensions
--------------
The following properties are only supported by the Vim editorconfig plugin.

WARNING: This plugin is in a early stage, the name of the following properties
might change!

`spell_lang`              Value: "comma separated list of word list names"
                        Sets the option |'spelllang'|, but does not enable
                        spell checking.
                        Note that this might trigger a download of the spell
                        file if the |spellfile.vim| plugin is active.

`spell_check`             Value: `true` or `false`
                        Whether spellcheck is wanted. Sets the option
                        |'spell'| or |'nospell'|.


==============================================================================
3. Commands                                   *editorconfig-cmd* *:EditorConfig*

                                                          *:EditorConfigApply*
:EditorConfigApply[!]   (Re)Applies editorconfig settings to the current file.
                        If `!` is given, ignores |g:editorconfig_blacklist|
                        and |g:editorconfig_base_dirs| and also applies the
                        settings to files that normally would be ignored.

                                                         *:EditorConfigStatus*
:EditorConfigStatus     This command prints information about the editorconfig
                        applied to the current file. It prints applied
                        settings, warning and error messages.
                        Example output:
                        Opening a new C file with the following
                        `.editorconfig`:
>
                        [*.c]
                        charset=utf-8
                        insert_final_newline=true
                        indent_style=space
                        indent_size=4
                        trim_trailing_whitespace=true
<
                        produces following status output:
>
                        EditorConfig Info:
                        - WARNING: /.../.editorconfig Section [*.c]: Unsupported option: unsupported = x
                        - setlocal fixendofline
                        - Changed fileencoding from unset to utf-8
                        - setlocal expandtab
                        - setlocal shiftwidth=4 softtabstop=4
                        - Installed autocmd TrimTrailingWhiteSpace
<

==============================================================================
4. Customization                                  *editorconfig-customization*

WARNING: This plugin is in a early stage, the name of the following variables
might change!

`g:editorconfig_base_dirs`
                        List of directories (absolute names) to be whitelisted
                        for editorconfig. Only files opened below one of this
                        directories triggers the search for `.editorconfig`
                        files.
                        If empty, always search for `.editorconfig`.

`g:editorconfig_blacklist_filetype`
                        A list of glob expressions matched against |filetype|s.
                        Prevents applying editorconfig by filetype.
                        E.g.:
>
                        let b:editorconfig_blacklist_filetype = [ 'c', 'git*']
<
                        Ignores files with the filetype `c` and any files with
                        a filetype starting with `git`.
                        This is case-insensitive.

`g:editorconfig_blacklist_name`
                        A list of glob expressions matched against file names..
                        Prevents applying editorconfig by file name.
                        E.g.:
>
                        let b:editorconfig_blacklist_name = [ '*.tmp', '*.xy']
<
                        Ignores files which name match `*.tmp` or `*.xy`.
                        This is case-insensitive.

                        Normally you need a leading `*` to ignore a file.
                        If you want to ignore the file `testcase.txt` you
                        have to give the filename as `*/testcase.txt`.
                        If you want to ignore remote files you add the
                        filename `scp:*` (or whatever protocol you use).

`g:editorconfig_verbose`  Numerical value to control messages from the
                        editorconfig plugin.
                        Possible values:
                          0: Default. Only print a message for errors. E.g. a
                             invalid value for a known property.
                          1: Also print a message if a warning occurred. E.g.
                             a unknown property.
                         -1: Don't print any message. (Not recommended)

                        Independent of this setting all messages are viewable
                        with the command |:EditorConfigStatus|.

`g:editorconfig_debug`    Numerical variable. If set, debug messages are added
                        to the editorconfig info and are displayable with the
                        command |:EditorConfigStatus|. Higher numbers, mean
                        more debug messages.

`g:editorconfig_max_line_length_visual`
                        Determines how the property `max_line_length` is
                        visually displayed. Possible values:

                        `none`: (default) No visual feedback is activated.

                        `exceed`: All characters beyond `max_line_length` are
                        highlighted with the color defined for
                        |hl-ColorColumn|.

                        `ruler`: The option |'colorcolumn'| is set. It is
                        set to the first column beyond `max_line_length`.

                        Any other value is silently ignored.


`EditorConfigPre()`       If a function with this name exists, it is called
                        before the editorconfig is processed and applied.

`EditorConfigPost()`      If a function with this name exists, it is called
                        after the editorconfig properties were applied to the
                        buffer.

`EditorConfigOnLoad()`    If a function with this name exists, it is called
                        after the initial configuration of the editorconfig
			plugin. This function could be used to register
			listeners (which is not possible before).
			See |editorconfig-integrating|.


==============================================================================
5. Extending Editorconfig                             *editorconfig-extending*

New custom editorconfig properties can be defined using the global dictionary
`g:editorconfig_config`. The variable must be defined before the editorconfig
plugin is loaded!

The entries in this dictionaries uses the name of the property as key and a
|funcref| as value. When the property is to be applied, the `funcref` is
called with the value as parameter. Note that the value is never lower-cased,
so if you do some string compare, consider doing it case-insensitive.

Examples:
---------
Define a new property `conceal_level` that sets the Vim option |conceallevel|.
>
    function SetConceal(value)
      if a:value =~# '^\d\+$'
        let i = str2nr(a:value)
        if i >= 0 && i <= 3
          let &l:conceallevel = i
          return
        endif
      endif
      throw "EditorConfig: conceal_level invalid: " . a:value
    endfunction

    let g:editorconfig_config = {
          \ 'conceal_level': funcref('SetConceal')
          \ }
<

To disable the support for a known property, define any String instead of a
`funcref`. The content of the String is irrelevant, could be empty.
The following disables support for the property `indent_style`:
>
    let g:editorconfig_config = { 'indent_style': "I don't like this." }
<

Support Functions:
------------------

Editorconfig provides three functions to add messages to its message
list. This messages can later be displayed with the |:EditorConfigStatus|
command.

`editorconfig#Info(msg)`
                      Adds the given message as info messages.

`editorconfig#Warning(msg)`
                      Adds the given message as warning messages.

`editorconfig#Debug(level, msg, ...)`
                      If `g:editorconfig_debug` is set to a value
		      greater-equal to `level`, adds the given
                      formatted message to the list as info message. This is
                      to be used like |printf()|. Example:
                      `editorconfig#Debug(1, "Hello %s", "world")`

BTW: The function |EditorConfigPre| and |EditorConfigPost| might also be
useful when the editorconfig plugin is extended.

==============================================================================
6. Integrating with the Editorconfig Plugin         *editorconfig-integrating*

Other Vim plugins are able to integrate with this editorconfig plugin. They
can register a listener and are then called whenever editorconfig applies a
property to the current buffer.

The listener function is called with two arguments:

1. `property` the name of the editorconfig property
2. `value`    the value of the editorconfig property

Note: If a called listener throws an exception it is automatically
unregistered and not called again.

`editorconfiglistener#register(funcref)`
                        Registers the given funcref as listener.

`editorconfiglistener#unregister(funcref)`
                        Removes the given funcref from the listener list.

Example:
--------
>
    function! EditorConfigDebug(property, value)
        echomsg "Editorconfig: " . a:property . " = " . a:value
    endfunction

    call editorconfiglistener#register(funcref("EditorConfigDebug"))
<

The function `EditorConfigDebug` is called whenever the editorconfig plugin
applies a property.

BTW: If you add the above code to your `vimrc` you either need to add
`packloadall` before registering the listener or do it from a function called
`EditorConfigOnLoad` (see section |editorconfig-customization|).

Example Output:
---------------
>
    Editorconfig: insert_final_newline = true
    Editorconfig: charset = utf-8
    Editorconfig: indent_style = space
    Editorconfig: indent_size = 2
    Editorconfig: trim_trailing_whitespace = true
<


 vim:tw=78:ts=8:noet:ft=help:norl: