首页 >web前端 >html教程 >[工具资源] Atom 语法高亮插件编写指南_html/css_WEB-ITnose

[工具资源] Atom 语法高亮插件编写指南_html/css_WEB-ITnose

WBOY
WBOY原创
2016-06-24 11:15:402432浏览

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 名称已经被占用了,于是我取名为 language-ssa,ASS 字幕是由 SSA 字幕添加高级特性后发展来的,两者语法基本一致 。其中 ssa.cson就是写语法正则的主文件,后缀 CSON 是个和 JSON 一样的数据交换语言,但它是 CoffeeScript 的子集,看下 该项目的 README 基本就会了; ssa-spec.coffee是测试文件,虽然不是必须的,但靠谱的项目都应该有测试; LICENSE.md和 README.md在 Atom 的插件页面会有链接和展示; package.json和普通的 Node.js 项目一样,它的 engines字段多了指定 Atom 的版本,看下 样例就清楚了。

在本地开发测试时,直接把 language-ssa 文件夹放到 ~/.atom/packages/目录下并重载( Ctrl+Alt+R) Atom 后就会生效了。

语法规则

Atom 语法文件的各个字段与 TextMate 编辑器的语法文件相同,TextMate 给出了较为详细的 文档,下面是补充介绍,可以对照着 language-ssa的语法文件来阅读:

  • scopeName字段,它应当是每种语言语法的唯一名字,一般取名为 source.ssa或 text.ssa,前一半一般是固定的,后一半是该语言的名称。而当该语言是另一个语言的扩展时,例如 markdown 是 HTML 的扩展,可以取名为 text.html.markdown,这样在当前 scope 的规则匹配完后,会匹配 text.htmlscope 的规则,相当于调用了 HTML 的语法规则。
  • name字段,在 Atom 右下角显示的语言名称。
  • fileTypes字段,是个数组,指定要生效于哪些后缀的文件。
  • firstLineMatch字段,是一条正则,如果该正则可以匹配某后缀不明的文件的第一行,那么就当作该语言来解析。
  • foldingStartMarker和 foldingStopMarker字段,都是正则,匹配到的位置会有一个折叠标记,可以将代码块折叠。但是我在测试时发现 Atom 会自动根据缩进来产生折叠标记,这两个字段是如何影响的还不太清楚。
  • patterns字段,是一个数组,这里是写语法正则的地方,里面是若干个 pattern 对象,姑且称之为「规则」,其中可以包含以下字段:
    • comment字段,注释,无实际效果,描述该「规则」。
    • name字段,是由若干个 .分隔的字符串,这些名称将作为被匹配部分的 class 名。假如其值为 comment.line.character.semicolon.ssa,被匹配到的文本是 ; 分号注释,那么可以按下 Ctrl+Alt+I打开 DevTools,查看到对应生成的 HTML 为 ; 分号注释

      代码高亮的颜色效果是由 Theme 决定的,Theme 事实上就是根据这些 class 来添加颜色。后面会提到一些约定俗成的 class 名。

    • match字段,是一条正则,被它匹配到的文本将被加上 name字段的 class。它只能匹配单行文本,并且只匹配一次。
    • captures字段,是一个对象,其 key 为一个数字,表示分配 match字段中的捕获,如果为 0则表示整体,这与 JS 中 String 的 match 方法表现一致;其 value 可以是一个 name字段,直接为分配到的部分命名,也可以是一个 patterns字段,然后对分配到的部分继续写「规则」。
    • include字段,它的值有三种情况:
      1. 调用另一个语言,例如值为 'text.html'时,表示在当前「规则」中应用 HTML 的语法。
      2. 调用该「规则」自身,值为 '$self',可以递归地去匹配文本。
      3. 调用一个「仓库」,值为井号开头的 '#repoName',后面会讲到在 repository字段中可以为一个「规则」命名。
    • begin和 end字段,都是正则,匹配 begin开始到 end结束的一段文本,它可以匹配多行文本,并且不能和 match字段一起使用。
    • patterns字段,当有 begin和 end时可以嵌套 patterns来匹配它们之间的文本。
    • contentName字段,它和 name字段类似,但是只给 begin与 end之间的文本加上 class。
    • beginCaptures和 endCaptures字段,与 captures字段类似,分别是 begin和 end的捕获。

    这些「规则」 按顺序执行下来,每条「规则」 每次只匹配一次,一次循环后,回到第一条「规则」,选择当前行中 还未被匹配的文本进行第二轮匹配,以此循环,直到全部都匹配完或者 超出循环次数。Atom 中一个 patterns 默认的循环次数貌似是 99 次,超出后就不处理该匹配范围内的文本了。一般我们打开压缩过的 JS 文件时,滚动条拖到行尾发现是没有高亮的,就是这个原因。

  • repository字段,是一个对象,用来命名一些需要重复调用的「规则」,可以被 include字段调用。

正则用法

上面提到的语法正则与 JavaScript 中的 RegExp 对象用法基本一致,不过还是有一些差异的。就正则本身来说,ES5 和 ES6 还不支持 look-behind,不能使用 (?

而写成字符串后就无法像原生正则那样加修饰符了,在 TextMate 找到 正则的文档,发现可以通过 (?imx-imx)和 (?imx-imx:subexp)的方式开启或关闭对应的修饰符。例如 (?i)abc(?-i)def, (?i)表示它之后的匹配忽略大小写, (?-i)表示取消忽略大小写,也就是该正则里 abc可以大小写, def必须小写。这种写法是对修饰符的后面起作用,还可以写成 (?i:abc)def这样的形式,只对 abc这个局部起作用。 (?m)表示支持匹配多行,虽然 TextMate 的文档是这么说,但是我测试发现在 Atom 中是无效的,对于单条正则来说是没办法匹配多行的,要想匹配多行只能使用 begin和 end的方式。 (?x)则可以忽略正则中的空白字符直接量(空格、Tab、换行),而有反斜杠转义的空白字符则不会被忽略,这样当正则过长时就可以换行书写了,也可以给正则的某一部分加上注释,详细的介绍可以看下 这篇文章。如果有多个修饰符可以写到一起,例如 (?ix)abc。RegExp 对象中的 g 修饰符是不支持的,语法正则每次只匹配一次。

命名约定

语法高亮主要是将代码解析为多个部分,然后给不同语义的部分加上不同的颜色。虽然各个部分可以随意命名生成 class,但是一个 Theme 不可能为每一个语言都专门写一套配色,所以会有一些约定俗成的名称,一般的 Theme 都会支持这些命名约定:

  • 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:章节的头部,可以在后面跟一个等级,例如

      ...

      可以是 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 的文档进行了补充。但本文应当作为参考,在上手开发之前还需多看看已有的项目,才能理解并解决问题。

声明:
本文内容由网友自发贡献,版权归原作者所有,本站不承担相应法律责任。如您发现有涉嫌抄袭侵权的内容,请联系admin@php.cn