Mode reference

ここではhighlight.jsで使われる各モードを説明しています。

各属性値の型

このリファレンスでの属性値の型は以下の通りです。

属性

case_insensitive

言語のキーワードと正規表現の大文字・小文字を区別しません。 トップレベルのモードでのみ使用可能です。

{
  case_insensitive: true,
  ...
}

aliases

HTMLで指定するクラスや、.getLanguage()メソッドで言語を検出するために追加する名前(エイリアス)のリスト。 (標準的な名前に加えて定義します。)

{
  aliases: ['js', 'jsx'],
  ...
}

className

モードの名前。 HTMLマークアップのクラス名として使用されます。

複数のモードに同じ名前を指定することができます。 言語がシングルクォーテーション(')やダブルクォーテーション(")で囲まれた文字列を、 どちらも"文字列"とするような、複数の構文を持つ場合に便利です。

{
  className: 'number',
  ...
},
{
  className: 'string',
  ...
},

begin

モードの開始を表す正規表現。 例えば、文字列を表すシングルクォーテーション(')や、 C言語のコメント用のスラッシュ(//)などです。 beginが未定義の場合、 デフォルトは全ての文字列にマッチする正規表現のため、 モードはただちに開始になります。

{
  begin: /^\s*['"]use (strict|asm)['"]/
  ...
},

end

モードの終了を表す正規表現。 例えば、文字列を表すシングルクォーテーション(')や、 1行コメント用の行末($)などです。

しばしば、開始の正規表現でモード全体を定義し、モードの終了を指定する必要が無いことがあります。 例えば、数字はbegin: "\\b\\d+"で全ての数字を定義することができます。

beginが未定義の場合、 デフォルトは全ての文字列にマッチする正規表現のため、 モードはただちに終了になります。

時々、モードは自身で終了することはできませんが、 自身を含んだ親のモードで暗黙的に終了することがあります。 これはendsWithParent属性で行われます。

{
  end: /$/
  ...
},

beginKeywords

不要な繰り返しを避けるために、モードをキーワードで開始します。 beginの代わりに使われます。

{
  begin: '\\b(extends|implements) ',
  keywords: 'extends implements'
}

上記の定義は、以下のように指定することもできます。

{
  beginKeywords: 'extends implements'
}

keywords属性とは異なり、スペースで区切られた単純なキーワードリストのみを許可します。 keywordsに追加機能が必要だったり、 単にこのモードにキーワードを追加したい場合、 beginKeywordsと併せて、keywordsを指定することができます。

endsWithParent

親のモードが終了した時に、モードを終了することを示すフラグです。

よく説明で使われるのは次の例です。 CSSではセレクタに、{と}で囲まれたルールを適用します。 個々のルールは;で区切られますが、 最後のルールは;を省略することができます。

p {
  width: 100%; color: red
}

このような場合にendsWithParentが動作します。

{
  className: 'rules', begin: '{', end: '}',
  contains: [
    {className: 'rule', /* ... */ end: ';', endsWithParent: true}
  ]
}

endsParent

現在のモードが終了した直後に、親のモードを強制的に終了します。

これは、簡単に表現できる終了語句が無いモードで、適用されるサブモードがあれば、 親のモードの代わりに、サブモードから親モードを閉じることができます。

例えば、Elixirでは関数を定義する2種類の方法があります。 1つめはdoキーワードを使う方法、2つめは,を使う方法です。

def foo :clear, list do
  :ok
end

def foo, do: IO.puts "hello world"

1つめの場合、関数名の後ろのパラメータにカンマを含めることができます。 そして、関数名のみを強調したい場合は、 関数名の後に関数定義を終了するよう指定することができます。

{
  className: 'function',
  beginKeywords: 'def', end: /\B\b/,
  contains: [
    {
      className: 'title',
      begin: hljs.IDENT_RE, endsParent: true
    }
  ]
}

正規表現end: /\B\b/は、関数自体が終了にならないように指定しています。

lexemes

言語のテキストから個々の語句を抽出し、 その中からキーワードを探す正規表現を指定します。 デフォルト値hljs.IDENT_REは、ほとんどの言語で使用可能です。

{
  lexemes: /[!#@\w]+/,
  ...
},

keywords

キーワードの定義は2つの方法があります。

• 'for while if else weird_voodoo|10 ... '
  スペースで区切ったキーワードと、関連オプションをパイプで渡す方法
• {'keyword': ' ... ', 'literal': ' ... '}
  異なる種類のキーワードと、その文字列をオブジェクト形式で指定します。 指定する文字列は1つ目の形式で指定します。

詳しくはキーワードを参照してください。

{
  keywords: {
    keyword:
      'cp cpf ... '+
      ...
      'vnoremap vnoremenu ... ',
    built_in: //built in func
      'synIDtrans ... ' +
      ...
      'exp'
  },
  ...
}

illegal

不正シンボルを定義する正規表現を指定します。 パーサが不正シンボルを見つけた場合、すぐに言語解析を終了します。

{
  illegal: /#(?!!)/
  ...
}

excludeBegin, excludeEnd

モードの開始語句、終了語句をマークアップから除外します。 例えばCSSの場合、スタイルのルールは;で終了します。 しかし、視覚的には;を色付けしない方が良いでしょう。 excludeEnd: trueを指定すると、 spanタグの要素が;の前に閉じられます。

{
  begin: /\(/, end: /\)/,
  excludeBegin: true, excludeEnd: true,
  ...
}

returnBegin

開始語句を見つけたらパーサへ戻ります。 これは、親のモード内だけではなく、 サブモードのルールで解析させるような、複雑な開始語句を使う時に指定します。

事実上、パーサが戻ってくることになり、 無限ループを発生させることが出来るので、扱いに注意してください！

var IDENT_RE = '[A-Za-z$_][0-9A-Za-z$_]*';
...
{
  begin: IDENT_RE + '\\s*:', returnBegin: true,
  ...
}

returnEnd

終了語句を見つけたらパーサへ戻ります。 これは例えば、HTMLに埋め込まれたJavaScriptを解析する場合に使います。 JavaScriptのブロックは、HTML終了タグ</script>で終了します。 これはJavaScriptのルールでは解析することができません。 そこで、解析内容を親のHTMLモードに戻します。 HTMLモードは</script>どのようにするべきか分かっているはずです。

事実上、パーサが戻ってくることになり、 無限ループを発生させることが出来るので、扱いに注意してください！

{
  end: '\<\/script\>', returnEnd: true,
  ...
}

contains

モード内で検索するサブモードのリスト。 詳しくはサブモードを参照してください。

{
  contains: [
    hljs.C_BLOCK_COMMENT_MODE,
    {
      className: 'selector-id', begin: /#[A-Za-z0-9_-]+/
    },
    {
      className: 'selector-class', begin: /\.[A-Za-z0-9_-]+/
    },
    ...
  ],
  ...
}

starts

現在のモードが終了した直後に開始するモード名を指定します。 新しく開始するモードには現在のモード(終了するモード)は含まれません。

現在、この属性はHTMLに含まれるJavaScriptとCSSをハイライトするために使われています。 scriptタグとstyleタグは、 タグの内容を解析するために、それぞれの言語定義を使用するサブモードを開始します。 (subLanguageを参照してください。)

{
  starts: {
    end: '\<\/script\>', returnEnd: true,
    subLanguage: ['actionscript', 'javascript', 'handlebars', 'xml']
  }
  ...
}

variants

モードのメインの定義を、 モードの全ての属性を持ったいくつかの同様のモードに効果的に拡張します。 拡張したモードはvariantsで上書きまたは、追記します。

{
  className: 'string',
  contains: [hljs.BACKSLASH_ESCAPE],
  relevance: 0,
  variants: [
    {begin: /"/, end: /"/},
    {begin: /'/, end: /'/, relevance: 1}
  ]
}

subLanguage

モードの内容全体を別の言語でハイライトします。 この属性を使う場合、キーワードや語句等の解析ルールの定義は不要です。 またサブ言語は、テキストを自身の<span class="language-name">で囲うので、 className属性を指定しないことをお勧めします。

この属性の値は、1つまたは複数の言語をハイライトし、制御します。

• 言語名 : 明示的に特定の言語でハイライトします。
• 空の配列 : 利用可能な全ての言語を自動で検出します。
• 言語名の配列 : 指定された言語の中から自動で検出します。

{
  begin: /<\?(php)?/, end: /\?>/,
  subLanguage: 'php',
  ...
}

skip

モードのマークアップ処理をスキップし、 開始語句と終了語句とともに、親のバッファの一部として残します。 この属性は、複雑な解析が必要な場合に、 親モードのサブ言語と組み合わせて使用します。

HTML内のPHPを解析する場合、

<p><? echo 'PHP'; /* ?> */ ?></p>

コメント内の?>でPHPを終了すべきではなく、 正しい終了タグである?>を見つけるために、 /* .. */をペアとして扱う必要があります。

{
  begin: /<\?/, end: /\?>/,
  subLanguage: 'php',
  contains: [{begin: '/\\*', end: '\\*/', skip: true}]
}

skip: trueを定義しない場合、 全てのコメントをHTMLモードとして扱います。