diff --git a/doc/builtin.jax b/doc/builtin.jax index a18a16aff..d3c32fa32 100644 --- a/doc/builtin.jax +++ b/doc/builtin.jax @@ -1,4 +1,4 @@ -*builtin.txt* For Vim バージョン 9.1. Last change: 2023 Nov 20 +*builtin.txt* For Vim バージョン 9.1. Last change: 2024 Jan 25 VIMリファレンスマニュアル by Bram Moolenaar @@ -215,6 +215,9 @@ foldclosedend({lnum}) 数値 {lnum}の折り畳みの最後の行(閉じてい foldlevel({lnum}) 数値 {lnum}の折り畳みレベル foldtext() 文字列 閉じた折り畳みに表示されている行 foldtextresult({lnum}) 文字列 {lnum}で閉じている折り畳みのテキスト +foreach({expr1}, {expr2}) リスト/辞書/Blob/文字列 + {expr1} の各項目に対して {expr2} を呼 + び出す foreground() 数値 Vimウィンドウを前面に移動する fullcommand({name} [, {vim9}]) 文字列 {name} から完全なコマンドを取得 funcref({name} [, {arglist}] [, {dict}]) @@ -392,6 +395,9 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) 数値 位置を {group} で強調表示する matcharg({nr}) リスト |:match|の引数 +matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}) + リスト バッファ {buf} 内のすべての {pat} の + マッチ matchdelete({id} [, {win}]) 数値 {id} で指定されるマッチを削除する matchend({expr}, {pat} [, {start} [, {count}]]) 数値 {expr}内で{pat}が終了する位置 @@ -405,6 +411,8 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) リスト {expr}内の{pat}のマッチと部分マッチ matchstr({expr}, {pat} [, {start} [, {count}]]) 文字列 {expr}内の{count}番目の{pat}のマッチ +matchstrlist({list}, {pat} [, {dict}) + リスト {list} 内のすべての {pat} にマッチ matchstrpos({expr}, {pat} [, {start} [, {count}]]) リスト {expr}内の{count}番目の{pat}のマッチ max({expr}) 数値 {expr}内の要素の最大値 @@ -2995,6 +3003,48 @@ foldtextresult({lnum}) *foldtextresult()* |method| としても使用できる: > GetLnum()->foldtextresult() + +foreach({expr1}, {expr2}) *foreach()* + {expr1} は |List|, |String|, |Blob| または |Dictionary| でなけ + ればならない。 + {expr1} の各項目に対して {expr2} を実行する。{expr1} は変更さ + れない。その値は |:lockvar| 1 と同様に変更されるかもしれない。 + |E741| + {expr1} を変更するには |map()| および |filter()| を参照。 + + {expr2} は |string| か |Funcref| でなければならない。 + + {expr2} が |string| の場合、{expr2} 内では |v:val| は現在の項 + 目の値を持つ。|Dictionary| の場合、|v:key| は現在の項目のキー + を持ち、|List| の場合、|v:key| は現在の項目のインデックスを持 + つ。 + |Blob| の場合、|v:key| は現在のバイトインデックスを持つ。 + |String| の場合、|v:key| は現在の文字インデックスを持つ。 + + 例: > + call foreach(mylist, 'used[v:val] = true') +< これは {expr1} リスト内の項目を記録する。 + + Note {expr2} は式の結果であり、コマンドとして使用されることに + 注意。多くの場合、|literal-string| を使用するのが良い。バック + スラッシュを 2 重にする必要がないようにするためである。 + + {expr2} が |Funcref| の場合 2 つの引数を取る必要がある: + 1. 現在の項目のキーまたはインデックス。 + 2. 現在の項目の値。 + 旧来のスクリプトの lambda では引数を 1 つだけ受け入れてもエラー + は発生しないが、Vim9 の lambda では "E1106: One argument too + many" になり、引数の数は一致する必要がある。 + 関数が値を返した場合、その値は無視される。 + + すべてのケースで {expr1} を返す。 + {expr2} の実行中にエラーが発生した場合、{expr1} 内の項目はそれ + 以上処理されない。 + {expr2} が Funcref の場合、"abort" フラグを使用して定義されて + いない限り、関数内のエラーは無視される。 + + |method| としても使用できる: > + mylist->foreach(expr2) < *foreground()* foreground() Vimのウィンドウを前面に移動する。この関数はクライアントからVim @@ -3198,6 +3248,8 @@ getbufinfo([{dict}]) bufnr バッファ番号。 changed バッファが変更されている場合はTRUE。 changedtick バッファに加えられた変更の数。 + command バッファがコマンドラインウィンドウ + |cmdwin| に属する場合は TRUE。 hidden バッファが隠されている場合はTRUE。 lastused バッファが最後に使用されたときの |localtime()| のような秒単位のタイムス @@ -3414,7 +3466,7 @@ getcharmod() *getcharmod()* 32 マウスのダブルクリック 64 マウスのトリプルクリック 96 マウスのクアドラプルクリック (== 32 + 64) - 128 command (Macintosh のみ) + 128 command (Mac) または super (GTK) 文字自身に含まれていない修飾キーのみ取得できる。つまり、 Shift-aは修飾キーなしの "A" となる。修飾なしの場合は 0 を返す。 @@ -3547,6 +3599,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* help ヘルプ項目 highlight ハイライトグループ history |:history| サブオプション + keymap キーボードマッピング locale ロケール名 (locale -aの出力) mapclear バッファ引数 mapping マッピング名 @@ -5091,8 +5144,12 @@ items({dict}) *items()* for [key, value] in items(mydict) echo key .. ': ' .. value endfor +< + リストまたは文字列引数もサポートされている。このようなケースで + は、items() はインデックスとインデックスの値を含むリストを返 + す。 -< |method| としても使用できる: > + |method| としても使用できる: > mydict->items() job_ 関数群はここに文書化されている: |job-functions-details| @@ -5948,6 +6005,51 @@ matcharg({nr}) *matcharg()* |method| としても使用できる: > GetMatch()->matcharg() +< + *matchbufline()* +matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) + バッファ {buf} 内の {lnum} から {end} までの行で、{pat} がマッ + チした行の |List| を返す。 + + {lnum} と {end} には、行番号または {buf} の最後の行を参照する + 文字列 "$" を指定できる。 + + {dict} 引数は次の項目をサポートする: + submatches サブマッチ情報を含める (|/\(|) + + マッチごとに、次の項目を含む |Dict| が返される: + byteidx マッチの開始バイトインデックス + lnum マッチする行番号 + text マッチした文字列 + Note 単一行に複数のマッチが存在する可能性があることに注意。 + + この関数はロードされたバッファに対してのみ機能する。必要であれ + ば、最初に |bufload()| を呼び出す。 + + {buf} が有効なバッファでない場合、バッファがロードされていない + 場合、{lnum} または {end} が有効でない場合は、エラー発生し、空 + の |List| が返される。 + + 例: > + " バッファ 5 の 3 行目に "a" が含まれていると仮定 + :echo matchbufline(5, '\<\k\+\>', 3, 3) + [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] + " バッファ 10 の 4 行目に "tik tok" が含まれていると仮定 + :echo matchbufline(10, '\<\k\+\>', 1, 4) + [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] +< + {submatch} が存在し、v:true の場合、"\1"、"\2" 等のサブマッチ + も返される。例: > + " バッファ 2 の 2 行目に "acd" が含まれていると仮定 + :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 + \ {'submatches': v:true}) + [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< "submatches" リストには常に 9 個のアイテムが含まれる。サブマッ + チが見つからない場合、そのサブマッチに対しては空文字列が返され + る。 + + |method| としても使用できる: > + GetBuffer()->matchbufline('mypat', 1, '$') matchdelete({id}, [, {win}]) *matchdelete()* *E802* *E803* |matchadd()| または |:match| で定義したマッチの中で ID が {id} @@ -6075,6 +6177,40 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* |method| としても使用できる: > GetText()->matchlist('word') +< + *matchstrlist()* +matchstrlist({list}, {pat} [, {dict}]) + {pat} がマッチする {list} 内のマッチの |List| を返す。 + {list} は文字列の |List| である。{list} 内の各文字列に対して + {pat} がマッチする。 + + {dict} 引数は次の項目をサポートする: + submatches サブマッチ情報を含める (|/\(|) + + マッチごとに、次の項目を含む |Dict| が返される: + byteidx マッチの開始バイトインデックス。 + idx {list} 内のマッチのインデックス。 + text マッチした文字列 + submatches サブマッチのリスト。{dict} で "submatches" が + v:true に設定されている場合にのみ存在する。 + + 例: > + :echo matchstrlist(['tik tok'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] + :echo matchstrlist(['a', 'b'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] +< + "submatch" が存在し、v:true の場合、"\1"、"\2" 等のサブマッチ + も返される。例: > + :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', + \ #{submatches: v:true}) + [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< "submatches" リストには常に 9 個のアイテムが含まれる。サブマッ + チが見つからない場合、そのサブマッチに対しては空文字列が返され + る。 + + |method| としても使用できる: > + GetListOfStrings()->matchstrlist('mypat') matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* |match()| と同じだが、マッチした文字列を返す。例: > @@ -9929,6 +10065,7 @@ type({expr}) {expr}の型を示す数値を返す。 Blob: 10 |v:t_blob| クラス: 12 |v:t_class| オブジェクト: 13 |v:t_object| + 型エイリアス: 14 |v:t_typealias| 後方互換性のためには、次のような使い方ができる: > :if type(myvar) == type(0) :if type(myvar) == type("") diff --git a/en/builtin.txt b/en/builtin.txt index 7bc02dce6..88cf642ca 100644 --- a/en/builtin.txt +++ b/en/builtin.txt @@ -1,4 +1,4 @@ -*builtin.txt* For Vim version 9.1. Last change: 2023 Nov 20 +*builtin.txt* For Vim version 9.1. Last change: 2024 Jan 25 VIM REFERENCE MANUAL by Bram Moolenaar @@ -198,6 +198,8 @@ foldclosedend({lnum}) Number last line of fold at {lnum} if closed foldlevel({lnum}) Number fold level at {lnum} foldtext() String line displayed for closed fold foldtextresult({lnum}) String text for closed fold at {lnum} +foreach({expr1}, {expr2}) List/Dict/Blob/String + for each item in {expr1} call {expr2} foreground() Number bring the Vim window to the foreground fullcommand({name} [, {vim9}]) String get full command from {name} funcref({name} [, {arglist}] [, {dict}]) @@ -370,6 +372,8 @@ matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) Number highlight positions with {group} matcharg({nr}) List arguments of |:match| +matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}) + List all the {pat} matches in buffer {buf} matchdelete({id} [, {win}]) Number delete match identified by {id} matchend({expr}, {pat} [, {start} [, {count}]]) Number position where {pat} ends in {expr} @@ -381,6 +385,8 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) List match and submatches of {pat} in {expr} matchstr({expr}, {pat} [, {start} [, {count}]]) String {count}'th match of {pat} in {expr} +matchstrlist({list}, {pat} [, {dict}) + List all the {pat} matches in {list} matchstrpos({expr}, {pat} [, {start} [, {count}]]) List {count}'th match of {pat} in {expr} max({expr}) Number maximum value of items in {expr} @@ -2991,6 +2997,45 @@ foldtextresult({lnum}) *foldtextresult()* Can also be used as a |method|: > GetLnum()->foldtextresult() + +foreach({expr1}, {expr2}) *foreach()* + {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. + For each item in {expr1} execute {expr2}. {expr1} is not + modified; its values may be, as with |:lockvar| 1. |E741| + See |map()| and |filter()| to modify {expr1}. + + {expr2} must be a |string| or |Funcref|. + + If {expr2} is a |string|, inside {expr2} |v:val| has the value + of the current item. For a |Dictionary| |v:key| has the key + of the current item and for a |List| |v:key| has the index of + the current item. For a |Blob| |v:key| has the index of the + current byte. For a |String| |v:key| has the index of the + current character. + Examples: > + call foreach(mylist, 'used[v:val] = true') +< This records the items that are in the {expr1} list. + + Note that {expr2} is the result of expression and is then used + as a command. Often it is good to use a |literal-string| to + avoid having to double backslashes. + + If {expr2} is a |Funcref| it must take two arguments: + 1. the key or the index of the current item. + 2. the value of the current item. + With a legacy script lambda you don't get an error if it only + accepts one argument, but with a Vim9 lambda you get "E1106: + One argument too many", the number of arguments must match. + If the function returns a value, it is ignored. + + Returns {expr1} in all cases. + When an error is encountered while executing {expr2} no + further items in {expr1} are processed. + When {expr2} is a Funcref errors inside a function are ignored, + unless it was defined with the "abort" flag. + + Can also be used as a |method|: > + mylist->foreach(expr2) < *foreground()* foreground() Move the Vim window to the foreground. Useful when sent from @@ -3199,6 +3244,8 @@ getbufinfo([{dict}]) bufnr Buffer number. changed TRUE if the buffer is modified. changedtick Number of changes made to the buffer. + command TRUE if the buffer belongs to the + command-line window |cmdwin|. hidden TRUE if the buffer is hidden. lastused Timestamp in seconds, like |localtime()|, when the buffer was @@ -3423,7 +3470,7 @@ getcharmod() *getcharmod()* 32 mouse double click 64 mouse triple click 96 mouse quadruple click (== 32 + 64) - 128 command (Macintosh only) + 128 command (Mac) or super (GTK) Only the modifiers that have not been included in the character itself are obtained. Thus Shift-a results in "A" without a modifier. Returns 0 if no modifiers are used. @@ -3566,6 +3613,7 @@ getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* help help subjects highlight highlight groups history |:history| suboptions + keymap keyboard mappings locale locale names (as output of locale -a) mapclear buffer argument mapping mapping name @@ -5163,8 +5211,12 @@ items({dict}) *items()* for [key, value] in items(mydict) echo key .. ': ' .. value endfor +< + A List or a String argument is also supported. In these + cases, items() returns a List with the index and the value at + the index. -< Can also be used as a |method|: > + Can also be used as a |method|: > mydict->items() job_ functions are documented here: |job-functions-details| @@ -6050,6 +6102,51 @@ matcharg({nr}) *matcharg()* Can also be used as a |method|: > GetMatch()->matcharg() +< + *matchbufline()* +matchbufline({buf}, {pat}, {lnum}, {end}, [, {dict}]) + Returns the |List| of matches in lines from {lnum} to {end} in + buffer {buf} where {pat} matches. + + {lnum} and {end} can either be a line number or the string "$" + to refer to the last line in {buf}. + + The {dict} argument supports following items: + submatches include submatch information (|/\(|) + + For each match, a |Dict| with the following items is returned: + byteidx starting byte index of the match + lnum line number where there is a match + text matched string + Note that there can be multiple matches in a single line. + + This function works only for loaded buffers. First call + |bufload()| if needed. + + When {buf} is not a valid buffer, the buffer is not loaded or + {lnum} or {end} is not valid then an error is given and an + empty |List| is returned. + + Examples: > + " Assuming line 3 in buffer 5 contains "a" + :echo matchbufline(5, '\<\k\+\>', 3, 3) + [{'lnum': 3, 'byteidx': 0, 'text': 'a'}] + " Assuming line 4 in buffer 10 contains "tik tok" + :echo matchbufline(10, '\<\k\+\>', 1, 4) + [{'lnum': 4, 'byteidx': 0, 'text': 'tik'}, {'lnum': 4, 'byteidx': 4, 'text': 'tok'}] +< + If {submatch} is present and is v:true, then submatches like + "\1", "\2", etc. are also returned. Example: > + " Assuming line 2 in buffer 2 contains "acd" + :echo matchbufline(2, '\(a\)\?\(b\)\?\(c\)\?\(.*\)', 2, 2 + \ {'submatches': v:true}) + [{'lnum': 2, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< The "submatches" List always contains 9 items. If a submatch + is not found, then an empty string is returned for that + submatch. + + Can also be used as a |method|: > + GetBuffer()->matchbufline('mypat', 1, '$') matchdelete({id} [, {win}) *matchdelete()* *E802* *E803* Deletes a match with ID {id} previously defined by |matchadd()| @@ -6183,6 +6280,40 @@ matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* Can also be used as a |method|: > GetText()->matchlist('word') +< + *matchstrlist()* +matchstrlist({list}, {pat} [, {dict}]) + Returns the |List| of matches in {list} where {pat} matches. + {list} is a |List| of strings. {pat} is matched against each + string in {list}. + + The {dict} argument supports following items: + submatches include submatch information (|/\(|) + + For each match, a |Dict| with the following items is returned: + byteidx starting byte index of the match. + idx index in {list} of the match. + text matched string + submatches a List of submatches. Present only if + "submatches" is set to v:true in {dict}. + + Example: > + :echo matchstrlist(['tik tok'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'tik'}, {'idx': 0, 'byteidx': 4, 'text': 'tok'}] + :echo matchstrlist(['a', 'b'], '\<\k\+\>') + [{'idx': 0, 'byteidx': 0, 'text': 'a'}, {'idx': 1, 'byteidx': 0, 'text': 'b'}] +< + If "submatches" is present and is v:true, then submatches like + "\1", "\2", etc. are also returned. Example: > + :echo matchstrlist(['acd'], '\(a\)\?\(b\)\?\(c\)\?\(.*\)', + \ #{submatches: v:true}) + [{'idx': 0, 'byteidx': 0, 'text': 'acd', 'submatches': ['a', '', 'c', 'd', '', '', '', '', '']}] +< The "submatches" List always contains 9 items. If a submatch + is not found, then an empty string is returned for that + submatch. + + Can also be used as a |method|: > + GetListOfStrings()->matchstrlist('mypat') matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* Same as |match()|, but return the matched string. Example: > @@ -6688,9 +6819,9 @@ printf({fmt}, {expr1} ...) *printf()* < This limits the length of the text used from "line" to "width" bytes. - If the argument to be formatted is specified using a posional - argument specifier, and a '*' is used to indicate that a - number argument is to be used to specify the width or + If the argument to be formatted is specified using a + positional argument specifier, and a '*' is used to indicate + that a number argument is to be used to specify the width or precision, the argument(s) to be used must also be specified using a {n$} positional argument specifier. See |printf-$|. @@ -7300,9 +7431,9 @@ reltime({start}, {end}) *reltime()* echo startTime->reltime()->reltimestr() < Without an argument reltime() returns the current time (the - representation is system-dependent, it can not be used as the + representation is system-dependent, it cannot be used as the wall-clock time, see |localtime()| for that). - With one argument is returns the time passed since the time + With one argument it returns the time passed since the time specified in the argument. With two arguments it returns the time passed between {start} and {end}. @@ -10181,6 +10312,7 @@ type({expr}) The result is a Number representing the type of {expr}. Blob: 10 |v:t_blob| Class: 12 |v:t_class| Object: 13 |v:t_object| + Typealias: 14 |v:t_typealias| For backward compatibility, this method can be used: > :if type(myvar) == type(0) :if type(myvar) == type("")