📗【翻訳】EditorConfigの仕様のなんちゃって日本語訳とおすすめ設定


ジェネレータ作りの練習で、EditorConfigの設定ジェネレーターを作りました。
今回は、そのついでに日本語訳をしたものを掲載します👀

その前に、EditorConfigとは?

コーディングするときの基本の1つ👀
インデントの種類、改行コードなどを統一してくれる大変有名な仕組みです。

Gitで余計な差分で現れると面倒な余計な空白や、改行コードの違いも解決してくれる優れものです。
Visual Studio Codeはもちろん、さまざまなエディタで動かすことができます。

プロジェクト(フォルダ)の中にEditorConfigファイル(.editorconfig)を作り、ファイルの種類ごとにルールを記述していきます。
VS Codeの場合は専用のエクステンションがインストールされた状態で、EditorConfigファイルを含むプロジェクトの中のファイルを保存すると、EditorConfigによってコードが整えられます。

EditorConfigの仕様(日本語訳)

はじめに、いくつかこの日本語訳で登場する用語を紹介します。

  • 設定ファイル:EditorConfigの設定ファイルで、つまりは「.editorconfig」のこと
  • コア:設定ファイルを解析する機能のこと
  • セクションヘッダ:設定ファイルにおいては、glob形式のファイルパスのこと
  • キーと値のペア:設定ファイルに記載するルール1つ1つのこと
# キーと値のペア
root = true

# セクションヘッダ
[*]

# キーと値のペア
indent_size = 2

以下、原文からかいつまんだ日本語訳です。
原文はこちら:EditorConfig Specification

File Format - .editorconfigのファイル形式

設定ファイルはINIファイルのようなフォーマットで記述されます。
この設定ファイルでは、各行頭の空白文字は無視されます。

各行はそれぞれ次のいずれかである必要があります。

  • 空行:空白文字のみ
  • コメント;または#で始まります
    • 行内で空白文字以外の後にこれらの記号を挿入しても、コメントとして解釈されず、セクション名やペア(後述)の一部としても解釈されません。なお、これは将来的に変更される可能性があるため、いずれにしても非推奨です。
  • セクションヘッダ[で始まり、]でおわります
    • この行では角括弧の外側に空白文字以外を記述できません
    • 角括弧の中には任意の文字を入れることができます
      • パスの区切りにはスラッシュを用います(/
      • Windowsの場合でも、バックスラッシュをパスの区切りとして使うことはできません
  • キーと値のペア(以下、ペア)=で区切られたキーと値

これらに当てはまらない行は無視されます。

設定ファイルは、改行コードが「LF」または「CRLF」、文字コードが「UTF-8」である必要があります。

Glob Expressions - セクション名の書き方

設定ファイルのセクション名は、.gitignoreで有効なフォーマットと同じglobを使ったファイルパスです。
これは、Unix shell-styleのワイルドカードによるパターンマッチをサポートしています。
globでは、次の記号を特殊文字として認識します。

記号 役割
* パスの区切り文字(/)を除く任意の文字列
** 任意の文字列
? パスの区切り文字(/)を除く任意の一文字
[seq] 「seq」のうち任意の一文字
[!seq] 「seq」以外の任意の一文字
{s1,s2,s3} カンマ区切りの文字列のうちいずれか(これは入れ子にできます)
{num1..num2} num1〜num2の間の任意の整数(num1とnum2は負の値でもOK)

特殊文字として解釈されないようにするには、バックスラッシュ(\)を用いてエスケープします。

コアは、1024文字までのセクション名を受け入れまなければなりません。
各実装が独自に上限を設定するか、明示的な上限を設定しないことができます。

File Processing - 設定ファイルの読み込み

EditorConfigはファイル名を渡されると、そのファイルのディレクトリとすべての親ディレクトリから設定ファイル(デフォルトでは.editorconfigという名前)を検索します。
存在しないディレクトリは、存在する空のディレクトリとして扱われます。

見つけられたすべての設定ファイルは、渡されたファイル名に一致するセクション名をもつセクションを検索します。

設定ファイルのroottrueに設定されている設定ファイルまでたどり着いた場合、またはファイルシステムのルートディレクトリまで到達したとき、検索を終了します。

設定ファイルは上位ディレクトリから下位ディレクトリの順に読み込まれ、最後に読み込まれたルールが優先されます。
複数の設定ファイルにマッチするセクションがある場合、より近い設定ファイルのルールが最後に読まれるため、より近いファイルのペアが優先されます。

Supported Pairs - サポートされているペア

設定ファイルのセクションは、イコール(=)で区切られたキーと値のペアで構成されています。
rootを除いて、すべてのペアはセクションヘッダより後の行に記述しなければなりません。

EditorConfigのプラグインは、認識されていないキーや無効なもの、サポートされていないキーの値を無視しなければなりません。

この仕様のこのバージョンで定義されているすべてのキーと、それらに関連するサポートされている値のリストは、次の通り。

(便宜上、一部次のような独自の表現を用います)

  • number - 半角数字を指します
  • boolean - trueまたはfalseのいずれかを指します
キー名 設定可能な値  備考
indent_style "space"
"tab"
インデントに「スペース」「タブ」どちらを使うか決めます。
なお、値は大文字小文字を考慮しません。
indent_size number
"tab"
インデントの空白文字数を決定します。

この値がtabの場合、tab_widthの値が利用されます。
なお、値は大文字小文字を考慮しません。
tab_width number タブ文字の幅を決めます。
デフォルトはindent_sizeの値が利用されるため、通常は指定する必要はありません
end_of_line "lf"
"cr"
"crlf"
改行コードを決定します。
なお、値は大文字小文字を考慮しません。
charset "latin1"
"utf-8"
"utf-8-bom"
"utf-16be"
"utf-16le"
文字コードを決定します。
utf-8-bom非推奨です。
trim_trailing_whitespace boolean trueを設定すると、ファイルの保存時に行末(改行文字より前)の空白文字を削除します。
insert_final_newline boolean trueを設定すると、ファイルの保存時に末尾に1つの空行が追加されます。
root boolean trueを設定すると、その設定ファイルよりも上位ディレクトリを検索しなくなります。
なお、設定ファイルの先頭に記述する必要があります。

いずれのペアも、値にunsetを設定することができます。この値は、そのキーがすでに設定済みだったとしても、それを無効にします。
たとえば、indent_size = unsetを追加すると、indent_sizeの定義が無効になります(エディタのデフォルト設定が参照される)。

ペアのキーは、大文字と小文字を区別せず、解析後にすべて小文字になります。

コアは、1024〜4096文字までの長さのキーと値を受け入れまなければなりません。
各実装が独自に上限を設定するか、明示的な上限を設定しないことができます。

Suggestions for Plugin Developers - プラグイン開発者への提案

準備中。とりあえず、GitHub wikiのPlugin Guidelinesを読んでください。


一部割愛している部分もありますが、こちらで以上です。
いままでずっと使ってきたのに、indent_sizetabなんて値が設定できたなんて知りませんでした🙈

最後におすすめ設定

個人的なおすすめ設定はこちら( ˘ω˘ )

最新版はこちら:https://gist.github.com/heppokofrontend/1587734087a9476dfe3fc16fb770bb96

.editorconfig
root = true

[*]
indent_style = space
indent_size = 2
end_of_line = lf
charset = utf-8
trim_trailing_whitespace = true
insert_final_newline = true

[*.{md,mdx}]
trim_trailing_whitespace = false

[*.ps1]
charset = utf-8-bom

# FOR WINDOWS
[*.{cmd,bat}]
end_of_line = crlf

基本的にはLFのインデント2、余計な空白無し。ただ、Markdownでは行末のスペースは改行を表すので、トリミングされないようにfalseを指定しています。
PowerShell用のファイルはBOMつきUTF-8でなければならないため指定していて、Windows向けのバッチファイルはCRLFでなければならないため指定しています。

運用が長くなることが予想されたり、さまざまな環境の開発者が参画することが予見される状況での開発環境構築では、「これをされたら困る〜><」ということが起こらないように設定を書いておくとよいと思っています。

よいコーディングライフを〜!!