本文へスキップ
`Ctrl`+`K`

# 7.16.11. `highlight_html`

Added in version 4.0.5.

## 7.16.11.1. 概要

`highlight_html` は対象テキストをタグ付けします。検索文字列をハイライトさせるために利用することができます。タグ付けされたテキストはHTML中に埋め込みやすいように処理されています。`<` や `>` などの特殊文字は &lt; や &gt; にエスケープされています。キーワードは `<span class="keyword">` と `</span>` で囲まれています。たとえば、 `I am a groonga user. <3` という対象テキストのキーワード `groonga` でタグ付けされたテキストは `I am a <span class="keyword">groonga</span> user. &lt;3` となります。

## 7.16.11.2. 構文

この関数の引数は1つから2つの引数を受け取ります。:

    highlight_html(text)
    highlight_html(text, {"option": "value of option"})

## 7.16.11.3. 使い方

使い方を示すために使うスキーマ定義とサンプルデータは以下の通りです。

実行例:

    table_create Entries TABLE_NO_KEY
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Entries body COLUMN_SCALAR ShortText
    # [[0,1337566253.89858,0.000355720520019531],true]
    table_create Terms TABLE_PAT_KEY ShortText --default_tokenizer TokenBigram --normalizer NormalizerAuto
    # [[0,1337566253.89858,0.000355720520019531],true]
    column_create Terms document_index COLUMN_INDEX|WITH_POSITION Entries body
    # [[0,1337566253.89858,0.000355720520019531],true]
    load --table Entries
    [
    {"body": "Mroonga is a ＭｙＳＱＬ storage engine based on Groonga. <b>Rroonga</b> is a Ruby binding of Groonga."}
    ]
    # [[0,1337566253.89858,0.000355720520019531],1]

10.0.6より前のバージョンでは、`highlight_html` は select コマンドの `--output_columns` 内でのみ指定できますが、10.0.6以降は、 logical_select コマンドの `--output_columns` 内でも使用できます。

`highlight_html` を使うには コマンドバージョン 2以降を使う必要があります。

また、 `--query` と `--filter` オプションも指定する必要があります。（どちらか一方でも構いません。）これは、 `--query` と `--filter` オプションからキーワードを抽出しているためです。

以下の例は `--query "groonga mysql"` を使っています。この場合は、キーワードとして `groonga` と `mysql` を使います。

実行例:

    select Entries --output_columns --match_columns body --query 'groonga mysql' --output_columns 'highlight_html(body)' --command_version 2
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "Mroonga is a <span class=\"keyword\">ＭｙＳＱＬ</span> storage engine based on <span class=\"keyword\">Groonga</span>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <span class=\"keyword\">Groonga</span>."
    #       ]
    #     ]
    #   ]
    # ]

キーワードとテキストは `NormalizerAuto` ノーマライザーで正規化されてタグ付けのためにスキャンされます。

`--query "groonga mysql"` は最初のレコードにマッチします。`highlight_html(body)` は、テキスト中に含まれるキーワード `groonga` と `mysql` を `<span class="keyword">` と `</span>` で囲みます。

カラムの代わりに文字列リテラルを指定することもできます。

実行例:

    select Entries --output_columns 'highlight_html("Groonga is very fast fulltext search engine.")' --command_version 2 --match_columns body --query "groonga"
    # [
    #   [
    #     0,
    #     1337566253.89858,
    #     0.000355720520019531
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "<span class=\"keyword\">Groonga</span> is very fast fulltext search engine."
    #       ]
    #     ]
    #   ]
    # ]

`sequential_class_tag_mode` を使うことで、それぞれのキーワードで異なるスタイル(例えば、背景色)を使えます。

実行例:

    select Entries --match_columns body --query 'groonga OR mroonga' --output_columns 'highlight_html(body, {"sequential_class_tag_mode": true})'
    # [
    #   [
    #     0,
    #     1686038572.355064,
    #     0.002784013748168945
    #   ],
    #   [
    #     [
    #       [
    #         1
    #       ],
    #       [
    #         [
    #           "highlight_html",
    #           null
    #         ]
    #       ],
    #       [
    #         "<mark class=\"keyword-0\">Mroonga</mark> is a ＭｙＳＱＬ storage engine based on <mark class=\"keyword-1\">Groonga</mark>. &lt;b&gt;Rroonga&lt;/b&gt; is a Ruby binding of <mark class=\"keyword-1\">Groonga</mark>."
    #       ]
    #     ]
    #   ]
    # ]

## 7.16.11.4. 引数

このセクションではすべての引数について説明します。

### 7.16.11.4.1. 必須引数

必須の引数は1つです。

#### 7.16.11.4.1.1. `text`

HTMLでハイライトする対象のテキストです。

### 7.16.11.4.2. 省略可能引数

#### 7.16.11.4.2.1. `{"sequential_class_tag_mode": true}`

Added in version 13.0.2.

`sequential_class_tag_mode` のデフォルト値は `false` です。`sequential_class_tag_mode` が `true` の場合、それぞれのキーワードで異なるスタイル(例えば、背景色)を使えます。

`sequential_class_tag_mode` が `true` の場合、classタグは今の所 `<mark class="keyword-%d">/<mark>` となります。

## 7.16.11.5. 戻り値

`highlight_html` はタグ付の文字列もしくは null を返します。`highlight_html` は該当するキーワードがない場合に null を返します。

## 7.16.11.6. 参考

- select

- logical_select

- highlight_full