*textprop.txt* For Vim バージョン 8.1. Last change: 2019 Nov 12
VIMリファレンスマニュアル by Bram Moolenaar
プロパティが付加されたテキストを表示します。
| 1. 前書き | |text-prop-intro| |
| 2. 函數 | |text-prop-functions| |
| 3. テキストが變更された場合 | |text-prop-changes| |
{Vim が |+textprop| 機能無效でコンパイルされたときはテキストプロパティを使用できません}
テキストプロパティは、バッファ內のテキストに付加することができます。それらはテキストとともに移動します: 行が削除または插入された場合、プロパティはそれらが付加されてゐるテキストと共に移動します。テキストプロパティの前の行にテキストを插入/削除する場合も同樣です。また、テキストプロパティ內にテキストを插入/削除すると、サイズが增減します。
テキストプロパティの主な用途は、テキストを强調表示することです。これは、構文ハイライトの置き換へと見ることができます。テキストと一致するやうにパターンを定義する代はりに、スクリプトによつて、おそらく外部パーサーの出力を使用して强調表示が設定されます。これは、畫面を再描畫するたびにではなく、一度だけおこなへば良いため、テキストプロパティを付加する最初のコスト以降ははるかに高速になります。
テキストプロパティは、テキストを識別するための他の目的にも使用できます。たとへば、函數名にテキストプロパティを追加すると、檢索を定義して次/前の函數にジャンプすることができます。
テキストプロパティは、特定の行と桁に付加され、指定された長さを持ちます。プロパティは複數の行にまたがることができます。
テキストプロパティには、次のフィールドがあります:
| "id" | 必要に應じて使はれる番號 |
| "type" | プロパティタイプ名 |
テキストプロパティは、通常、テキストをハイライトする方法を定義するプロパティタイプ名を持ちます。プロパティタイプには、次のエントリを含めることができます:
| "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 が表示された場合は、バグを報告してください。Githubでできます:
https://github.com/vim/vim/issues/new
| 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}]]) | テキストプロパティを削除 |
{lnum} 行 {col} 桁の位置にテキストプロパティを付加する。{col} はバイト數でカウントされる。最初の桁は 1 を使用する。
{lnum} が無效な場合、エラーが發生する。
{col} が無效な場合、エラーが發生する。
{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)
{lnum} 行からすべてのテキストプロパティを削除する。{lnum-end} が指定された場合、{lnum} 行から {lnum-end} (その行を含む) 行までのすべてのテキストプロパティを削除する。
{props} に "bufnr" 項目が含まれてゐる場合はこのバッファを使用し、さうでない場合はカレントバッファを使用する。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetLnum()->prop_clear()
{まだ實裝されてゐません}
{props} で指定されたテキストプロパティを檢索する:
| id | プロパティ ID |
| type | プロパティタイプ名 |
| bufnr | 檢索するバッファ。指定時は "lnum" と"col" を指定して開始位置を指定する必要がある。省略された場合、カレントバッファが使用される |
| lnum | この行から開始する (省略時はカーソル位置で開始) |
| col | この桁から開始する (省略され "lnum" が指定された場合: 列 1 を使用する。さうでない場合はカーソル位置で開始する) |
| skipstart | 開始位置の一致を見ない |
{direction} は、前方の場合は "f"、後方の場合は "b" となる。省略すると前方檢索が行はれる。
一致するものが見つかつた場合は、prop_list() と同樣のエントリと "lnum" エントリを倂せた辭書が返される。一致するものが見つからなければ、空の辭書が返される。
テキストプロパティについては、|text-properties| を參照。
{lnum} 行のすべてのテキストプロパティを持つリストを返す。
{props} に "bufnr" 項目が含まれてゐる場合は、カレントバッファの代はりにこのバッファを使用する。
プロパティは、開始桁と優先順位によつて順序付けられる。各プロパティは、次のエントリを持つ辭書である:
| col | 開始桁 |
| length | バイト長。改行が含まれる場合は 1 以上。 |
| id | プロパティ ID |
| type | プロパティタイプ名。タイプが削除された場合は省略される |
| start | TRUE の時はプロパティはこの行から始まる |
| end | TRUE の時はプロパティはこの行で終はる |
"start" が 0 の場合、プロパティは以前の行で開始され、現在行は續きである。
"end" が 0 の場合、プロパティは次の行に續く。この行の後に改行が含まれる。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetLnum()->prop_list()
{lnum} 行から一致するテキストプロパティを削除する。{lnum-end} が指定された場合、{lnum} 行から {lnum-end} (その行を含む) までの一致するテキストプロパティを削除する。{lnum} を省略した場合、一致するテキストプロパティをすべての行から削除する。
{props} は次のフィールドを持つ辭書である:
| id | この ID を持つテキストプロパティを削除する |
| type | このタイプ名を持つテキストプロパティを削除する |
| bufnr | カレントバッファの代はりにこのバッファを使ふ |
| all | TRUE の場合、最初のテキストプロパティだけでなく、一致するテキストプロパティをすべて削除する。 |
"id" または "type" のどちらかが一致するとプロパティが一致する。バッファ "bufnr" が存在しない場合はエラーメッセージが表示される。バッファ "bufnr" がロードされてゐなければ、何も起こらない。
削除されたプロパティの數を返す。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetProps()->prop_remove()
テキストプロパティタイプ {name} を追加する。この名前のプロパティタイプがすでに存在する場合、エラーが發生する。何も返しません。 {props} は、次のオプションフィールドを持つ辭書である:
| bufnr | このバッファに對してのみプロパティを定義する。バッファが削除されたときに、名前の衝突を防ぎ、かつ、自動的にプロパティタイプをクリアする |
| highlight | 使用するハイライトグループ名 |
| priority | 文字に複數のテキストプロパティがある場合は、優先度が最も高いものが使用される。負の値を使用できる。デフォルトの優先順位は 0 である |
| combine | TRUE の場合、ハイライトを任意の構文ハイライトと結び付ける。省略するか FALSE の場合は構文ハイライトは使用されない |
| start_incl | TRUE の場合、開始位置の插入はテキストプロパティに含まれる |
| end_incl | TRUE の場合、終了位置の插入はテキストプロパティに含まれる |
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetPropName()->prop_type_add(props)
既存のテキストプロパティタイプのプロパティを變更する。この名前のプロパティが存在しない場合、エラーが發生する。{props} 引數は |prop_type_add()| と似てゐる。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetPropName()->prop_type_change(props)
テキストプロパティタイプ {name} を削除する。{name} 型を使用するテキストプロパティがまだ存在する場合、それらは效果を持たず、もはや名前で削除できなくなる。
{props} には "bufnr" 項目を含めることができる。指定すると、グローバルプロパティタイプではなく、このバッファからプロパティタイプを削除する。
テキストプロパティタイプ {name} が見つからなくてもエラーにならない。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetPropName()->prop_type_delete()
プロパティタイプ {name} のプロパティを返す。これは、prop_type_add() に與へられたものと同じフィールドを持つ辭書である。
プロパティタイプ {name} が存在しない場合、空の辭書が返される。
{props} には "bufnr" 項目を含めることができる。指定すると、グローバルプロパティタイプの代はりにこのバッファを使用する。
テキストプロパティについては、|text-properties| を參照。
|method| としても使用できます:
GetPropName()->prop_type_get()
すべてのプロパティタイプ名のリストを返す。
{props} には "bufnr" 項目を含めることができる。指定すると、グローバルプロパティタイプの代はりにこのバッファを使用する。
テキストプロパティについては、|text-properties| を參照。
Vim はテキストプロパティをそれが付加されたテキストの上に置くやうに最善を盡くします。 テキストを插入または削除するときは、變更後のプロパティもそれに從つて移動します。
テキストが削除され、テキストプロパティにテキストが含まれなくなつた場合は削除されます。 ただし、行全體が削除されない限り、幅ゼロとして定義されたテキストプロパティは殘ります。 バッファがアンロードされると、すべてのテキストプロパティがなくなります。プロパティをファイルに保存する方法はありません。再作成することしかできません。バッファが非表示 (hidden) の場合、テキストは保持され、テキストプロパティも保持されます。アンロードされたバッファにテキストプロパティを追加することはできません。
置換モードを使用すると、文字自體が變更しても、テキストプロパティは同じ文字位置に留まります。
テキストが變更された後にテキストのプロパティを更新するには、‘listener_add()‘ でコールバックを設置します。例へば、もしあなたのプラグインがスペルチェックをしてゐるのなら、變更されたテキスト內のスペルミスをコールバックで更新することができます。變更されたテキストの下にプロパティが移動し、同じテキストがハイライトされるため、これらを更新する必要はありません。