[ツールリソース] Atom構文ハイライトプラグイン作成ガイド_html/css_WEB-ITnose

Atom は、起動と実行が遅いことを除けば、説明の必要はないと思います。私は ASS 字幕を解析してレンダリングする JavaScript ライブラリ (ASS.js) を作成しているため、.ass ファイルをよく見ます。しかし、大きな白いコードに直面するのは不快でしたし、Atom 用の既製の ASS 構文強調表示プラグインもなかったので、自分で作成することにしました。

ディレクトリ構造

では、構文強調表示プラグインを作成するにはどうすればよいでしょうか? 公式ドキュメントでは、一般的なプラグインの作成方法について説明しています。構文強調表示プラグインに慣れる最も早い方法は、Atom によって公式に維持されている language-json などの既存のプラグインを確認することです。 。構文強調表示プラグインは通常、次のディレクトリ構造を持っています (ssa は言語名です):

language-ssa├── grammars│   └── ssa.cson├── spec│   └── ssa-spec.coffee├── LICENSE.md├── README.md└── package.json

language-ass 名はすでに使用されているため、高度な機能を備えた ASS 字幕が追加されています。 by SSA 字幕 後で開発されましたが、この 2 つの構文は基本的に同じです。このうち、ssa.cson は、通常の文法を記述するためのメイン ファイルです。接尾辞 CSON は、CoffeeScript のサブセットです。基本的には、プロジェクトの README を参照してください。 spec.coffee はテスト ファイルですが、必須ではありません。LICENSE.md と README.md は Atom プラグイン ページにリンクされて表示されます。通常の Node.js プロジェクトとそのエンジン フィールド Atom バージョンを指定する方法は他にもあります。例を見れば明らかです。

ローカルで開発およびテストする場合は、 language-ssa フォルダーを ~/.atom/packages/ ディレクトリに直接配置し、Atom をリロード (Ctrl+Alt+R) すると有効になります。

文法規則

Atom 文法ファイルの各フィールドは、TextMate エディターの文法ファイルと同じです。 以下は、言語の文法ファイルと照らし合わせて補足的に説明するドキュメントです。 -ssa:

• scopeName フィールドは、各言語構文の一意の名前である必要があります。通常、前半は固定で、後半は言語の名前です。たとえば、言語が別の言語の拡張である場合、markdown は HTML の拡張であり、text.html.markdown という名前を付けることができます。このように、現在のスコープのルールが一致した後、text.htmlscope のルールが一致します。これは、HTML の構文規則を理解するを呼び出すのと同じです。
• 名前フィールド。Atom の右下隅に表示される言語名。
• fileTypes フィールドは配列であり、どのサフィックス ファイルが有効になるかを指定します。
• firstLineMatch フィールドは通常のルールです。通常のルールが未知のサフィックスを持つファイルの最初の行と一致する場合、その言語として解析されます。
• [foldingStartMarker] フィールドと [foldingStopMarker] フィールドは両方とも正規表現です。一致する位置に折りたたみマークがあり、コード ブロックを折りたたむことができます。ただし、テスト中に、Atom がインデントに基づいて折り目マークを自動的に生成することがわかりました。これら 2 つのフィールドがどのように影響するかは不明です。
• パターン フィールドは配列です。ここに文法ルールが記述されています。これらを「ルール」と呼びます。以下のフィールドを含めることができます。
  • コメント フィールド、コメント、実際の効果はありません。 , 説明 「ルール」。

  • name フィールドは複数の . で区切られた文字列で、これらの名前は一致した部分のクラス名として使用されます。その値が comment.line.character.semicolon.ssa で、一致するテキストがセミコロン コメントである場合、Ctrl+Alt+I を押して DevTools を開くと、対応する生成された HTML が e798ca46c28e33b859becc1f821de634; セミコロン コメント54bdf357c58b8a65c66d7c19c8e4d114。

    コードの強調表示の色の効果はテーマによって決まり、テーマは実際にこれらのクラスに基づいて色を追加します。従来のクラス名については後述します。

  • 一致フィールドは通常のルールであり、これに一致したテキストが名前フィールドのクラスに追加されます。テキストの 1 行に 1 回だけ一致します。
  • キャプチャ フィールドはキーが数値であるオブジェクトで、それが 0 の場合は全体を表し、その値は名前にすることができます。フィールドに、割り当てられた部分に直接名前を付けます (パターン フィールドにすることもできます)。その後、割り当てられた部分の「ルール」の書き込みを続けます。
  • include フィールド、その値には 3 つの状況があります:
    1. 別の言語を呼び出します。たとえば、値が 'text.html' の場合、現在の「ルール」で HTML 構文を適用することを意味します。
    2. テキストを再帰的に照合するには、値「$self」を使用して「ルール」自体を呼び出します。
    3. 「リポジトリ」を呼び出します。値はポンド記号で始まる「#repoName」です。リポジトリ フィールドで「ルール」に名前を付けることができることについては後で説明します。
  • begin フィールドと end フィールドは両方とも通常であり、最初から最後までのテキストに一致します。複数行のテキストに一致しますが、一致フィールドと一緒に使用することはできません。
  • パターン フィールドに begin と end がある場合、それらの間のテキストと一致するようにパターンをネストできます。
  • contentName フィールド。名前フィールドと似ていますが、開始と終了の間のテキストにクラスを追加するだけです。
  • beginCaptures フィールドと endCaptures フィールドは、それぞれ begin と end のキャプチャである Captures フィールドに似ています。

  これらの「ルール」は順番に実行されます、各「ルール」は 1 回のみ一致します。ループの後、最初の「ルール」に戻り、現在の行で一致しないものを選択します。テキスト は実行されます。 2 回目のマッチング ラウンド。このサイクルは、すべてが一致するか、 サイクル数 を超えるまで継続します。 Atom のパターンのデフォルトのループ数は 99 のようです。これを超えると、一致範囲内のテキストは処理されなくなります。通常、圧縮された JS ファイルを開くときに、スクロール バーを行末までドラッグすると、ハイライトがないことがわかります。これが原因です。

• リポジトリ フィールドは、繰り返し呼び出す必要があるいくつかの「ルール」に名前を付けるために使用されるオブジェクトであり、include フィールドによって呼び出すことができます。

通常の使用法

上記の正規構文は、JavaScript での RegExp オブジェクトの使用法と基本的に同じですが、それでもいくつかの違いがあります。通常のルール自体に関する限り、ES5 と ES6 はまだ後読みをサポートしていないため、(?

文字列として書いた後は、ネイティブ正規表現のような修飾子を追加することはできません。TextMate で正規表現のドキュメントを見つけたところ、(?imx-imx) と (? を使用して、対応する正規表現をオンまたはオフにできることがわかりました。 imx-imx:subexp) 修飾子。たとえば、(?i)abc(?-i)def、(?i) は大文字と小文字を無視した後のマッチングを意味し、(?-i) は大文字と小文字を無視してキャンセルすることを意味します。つまり、この場合 abc は大文字でも小文字でも構いません。規則性があるため、 def は小文字にする必要があります。この記述方法は、修飾子の後に機能します。また、abc に対してのみ機能する (?i:abc)def の形式で記述することもできます。 (?m) は、複数行のマッチングをサポートすることを意味します。TextMate のドキュメントにはそう記載されていますが、私のテストでは、単一の通常のルールに対して複数行をマッチングする方法はありません。 begin メソッドと end メソッドを使用します。 (? 正規表現の特定の部分にコメントを追加することもできます。詳細については、この記事を参照してください。複数の修飾子がある場合は、(?ix)abc のようにまとめて記述することができます。 RegExp オブジェクトの g 修飾子はサポートされておらず、構文の規則性は一度に 1 回のみ照合されます。

命名規則

構文の強調表示は主にコードを複数の部分に解析し、異なるセマンティクスを持つ部分に異なる色を追加します。クラスを生成するために各部分に任意の名前を付けることができますが、テーマが言語ごとにカラーマッチングの特別なセットを記述することは不可能であるため、いくつかの従来の名前があり、一般的なテーマはこれらの命名規則をサポートします:

• comment：注释
  • line：单行注释
    • double-slash： //注释
    • double-dash： --注释
    • number-sign： #注释
    • percentage： %注释
    • character：其他类型的注释
  • block：块级注释
    • documentation：注释文档
• constant：各种形式的常量
  • numeric：数字常量，例如 42, 6.626e-34, 0xFF
  • character：字符常量，例如 <
    • escape：转义字符常量，例如 \n
  • language：语言本身提供的特殊常量，例如 true, false, null
  • other：其他常量，例如 CSS 中的颜色
• invalid：无效的语法
  • illegal：非法的语法
  • deprecated：弃用的语法
• keyword：关键字
  • control：流程控制关键字，例如 continue, while, return
  • operator：操作符关键字，例如 and, &&
  • other：其他关键字
• markup：适用于标记语言，例如 HTML、markdown
  • underline：下划线
    • link：链接
  • bold：粗体
  • heading：章节的头部，可以在后面跟一个等级，例如 c1a436a314ed609750bd7c7d319db4da...2e9b454fa8428549ca2e64dfac4625cd可以是 markup.heading.2.html
  • italic：斜体
  • list：列表
    • numbered：有序列表
    • unnumbered：无序列表
  • quote：引用
  • raw：原始文本，例如一段代码。
  • other：其他标记结构体
• meta：元通常用来标记文档中的较大的一部分。标记为元的部分一般是没有样式的，通常某一块文本如果语义或结构上是同一部分，就可以标记为元。例如声明函数的一行可以是 meta.function，然后它的子集是 storage.type, entity.name.function, variable.parameter之类的。
• punctuation：标点，这个在 TextMate 文档中没有提到，但是实际中有使用。不过似乎并没有样式。
  • definition：定义符，例如 :
  • separator：分隔符，例如 ,
  • terminator：结束符，例如 ;
• storage：有关「存放」的东西
  • type：类型，例如 class, function, int, var
  • modifier：修饰符，例如 static, final, abstract
• string：字符串
  • quoted：有引号字符串
    • single：单引号字符串，例如 'foo'
    • double：双引号字符串，例如 "foo"
    • triple：三引号字符串，例如 """Python"""
    • other：其他引号字符串，例如 $'shell'
  • unquoted：无引号字符串
  • interpolated：插值字符串，例如 `foo: ${foo}`
  • regexp：正则表达式
  • other：其他字符串
• support：由框架或库提供的东西
  • function：由框架或库提供的函数，例如 Objective-C 中的 NSLog
  • class：由框架或库提供的类
  • type：由框架或库提供的类型，可能只会在 C 派生的语言中用到，有 typedef和 struct的那些语言。大多数语言使用类而非类型。
  • constant：由框架或库提供的常量（魔术数字）
  • variable：由框架或库提供的变量，例如 AppKit 中的 NSApp
  • other：除了上面提到的
• variable：变量
  • parameter：参数
  • language：语言本身提供的变量，例如 this, super, self
  • other：其他变量

通常，命名时应以上述的约定开头，并且能满足子项的都应写上去；之后一般会根据当前的部分写一个自定义的名称，虽然可能对样式不起作用，但额外的信息可以将它标识为特定的语义；最后一般都是跟一个语言名称。例如 ASS 文件中区块头部 [Script Info]，其中的 [可以命名为 punctuation.definition.section.begin.ssa，约定部分是 punctuation.definition，自定义部分是 section.begin，最后是语言名称。

测试集成

Atom 插件是使用 Jasmine测试框架的，对语法高亮插件的测试主要用到了 Atom Grammar API，Atom 官方维护的 语法高亮插件都有写测试，具体写法可以参考。

Atom 插件的持续集成依然可以参考 Atom 官方项目，一般 .travis.yml文件 长这样就行了，它会跑一遍 spec目录下的测试，有配置 lint 的话就再跑一遍 lint。如果不用 Travis CI，可以根据 这个项目部署其他服务。

发布插件

发布插件时首先要检查名称是否可用，一般语法高亮插件都是命名为 language-语言名的。然后需要一个公开的 Git 仓库来放置代码，一般都是开源在 GitHub 上，并在 package.json中写明仓库地址。当第一次 push 到 Git 时， package.json中的 version一般是 0.0.0。然后登录 https://atom.io/account获得 API token，在终端输入 apm login --token YOUR_TOKEN就可以准备发布了：

$ apm publish minorPreparing and tagging a new version donePushing v0.1.0 tag donePublishing language-ssa@v0.1.0 done

运行上述命令后，apm 会自动给 version的次版本加一，然后生成一个 message 为 Prepare 0.1.0 release的 commit，并加上一个 v0.1.0的 Tag，一起 push 到 GitHub 上。之后就可以在 https://atom.io/packages/language-语言名上看到已成功发布了。

总结

本文大致介绍了 Atom 语法高亮插件的编写流程和方式，并根据我在开发中遇到的情况对 TextMate 的文档进行了补充。但本文应当作为参考，在上手开发之前还需多看看已有的项目，才能理解并解决问题。