textprop.txt For Vim バージョン 9.1. Last change: 2024 Sep 08
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.
このテキスト内の数字をハイライトするには:
テキストの上の行を挿入または削除してみると、テキストのプロパティがテキストに固
定されていることが分かる。したがって、行番号は必要に応じて調整される。
"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_add_list({props}, [{item}, ...])
複数位置にテキストプロパティを追加
prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
全てのテキストプロパティを削除
prop_find({props} [, {direction}]) テキストプロパティを検索
prop_list({lnum} [, {props}]) 行番号{lnum}のテキストプロパティを取得
prop_remove({props} [, {lnum} [, {lnum-end}]])
テキストプロパティを削除
text-prop-functions-details
prop_add() E965
prop_add({lnum}, {col}, {props})
{lnum}行{col}桁の位置にテキストプロパティを付加する。{col}はバ
イト数でカウントされる。最初の桁は1を使用する。
{lnum}が無効な場合、エラーが発生する。 E966
{col}が無効な場合、エラーが発生する。 E964
{props}は次のフィールドを持つ辞書である:
type テキストプロパティタイプ名
length テキストの長さ(バイト)。別の行に続かないプロパ
ティに対してのみ使用できる。0指定可能。
end_lnum テキスト終端(内包的)の行番号
end_col テキストの直後の桁。"length" が与えられた場合
は使用されない。{col}と "end_col" が等しい場
合、および "end_lnum" が省略されるか{lnum}と等
しい場合、これは幅ゼロのテキストプロパティであ
る。
bufnr プロパティを追加するバッファ。省略された場合、
カレントバッファが使用される
id プロパティのユーザー定義 ID。数値かつ正の値で
ある必要がある E1510。
"text" を使用する場合、"id" は存在してはなら
ず、自動的に負の数値に設定される。それ以外の場
合はゼロが使用される。
E1305
text {col} の前、または {col} がゼロの場合は行の上/
下に表示されるテキスト。ハイライトによるパディ
ング用のスペースを先頭および/または末尾に追加
する。"length", "end_lnum" および "end_col" と
一緒に使用することはできない。
詳細については virtual-text を参照。
E1294
text_align "text" が存在し、{col} がゼロの場合; テキスト
を表示する場所を指定する:
after 行末の後ろ
right ウィンドウ内で右揃え (テキストが画
面の次の行に折り返されない限り)
below 次のスクリーン行
above 行のすぐ上
省略した場合は "after" が使用される。各行に収
まる "right" プロパティは 1 つだけだが、2 つ以
上ある場合は別の行に配置される (右揃えのまま
で)。
text_padding_left E1296
"text" が存在し、{col} がゼロの場合に使用され
る。テキスト行末 ("above" と "below" の左端の
桁) とハイライトされていない仮想テキストの間の
パディング
text_wrap "text" が存在し、{col} がゼロの場合、テキスト
がぴったり合わない場合に何が起こるかを指定する:
wrap テキストを次の行に折り返す
truncate テキストを切り捨てて収める
省略時は "truncate" が使用される。
Note これは個々のテキストプロパティに適用され、
'wrap' オプションは全体の動作を設定することに
注意。
"type" を除くすべてのフィールドは任意である。
"length" と "end_lnum" または "end_col" の両方が与えられるとエ
ラーになる。1行内のプロパティに "length" または "end_col" を使
用するか、複数の行にまたがるプロパティに対して "end_lnum" と
"end_col" を使用する。
"length" または "end_col" のどちらも与えられない場合、プロパテ
ィは幅ゼロになる。これは、テキストと共にマークのように移動する
ことを意味する。もし、テキストプロパティ名が強調表示を指定する
のならば、1文字ハイライトされる。
プロパティは、テキストの最後の文字、またはその直後で終わらせる
ことができる。最後のケースでは、テキストが行に追加されると、プ
ロパティタイプに "end_incl" が設定されていない場合にも、テキス
トプロパティのサイズが増える。
プロパティが追加されたバッファで、"type" が最初に検索される。
見つからない場合は、グローバルプロパティタイプが使用される。見
つからなければエラーになる。
virtual-text
"text" が使用され、桁が非ゼロの場合、このテキストはテキストプ
ロパティの指定された開始位置に表示される。バッファ行のテキスト
は、スペースを確保するためにシフトされる。これを "virtual text"
(仮想テキスト) と呼ぶ。
桁がゼロの場合、仮想テキストはバッファテキストの上、後ろ、また
は下に表示される。"text_align" および "text_wrap" 引数によっ
て、どのように表示されるかが決定される。
仮想テキストをバッファテキストから分離するには、"text" フィー
ルドにスペースを追加するか、"text_padding_left" を使用する。
これが仮想テキストであることがユーザーに明確に分かるように必ず
ハイライトを使用すること。そうしないと、テキストが編集できない
ため非常に混乱することになる。"above" を使用する場合は、このテ
キストがその下のテキスト行に属していることを明確にする必要があ
り、"below" を使用する場合は、そのテキストがその上のテキスト行
に属していることを明確にする必要がある。
テキストは表示されるが、実際のバッファ行の一部ではないので、
カーソルをその上に置くことはできない。テキスト内でマウスをク
リックすると、カーソルはテキストの後の最初の文字か、行の最後の
文字に移動する。
テキスト中のタブやその他の制御文字はスペースに変更される (理由:
そうしないとテキストのサイズ計算が困難になる)。
負の "id" が選択され、返される。
テキストを含むテキストプロパティがサポートされる前は、非常にま
れではあるが、負の "id" を使用することができた。負の "id" はテ
キストを含むテキストプロパティ用に予約されているため、負の "id"
を使用するとエラーが発生する。テキストを含むテキストプロパティ
が既に存在する場合、負の "id" を使用すると E1293 が発生する。
負の "id" が使用され、後でテキストを含むテキストプロパティが追
加されると、 E1339 が発生する。
method としても使用できる:
戻り値の型: Number
prop_add_list({props}, [{item}, ...]) prop_add_list()
prop_add() に似ているが、バッファ内の複数位置にテキストプロパ
ティが付加される。
{props}は次のフィールドを持つ辞書である:
bufnr プロパティを追加するバッファ。省略された場合、
カレントバッファが使用される
id プロパティのユーザー定義ID。数字でなければなら
ない。省略時は0が使われる
type テキストプロパティ名
"type" を除くすべてのフィールドは任意である。
第2引数はリストのリストで、各リストはテキストの開始と終了の位
置を示す。最初の2つの項目 {lnum} と {col} はプロパティを付加す
る開始位置を、最後の2つの項目 {end-lnum} と {end-col} は付加さ
れる位置の直後を示す。
第 2 引数は項目のリストで、各 {item} はテキストの開始位置と終
了位置を指定するリストである:
[{lnum}, {col}, {end-lnum}, {end-col}]
または: [{lnum}, {col}, {end-lnum}, {end-col}, {id}]
最初の 2 つの項目 {lnum} と {col} は、プロパティが付加されるテ
キストの開始位置を指定する。
次の 2 つの項目 {end-lnum} と {end-col} は、テキストの直後の位
置を指定する。
オプションの 5 番目の項目 {id} を使用して、プロパティに別の ID
を与えることができる。省略すると、{props} の ID が使用され、何
も存在しない場合はゼロにフォールバックする。
ここで "text" フィールドを含むテキストプロパティを追加すること
はできない。
例:
method としても使用できる:
prop_clear({lnum} [, {lnum-end} [, {props}]]) prop_clear()
{lnum}行からすべてのテキストプロパティを削除する。
{lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
む)行までのすべてのテキストプロパティを削除する。
{props}に "bufnr" 項目が含まれている場合はこのバッファを使用
し、そうでない場合はカレントバッファを使用する。
method としても使用できる:
戻り値の型: Number
prop_find({props} [, {direction}]) prop_find()
{props}で指定されたテキストプロパティを検索する:
id プロパティID
type プロパティタイプ名
both "id" と "type" 両方ともに一致する
bufnr 検索するバッファ。指定時は "lnum" と"col" を指
定して開始位置を指定する必要がある。省略された
場合、カレントバッファが使用される
lnum この行から開始する(省略時はカーソル位置で開始)
col この桁から開始する(省略され "lnum" が指定され
た場合: 列1を使用する。そうでない場合はカーソ
ル位置で開始する)
skipstart 開始位置の一致を見ない
"id" または "type" のいずれかが一致すると、プロパティが一致する。
{direction}は、前方の場合は "f"、後方の場合は "b" となる。省略
すると前方検索が行われる。
一致するものが見つかった場合は、prop_list()と同様のエントリと
"lnum" エントリを併せた辞書が返される。
一致するものが見つからなければ、空の辞書が返される。
戻り値の型: dict<any>
prop_list({lnum} [, {props}]) prop_list()
{lnum}行のすべてのテキストプロパティを持つリストを返す。
{props} では以下の省略可能な項目をサポートする:
bufnr カレントバッファのかわりに指定したバッファを使
う
end_lnum {lnum} と {end_lnum} の間の行すべてのテキスト
プロパティを返す(包括的)。値が負数だとバッファ
の最終行からのオフセットとして使用される。-1は
バッファの最終行を参照する。
types プロパティのタイプ名のリスト。タイプ名のいずれ
かにマッチしたテキストプロパティだけを返す。
ids プロパティのIDのリスト。これらのIDのテキストプ
ロパティだけを返す。
プロパティは、開始桁と優先順位によって順序付けられる。
各プロパティは、次のエントリを持つ辞書である:
lnum 開始行。{lnum} と {end_lnum} の間のテキストプ
ロパティを返す場合にのみ存在する。
col 開始桁
length バイト長。改行が含まれる場合は1以上。
id プロパティID
text {col} の前に表示されるテキスト。virtual-text
プロパティにのみ存在する。
text_align virtual-text の配置プロパティ。
text_padding_left
仮想テキストに使用される左パディング。
text_wrap virtual-text を折り返すかどうかを指定する。
type プロパティタイプ名。タイプが削除された場合は省
略される
type_bufnr プロパティタイプが定義されたバッファ番号。
タイプがグローバルの場合は0を指定する
start TRUEの時はプロパティはこの行から始まる
end TRUEの時はプロパティはこの行で終わる
"start" が0の場合、プロパティは以前の行で開始され、現在行は続
きである。
"end" が0の場合、プロパティは次の行に続く。この行の後に改行が
含まれる。
エラーの時は空のリストを返す。
例:
" 5行目に置かれている全テキストプロパティを取得する
echo prop_list(5)
" バッファ4の20行目に置かれている全テキストプロパティを取得
" する
echo prop_list(20, {'bufnr': 4})
" 1行目から20行目に置かれている全テキストプロパティを取得す
" る
echo prop_list(1, {'end_lnum': 20})
" タイプが 'myprop' の全テキストプロパティを取得する
echo prop_list(1, {'types': ['myprop'],
\ 'end_lnum': -1})
" タイプが 'prop1' か 'prop2' の全テキストプロパティを取得
" する
echo prop_list(1, {'types': ['prop1', 'prop2'],
\ 'end_lnum': -1})
" IDが8の全テキストプロパティを取得する
echo prop_list(1, {'ids': [8], 'end_lnum': line('$')})
" IDが10と20の全テキストプロパティを取得する
echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1})
" バッファ4からタイプが 'myprop' かつIDが100のテキストプロ
" パティを取得する。
echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],
\ 'ids': [100], 'end_lnum': -1})
method としても使用できる:
戻り値の型: list<dict<any>> または list<any>
prop_remove() E968 E860
prop_remove({props} [, {lnum} [, {lnum-end}]])
{lnum}行から一致するテキストプロパティを削除する。
{lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
む)までの一致するテキストプロパティを削除する。
{lnum}を省略した場合、一致するテキストプロパティをすべての行か
ら削除する(これにはすべての行を調べる必要があるため、多くの行
があるバッファでは少し遅くなる)。
{props}は次のフィールドを持つ辞書である:
id このIDを持つテキストプロパティを削除する
type このタイプ名を持つテキストプロパティを削除する
types このリスト内のタイプ名を持つテキストプロパティ
を削除する
both "id" と "type"/"types" の両方が一致しなければ
ならない
bufnr カレントバッファの代わりにこのバッファを使う
all TRUEの場合、最初のテキストプロパティだけでな
く、一致するテキストプロパティをすべて削除す
る。
"type" と "types" のいずれか 1 つだけを指定できる。 E1295
プロパティは、"id" または指定されたタイプのいずれかが一致する
場合に一致する。
バッファ "bufnr" が存在しない場合はエラーメッセージが表示され
る。
バッファ "bufnr" がロードされていなければ、何も起こらない。
削除されたプロパティの数を返す。
method としても使用できる:
戻り値の型: Number
prop_type_add({name}, {props}) prop_type_add() E969 E970
テキストプロパティタイプ{name}を追加する。この名前のプロパティ
タイプがすでに存在する場合、エラーが発生する。何も返さない。
{props}は、次のオプションフィールドを持つ辞書である:
bufnr このバッファに対してのみプロパティを定義する。
バッファが削除されたときに、名前の衝突を防ぎ、
かつ、自動的にプロパティタイプをクリアする
highlight 使用するハイライトグループ名
priority 文字に複数のテキストプロパティがある場合は、優
先度が最も高いものが使用される。負の値を使用で
きる。デフォルトの優先順位は0である
combine 省略されるかTRUEの場合、ハイライトを任意の構文
ハイライトと結び付ける。FALSEの場合は構文ハイ
ライトは使用されない
override TRUE の場合、ハイライトは 'cursorline' やビジュ
アルを含む他のハイライトをオーバーライドする
start_incl TRUEの場合、開始位置の挿入はテキストプロパティ
に含まれる
end_incl TRUEの場合、終了位置の挿入はテキストプロパティ
に含まれる
method としても使用できる:
戻り値の型: Number
prop_type_change({name}, {props}) prop_type_change()
既存のテキストプロパティタイプのプロパティを変更する。この名前
のプロパティが存在しない場合、エラーが発生する。
{props}引数は prop_type_add() と似ている。
method としても使用できる:
戻り値の型: Number
prop_type_delete({name} [, {props}]) prop_type_delete()
テキストプロパティタイプ{name}を削除する。{name}型を使用するテ
キストプロパティがまだ存在する場合、それらは効果を持たず、もは
や名前で削除できなくなる。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプではなく、このバッファからプロパティタ
イプを削除する。
テキストプロパティタイプ{name}が見つからなくてもエラーにならな
い。
method としても使用できる:
戻り値の型: Number
prop_type_get({name} [, {props}]) prop_type_get()
プロパティタイプ{name}のプロパティを返す。これは、
prop_type_add() に与えられたものと同じフィールドを持つ辞書であ
る。
プロパティタイプ{name}が存在しない場合、空の辞書が返される。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプの代わりにこのバッファを使用する。
method としても使用できる:
戻り値の型: dict<any>
prop_type_list([{props}]) prop_type_list()
すべてのプロパティタイプ名のリストを返す。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプの代わりにこのバッファを使用する。
戻り値の型: list<string> または list<any>
==============================================================================
3. テキストが変更された場合 text-prop-changes
Vimはテキストプロパティをそれが付加されたテキストの上に置くように最善を尽くす。
テキストを挿入または削除するときは、変更後のプロパティもそれに従って移動する。
テキストが削除され、テキストプロパティにテキストが含まれなくなった場合は削除さ
れる。ただし、行全体が削除されない限り、幅ゼロとして定義されたテキストプロパ
ティは残る。
E275
バッファがアンロードされると、すべてのテキストプロパティがなくなる。プロパティ
をファイルに保存する方法はない。再作成することしかできない。バッファが非表示
(hidden)の場合、テキストは保持され、テキストプロパティも保持される。アンロード
されたバッファにテキストプロパティを追加することはできない。
置換モードを使用すると、文字自体が変更しても、テキストプロパティは同じ文字位置
に留まる。
テキストが変更された後にテキストのプロパティを更新するには、listener_add()
でコールバックを設置する。例えば、もしあなたのプラグインがスペルチェックをして
いるのなら、変更されたテキスト内のスペルミスをコールバックで更新することができ
る。変更されたテキストの下にプロパティが移動し、同じテキストがハイライトされる
ため、これらを更新する必要はない。
text-prop-cleared
テキストプロパティの桁が更新、コピーされない:
- setline() または Lua, Tcl または Python などのインターフェイスを介して行を
設定した場合。Vim はどのテキストが挿入または削除されたのかを知らない。
- :moveのような文脈から行ごとテキストを取り出すコマンドを使用した場合。
vim:tw=78:ts=8:noet:ft=help:norl:
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'})
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_add_list({props}, [{item}, ...])
複数位置にテキストプロパティを追加
prop_clear({lnum} [, {lnum-end} [, {bufnr}]])
全てのテキストプロパティを削除
prop_find({props} [, {direction}]) テキストプロパティを検索
prop_list({lnum} [, {props}]) 行番号{lnum}のテキストプロパティを取得
prop_remove({props} [, {lnum} [, {lnum-end}]])
テキストプロパティを削除
text-prop-functions-details
prop_add() E965
prop_add({lnum}, {col}, {props})
{lnum}行{col}桁の位置にテキストプロパティを付加する。{col}はバ
イト数でカウントされる。最初の桁は1を使用する。
{lnum}が無効な場合、エラーが発生する。 E966
{col}が無効な場合、エラーが発生する。 E964
{props}は次のフィールドを持つ辞書である:
type テキストプロパティタイプ名
length テキストの長さ(バイト)。別の行に続かないプロパ
ティに対してのみ使用できる。0指定可能。
end_lnum テキスト終端(内包的)の行番号
end_col テキストの直後の桁。"length" が与えられた場合
は使用されない。{col}と "end_col" が等しい場
合、および "end_lnum" が省略されるか{lnum}と等
しい場合、これは幅ゼロのテキストプロパティであ
る。
bufnr プロパティを追加するバッファ。省略された場合、
カレントバッファが使用される
id プロパティのユーザー定義 ID。数値かつ正の値で
ある必要がある E1510。
"text" を使用する場合、"id" は存在してはなら
ず、自動的に負の数値に設定される。それ以外の場
合はゼロが使用される。
E1305
text {col} の前、または {col} がゼロの場合は行の上/
下に表示されるテキスト。ハイライトによるパディ
ング用のスペースを先頭および/または末尾に追加
する。"length", "end_lnum" および "end_col" と
一緒に使用することはできない。
詳細については virtual-text を参照。
E1294
text_align "text" が存在し、{col} がゼロの場合; テキスト
を表示する場所を指定する:
after 行末の後ろ
right ウィンドウ内で右揃え (テキストが画
面の次の行に折り返されない限り)
below 次のスクリーン行
above 行のすぐ上
省略した場合は "after" が使用される。各行に収
まる "right" プロパティは 1 つだけだが、2 つ以
上ある場合は別の行に配置される (右揃えのまま
で)。
text_padding_left E1296
"text" が存在し、{col} がゼロの場合に使用され
る。テキスト行末 ("above" と "below" の左端の
桁) とハイライトされていない仮想テキストの間の
パディング
text_wrap "text" が存在し、{col} がゼロの場合、テキスト
がぴったり合わない場合に何が起こるかを指定する:
wrap テキストを次の行に折り返す
truncate テキストを切り捨てて収める
省略時は "truncate" が使用される。
Note これは個々のテキストプロパティに適用され、
'wrap' オプションは全体の動作を設定することに
注意。
"type" を除くすべてのフィールドは任意である。
"length" と "end_lnum" または "end_col" の両方が与えられるとエ
ラーになる。1行内のプロパティに "length" または "end_col" を使
用するか、複数の行にまたがるプロパティに対して "end_lnum" と
"end_col" を使用する。
"length" または "end_col" のどちらも与えられない場合、プロパテ
ィは幅ゼロになる。これは、テキストと共にマークのように移動する
ことを意味する。もし、テキストプロパティ名が強調表示を指定する
のならば、1文字ハイライトされる。
プロパティは、テキストの最後の文字、またはその直後で終わらせる
ことができる。最後のケースでは、テキストが行に追加されると、プ
ロパティタイプに "end_incl" が設定されていない場合にも、テキス
トプロパティのサイズが増える。
プロパティが追加されたバッファで、"type" が最初に検索される。
見つからない場合は、グローバルプロパティタイプが使用される。見
つからなければエラーになる。
virtual-text
"text" が使用され、桁が非ゼロの場合、このテキストはテキストプ
ロパティの指定された開始位置に表示される。バッファ行のテキスト
は、スペースを確保するためにシフトされる。これを "virtual text"
(仮想テキスト) と呼ぶ。
桁がゼロの場合、仮想テキストはバッファテキストの上、後ろ、また
は下に表示される。"text_align" および "text_wrap" 引数によっ
て、どのように表示されるかが決定される。
仮想テキストをバッファテキストから分離するには、"text" フィー
ルドにスペースを追加するか、"text_padding_left" を使用する。
これが仮想テキストであることがユーザーに明確に分かるように必ず
ハイライトを使用すること。そうしないと、テキストが編集できない
ため非常に混乱することになる。"above" を使用する場合は、このテ
キストがその下のテキスト行に属していることを明確にする必要があ
り、"below" を使用する場合は、そのテキストがその上のテキスト行
に属していることを明確にする必要がある。
テキストは表示されるが、実際のバッファ行の一部ではないので、
カーソルをその上に置くことはできない。テキスト内でマウスをク
リックすると、カーソルはテキストの後の最初の文字か、行の最後の
文字に移動する。
テキスト中のタブやその他の制御文字はスペースに変更される (理由:
そうしないとテキストのサイズ計算が困難になる)。
負の "id" が選択され、返される。
テキストを含むテキストプロパティがサポートされる前は、非常にま
れではあるが、負の "id" を使用することができた。負の "id" はテ
キストを含むテキストプロパティ用に予約されているため、負の "id"
を使用するとエラーが発生する。テキストを含むテキストプロパティ
が既に存在する場合、負の "id" を使用すると E1293 が発生する。
負の "id" が使用され、後でテキストを含むテキストプロパティが追
加されると、 E1339 が発生する。
method としても使用できる:
GetLnum()->prop_add(col, props)
戻り値の型: Number
prop_add_list({props}, [{item}, ...]) prop_add_list()
prop_add() に似ているが、バッファ内の複数位置にテキストプロパ
ティが付加される。
{props}は次のフィールドを持つ辞書である:
bufnr プロパティを追加するバッファ。省略された場合、
カレントバッファが使用される
id プロパティのユーザー定義ID。数字でなければなら
ない。省略時は0が使われる
type テキストプロパティ名
"type" を除くすべてのフィールドは任意である。
第2引数はリストのリストで、各リストはテキストの開始と終了の位
置を示す。最初の2つの項目 {lnum} と {col} はプロパティを付加す
る開始位置を、最後の2つの項目 {end-lnum} と {end-col} は付加さ
れる位置の直後を示す。
第 2 引数は項目のリストで、各 {item} はテキストの開始位置と終
了位置を指定するリストである:
[{lnum}, {col}, {end-lnum}, {end-col}]
または: [{lnum}, {col}, {end-lnum}, {end-col}, {id}]
最初の 2 つの項目 {lnum} と {col} は、プロパティが付加されるテ
キストの開始位置を指定する。
次の 2 つの項目 {end-lnum} と {end-col} は、テキストの直後の位
置を指定する。
オプションの 5 番目の項目 {id} を使用して、プロパティに別の ID
を与えることができる。省略すると、{props} の ID が使用され、何
も存在しない場合はゼロにフォールバックする。
ここで "text" フィールドを含むテキストプロパティを追加すること
はできない。
例:
call prop_add_list(#{type: 'MyProp', id: 2},
\ [[1, 4, 1, 7],
\ [1, 15, 1, 20],
\ [2, 30, 3, 30]])
\ [[1, 4, 1, 7],
\ [1, 15, 1, 20],
\ [2, 30, 3, 30]])
method としても使用できる:
GetProp()->prop_add_list([[1, 1, 1, 2], [1, 4, 1, 8]])
prop_clear({lnum} [, {lnum-end} [, {props}]]) prop_clear()
{lnum}行からすべてのテキストプロパティを削除する。
{lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
む)行までのすべてのテキストプロパティを削除する。
{props}に "bufnr" 項目が含まれている場合はこのバッファを使用
し、そうでない場合はカレントバッファを使用する。
method としても使用できる:
GetLnum()->prop_clear()
戻り値の型: Number
prop_find({props} [, {direction}]) prop_find()
{props}で指定されたテキストプロパティを検索する:
id プロパティID
type プロパティタイプ名
both "id" と "type" 両方ともに一致する
bufnr 検索するバッファ。指定時は "lnum" と"col" を指
定して開始位置を指定する必要がある。省略された
場合、カレントバッファが使用される
lnum この行から開始する(省略時はカーソル位置で開始)
col この桁から開始する(省略され "lnum" が指定され
た場合: 列1を使用する。そうでない場合はカーソ
ル位置で開始する)
skipstart 開始位置の一致を見ない
"id" または "type" のいずれかが一致すると、プロパティが一致する。
{direction}は、前方の場合は "f"、後方の場合は "b" となる。省略
すると前方検索が行われる。
一致するものが見つかった場合は、prop_list()と同様のエントリと
"lnum" エントリを併せた辞書が返される。
一致するものが見つからなければ、空の辞書が返される。
戻り値の型: dict<any>
prop_list({lnum} [, {props}]) prop_list()
{lnum}行のすべてのテキストプロパティを持つリストを返す。
{props} では以下の省略可能な項目をサポートする:
bufnr カレントバッファのかわりに指定したバッファを使
う
end_lnum {lnum} と {end_lnum} の間の行すべてのテキスト
プロパティを返す(包括的)。値が負数だとバッファ
の最終行からのオフセットとして使用される。-1は
バッファの最終行を参照する。
types プロパティのタイプ名のリスト。タイプ名のいずれ
かにマッチしたテキストプロパティだけを返す。
ids プロパティのIDのリスト。これらのIDのテキストプ
ロパティだけを返す。
プロパティは、開始桁と優先順位によって順序付けられる。
各プロパティは、次のエントリを持つ辞書である:
lnum 開始行。{lnum} と {end_lnum} の間のテキストプ
ロパティを返す場合にのみ存在する。
col 開始桁
length バイト長。改行が含まれる場合は1以上。
id プロパティID
text {col} の前に表示されるテキスト。virtual-text
プロパティにのみ存在する。
text_align virtual-text の配置プロパティ。
text_padding_left
仮想テキストに使用される左パディング。
text_wrap virtual-text を折り返すかどうかを指定する。
type プロパティタイプ名。タイプが削除された場合は省
略される
type_bufnr プロパティタイプが定義されたバッファ番号。
タイプがグローバルの場合は0を指定する
start TRUEの時はプロパティはこの行から始まる
end TRUEの時はプロパティはこの行で終わる
"start" が0の場合、プロパティは以前の行で開始され、現在行は続
きである。
"end" が0の場合、プロパティは次の行に続く。この行の後に改行が
含まれる。
エラーの時は空のリストを返す。
例:
" 5行目に置かれている全テキストプロパティを取得する
echo prop_list(5)
" バッファ4の20行目に置かれている全テキストプロパティを取得
" する
echo prop_list(20, {'bufnr': 4})
" 1行目から20行目に置かれている全テキストプロパティを取得す
" る
echo prop_list(1, {'end_lnum': 20})
" タイプが 'myprop' の全テキストプロパティを取得する
echo prop_list(1, {'types': ['myprop'],
\ 'end_lnum': -1})
" タイプが 'prop1' か 'prop2' の全テキストプロパティを取得
" する
echo prop_list(1, {'types': ['prop1', 'prop2'],
\ 'end_lnum': -1})
" IDが8の全テキストプロパティを取得する
echo prop_list(1, {'ids': [8], 'end_lnum': line('$')})
" IDが10と20の全テキストプロパティを取得する
echo prop_list(1, {'ids': [10, 20], 'end_lnum': -1})
" バッファ4からタイプが 'myprop' かつIDが100のテキストプロ
" パティを取得する。
echo prop_list(1, {'bufnr': 4, 'types': ['myprop'],
\ 'ids': [100], 'end_lnum': -1})
method としても使用できる:
GetLnum()->prop_list()
戻り値の型: list<dict<any>> または list<any>
prop_remove() E968 E860
prop_remove({props} [, {lnum} [, {lnum-end}]])
{lnum}行から一致するテキストプロパティを削除する。
{lnum-end}が指定された場合、{lnum}行から{lnum-end}(その行を含
む)までの一致するテキストプロパティを削除する。
{lnum}を省略した場合、一致するテキストプロパティをすべての行か
ら削除する(これにはすべての行を調べる必要があるため、多くの行
があるバッファでは少し遅くなる)。
{props}は次のフィールドを持つ辞書である:
id このIDを持つテキストプロパティを削除する
type このタイプ名を持つテキストプロパティを削除する
types このリスト内のタイプ名を持つテキストプロパティ
を削除する
both "id" と "type"/"types" の両方が一致しなければ
ならない
bufnr カレントバッファの代わりにこのバッファを使う
all TRUEの場合、最初のテキストプロパティだけでな
く、一致するテキストプロパティをすべて削除す
る。
"type" と "types" のいずれか 1 つだけを指定できる。 E1295
プロパティは、"id" または指定されたタイプのいずれかが一致する
場合に一致する。
バッファ "bufnr" が存在しない場合はエラーメッセージが表示され
る。
バッファ "bufnr" がロードされていなければ、何も起こらない。
削除されたプロパティの数を返す。
method としても使用できる:
GetProps()->prop_remove()
戻り値の型: Number
prop_type_add({name}, {props}) prop_type_add() E969 E970
テキストプロパティタイプ{name}を追加する。この名前のプロパティ
タイプがすでに存在する場合、エラーが発生する。何も返さない。
{props}は、次のオプションフィールドを持つ辞書である:
bufnr このバッファに対してのみプロパティを定義する。
バッファが削除されたときに、名前の衝突を防ぎ、
かつ、自動的にプロパティタイプをクリアする
highlight 使用するハイライトグループ名
priority 文字に複数のテキストプロパティがある場合は、優
先度が最も高いものが使用される。負の値を使用で
きる。デフォルトの優先順位は0である
combine 省略されるかTRUEの場合、ハイライトを任意の構文
ハイライトと結び付ける。FALSEの場合は構文ハイ
ライトは使用されない
override TRUE の場合、ハイライトは 'cursorline' やビジュ
アルを含む他のハイライトをオーバーライドする
start_incl TRUEの場合、開始位置の挿入はテキストプロパティ
に含まれる
end_incl TRUEの場合、終了位置の挿入はテキストプロパティ
に含まれる
method としても使用できる:
GetPropName()->prop_type_add(props)
戻り値の型: Number
prop_type_change({name}, {props}) prop_type_change()
既存のテキストプロパティタイプのプロパティを変更する。この名前
のプロパティが存在しない場合、エラーが発生する。
{props}引数は prop_type_add() と似ている。
method としても使用できる:
GetPropName()->prop_type_change(props)
戻り値の型: Number
prop_type_delete({name} [, {props}]) prop_type_delete()
テキストプロパティタイプ{name}を削除する。{name}型を使用するテ
キストプロパティがまだ存在する場合、それらは効果を持たず、もは
や名前で削除できなくなる。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプではなく、このバッファからプロパティタ
イプを削除する。
テキストプロパティタイプ{name}が見つからなくてもエラーにならな
い。
method としても使用できる:
GetPropName()->prop_type_delete()
戻り値の型: Number
prop_type_get({name} [, {props}]) prop_type_get()
プロパティタイプ{name}のプロパティを返す。これは、
prop_type_add() に与えられたものと同じフィールドを持つ辞書であ
る。
プロパティタイプ{name}が存在しない場合、空の辞書が返される。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプの代わりにこのバッファを使用する。
method としても使用できる:
GetPropName()->prop_type_get()
戻り値の型: dict<any>
prop_type_list([{props}]) prop_type_list()
すべてのプロパティタイプ名のリストを返す。
{props}には "bufnr" 項目を含めることができる。指定すると、グ
ローバルプロパティタイプの代わりにこのバッファを使用する。
戻り値の型: list<string> または list<any>
==============================================================================
3. テキストが変更された場合 text-prop-changes
Vimはテキストプロパティをそれが付加されたテキストの上に置くように最善を尽くす。
テキストを挿入または削除するときは、変更後のプロパティもそれに従って移動する。
テキストが削除され、テキストプロパティにテキストが含まれなくなった場合は削除さ
れる。ただし、行全体が削除されない限り、幅ゼロとして定義されたテキストプロパ
ティは残る。
E275
バッファがアンロードされると、すべてのテキストプロパティがなくなる。プロパティ
をファイルに保存する方法はない。再作成することしかできない。バッファが非表示
(hidden)の場合、テキストは保持され、テキストプロパティも保持される。アンロード
されたバッファにテキストプロパティを追加することはできない。
置換モードを使用すると、文字自体が変更しても、テキストプロパティは同じ文字位置
に留まる。
テキストが変更された後にテキストのプロパティを更新するには、listener_add()
でコールバックを設置する。例えば、もしあなたのプラグインがスペルチェックをして
いるのなら、変更されたテキスト内のスペルミスをコールバックで更新することができ
る。変更されたテキストの下にプロパティが移動し、同じテキストがハイライトされる
ため、これらを更新する必要はない。
text-prop-cleared
テキストプロパティの桁が更新、コピーされない:
- setline() または Lua, Tcl または Python などのインターフェイスを介して行を
設定した場合。Vim はどのテキストが挿入または削除されたのかを知らない。
- :moveのような文脈から行ごとテキストを取り出すコマンドを使用した場合。
vim:tw=78:ts=8:noet:ft=help:norl: