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

sign.txt      For Vim バージョン 9.1.  Last change: 2024 Jul 07


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


目印機能                                        sign-support

1. 機能紹介                             sign-intro
2. コマンド                             sign-commands
3. 関数                                 sign-functions-details

{+signs 機能付きでコンパイルした場合にのみ利用可能}

==============================================================================
1. 機能紹介                                     sign-intro signs

デバッガやその他のIDE {訳注: 統合開発環境} ツールはエディタをコントロールする。
そのエディタはユーザーにファイルについての役立つ情報を素早く提供するために特別
なハイライトを表示できる必要がある。一例としては左のカラムにブレークポイントを
示すアイコンを持つデバッガを挙げることができる。別の例としてはプログラムカウン
タ(PC)を示す矢印が挙げられる。この目印機能により、ウィンドウの左端に目印やアイ
コン画像を置いたり、ある行に適用される強調を定義することができるようになる。画
像による目印はgvimでだけ利用で可能である(しかしSun Microsystemsのdttermはそれ
をサポートしている。これは著者が知り得る限りで唯一の端末エミュレータである)。
テキストによる目印と色による強調表示は、あらゆるカラーの端末エミュレータで利用
できる。

目印と強調はデバッガにとってだけ便利なわけではない。SunのVisual WorkShopはビル
ドエラーとSourceBrowserの検索一致箇所を示すのに目印と強調を使用する。加えて、
デバッガは8個から10個の異なる目印と強調色をサポートする。netbeans を参照。

目印を使うには2つの段階がある:

1. 目印を定義する。画像とテキストと強調色を指定する。例えば "break" の目印とし
   て道路の停止の画像を使用し、テキストとして "!!" を使用して定義することがで
   きる。

2. 目印を設置する。目印を設置したいファイルと行番号を指定する。定義された目印
   は異なるファイルと異なる位置に複数箇所に置くことができる。

                                                        sign-column
ファイルに対して目印が定義されると、Vimは自動的に表示画面に2文字分のカラムを付
け加える。全てのサインが取り除かれるとそのカラムは再度消滅する。この動作は
'signcolumn' オプションにより変更可能できる。

そのカラムは SignColumnの色を使うhl-SignColumnが設定される。色を設定するには
次のようにする:


'cursorline' が有効な場合、CursorLineSign ハイライトグループが使われる
hl-CursorLineSign。
                                                        sign-identifier
設置された各目印は、目印IDと呼ばれる番号によって識別される。この識別子は、目印
にジャンプするため、または目印を解除するために使用される。この識別子は、
:sign-place コマンドまたは sign_place() 関数を使用して目印を設置するときに
割り当てられる。各目印IDは固有の番号でなければならない。複数の設置された目印が
同じ識別子を使用する場合、目印へのジャンプまたは目印の解除は予測不可能になる。
重複する識別子を避けるために、目印グループを使うことができる。sign_place()
関数は、次に使用可能な識別子を割り当てるために、目印IDを 0で呼び出すことができ
る。

                                                        sign-group
設置された各目印は、グローバルグループまたは名前付きグループのどちらにも割り当
てることができる。目印を設置するときに、グループ名が指定されていない場合、また
は空の文字列が使用されている場合は、目印はグローバルグループに設置される。それ
以外の場合は名前付きグループに設置される。目印IDはグループ内で一意である。グ
ループを使うと、Vimプラグインは他のプラグインを妨害することなく独自の目印を使
うことができる。

ポップアップウィンドウの中に目印を配置する場合、グループ名は "PopUp" で始める
必要がある。その他の目印はポップアップウィンドウ内では表示されない。グループ名
"PopUpMenu" はポップアップウィンドウ内 'cursorline' がセットされた場所で使われ
る。

                                                        sign-priority
設置された各目印には、優先順位値が割り当てられる。同じ行に複数の目印が設置され
ている場合、最も優先順位の高い目印の属性が目印のグループとは独立して使用され
る。デフォルトの優先順位は 10 だが、定義時に違う値を指定することにより、この値
を異なる目印に対して変更することができる。優先順位は、目印の設置時に割り当てら
れる。

