vim-jp / vimdoc-ja / textprop

textprop - Vim日本語ドキュメント

メインヘルプファイルに戻る English | 日本語 | 編集
textprop.txt  For Vim バージョン 8.1.  Last change: 2019 Oct 23


                VIMリファレンスマニュアル    by Bram Moolenaar


プロパティが付加されたテキストを表示します。    textprop text-properties


1. 前書き                       text-prop-intro
2. 関数                         text-prop-functions
3. テキストが変更された場合     text-prop-changes


{Vimが +textprop 機能無効でコンパイルされたときはテキストプロパティを使用で
きません}

==============================================================================
1. 前書き                                               text-prop-intro

テキストプロパティは、バッファ内のテキストに付加することができます。それらはテ
キストとともに移動します: 行が削除または挿入された場合、プロパティはそれらが付
加されているテキストと共に移動します。テキストプロパティの前の行にテキストを挿
入/削除する場合も同様です。また、テキストプロパティ内にテキストを挿入/削除する
と、サイズが増減します。

テキストプロパティの主な用途は、テキストを強調表示することです。これは、構文ハ
イライトの置き換えと見ることができます。テキストと一致するようにパターンを定義
する代わりに、スクリプトによって、おそらく外部パーサーの出力を使用して強調表示
が設定されます。これは、画面を再描画するたびにではなく、一度だけおこなえば良い
ため、テキストプロパティを付加する最初のコスト以降ははるかに高速になります。

テキストプロパティは、テキストを識別するための他の目的にも使用できます。たとえ
ば、関数名にテキストプロパティを追加すると、検索を定義して次/前の関数にジャン
プすることができます。

テキストプロパティは、特定の行と桁に付加され、指定された長さを持ちます。プロパ
ティは複数の行にまたがることができます。

テキストプロパティには、次のフィールドがあります:
        "id"            必要に応じて使われる番号
        "type"          プロパティタイプ名


プロパティタイプ
                                                        E971
テキストプロパティは、通常、テキストをハイライトする方法を定義するプロパティタ
イプ名を持ちます。プロパティタイプには、次のエントリを含めることができます:
        "highlight"     使用するハイライトグループ名
        "combine"       TRUEの場合はテキストプロパティのハイライトが構文ハイラ
                        イトと組み合わされ、省略されるかFALSEの場合はテキスト
                        プロパティのハイライトが構文ハイライトに置き換わりま
                        す。
        "priority"      プロパティが重なる場合は、優先度の高いものが使用されま
                        す。
        "start_incl"    TRUEの場合、開始位置の挿入はテキストプロパティに含まれ
                        ます。
        "end_incl"      TRUEの場合、終了位置の挿入はテキストプロパティに含まれ
                        ます。




バッファの11行目にこのテキスト(インデントを除く)があるとします:

        The number 123 is smaller than 4567.

このテキスト内の数字をハイライトするには:
        call prop_type_add('number', {'highlight': 'Constant'})
        call prop_add(11, 12, {'length': 3, 'type': 'number'})
        call prop_add(11, 32, {'length': 4, 'type': 'number'})

テキストの上の行を挿入または削除してみると、テキストのプロパティがテキストに固
定されていることが分かります。したがって、行番号は必要に応じて調整されます。

"start_incl" と "end_incl" を設定すると、空白がテキストを囲む場合に便利です。
例えば、関数名のために。falseを使用すると、文字列を囲む引用符などの特定の文字
で開始または終了する場合に便利です。

        func FuncName(arg)
             ^^^^^^^^        start_incl と end_incl が設定されたプロパティ

        var = "text";
              ^^^^^^         start_incl と end_incl が設定されていないプロパ
                             ティ

しかしながら、テキストが挿入または削除されると、テキストを解析してテキストプロ
パティを更新する必要があります。しかし、これは非同期で行うことができます。


内部エラー E967

E967 が表示された場合は、バグを報告してください。Githubでできます:
https://github.com/vim/vim/issues/new

==============================================================================
2. 関数                                                 text-prop-functions

テキストプロパティタイプの操作:

prop_type_add({name}{props})          新しいプロパティタイプを定義
prop_type_change({name}{props})       既存のプロパティタイプを変更
prop_type_delete({name} [, {props}])    プロパティタイプを削除
prop_type_get([{name} [, {props}])      プロパティタイプの値を取得
prop_type_list([{props}])               プロパティタイプ一覧を取得


テキストプロパティの操作:

prop_add({lnum}{col}{props})        テキストプロパティを追加
prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
                                        全てのテキストプロパティを削除
prop_find({props} [, {direction}])      テキストプロパティを検索
prop_list({lnum} [, {props})            行番号{lnum}のテキストプロパティを取得
prop_remove({props} [, {lnum} [, {lnum-end}]])
                                        テキストプロパティを削除

                                                prop_add() E965
prop_add({lnum}{col}{props})
                {lnum}{col}桁の位置にテキストプロパティを付加する。{col}はバ
                イト数でカウントされる。最初の桁は1を使用する。
                {lnum}が無効な場合、エラーが発生する。 E966
                {col}が無効な場合、エラーが発生する。 E964

                {props}は次のフィールドを持つ辞書である:
                   length       テキストの長さ(バイト)。別の行に続かないプロパ
                                ティに対してのみ使用できる。0指定可能。
                   end_lnum     テキスト終端の行番号
                   end_col      テキストの直後の桁。"length" が与えられた場合
                                は使用されない。{col}と "end_col" が等しい場
                                合、および "end_lnum" が省略されるか{lnum}と等
                                しい場合、これは幅ゼロのテキストプロパティであ
                                る。
                   bufnr        プロパティを追加するバッファ。省略された場合、
                                カレントバッファが使用される
                   id           プロパティのユーザー定義ID。省略時は0が使われ
                                る
                   type         テキストプロパティ名
                "type" を除くすべてのフィールドは任意である。

                "length" と "end_lnum" または "end_col" の両方が与えられるとエ
                ラーになる。1行内のプロパティに "length" または "end_col" を使
                用するか、複数の行にまたがるプロパティに対して "end_lnum" と
                "end_col" を使用する。
                "length" または "end_col" のどちらも与えられない場合、プロパ
                ティは幅ゼロになる。これは、強調表示されないが、テキストと共に
                マークのように移動することを意味する。
                プロパティは、テキストの最後の文字、またはその直後で終わらせる
                ことができる。最後のケースでは、テキストが行に追加されると、プ
                ロパティタイプに "end_incl" が設定されていない場合にも、テキス
                トプロパティのサイズが増える。

                プロパティが追加されたバッファで、"type" が最初に検索される。
                見つからない場合は、グローバルプロパティタイプが使用される。見
                つからなければエラーになる。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetLnum()->prop_add(col, props)


prop_clear({lnum} [, {lnum-end} [, {props}]])           prop_clear()
                {lnum}行からすべてのテキストプロパティを削除する。
                {lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
                む)行までのすべてのテキストプロパティを削除する。

                {props}に "bufnr" 項目が含まれている場合はこのバッファを使用
                し、そうでない場合はカレントバッファを使用する。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetLnum()->prop_clear()

                                                        prop_find()
prop_find({props} [, {direction}])
                まだ実装されていない。 {not implemented yet}
                {props}で指定されたテキストプロパティを検索する:
                   id           プロパティID
                   type         プロパティタイプ名
                   bufnr        検索するバッファ。指定時は "lnum" と"col" を指
                                定して開始位置を指定する必要がある。省略された
                                場合、カレントバッファが使用される
                   lnum         この行から開始する(省略時はカーソル位置で開始)
                   col          この桁から開始する(省略され "lnum" が指定され
                                た場合:  列1を使用する。そうでない場合はカーソ
                                ル位置で開始する)
                   skipstart    開始位置の一致を見ない

                {direction}は、前方の場合は "f"、後方の場合は "b" となる。省略
                すると前方検索が行われる。

                一致するものが見つかった場合は、prop_list()と同様のエントリと
                "lnum" エントリを併せた辞書が返される。
                一致するものが見つからなければ、空の辞書が返される。

                テキストプロパティについては、text-properties を参照。


prop_list({lnum} [, {props}])                           prop_list()
                {lnum}行のすべてのテキストプロパティを持つリストを返す。

                {props}に "bufnr" 項目が含まれている場合は、カレントバッファの
                代わりにこのバッファを使用する。

                プロパティは、開始桁と優先順位によって順序付けられる。
                各プロパティは、次のエントリを持つ辞書である:
                   col          開始桁
                   length       バイト長。改行が含まれる場合は1以上。
                   id           プロパティID
                   type         プロパティタイプ名。タイプが削除された場合は省
                                略される
                   start        TRUEの時はプロパティはこの行から始まる
                   end          TRUEの時はプロパティはこの行で終わる

                "start" が0の場合、プロパティは以前の行で開始され、現在行は続
                きである。
                "end" が0の場合、プロパティは次の行に続く。この行の後に改行が
                含まれる。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetLnum()->prop_list()


                                                prop_remove() E968
prop_remove({props} [, {lnum} [, {lnum-end}]])
                {lnum}行から一致するテキストプロパティを削除する。
                {lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
                む)までの一致するテキストプロパティを削除する。
                {lnum}を省略した場合、一致するテキストプロパティをすべての行か
                ら削除する。

                {props}は次のフィールドを持つ辞書である:
                   id           このIDを持つテキストプロパティを削除する
                   type         このタイプ名を持つテキストプロパティを削除する
                   bufnr        カレントバッファの代わりにこのバッファを使う
                   all          TRUEの場合、最初のテキストプロパティだけでな
                                く、一致するテキストプロパティをすべて削除す
                                る。
                "id" または "type" のどちらかが一致するとプロパティが一致する。
                バッファ "bufnr" が存在しない場合はエラーメッセージが表示され
                る。
                バッファ "bufnr" がロードされていなければ、何も起こらない。

                削除されたプロパティの数を返す。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetProps()->prop_remove()


prop_type_add({name}{props})          prop_type_add() E969 E970
                テキストプロパティタイプ{name}を追加する。この名前のプロパティ
                タイプがすでに存在する場合、エラーが発生する。何も返さない。
                {props}は、次のオプションフィールドを持つ辞書である:
                   bufnr        このバッファに対してのみプロパティを定義する。
                                バッファが削除されたときに、名前の衝突を防ぎ、
                                かつ、自動的にプロパティタイプをクリアする
                   highlight    使用するハイライトグループ名
                   priority     文字に複数のテキストプロパティがある場合は、優
                                先度が最も高いものが使用される。負の値を使用で
                                きる。デフォルトの優先順位は0である
                   combine      TRUEの場合、ハイライトを任意の構文ハイライトと
                                結び付ける。省略するかFALSEの場合は構文ハイラ
                                イトは使用されない
                   start_incl   TRUEの場合、開始位置の挿入はテキストプロパティ
                                に含まれる
                   end_incl     TRUEの場合、終了位置の挿入はテキストプロパティ
                                に含まれる

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetPropName()->prop_type_add(props)

prop_type_change({name}{props})                       prop_type_change()
                既存のテキストプロパティタイプのプロパティを変更する。この名前
                のプロパティが存在しない場合、エラーが発生する。
                {props}引数は prop_type_add() と似ている。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetPropName()->prop_type_change(props)

prop_type_delete({name} [, {props}])                    prop_type_delete()
                テキストプロパティタイプ{name}を削除する。{name}型を使用するテ
                キストプロパティがまだ存在する場合、それらは効果を持たず、もは
                や名前で削除できなくなる。

                {props}には "bufnr" 項目を含めることができる。指定すると、グ
                ローバルプロパティタイプではなく、このバッファからプロパティタ
                イプを削除する。

                テキストプロパティタイプ{name}が見つからなくてもエラーにならな
                い。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetPropName()->prop_type_delete()

prop_type_get([{name} [, {props}])                      prop_type_get()
                プロパティタイプ{name}のプロパティを返す。これは、
                prop_type_add() に与えられたものと同じフィールドを持つ辞書であ
                る。
                プロパティタイプ{name}が存在しない場合、空の辞書が返される。

                {props}には "bufnr" 項目を含めることができる。指定すると、グ
                ローバルプロパティタイプの代わりにこのバッファを使用する。

                テキストプロパティについては、text-properties を参照。

                method としても使用できる:
                        GetPropName()->prop_type_get()

prop_type_list([{props}])                               prop_type_list()
                すべてのプロパティタイプ名のリストを返す。

                {props}には "bufnr" 項目を含めることができる。指定すると、グ
                ローバルプロパティタイプの代わりにこのバッファを使用する。

                テキストプロパティについては、text-properties を参照。


==============================================================================
3. テキストが変更された場合                     text-prop-changes

Vimはテキストプロパティをそれが付加されたテキストの上に置くように最善を尽くし
ます。 テキストを挿入または削除するときは、変更後のプロパティもそれに従って移
動します。

テキストが削除され、テキストプロパティにテキストが含まれなくなった場合は削除さ
れます。 ただし、行全体が削除されない限り、幅ゼロとして定義されたテキストプロ
パティは残ります。
                                                                E275
バッファがアンロードされると、すべてのテキストプロパティがなくなる。プロパティ
をファイルに保存する方法はない。再作成することしかできない。バッファが非表示
(hidden)の場合、テキストは保持され、テキストプロパティも保持される。アンロード
されたバッファにテキストプロパティを追加することはできない。

置換モードを使用すると、文字自体が変更しても、テキストプロパティは同じ文字位置
に留まります。

テキストが変更された後にテキストのプロパティを更新するには、listener_add()
でコールバックを設置します。例えば、もしあなたのプラグインがスペルチェックをし
ているのなら、変更されたテキスト内のスペルミスをコールバックで更新することがで
きます。変更されたテキストの下にプロパティが移動し、同じテキストがハイライトさ
れるため、これらを更新する必要はありません。


テキストプロパティの桁が更新されません:

setline() または Lua, Tcl または Python などのインターフェイスを介して行を
  設定した場合。Vimはどのテキストが挿入または削除されたのかを知りません。


 vim:tw=78:ts=8:noet:ft=help:norl: