*sign.txt* For Vim バージョン 8.1. Last change: 2019 Nov 12
VIMリファレンスマニュアル by Gordon Prieur
and Bram Moolenaar
目印機能
| 1. 機能紹介 | |sign-intro| |
| 2. コマンド | |sign-commands| |
| 3. 函數 | |sign-functions-details| |
{|+signs| 機能付きでコンパイルした場合にのみ利用可能}
デバッガやその他の IDE {譯注: 統合開發環境} ツールはエディタをコントロールする。そのエディタはユーザーにファイルについての役立つ情報を素早く提供するために特別なハイライトを表示できる必要がある。
一例としては左のカラムにブレークポイントを示すアイコンを持つデバッガを擧げることができる。別の例としてはプログラムカウンタ (PC) を示す矢印が擧げられる。
この目印機能により、ウィンドウの左端に目印やアイコン畫像を置いたり、ある行に適用される强調を定義することができるやうになる。畫像による目印は gvim でだけ利用で可能である (しかし Sun Microsystems の dtterm はそれをサポートしてゐる。これは著者が知り得る限りで唯一の端末エミュレータである)。
テキストによる目印と色による强調表示は、あらゆるカラーの端末エミュレータで利用できる。
目印と强調はデバッガにとつてだけ便利なわけではない。Sun の Visual WorkShop はビルドエラーと SourceBrowser の檢索一致箇所を示すのに目印と强調を使用する。加へて、デバッガは 8 個から 10 個の異なる目印と强調色をサポートする。|NetBeans| を參照。
目印を使ふには 2 つの段階がある:
ファイルに對して目印が定義されると、Vim は自動的に表示畫面に 2 文字分のカラムを付け加へる。全てのサインが取り除かれるとそのカラムは再度消滅する。この動作は ’signcolumn’ オプションにより變更可能できる。
そのカラムは SignColumn の色を使ふ |hl-SignColumn| が設定される。色を設定するには次のやうにする:
:highlight SignColumn guibg=darkgrey
設置された各目印は、目印 ID と呼ばれる番號によつて識別される。この識別子は、目印にジャンプするため、または目印を解除するために使用される。この識別子は、|:sign-place| コマンドまたは |sign_place()| 函數を使用して目印を設置するときに割り當てられる。各目印 ID は固有の番號でなければならない。複數の設置された目印が同じ識別子を使用する場合、目印へのジャンプまたは目印の解除は豫測不可能になる。重複する識別子を避けるために、目印グループを使ふことができる。|sign_place()| 函數は、次に使用可能な識別子を割り當てるために、目印 ID を 0 で呼び出すことができる。
設置された各目印は、グローバルグループまたは名前付きグループのどちらにも割り當てることができる。目印を設置するときに、グループ名が指定されてゐない場合、または空の文字列が使用されてゐる場合は、目印はグローバルグループに設置される。それ以外の場合は名前付きグループに設置される。目印 ID はグループ內で一意である。グループを使ふと、Vim プラグインは他のプラグインを妨碍することなく獨自の目印を使ふことができる。
"popupmenu" のグループ名は ’cursorline’ で設定されたポップアップウィンドウで使はれます。
設置された各目印には、優先順位値が割り當てられる。同じ行に複數の目印が設置されてゐる場合、最も優先順位の高い目印の屬性が目印のグループとは獨立して使用される。デフォルトの優先順位は 10 である。優先順位は、目印の設置時に割り當てられる。
目印が置かれてゐる行が削除されると、その目印は次の行 (または次の行がない場合はバッファの最後の行) に移動される。削除が元に戾されても、目印は戾らない。
次の例ではカレントファイルの 23 行目に "piet" といふ目印を置いてゐる。目印は ">>" といふ文字をともなつて表示される。
:sign define piet text=>> texthl=Search
:exe ":sign place 2 line=23 name=piet file=" . expand("%:p")
それをもう一度消すコマンドを追記しておく:
:sign unplace 2
Note:
":sign" コマンドの後には他のコマンドを續けられないことに注意すること。そのやうにするには |:execute| を使ふ。
同等の Vim script 函數については |sign_define()| を參照。
新しい目印を定義するか既にある目印に屬性を設定する。{name} は番號 (全て數字) か非數字で始まる名前である。先行するゼロは無視されるので、"0012" と "012" と "12" は同じ名前として解釋される。約 120 の異なる目印を定義することができる。
利用可能な引數:
目印に使用する畫像ファイルを定義する。フルパス指定したはうが良い。畫像は 2 文字の幅に納まるものでなければならない。これはチェックされない。大きすぎる畫像を使用すると再描畫の際に問題が生じることがある。GTK2 では畫像がちやうど納まるやうに調整される。
{譯注: Windows では自動的に調整される}
| toolkit | サポートフォーマット |
|---|---|
| GTK 1 | pixmap (.xpm) |
| GTK 2 | many |
| Motif | pixmap (.xpm) |
| Win32 | .bmp, .ico, .cur pixmap (.xpm) |+xpm_w32| |
目印が設置された行全體を强調表示するのに使はれるハイライトグループを定義する。背景色を定義するのに良く利用される。
アイコンが無いか GUI ではない時に表示されるテキストを定義する。表示可能な文字のみ指定できる。これは表示幅で 1 文字か 2 文字分の文字を指定できる。
{譯注: アルファベットなら 1 or 2 文字。漢字なら 1 文字}
テキスト部分に使用されるハイライトグループ。
同等の Vim script 函數については |sign_undefine()| を參照。
既に定義された目印を削除する。{name} といふ名前の目印がまだ設置されたままの場合はトラブルを引き起こす。
同等の Vim script 函數については |sign_getdefined()| を參照。
全部の定義濟み目印とその屬性を一覽表示する。
{name} といふ名で定義された目印とその屬性を表示する。
同等の Vim script 函數については |sign_place()| を參照。
{name} として定義された目印をファイル {fname} の {lnum} 行目に設置する。 ファイル名 {fname} は既に讀込濟みのバッファでなければならない。正確なファイル名でなければならず、ワイルドカードや環境變數そして "~" は展開されない。空白はエスケープされない。末尾の空白は無視される。
目印は {id} といふ識別子で記憶され、後の操作に使用される。{id} は番號でなければならない。
ユーザーは自分で、1 つの {id} が各々のファイルに1つしか無いやうに氣をつけなければならない (同じ {id} を複數回設置したときには解除も同じ回數だけ行ふ必要がある。同じ {id} を使ふことで目印の位置を變更しようといふ試みはうまく行かない)。
次の任意の目印屬性は、"file=" の前に指定できる:
| group={group} | 目印を目印グループ {group} に設置する |
| priority={prio} | 目印に優先順位 {prio} を割り當てる |
デフォルトでは、目印はグローバル目印グループに設置される。
デフォルトでは、目印にデフォルトの優先順位 10 が割り當てられてゐる。別の優先順位値を割り當てるには、"priority={prio}" を使用して値を指定する。優先順位は、複數の目印が同じ行に設置されてゐるときに、表示される目印を決定するために使用される。
例:
:sign place 5 line=3 name=sign1 file=a.py
:sign place 6 group=g2 line=2 name=sign2 file=x.py
:sign place 9 group=g2 priority=50 line=5
\ name=sign1 file=a.py
上に同じ。バッファ番號を使用してゐることが異なる。buffer 引數が與へられてゐない場合は、現在のバッファに目印を設置する。
ファイル {fname} に {id} で設置された目印を、{name} で定義されてゐる目印に變更する。{fname} については上述の |:sign-fname| を參照すること。
これは既に設置された目印を動かすことなく變更するのに使はれる。(例: デバッガがブレークポイントで停止した時)
任意の "group={group}" 屬性を "file=" の前に使用して、特定のグループの目印を選擇することができる。任意の "priority={prio}" 屬性を使用して、既存の目印の優先順位を變更することができる。
上に同じ。バッファ番號を使用してゐることが異なる。buffer 引數が與へられてゐない場合は、現在のバッファを使用する。
同等の Vim script 函數については |sign_unplace()| を參照。
ファイル {fname} に {id} で設置された目印を解除する。{fname} については上述の |:sign-fname| を參照すること。
上に同じだが、目印グループ {group} の目印 ID {id} を解除する。
上に同じだが、全ての目印グループから目印 ID {id} を解除する。
ファイル {fname} に設置された目印をすべて解除する。
ファイル {fname} からグループ {group} に設置されてゐる全ての目印を解除する。
ファイル {fname} から全てのグループに設置されてゐる全ての目印を解除する。
バッファ {nr} に {id} で設置された目印を解除する。
バッファ {nr} からグループ {group} の以前に設置された目印 ID {id} を解除する。
バッファ {nr} から、全てのグループで以前に設置された目印 ID {id} を解除する。
バッファ {nr} に設置された目印をすべて解除する。
グループ {group} に設置されてゐる全ての目印をバッファ {nr} から解除する。
全てのグループに設置されてゐる全ての目印をバッファ {nr} から解除する。
{id} で設置された目印を、全てのファイルから削除する。
表示されてゐる全てのファイルから、グループ {group} の以前に設置された目印 ID {id} を解除する。
表示されてゐる全てのファイルから、全てのグループの以前に設置された目印 ID {id} を解除する。
全てのファイルからグローバルグループの設置された全ての目印を解除する。
全てのファイルからグループ {group} の設置された全ての目印を解除する。
全てのファイルから全てのグループの設置された全ての目印を解除する。
カーソル位置の設置された目印を解除する。複數の目印が行內に設置されてゐる場合は、1 つだけが削除される。
カーソル位置のグループ {group} の設置された目印を解除する。
カーソル位置の全てのグループの設置された目印を解除する。
同等の Vim script 函數については |sign_getplaced()| を參照。
ファイル {fname} に設置されてゐる目印を一覽表示する。{fname} については上述の |:sign-fname| を參照すること。
ファイル {fname} に設置されてゐるグループ {group} の目印を一覽表示する。
ファイル {fname} に設置されてゐる全てのグループの目印を一覽表示する。
バッファ {nr} に設置されてゐる目印を一覽表示する。
バッファ {nr} に設置されてゐるグループ {group} の目印を一覽表示する。
バッファ {nr} に設置されてゐる全てのグループの目印を一覽表示する。
全てのファイルに設置されてゐるグローバルグループの目印を一覽表示する。
全てのファイルの目印グループ {group} に設置されてゐる目印を一覽表示する。
全てのファイルの全ての目印グループに設置されてゐる目印を一覽表示する。
同等の Vim script の函數については |sign_jump()| を參照。
ファイル {fname} を開くか、{fname} を編輯中のウィンドウへ移動し、目印 {id} の位置へカーソルを移動させる。
{fname} については上述の |:sign-fname| を參照すること。
ファイルがウィンドウに表示されてをらず、現在のファイルを抛棄 |abandon| できない時には、これは失敗する。
上に同じだが、グループ {group} の目印に移動する。
上に同じだが、バッファ {nr} を使ふ。バッファ {nr} が名前を持つてゐない場合には失敗する。buffer 引數が與へられてゐない場合は、現在のバッファを使用する。
上に同じだが、グループ {group} の目印に移動する。
{name} といふ名前の新しい目印を定義するか、既存の目印の屬性を變更する。これは |:sign-define| コマンドに似てゐる。
名前の衝突を避けるために、{name} に一意のテキストを付けること。目印を設置するやうな {group} はない。
{name} は文字列または數値である。任意の {dict} 引數は目印屬性を指定する。以下の値がサポートされてゐる:
| icon | 目印用のビットマップファイルへのフルパス。 |
| linehl | 目印が設置されてゐる行全體に使用されるハイライトグループ。 |
| text | アイコンがない場合、または GUI が使用されてゐない場合に表示されるテキスト。 |
| texthl | text 項目に使用されるハイライトグループ |
{name} といふ名前の目印がすでに存在する場合は、その目印の屬性が更新される。
1 つの引數 {list} は目印のリストを定義するのに使ふことができます。リストの項目はそれぞれ上記 {dict} 內の項目をもつ辭書です。’name’ 項目は目印の名前です。
成功のときは 0、失敗のときは -1 を返します。1 つの引數 {list} が使用されたときは、それぞれに定義された目印の値のリストを返します。
例:
call sign_define("mySign", {
\ "text" : "=>",
\ "texthl" : "Error",
\ "linehl" : "Search"})
call sign_define([
\ {'name' : 'sign1',
\ 'text' : '=>'},
\ {'name' : 'sign2',
\ 'text' : '!!'}
\ ])
|method| としても使用できます:
GetSignList()->sign_define()
定義濟みの目印とその屬性のリストを取得する。これは |:sign-list| コマンドに似てゐる。
{name} が指定されてゐない場合は、定義されてゐるすべての目印のリストが返される。さうでなければ、指定された目印の屬性が返される。
戾り値の各リスト項目は、次のエントリを持つ辭書である:
| icon | 目印用のビットマップファイルへのフルパス。 |
| linehl | 目印が設置されてゐる行全體に使用されるハイライトグループ。 |
| name | 目印の名前 |
| text | アイコンがない場合、または GUI が使用されてゐない場合に表示されるテキスト。 |
| texthl | text 項目に使用されるハイライトグループ |
目印がなく、{name} が見つからない場合は、空の List を返す。
例:
" すべての定義濟み目印のリストを取得する
echo sign_getdefined()
" mySignといふ名前の目印の屬性を取得する
echo sign_getdefined("mySign")
|method| としても使用できます:
GetSignList()->sign_getdefined()
バッファまたはすべてのバッファに設置されてゐる目印のリストを返す。これは |:sign-place-list| コマンドに似てゐる。
任意のバッファ名 {expr} が指定されてゐる場合、そのバッファに設置されてゐる目印のリストだけが返される。{expr} の使ひ方については |bufname()| を參照。任意の {dict} には、以下のエントリを含めることができる。
| group | このグループの目印のみを選擇する |
| id | この識別子を持つ目印を選擇する |
| lnum | この行に設置されてゐる目印を選擇する。{lnum} の使ひ方については |line()| を參照。 |
{group} が ’*’ の場合、グローバルグループを含むすべてのグループの目印が返される。{group} が指定されてゐないか、空の文字列の場合は、グローバルグループ內の目印のみが返される。引數が指定されてゐない場合は、すべてのバッファに設置されてゐるグローバルグループ內の目印が返される。
|sign-group| を參照。
戾り値の各リスト項目は、次のエントリを持つ辭書である:
| bufnr | 目印付きバッファの番號 |
| signs | {bufnr} に設置されてゐる目印のリスト。各リスト項目は、以下の項目を含む辭書である。 |
各目印の辭書には、次のエントリが含まれてゐる:
| group | 目印グループ。グローバルグループの場合は ” に設定する。 |
| id | 目印 ID |
| lnum | 目印が設置されてゐる行番號 |
| name | 定義されてゐる目印の名前 |
| priority | 目印の優先度 |
返されるバッファ內の目印は、行番號および優先度で竝べられる。
失敗した場合、または設置された目印がない場合は、空のリストを返す。
例:
" eval.c に設置されてゐるグローバルグループの目印のリ
" ストを取得する
echo sign_getplaced("eval.c")
" eval.c の 'g1' グループに設置されてゐる目印のリスト
" を取得する
echo sign_getplaced("eval.c", {'group' : 'g1'})
" eval.c の 10行目に設置されてゐる目印のリストを取得す
" る
echo sign_getplaced("eval.c", {'lnum' : 10})
" a.py に設置されてゐる識別子 10 の目印を取得する
echo sign_getplaced("a.py", {'id' : 10'})
" a.py の 'g1' グループ 'g1' に設置されてゐる識別子 20
" の目印を取得する
echo sign_getplaced("a.py", {'group' : 'g1',
\ 'id' : 20'})
" 設置されてゐるすべての目印のリストを取得する
echo sign_getplaced()
|method| としても使用できます:
GetBufname()->sign_getplaced()
バッファ {expr} を開くか、{expr} を含むウィンドウに移動して、グループ {group} の目印 {id} にカーソルを置く。これは |:sign-jump| コマンドに似てゐる。
{expr} の使ひ方については |bufname()| を參照。
目印の行番號を返す。引數が無效な場合は -1 を返す。
例:
" 現在のバッファの目印 ID 10 へ移動する call sign_jump(10, '', '')
|method| としても使用できます:
GetSignid()->sign_jump()
{name} として定義された目印をファイル {expr} の行 {lnum} または {expr} バッファに設置し、目印に {id} と {group} を割り當てる。 これは |:sign-place| コマンドに似てゐる。
目印 ID {id} がゼロの場合は、新しい識別子が割り當てられる。それ以外の場合は、指定された番號が使用される。{group} は目印グループ名である。グローバルサイングループを使用するには、空の文字列を使用する。{group} は {id} の名前空閒として機能するため、2 つのグループが同じ ID を使用できる。詳細については |sign-identifier|と |sign-group| を參照。
{name} は定義濟みの目印を參照する。{expr} はバッファの名前か番號を參照する。許容値については、|bufname()| を參照。
任意の {dict} 引數は、以下のエントリをサポートする:
| lnum | 目印が設置されるファイルやバッファ {expr} の行番號。許容値については、|line()| を參照。 |
| priority | 目印の優先順位。詳細については |sign-priority| を參照。 |
任意の {dict} が指定されてゐない場合は、定義されてゐる目印 {name} を使用するやうにグループ {group} 內の設置された目印 ID {id} を變更します。
成功した場合は目印 ID、失敗した場合は -1 を返す。
例:
" バッファ json.c の 20 行目に識別子 5 で sign1 といふ名前
" の目印を設置する
call sign_place(5, '', 'sign1', 'json.c',
\ {'lnum' : 20})
" バッファ json.c の識別子 5 が目印 sign2 を使用するやう
" に更新する
call sign_place(5, '', 'sign2', 'json.c')
" バッファ json.c の 30 行目に sign3 といふ名前の目印を
" 新しい識別子で設置する
let id = sign_place(0, '', 'sign3', 'json.c',
\ {'lnum' : 30})
" バッファ json.c の 40 行目に 'g3' グループで識別子 10 の
" sign4 といふ名前の目印を優先順位 90 で設置する
call sign_place(10, 'g3', 'sign4', 'json.c',
\ {'lnum' : 40, 'priority' : 90})
|method| としても使用できます:
GetSignid()->sign_place(group, name, expr)
1 つもしくはそれ以上の目印を置きます。これは |sign_place()| 函數と似てゐます。{list} 引數は目印のリストの場所を指定します。それぞれのリスト項目は以下の目印特性をもつ辭書です:
| buffer | バッファ名もしくは番號。受け取ることのできる値については |bufname() を參照してください。 |
| group | 目印のグループ。{group} は {id} の名前空閒として機能します。そのため、2 つのグループは同じ ID に使ふことができます。もしも指定されてゐないか空文字が設定されてゐるのなら、グーローバルグープが使はれます。より多くの情報は |sign-group| を參照してください。 |
| id | 目印の識別子。もしも指定されてゐないかゼロなら、新しいユニークな識別子が割り當てられます。さうでなければ指定された番號が使はれます。より多くの情報は |sign-identifier| を參照してください。 |
| lnum | 目印を置くことのできるバッファ {expr} 內の 行番號。受け取ることのできる値については |line()| を參照してください。 |
| name | 配置するための目印の名前。より多くの情報については |sign_define()| を參照してください。 |
| priority | 目印の優先順位。複數の目印が 1 行に置かれたときに、もつとも高い優先順位をもつ目印が使はれます。もしも指定されてゐなければ、既定の値 10 が使はれます。より多くの情報については |sign-priority| を參照してください。 |
もしも {id} が存在する目印を參照してゐるなら、その存在してゐる目印は指定された {name} かつ/または {priority} を使ふために變更されます。
目印の識別子のリストを返します。もしも目印を置くのに失敗したなら、對應するリスト項目は -1 に設定されます。
例:
" バッファ a.c の 20 行目に id を 5 として、
" また、30 行目に id を 10 として 目印 s1 を置きます
let [n1, n2] = sign_placelist([
\ {'id' : 5,
\ 'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 20},
\ {'id' : 10,
\ 'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 30}
\ ])
" バッファ a.c の 40 行目と 50 行目に、
" 自動的に生成された識別子をつけて目印 s1 を置きます
let [n1, n2] = sign_placelist([
\ {'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 40},
\ {'name' : 's1',
\ 'buffer' : 'a.c',
\ 'lnum' : 50}
\ ])
|method| としても使用できます:
GetSignlist()->sign_placelist()
定義濟みの目印 {name} を削除する。これは |:sign-undefine| コマンドに似てゐる。{name} が指定されてゐない場合は、定義されてゐるすべての目印を削除する。
1 つの引數 {list} は目印のリストを未定義にするために使ふことができます。リスト項目のそれぞれは、目印の番號です。
成功すると 0 を返し、失敗すると -1 を返します。1 つの引數 {list} を呼ぶために、未定義にされた目印の値のリストを返します。
例:
" mySign といふ名前の目印を削除します
call sign_undefine("mySign")
" 目印 'sign1' と 'sign2' を削除します
call sign_undefine(["sign1", "sign2"])
" すべての目印を削除します
call sign_undefine()
|method| としても使用できます:
GetSignlist()->sign_undefine()
設置濟みの 1 つ以上のバッファ內の目印を解除する。これは |:sign-unplace| コマンドに似てゐる。
{group} は目印グループ名である。グローバルサイングループを使用するには、空の文字列を使用する。{group} が ’*’ に設定されてゐる場合、グローバルグループを含むすべてのグループが使用される。 {group} 內の目印は、{dict} 內のエントリに基づいて選擇される。{dict} の以下の任意のエントリがサポートされてゐる:
| buffer | バッファの名前または番號。|bufname()| を參照。 |
| id | 目印 ID |
{dict} が指定されてゐない場合は、{group} 內のすべての目印が解除される。
成功すると 0 を返し、失敗すると -1 を返す。
例:
" バッファ a.vim から識別子10の目印を解除する
call sign_unplace('', {'buffer' : "a.vim", 'id' : 10})
" バッファ番號3から 'g1' グループの識別子20の目印を解
" 除する
call sign_unplace('g1', {'buffer' : 3, 'id' : 20})
" バッファ番號10から 'g2' グループのすべての目印を解除
" する
call sign_unplace('g2', {'buffer' : 10})
" すべてのバッファから 'g3' グループの識別子30の目印を
" 解除する
call sign_unplace('g3', {'id' : 30})
" バッファ番號5 のすべての目印を解除する
call sign_unplace('*', {'buffer' : 5})
" すべてのバッファから 'g4' グループの目印を解除する
call sign_unplace('g4')
" すべてのバッファから識別子40の目印を解除する
call sign_unplace('*', {'id' : 40})
" すべてのバッファからすべての目印を解除する
call sign_unplace('*')
|method| としても使用できます:
GetSigngroup()->sign_unplace()
1 つもしくはそれ以上のバッファから以前に置かれた目印を削除します。これは |sign_unplace()| 函數と似てゐます。
{list} 引數は削除する目印のリスト指定します。それぞれのリスト項目は次の目印屬性を持つ辭書です:
| buffer | バッファ名もしくは番號。受け取ることのできる値については |bufname()| を參照してください。もしも {譯注: バッファ名もしくは番號が} 指定されてゐなければ、指定された目印はすべてのバッファから削除されます。 |
| group | 目印のグループ名。もしも指定されてゐない、もしくは空文字の場合は、グローバルな目印グループが使はれます。もしも ’*’ が設定されてゐなければ、グローバルグループを含むすべてのグループが使はれます。 |
| id | 目印の識別子。もしも {譯注: 目印の識別子が} 指定されてゐなければ、指定されたグループのすべての目印が削除されます。 |
もしも對應する目印の削除が成功した場合は 0 を、失敗した場合は -1 を設定されたエントリのリストを返します。
例:
" バッファ a.vim から id が 10 の目印を、
" バッファ b.vim から id が 20 の目印を削除します
call sign_unplacelist([
\ {'id' : 10, 'buffer' : "a.vim"},
\ {'id' : 20, 'buffer' : 'b.vim'},
\ ])
|method| としても使用できます:
GetSignlist()->sign_unplacelist()