2つの同じプライオリティの目印が、1つがアイコンかテキストで signcolumn にあり、
もう1つが行のハイライトとなっている場合であれば、両方が表示される。

目印が置かれている行が削除されると、その目印は次の行(または次の行がない場合は
バッファの最後の行)に移動される。削除が元に戻されても、目印は戻らない。

目印の行ハイライトと 'cursorline' のハイライト両方ある場合、目印の行ハイライト
のプライオリティが100以上ならそちらが表示され、そうでないなら 'cursorline' の
ハイライトとなる。

==============================================================================
2. コマンド                                     sign-commands :sig :sign

次の例ではカレントファイルの23行目に "piet" という目印を置いている。目印は ">>"
という文字をともなって表示される。

それをもう一度消すコマンドを追記しておく:

":sign" コマンドの後には他のコマンドを続けられないことに注意すること。そのよう
にするには:executeを使う。


目印を定義する                 :sign-define E255 E160 E612

同等のVim script関数については sign_define() を参照。

:sign define {name} {argument}...
                新しい目印を定義するか既にある目印に属性を設定する。{name}は番
                号(全て数字)か非数字で始まる名前である。先行するゼロは無視され
                るので、"0012" と "012" と "12" は同じ名前として解釈される。
                約120の異なる目印を定義することができる。

                利用可能な引数:

        icon={bitmap}
                目印に使用する画像ファイルを定義する。フルパス指定したほうが良
                い。画像は2文字の幅に納まるものでなければならない。これは
                チェックされない。大きすぎる画像を使用すると再描画の際に問題が
                生じることがある。GTK2では画像がちょうど納まるように調整され
                る。
                {訳注: Windowsでは自動的に調整される}
                        toolkit         サポートフォーマット
                        GTK 1           pixmap (.xpm)
                        GTK 2           many
                        Motif           pixmap (.xpm)
                        Win32           .bmp, .ico, .cur
                                        pixmap (.xpm) +xpm_w32
        priority={prio}
                目印のデフォルトの優先順位。sign-priority を参照。

        linehl={group}
                目印が設置された行全体を強調表示するのに使われるハイライトグ
                ループを定義する。背景色を定義するのに良く利用される。

        numhl={group}
                目印が設置されている行の行番号に使われるハイライトグルー
                プ。hl-LineNr, hl-LineNrAbove, hl-LineNrBelow,
                hl-CursorLineNr を上書きする。

        text={text}                                             E239
                アイコンが無いかGUIではない時に表示されるテキストを定義する。
                表示可能な文字のみ指定できる。これは表示幅で1文字か2文字分の文
                字を指定できる。
                {訳注: アルファベットなら1or2文字。漢字なら1文字}

        texthl={group}
                テキスト部分に使用されるハイライトグループ。

        culhl={group}
                カーソルが目印と同じ行にあり、'cursorline' が有効な場合にテキ
                スト部分に使用されるハイライトグループ。

        例:


(定義した)目印を削除する                               :sign-undefine E155

同等のVim script関数については sign_undefine() を参照。

:sign undefine {name}
                既に定義された目印を削除する。{name}という名前の目印がまだ設置
                されたままの場合はトラブルを引き起こす。

                例:


(定義した)目印を一覧表示する                           :sign-list E156

同等のVim script関数については sign_getdefined() を参照。

:sign list      全部の定義済み目印とその属性を一覧表示する。

:sign list {name}
                {name}という名で定義された目印とその属性を表示する。


目印を設置する                                 :sign-place E158

同等のVim script関数については sign_place() を参照。

:sign place {id} line={lnum} name={name} file={fname}
                {name}として定義された目印をファイル{fname}の{lnum}行目に設置
                する。
                                                        :sign-fname
                ファイル名{fname}は既に読込済みのバッファでなければなら
                ない。正確なファイル名でなければならず、ワイルドカードや環境変
                数そして "~" は展開されない。空白はエスケープされない。末尾の
                空白は無視される。

                目印は{id}という識別子で記憶され、後の操作に使用される。{id}は
                番号でなければならない。
                ユーザーは自分で、1つの{id}が各々のファイルに1つしか無いように
                気をつけなければならない(同じ{id}を複数回設置したときには解除
                も同じ回数だけ行う必要がある。同じ{id}を使うことで目印の位置を
                変更しようという試みはうまく行かない)。

                次の任意の目印属性は、"file=" の前に指定できる:
                        group={group}   目印を目印グループ{group}に設置する
                        priority={prio} 目印に優先順位{prio}を割り当てる

                デフォルトでは、目印はグローバル目印グループに設置される。

                デフォルトでは、目印の定義で別途指定されていない限り、目印には
                デフォルトの優先順位 10 が割り当てられる。別の優先順位値を割り
                当てるには、"priority={prio}" を使用して値を指定する。優先順位
                は、複数の目印が同じ行に設置されているときに、表示される目印を
                決定するために使用される。

                例:

:sign place {id} line={lnum} name={name} [buffer={nr}]
                上に同じ。バッファ番号を使用していることが異なる。buffer引数が
                与えられていない場合は、現在のバッファに目印を設置する。

                例:

                                                        E885
:sign place {id} name={name} file={fname}
                ファイル{fname}に{id}で設置された目印を、{name}で定義されてい
                る目印に変更する。{fname}については上述の:sign-fnameを参照す
                ること。
                これは既に設置された目印を動かすことなく変更するのに使われる。
                (例: デバッガがブレークポイントで停止した時)

                任意の "group={group}" 属性を "file=" の前に使用して、特定のグ
                ループの目印を選択することができる。任意の "priority={prio}"
                属性を使用して、既存の目印の優先順位を変更することができる。

                例:

:sign place {id} name={name} buffer={nr}
                上に同じ。バッファ番号を使用していることが異なる。buffer引数が
                与えられていない場合は、現在のバッファを使用する。

                例:


(設置した)目印を解除する                               :sign-unplace E159

同等のVim script関数については sign_unplace() を参照。

:sign unplace {id} file={fname}
                ファイル{fname}に{id}で設置された目印を解除する。
                {fname}については上述の:sign-fnameを参照すること。

:sign unplace {id} group={group} file={fname}
                上に同じだが、目印グループ{group}の目印ID{id}を解除する。

:sign unplace {id} group=* file={fname}
                上に同じだが、全ての目印グループから目印ID{id}を解除する。

:sign unplace * file={fname}
                ファイル{fname}に設置された目印を全て解除する。

:sign unplace * group={group} file={fname}
                ファイル{fname}からグループ{group}に設置されている全ての目印を
                解除する。

:sign unplace * group=* file={fname}
                ファイル{fname}から全てのグループに設置されている全ての目印を
                解除する。

:sign unplace {id} buffer={nr}
                バッファ{nr}に{id}で設置された目印を解除する。

:sign unplace {id} group={group} buffer={nr}
                バッファ{nr}からグループ{group}の以前に設置された目印ID{id}を
                解除する。

:sign unplace {id} group=* buffer={nr}
                バッファ{nr}から、全てのグループで以前に設置された目印ID{id}を
                解除する。

:sign unplace * buffer={nr}
                バッファ{nr}に設置された目印を全て解除する。

:sign unplace * group={group} buffer={nr}
                グループ{group}に設置されている全ての目印をバッファ{nr}から解
                除する。

:sign unplace * group=* buffer={nr}
                全てのグループに設置されている全ての目印をバッファ{nr}から解除
                する。

:sign unplace {id}
                {id}で設置された目印を、全てのファイルから削除する。

:sign unplace {id} group={group}
                表示されている全てのファイルから、グループ{group}の以前に設置
                された目印ID{id}を解除する。

:sign unplace {id} group=*
                表示されている全てのファイルから、全てのグループの以前に設置さ
                れた目印ID{id}を解除する。

:sign unplace *
                全てのファイルからグローバルグループの設置された全ての目印を解
                除する。

:sign unplace * group={group}
                全てのファイルからグループ{group}の設置された全ての目印を解除
                する。

:sign unplace * group=*
                全てのファイルから全てのグループの設置された全ての目印を解除す
                る。

:sign unplace
                カーソル位置の設置された目印を解除する。複数の目印が行内に設置
                されている場合は、1つだけが削除される。

:sign unplace group={group}
                カーソル位置のグループ{group}の設置された目印を解除する。

:sign unplace group=*
                カーソル位置の全てのグループの設置された目印を解除する。


(設置した)目印を一覧表示する                           :sign-place-list

同等のVim script関数については sign_getplaced() を参照。

:sign place file={fname}
                ファイル{fname}に設置されている目印を一覧表示する。
                {fname}については上述の:sign-fnameを参照すること。

:sign place group={group} file={fname}
                ファイル{fname}に設置されているグループ{group}の目印を一覧表示
                する。

:sign place group=* file={fname}
                ファイル{fname}に設置されている全てのグループの目印を一覧表示
                する。

:sign place buffer={nr}
                バッファ{nr}に設置されている目印を一覧表示する。

:sign place group={group} buffer={nr}
                バッファ{nr}に設置されているグループ{group}の目印を一覧表示す
                る。

:sign place group=* buffer={nr}
                バッファ{nr}に設置されている全てのグループの目印を一覧表示す
                る。

:sign place     全てのファイルに設置されているグローバルグループの目印を一覧表
                示する。

:sign place group={group}
                全てのファイルの目印グループ{group}に設置されている目印を一覧
                表示する。

:sign place group=*
                全てのファイルの全ての目印グループに設置されている目印を一覧表
                示する。


(設置した)目印へ移動する                               :sign-jump E157

同等のVim scriptの関数については sign_jump() を参照。

:sign jump {id} file={fname}
                ファイル{fname}を開くか、{fname}を編集中のウィンドウへ移動し、
                目印ID{id}の位置へカーソルを移動させる。
                {fname}については上述の:sign-fnameを参照すること。
                ファイルがウィンドウに表示されておらず、現在のファイルを放棄で
                きない時には、これは失敗する。

:sign jump {id} group={group} file={fname}
                上に同じだが、グループ{group}の目印に移動する。

:sign jump {id} [buffer={nr}]                                   E934
                上に同じだが、バッファ{nr}を使う。バッファ{nr}が名前を持ってい
                ない場合には失敗する。buffer引数が与えられていない場合は、現在
                のバッファを使用する。

:sign jump {id} group={group} [buffer={nr}]
                上に同じだが、グループ{group}の目印に移動する。


==============================================================================
3. 関数                                         sign-functions-details

sign_define({name} [, {dict}])                          sign_define()
sign_define({list})
                {name}という名前の新しい目印を定義するか、既存の目印の属性を変
                更する。これは :sign-define コマンドに似ている。

                名前の衝突を避けるために、{name}に一意のテキストを付けること。
                目印を設置するような{group}はない。

                {name}は文字列または数値である。任意の{dict}引数は目印属性を指
                定する。以下の値がサポートされている:
                   icon         目印用のビットマップファイルへのフルパス。
                   linehl       目印が設置されている行全体に使用されるハイライ
                                トグループ。
                   priority     目印のデフォルトの優先順位
                   numhl        目印が設置されている行番号に使用されるハイライ
                                トグループ。
                   text         アイコンがない場合、またはGUIが使用されていな
                                い場合に表示されるテキスト。
                   texthl       text項目に使用されるハイライトグループ
                   culhl        カーソルが目印と同じ行にあり、'cursorline' が
                                有効な場合にtext項目に使用されるハイライトグ
                                ループ。

                {name}という名前の目印がすでに存在する場合は、その目印の属性が
                更新される。

                1つの引数{list}を使用して、目印のリストを定義できる。各リスト
                項目は、{dict}の上記項目と目印名の "name" 項目を持つ辞書であ
                る。
                成功すると 0 を返し、失敗すると -1 を返す。1つの引数{list}が使
                用されると、定義された各目印ごとに値のリストが返される。

                例:

                method としても使用できる:

                戻り値の型: Number


sign_getdefined([{name}])                               sign_getdefined()
                定義済みの目印とその属性のリストを取得する。
                これは :sign-list コマンドに似ている。

                {name}が指定されていない場合は、定義されているすべての目印のリ
                ストが返される。そうでなければ、指定された目印の属性が返され
                る。

                戻り値の各リスト項目は、次のエントリを持つ辞書である:
                   icon         目印用のビットマップファイルへのフルパス。
                   linehl       目印が設置されている行全体に使用されるハイライ
                                トグループ。設定されなければ存在しない。
                   name         目印の名前
                   priority     目印のデフォルトの優先順位
                   numhl        目印が設置されている行番号に使用されるハイライ
                                トグループ。設定されなければ存在しない。
                   text         アイコンがない場合、またはGUIが使用されていな
                                い場合に表示されるテキスト。
                   texthl       text 項目に使用されるハイライトグループ。設定
                                されなければ存在しない。
                   culhl        カーソルが目印と同じ行にあり、'cursorline' が有
                                効な時に text 項目が利用するハイライトグルー
                                プ。設定されなければ存在しない。

                目印がなく、{name}が見つからない場合は、空のListを返す。

                例:


                method としても使用できる:

                戻り値の型: list<dict<string>> または list<any>


sign_getplaced([{buf} [, {dict}]])                      sign_getplaced()
                バッファまたはすべてのバッファに設置されている目印のリストを返
                す。これは :sign-place-list コマンドに似ている。

                任意のバッファ名{buf}が指定されている場合、そのバッファに設置
                されている目印のリストだけが返される。{buf}の使い方については
                bufname() を参照。任意の{dict}には、以下のエントリを含めるこ
                とができる。
                   group        このグループの目印のみを選択する
                   id           この識別子を持つ目印を選択する
                   lnum         この行に設置されている目印を選択する。{lnum}の
                                使い方については line() を参照。
                {group}が '*' の場合、グローバルグループを含むすべてのグループ
                の目印が返される。{group}が指定されていないか、空の文字列の場
                合は、グローバルグループ内の目印のみが返される。引数が指定され
                ていない場合は、すべてのバッファに設置されているグローバルグ
                ループ内の目印が返される。
                sign-group を参照。

                戻り値の各リスト項目は、次のエントリを持つ辞書である:
                        bufnr   目印付きバッファの番号
                        signs   {bufnr}に設置されている目印のリスト。各リスト
                                項目は、以下の項目を含む辞書である。

                各目印の辞書には、次のエントリが含まれている:
                        group    目印グループ。グローバルグループの場合は '' に
                                 設定する。
                        id       目印ID
                        lnum     目印が設置されている行番号
                        name     定義されている目印の名前
                        priority 目印の優先度

                返されるバッファ内の目印は、行番号および優先度で並べられる。

                失敗した場合、または設置された目印がない場合は、空のリストを返
                す。

                例:






                method としても使用できる:

                戻り値の型: list<dict<any>>


sign_jump({id}, {group}, {buf})                         sign_jump()
                バッファ{buf}を開くか、{buf}を含むウィンドウに移動して、グルー
                プ{group}の目印{id}にカーソルを置く。これは :sign-jump コマ
                ンドに似ている。

                {group}が空文字列の場合、グローバルのグループが使われる。{buf}
                の使い方については bufname() を参照。

                目印の行番号を返す。引数が無効な場合は -1 を返す。

                例:

                method としても使用できる:

                戻り値の型: Number


                                                        sign_place()
sign_place({id}, {group}, {name}, {buf} [, {dict}])
                {name}として定義された目印をファイルまたはバッファ{buf}の行
                {lnum}に設置し、目印に{id}と{group}を割り当てる。これは
                :sign-place コマンドに似ている。

                目印ID{id}がゼロの場合は、新しい識別子が割り当てられる。それ以
                外の場合は、指定された番号が使用される。{group}は目印グループ
                名である。グローバルサイングループを使用するには、空の文字列を
                使用する。{group}は{id}の名前空間として機能するため、2つのグ
                ループが同じIDを使用できる。詳細については sign-identifier
                と sign-group を参照。

                {name}は定義済みの目印を参照する。
                {buf}はバッファの名前か番号を参照する。許容値については、
                bufname() を参照。

                任意の{dict}引数は、以下のエントリをサポートする:
                        lnum            目印が設置されるファイルまたはバッファ
                                        {buf}の行番号。許容値については、
                                        line() を参照。
                        priority        目印の優先順位。詳細については
                                        sign-priority を参照。

                任意の{dict}が指定されていない場合は、定義されている目印{name}
                を使用するようにグループ{group}内の設置された目印ID{id}を変更
                する。

                成功した場合は目印ID、失敗した場合は -1 を返す。

                例:




                method としても使用できる:

                戻り値の型: Number


sign_placelist({list})                          sign_placelist()
                1つ以上の目印を設置する。これは sign_place() 関数に似ている。
                引数{list}には、設置する目印のリストを指定する。各リスト項目
                は、次の目印属性を持つ辞書である:
                    buffer      バッファの名前または番号。受け入れられる値につ
                                いては、bufname() を参照。
                    group       目印グループ。{group}は{id}のネームスペースと
                                して機能するため、2つのグループは同じIDを使用
                                できる。指定されていないか、空の文字列に設定さ
                                れている場合、グローバルグループが使用される。
                                詳細については sign-group を参照。
                    id          目印ID。指定しないかゼロの場合、新しい一意の識
                                別子が割り当てられる。それ以外の場合は、指定さ
                                れた番号が使用される。詳細については
                                sign-identifier を参照。
                    lnum        目印が設置されるバッファの行番号。受け入れられ
                                る値については、line() を参照。
                    name        設置する目印の名前。詳細については
                                sign_define() を参照。
                    priority    目印の優先順位。1行に複数の目印が設置されてい
                                る場合、最も優先度の高い目印が使用される。指定
                                されていない場合は、目印の定義で別途指定されて
                                いない限り、デフォルト値の 10 が使用される。詳
                                細については sign-priority を参照。

                {id}が既存の目印を参照する場合、指定された{name}または
                {priority}を使用するように既存の目印が変更される。

                目印IDのリストを返す。目印の設置に失敗した場合、対応するリスト
                項目は -1 に設定される。

                例:


                method としても使用できる:

                戻り値の型: Number


sign_undefine([{name}])                                 sign_undefine()
sign_undefine({list})
                定義済みの目印{name}を削除する。これは :sign-undefine コマン
                ドに似ている。{name}が指定されていない場合は、定義されているす
                べての目印を削除する。

                1つの引数{list}を使用して、目印のリストの定義を解除できる。各
                リスト項目は目印の名前である。

                成功すると 0 を返し、失敗すると -1 を返す。1つの引数{list}で呼
                び出した場合、解除した目印のリストを返す。

                例:



                method としても使用できる:

                戻り値の型: Number


sign_unplace({group} [, {dict}])                        sign_unplace()
                設置済みの1つ以上のバッファ内の目印を解除する。これは
                :sign-unplace コマンドに似ている。

                {group}は目印グループ名である。グローバルサイングループを使用
                するには、空の文字列を使用する。{group}が '*' に設定されている
                場合、グローバルグループを含むすべてのグループが使用される。
                {group}内の目印は、{dict}内のエントリに基づいて選択される。
                {dict}の以下の任意のエントリがサポートされている:
                        buffer  バッファの名前または番号。bufname() を参照。
                        id      目印ID
                {dict}が指定されていない場合は、{group}内のすべての目印が解除
                される。

                成功すると 0 を返し、失敗すると -1 を返す。

                例:








                method としても使用できる:

                戻り値の型: Number


sign_unplacelist({list})                                sign_unplacelist()
                1つ以上のバッファから以前に設置された目印を削除する。これは
                sign_unplace() 関数に似ている。

                引数{list}は、削除する目印のリストを指定する。 各リスト項目は、
                次の目印属性を持つ辞書である:
                    buffer      バッファの名前または番号。受け入れられる値につ
                                いては、bufname() を参照。指定しない場合、指
                                定された目印はすべてのバッファから削除される。
                    group       目印グループ名。指定されていないか、空の文字列
                                に設定されている場合、グローバル記号グループが
                                使用される。'*' に設定すると、グローバルグルー
                                プを含むすべてのグループが使用される。
                    id          目印ID。指定しない場合、指定したグループ内のす
                                べての目印が削除される。

                対応する目印が正常に削除された場合、エントリが 0 に設定された
                リストを返す。失敗した場合は -1 を返す。

                例:

                method としても使用できる:

                戻り値の型: list<number> または list<any>

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