Mercurial > vim
comparison runtime/doc/eval.txt @ 26777:629e7046ef63 v8.2.3917
patch 8.2.3917: the eval.txt help file is way too big
Commit: https://github.com/vim/vim/commit/1cae5a0a034d0545360387407a7a409310f1efe2
Author: Bram Moolenaar <Bram@vim.org>
Date: Mon Dec 27 21:28:34 2021 +0000
patch 8.2.3917: the eval.txt help file is way too big
Problem: The eval.txt help file is way too big.
Solution: Move the builtin function details to a separate file.
author | Bram Moolenaar <Bram@vim.org> |
---|---|
date | Mon, 27 Dec 2021 22:30:02 +0100 |
parents | 30972227ac8d |
children | eafb9fd4ec32 |
comparison
equal
deleted
inserted
replaced
26776:7560ecdb2a6e | 26777:629e7046ef63 |
---|---|
10 | 10 |
11 Note: Expression evaluation can be disabled at compile time. If this has been | 11 Note: Expression evaluation can be disabled at compile time. If this has been |
12 done, the features in this document are not available. See |+eval| and | 12 done, the features in this document are not available. See |+eval| and |
13 |no-eval-feature|. | 13 |no-eval-feature|. |
14 | 14 |
15 This file is about the backwards compatible Vim script. For Vim9 script, | 15 This file is mainly about the backwards compatible (legacy) Vim script. For |
16 which executes much faster, supports type checking and much more, see | 16 specifics of Vim9 script, which executes much faster, supports type checking |
17 |vim9.txt|. | 17 and much more, see |vim9.txt|. Where the syntax or semantics differ a remark |
18 is given. | |
18 | 19 |
19 1. Variables |variables| | 20 1. Variables |variables| |
20 1.1 Variable types | 21 1.1 Variable types |
21 1.2 Function references |Funcref| | 22 1.2 Function references |Funcref| |
22 1.3 Lists |Lists| | 23 1.3 Lists |Lists| |
2531 ============================================================================== | 2532 ============================================================================== |
2532 4. Builtin Functions *functions* | 2533 4. Builtin Functions *functions* |
2533 | 2534 |
2534 See |function-list| for a list grouped by what the function is used for. | 2535 See |function-list| for a list grouped by what the function is used for. |
2535 | 2536 |
2536 (Use CTRL-] on the function name to jump to the full explanation.) | 2537 The alphabetic list of all builtin functions and details are in a separate |
2537 | 2538 help file: |builtin-functions|. |
2538 USAGE RESULT DESCRIPTION ~ | |
2539 | |
2540 abs({expr}) Float or Number absolute value of {expr} | |
2541 acos({expr}) Float arc cosine of {expr} | |
2542 add({object}, {item}) List/Blob append {item} to {object} | |
2543 and({expr}, {expr}) Number bitwise AND | |
2544 append({lnum}, {text}) Number append {text} below line {lnum} | |
2545 appendbufline({expr}, {lnum}, {text}) | |
2546 Number append {text} below line {lnum} | |
2547 in buffer {expr} | |
2548 argc([{winid}]) Number number of files in the argument list | |
2549 argidx() Number current index in the argument list | |
2550 arglistid([{winnr} [, {tabnr}]]) Number argument list id | |
2551 argv({nr} [, {winid}]) String {nr} entry of the argument list | |
2552 argv([-1, {winid}]) List the argument list | |
2553 asin({expr}) Float arc sine of {expr} | |
2554 assert_beeps({cmd}) Number assert {cmd} causes a beep | |
2555 assert_equal({exp}, {act} [, {msg}]) | |
2556 Number assert {exp} is equal to {act} | |
2557 assert_equalfile({fname-one}, {fname-two} [, {msg}]) | |
2558 Number assert file contents are equal | |
2559 assert_exception({error} [, {msg}]) | |
2560 Number assert {error} is in v:exception | |
2561 assert_fails({cmd} [, {error} [, {msg} [, {lnum} [, {context}]]]]) | |
2562 Number assert {cmd} fails | |
2563 assert_false({actual} [, {msg}]) | |
2564 Number assert {actual} is false | |
2565 assert_inrange({lower}, {upper}, {actual} [, {msg}]) | |
2566 Number assert {actual} is inside the range | |
2567 assert_match({pat}, {text} [, {msg}]) | |
2568 Number assert {pat} matches {text} | |
2569 assert_nobeep({cmd}) Number assert {cmd} does not cause a beep | |
2570 assert_notequal({exp}, {act} [, {msg}]) | |
2571 Number assert {exp} is not equal {act} | |
2572 assert_notmatch({pat}, {text} [, {msg}]) | |
2573 Number assert {pat} not matches {text} | |
2574 assert_report({msg}) Number report a test failure | |
2575 assert_true({actual} [, {msg}]) Number assert {actual} is true | |
2576 atan({expr}) Float arc tangent of {expr} | |
2577 atan2({expr1}, {expr2}) Float arc tangent of {expr1} / {expr2} | |
2578 balloon_gettext() String current text in the balloon | |
2579 balloon_show({expr}) none show {expr} inside the balloon | |
2580 balloon_split({msg}) List split {msg} as used for a balloon | |
2581 blob2list({blob}) List convert {blob} into a list of numbers | |
2582 browse({save}, {title}, {initdir}, {default}) | |
2583 String put up a file requester | |
2584 browsedir({title}, {initdir}) String put up a directory requester | |
2585 bufadd({name}) Number add a buffer to the buffer list | |
2586 bufexists({buf}) Number |TRUE| if buffer {buf} exists | |
2587 buflisted({buf}) Number |TRUE| if buffer {buf} is listed | |
2588 bufload({buf}) Number load buffer {buf} if not loaded yet | |
2589 bufloaded({buf}) Number |TRUE| if buffer {buf} is loaded | |
2590 bufname([{buf}]) String Name of the buffer {buf} | |
2591 bufnr([{buf} [, {create}]]) Number Number of the buffer {buf} | |
2592 bufwinid({buf}) Number window ID of buffer {buf} | |
2593 bufwinnr({buf}) Number window number of buffer {buf} | |
2594 byte2line({byte}) Number line number at byte count {byte} | |
2595 byteidx({expr}, {nr}) Number byte index of {nr}'th char in {expr} | |
2596 byteidxcomp({expr}, {nr}) Number byte index of {nr}'th char in {expr} | |
2597 call({func}, {arglist} [, {dict}]) | |
2598 any call {func} with arguments {arglist} | |
2599 ceil({expr}) Float round {expr} up | |
2600 ch_canread({handle}) Number check if there is something to read | |
2601 ch_close({handle}) none close {handle} | |
2602 ch_close_in({handle}) none close in part of {handle} | |
2603 ch_evalexpr({handle}, {expr} [, {options}]) | |
2604 any evaluate {expr} on JSON {handle} | |
2605 ch_evalraw({handle}, {string} [, {options}]) | |
2606 any evaluate {string} on raw {handle} | |
2607 ch_getbufnr({handle}, {what}) Number get buffer number for {handle}/{what} | |
2608 ch_getjob({channel}) Job get the Job of {channel} | |
2609 ch_info({handle}) String info about channel {handle} | |
2610 ch_log({msg} [, {handle}]) none write {msg} in the channel log file | |
2611 ch_logfile({fname} [, {mode}]) none start logging channel activity | |
2612 ch_open({address} [, {options}]) | |
2613 Channel open a channel to {address} | |
2614 ch_read({handle} [, {options}]) String read from {handle} | |
2615 ch_readblob({handle} [, {options}]) | |
2616 Blob read Blob from {handle} | |
2617 ch_readraw({handle} [, {options}]) | |
2618 String read raw from {handle} | |
2619 ch_sendexpr({handle}, {expr} [, {options}]) | |
2620 any send {expr} over JSON {handle} | |
2621 ch_sendraw({handle}, {expr} [, {options}]) | |
2622 any send {expr} over raw {handle} | |
2623 ch_setoptions({handle}, {options}) | |
2624 none set options for {handle} | |
2625 ch_status({handle} [, {options}]) | |
2626 String status of channel {handle} | |
2627 changenr() Number current change number | |
2628 char2nr({expr} [, {utf8}]) Number ASCII/UTF-8 value of first char in {expr} | |
2629 charclass({string}) Number character class of {string} | |
2630 charcol({expr}) Number column number of cursor or mark | |
2631 charidx({string}, {idx} [, {countcc}]) | |
2632 Number char index of byte {idx} in {string} | |
2633 chdir({dir}) String change current working directory | |
2634 cindent({lnum}) Number C indent for line {lnum} | |
2635 clearmatches([{win}]) none clear all matches | |
2636 col({expr}) Number column byte index of cursor or mark | |
2637 complete({startcol}, {matches}) none set Insert mode completion | |
2638 complete_add({expr}) Number add completion match | |
2639 complete_check() Number check for key typed during completion | |
2640 complete_info([{what}]) Dict get current completion information | |
2641 confirm({msg} [, {choices} [, {default} [, {type}]]]) | |
2642 Number number of choice picked by user | |
2643 copy({expr}) any make a shallow copy of {expr} | |
2644 cos({expr}) Float cosine of {expr} | |
2645 cosh({expr}) Float hyperbolic cosine of {expr} | |
2646 count({comp}, {expr} [, {ic} [, {start}]]) | |
2647 Number count how many {expr} are in {comp} | |
2648 cscope_connection([{num}, {dbpath} [, {prepend}]]) | |
2649 Number checks existence of cscope connection | |
2650 cursor({lnum}, {col} [, {off}]) | |
2651 Number move cursor to {lnum}, {col}, {off} | |
2652 cursor({list}) Number move cursor to position in {list} | |
2653 debugbreak({pid}) Number interrupt process being debugged | |
2654 deepcopy({expr} [, {noref}]) any make a full copy of {expr} | |
2655 delete({fname} [, {flags}]) Number delete the file or directory {fname} | |
2656 deletebufline({buf}, {first} [, {last}]) | |
2657 Number delete lines from buffer {buf} | |
2658 did_filetype() Number |TRUE| if FileType autocmd event used | |
2659 diff_filler({lnum}) Number diff filler lines about {lnum} | |
2660 diff_hlID({lnum}, {col}) Number diff highlighting at {lnum}/{col} | |
2661 digraph_get({chars}) String get the |digraph| of {chars} | |
2662 digraph_getlist([{listall}]) List get all |digraph|s | |
2663 digraph_set({chars}, {digraph}) Boolean register |digraph| | |
2664 digraph_setlist({digraphlist}) Boolean register multiple |digraph|s | |
2665 echoraw({expr}) none output {expr} as-is | |
2666 empty({expr}) Number |TRUE| if {expr} is empty | |
2667 environ() Dict return environment variables | |
2668 escape({string}, {chars}) String escape {chars} in {string} with '\' | |
2669 eval({string}) any evaluate {string} into its value | |
2670 eventhandler() Number |TRUE| if inside an event handler | |
2671 executable({expr}) Number 1 if executable {expr} exists | |
2672 execute({command}) String execute {command} and get the output | |
2673 exepath({expr}) String full path of the command {expr} | |
2674 exists({expr}) Number |TRUE| if {expr} exists | |
2675 exists_compiled({expr}) Number |TRUE| if {expr} exists at compile time | |
2676 exp({expr}) Float exponential of {expr} | |
2677 expand({expr} [, {nosuf} [, {list}]]) | |
2678 any expand special keywords in {expr} | |
2679 expandcmd({expr}) String expand {expr} like with `:edit` | |
2680 extend({expr1}, {expr2} [, {expr3}]) | |
2681 List/Dict insert items of {expr2} into {expr1} | |
2682 extendnew({expr1}, {expr2} [, {expr3}]) | |
2683 List/Dict like |extend()| but creates a new | |
2684 List or Dictionary | |
2685 feedkeys({string} [, {mode}]) Number add key sequence to typeahead buffer | |
2686 filereadable({file}) Number |TRUE| if {file} is a readable file | |
2687 filewritable({file}) Number |TRUE| if {file} is a writable file | |
2688 filter({expr1}, {expr2}) List/Dict/Blob/String | |
2689 remove items from {expr1} where | |
2690 {expr2} is 0 | |
2691 finddir({name} [, {path} [, {count}]]) | |
2692 String find directory {name} in {path} | |
2693 findfile({name} [, {path} [, {count}]]) | |
2694 String find file {name} in {path} | |
2695 flatten({list} [, {maxdepth}]) List flatten {list} up to {maxdepth} levels | |
2696 flattennew({list} [, {maxdepth}]) | |
2697 List flatten a copy of {list} | |
2698 float2nr({expr}) Number convert Float {expr} to a Number | |
2699 floor({expr}) Float round {expr} down | |
2700 fmod({expr1}, {expr2}) Float remainder of {expr1} / {expr2} | |
2701 fnameescape({fname}) String escape special characters in {fname} | |
2702 fnamemodify({fname}, {mods}) String modify file name | |
2703 foldclosed({lnum}) Number first line of fold at {lnum} if closed | |
2704 foldclosedend({lnum}) Number last line of fold at {lnum} if closed | |
2705 foldlevel({lnum}) Number fold level at {lnum} | |
2706 foldtext() String line displayed for closed fold | |
2707 foldtextresult({lnum}) String text for closed fold at {lnum} | |
2708 foreground() Number bring the Vim window to the foreground | |
2709 fullcommand({name}) String get full command from {name} | |
2710 funcref({name} [, {arglist}] [, {dict}]) | |
2711 Funcref reference to function {name} | |
2712 function({name} [, {arglist}] [, {dict}]) | |
2713 Funcref named reference to function {name} | |
2714 garbagecollect([{atexit}]) none free memory, breaking cyclic references | |
2715 get({list}, {idx} [, {def}]) any get item {idx} from {list} or {def} | |
2716 get({dict}, {key} [, {def}]) any get item {key} from {dict} or {def} | |
2717 get({func}, {what}) any get property of funcref/partial {func} | |
2718 getbufinfo([{buf}]) List information about buffers | |
2719 getbufline({buf}, {lnum} [, {end}]) | |
2720 List lines {lnum} to {end} of buffer {buf} | |
2721 getbufvar({buf}, {varname} [, {def}]) | |
2722 any variable {varname} in buffer {buf} | |
2723 getchangelist([{buf}]) List list of change list items | |
2724 getchar([expr]) Number or String | |
2725 get one character from the user | |
2726 getcharmod() Number modifiers for the last typed character | |
2727 getcharpos({expr}) List position of cursor, mark, etc. | |
2728 getcharsearch() Dict last character search | |
2729 getcharstr([expr]) String get one character from the user | |
2730 getcmdline() String return the current command-line | |
2731 getcmdpos() Number return cursor position in command-line | |
2732 getcmdtype() String return current command-line type | |
2733 getcmdwintype() String return current command-line window type | |
2734 getcompletion({pat}, {type} [, {filtered}]) | |
2735 List list of cmdline completion matches | |
2736 getcurpos([{winnr}]) List position of the cursor | |
2737 getcursorcharpos([{winnr}]) List character position of the cursor | |
2738 getcwd([{winnr} [, {tabnr}]]) String get the current working directory | |
2739 getenv({name}) String return environment variable | |
2740 getfontname([{name}]) String name of font being used | |
2741 getfperm({fname}) String file permissions of file {fname} | |
2742 getfsize({fname}) Number size in bytes of file {fname} | |
2743 getftime({fname}) Number last modification time of file | |
2744 getftype({fname}) String description of type of file {fname} | |
2745 getimstatus() Number |TRUE| if the IME status is active | |
2746 getjumplist([{winnr} [, {tabnr}]]) | |
2747 List list of jump list items | |
2748 getline({lnum}) String line {lnum} of current buffer | |
2749 getline({lnum}, {end}) List lines {lnum} to {end} of current buffer | |
2750 getloclist({nr}) List list of location list items | |
2751 getloclist({nr}, {what}) Dict get specific location list properties | |
2752 getmarklist([{buf}]) List list of global/local marks | |
2753 getmatches([{win}]) List list of current matches | |
2754 getmousepos() Dict last known mouse position | |
2755 getpid() Number process ID of Vim | |
2756 getpos({expr}) List position of cursor, mark, etc. | |
2757 getqflist() List list of quickfix items | |
2758 getqflist({what}) Dict get specific quickfix list properties | |
2759 getreg([{regname} [, 1 [, {list}]]]) | |
2760 String or List contents of a register | |
2761 getreginfo([{regname}]) Dict information about a register | |
2762 getregtype([{regname}]) String type of a register | |
2763 gettabinfo([{expr}]) List list of tab pages | |
2764 gettabvar({nr}, {varname} [, {def}]) | |
2765 any variable {varname} in tab {nr} or {def} | |
2766 gettabwinvar({tabnr}, {winnr}, {name} [, {def}]) | |
2767 any {name} in {winnr} in tab page {tabnr} | |
2768 gettagstack([{nr}]) Dict get the tag stack of window {nr} | |
2769 gettext({text}) String lookup translation of {text} | |
2770 getwininfo([{winid}]) List list of info about each window | |
2771 getwinpos([{timeout}]) List X and Y coord in pixels of the Vim window | |
2772 getwinposx() Number X coord in pixels of the Vim window | |
2773 getwinposy() Number Y coord in pixels of the Vim window | |
2774 getwinvar({nr}, {varname} [, {def}]) | |
2775 any variable {varname} in window {nr} | |
2776 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
2777 any expand file wildcards in {expr} | |
2778 glob2regpat({expr}) String convert a glob pat into a search pat | |
2779 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
2780 String do glob({expr}) for all dirs in {path} | |
2781 has({feature} [, {check}]) Number |TRUE| if feature {feature} supported | |
2782 has_key({dict}, {key}) Number |TRUE| if {dict} has entry {key} | |
2783 haslocaldir([{winnr} [, {tabnr}]]) | |
2784 Number |TRUE| if the window executed |:lcd| | |
2785 or |:tcd| | |
2786 hasmapto({what} [, {mode} [, {abbr}]]) | |
2787 Number |TRUE| if mapping to {what} exists | |
2788 histadd({history}, {item}) Number add an item to a history | |
2789 histdel({history} [, {item}]) Number remove an item from a history | |
2790 histget({history} [, {index}]) String get the item {index} from a history | |
2791 histnr({history}) Number highest index of a history | |
2792 hlID({name}) Number syntax ID of highlight group {name} | |
2793 hlexists({name}) Number |TRUE| if highlight group {name} exists | |
2794 hlget([{name} [, {resolve}]]) List get highlight group attributes | |
2795 hlset({list}) Number set highlight group attributes | |
2796 hostname() String name of the machine Vim is running on | |
2797 iconv({expr}, {from}, {to}) String convert encoding of {expr} | |
2798 indent({lnum}) Number indent of line {lnum} | |
2799 index({object}, {expr} [, {start} [, {ic}]]) | |
2800 Number index in {object} where {expr} appears | |
2801 input({prompt} [, {text} [, {completion}]]) | |
2802 String get input from the user | |
2803 inputdialog({prompt} [, {text} [, {completion}]]) | |
2804 String like input() but in a GUI dialog | |
2805 inputlist({textlist}) Number let the user pick from a choice list | |
2806 inputrestore() Number restore typeahead | |
2807 inputsave() Number save and clear typeahead | |
2808 inputsecret({prompt} [, {text}]) String like input() but hiding the text | |
2809 insert({object}, {item} [, {idx}]) List insert {item} in {object} [before {idx}] | |
2810 interrupt() none interrupt script execution | |
2811 invert({expr}) Number bitwise invert | |
2812 isdirectory({directory}) Number |TRUE| if {directory} is a directory | |
2813 isinf({expr}) Number determine if {expr} is infinity value | |
2814 (positive or negative) | |
2815 islocked({expr}) Number |TRUE| if {expr} is locked | |
2816 isnan({expr}) Number |TRUE| if {expr} is NaN | |
2817 items({dict}) List key-value pairs in {dict} | |
2818 job_getchannel({job}) Channel get the channel handle for {job} | |
2819 job_info([{job}]) Dict get information about {job} | |
2820 job_setoptions({job}, {options}) none set options for {job} | |
2821 job_start({command} [, {options}]) | |
2822 Job start a job | |
2823 job_status({job}) String get the status of {job} | |
2824 job_stop({job} [, {how}]) Number stop {job} | |
2825 join({list} [, {sep}]) String join {list} items into one String | |
2826 js_decode({string}) any decode JS style JSON | |
2827 js_encode({expr}) String encode JS style JSON | |
2828 json_decode({string}) any decode JSON | |
2829 json_encode({expr}) String encode JSON | |
2830 keys({dict}) List keys in {dict} | |
2831 len({expr}) Number the length of {expr} | |
2832 libcall({lib}, {func}, {arg}) String call {func} in library {lib} with {arg} | |
2833 libcallnr({lib}, {func}, {arg}) Number idem, but return a Number | |
2834 line({expr} [, {winid}]) Number line nr of cursor, last line or mark | |
2835 line2byte({lnum}) Number byte count of line {lnum} | |
2836 lispindent({lnum}) Number Lisp indent for line {lnum} | |
2837 list2blob({list}) Blob turn {list} of numbers into a Blob | |
2838 list2str({list} [, {utf8}]) String turn {list} of numbers into a String | |
2839 listener_add({callback} [, {buf}]) | |
2840 Number add a callback to listen to changes | |
2841 listener_flush([{buf}]) none invoke listener callbacks | |
2842 listener_remove({id}) none remove a listener callback | |
2843 localtime() Number current time | |
2844 log({expr}) Float natural logarithm (base e) of {expr} | |
2845 log10({expr}) Float logarithm of Float {expr} to base 10 | |
2846 luaeval({expr} [, {expr}]) any evaluate |Lua| expression | |
2847 map({expr1}, {expr2}) List/Dict/Blob/String | |
2848 change each item in {expr1} to {expr2} | |
2849 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) | |
2850 String or Dict | |
2851 rhs of mapping {name} in mode {mode} | |
2852 mapcheck({name} [, {mode} [, {abbr}]]) | |
2853 String check for mappings matching {name} | |
2854 mapnew({expr1}, {expr2}) List/Dict/Blob/String | |
2855 like |map()| but creates a new List or | |
2856 Dictionary | |
2857 mapset({mode}, {abbr}, {dict}) none restore mapping from |maparg()| result | |
2858 match({expr}, {pat} [, {start} [, {count}]]) | |
2859 Number position where {pat} matches in {expr} | |
2860 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) | |
2861 Number highlight {pattern} with {group} | |
2862 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) | |
2863 Number highlight positions with {group} | |
2864 matcharg({nr}) List arguments of |:match| | |
2865 matchdelete({id} [, {win}]) Number delete match identified by {id} | |
2866 matchend({expr}, {pat} [, {start} [, {count}]]) | |
2867 Number position where {pat} ends in {expr} | |
2868 matchfuzzy({list}, {str} [, {dict}]) | |
2869 List fuzzy match {str} in {list} | |
2870 matchfuzzypos({list}, {str} [, {dict}]) | |
2871 List fuzzy match {str} in {list} | |
2872 matchlist({expr}, {pat} [, {start} [, {count}]]) | |
2873 List match and submatches of {pat} in {expr} | |
2874 matchstr({expr}, {pat} [, {start} [, {count}]]) | |
2875 String {count}'th match of {pat} in {expr} | |
2876 matchstrpos({expr}, {pat} [, {start} [, {count}]]) | |
2877 List {count}'th match of {pat} in {expr} | |
2878 max({expr}) Number maximum value of items in {expr} | |
2879 menu_info({name} [, {mode}]) Dict get menu item information | |
2880 min({expr}) Number minimum value of items in {expr} | |
2881 mkdir({name} [, {path} [, {prot}]]) | |
2882 Number create directory {name} | |
2883 mode([expr]) String current editing mode | |
2884 mzeval({expr}) any evaluate |MzScheme| expression | |
2885 nextnonblank({lnum}) Number line nr of non-blank line >= {lnum} | |
2886 nr2char({expr} [, {utf8}]) String single char with ASCII/UTF-8 value {expr} | |
2887 or({expr}, {expr}) Number bitwise OR | |
2888 pathshorten({expr} [, {len}]) String shorten directory names in a path | |
2889 perleval({expr}) any evaluate |Perl| expression | |
2890 popup_atcursor({what}, {options}) Number create popup window near the cursor | |
2891 popup_beval({what}, {options}) Number create popup window for 'ballooneval' | |
2892 popup_clear() none close all popup windows | |
2893 popup_close({id} [, {result}]) none close popup window {id} | |
2894 popup_create({what}, {options}) Number create a popup window | |
2895 popup_dialog({what}, {options}) Number create a popup window used as a dialog | |
2896 popup_filter_menu({id}, {key}) Number filter for a menu popup window | |
2897 popup_filter_yesno({id}, {key}) Number filter for a dialog popup window | |
2898 popup_findinfo() Number get window ID of info popup window | |
2899 popup_findpreview() Number get window ID of preview popup window | |
2900 popup_getoptions({id}) Dict get options of popup window {id} | |
2901 popup_getpos({id}) Dict get position of popup window {id} | |
2902 popup_hide({id}) none hide popup menu {id} | |
2903 popup_list() List get a list of window IDs of all popups | |
2904 popup_locate({row}, {col}) Number get window ID of popup at position | |
2905 popup_menu({what}, {options}) Number create a popup window used as a menu | |
2906 popup_move({id}, {options}) none set position of popup window {id} | |
2907 popup_notification({what}, {options}) | |
2908 Number create a notification popup window | |
2909 popup_setoptions({id}, {options}) | |
2910 none set options for popup window {id} | |
2911 popup_settext({id}, {text}) none set the text of popup window {id} | |
2912 popup_show({id}) none unhide popup window {id} | |
2913 pow({x}, {y}) Float {x} to the power of {y} | |
2914 prevnonblank({lnum}) Number line nr of non-blank line <= {lnum} | |
2915 printf({fmt}, {expr1}...) String format text | |
2916 prompt_getprompt({buf}) String get prompt text | |
2917 prompt_setcallback({buf}, {expr}) none set prompt callback function | |
2918 prompt_setinterrupt({buf}, {text}) none set prompt interrupt function | |
2919 prompt_setprompt({buf}, {text}) none set prompt text | |
2920 prop_add({lnum}, {col}, {props}) none add one text property | |
2921 prop_add_list({props}, [[{lnum}, {col}, {end-lnum}, {end-col}], ...]) | |
2922 none add multiple text properties | |
2923 prop_clear({lnum} [, {lnum-end} [, {props}]]) | |
2924 none remove all text properties | |
2925 prop_find({props} [, {direction}]) | |
2926 Dict search for a text property | |
2927 prop_list({lnum} [, {props}]) List text properties in {lnum} | |
2928 prop_remove({props} [, {lnum} [, {lnum-end}]]) | |
2929 Number remove a text property | |
2930 prop_type_add({name}, {props}) none define a new property type | |
2931 prop_type_change({name}, {props}) | |
2932 none change an existing property type | |
2933 prop_type_delete({name} [, {props}]) | |
2934 none delete a property type | |
2935 prop_type_get({name} [, {props}]) | |
2936 Dict get property type values | |
2937 prop_type_list([{props}]) List get list of property types | |
2938 pum_getpos() Dict position and size of pum if visible | |
2939 pumvisible() Number whether popup menu is visible | |
2940 py3eval({expr}) any evaluate |python3| expression | |
2941 pyeval({expr}) any evaluate |Python| expression | |
2942 pyxeval({expr}) any evaluate |python_x| expression | |
2943 rand([{expr}]) Number get pseudo-random number | |
2944 range({expr} [, {max} [, {stride}]]) | |
2945 List items from {expr} to {max} | |
2946 readblob({fname}) Blob read a |Blob| from {fname} | |
2947 readdir({dir} [, {expr} [, {dict}]]) | |
2948 List file names in {dir} selected by {expr} | |
2949 readdirex({dir} [, {expr} [, {dict}]]) | |
2950 List file info in {dir} selected by {expr} | |
2951 readfile({fname} [, {type} [, {max}]]) | |
2952 List get list of lines from file {fname} | |
2953 reduce({object}, {func} [, {initial}]) | |
2954 any reduce {object} using {func} | |
2955 reg_executing() String get the executing register name | |
2956 reg_recording() String get the recording register name | |
2957 reltime([{start} [, {end}]]) List get time value | |
2958 reltimefloat({time}) Float turn the time value into a Float | |
2959 reltimestr({time}) String turn time value into a String | |
2960 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) | |
2961 String send expression | |
2962 remote_foreground({server}) Number bring Vim server to the foreground | |
2963 remote_peek({serverid} [, {retvar}]) | |
2964 Number check for reply string | |
2965 remote_read({serverid} [, {timeout}]) | |
2966 String read reply string | |
2967 remote_send({server}, {string} [, {idvar}]) | |
2968 String send key sequence | |
2969 remote_startserver({name}) none become server {name} | |
2970 remove({list}, {idx} [, {end}]) any/List | |
2971 remove items {idx}-{end} from {list} | |
2972 remove({blob}, {idx} [, {end}]) Number/Blob | |
2973 remove bytes {idx}-{end} from {blob} | |
2974 remove({dict}, {key}) any remove entry {key} from {dict} | |
2975 rename({from}, {to}) Number rename (move) file from {from} to {to} | |
2976 repeat({expr}, {count}) String repeat {expr} {count} times | |
2977 resolve({filename}) String get filename a shortcut points to | |
2978 reverse({list}) List reverse {list} in-place | |
2979 round({expr}) Float round off {expr} | |
2980 rubyeval({expr}) any evaluate |Ruby| expression | |
2981 screenattr({row}, {col}) Number attribute at screen position | |
2982 screenchar({row}, {col}) Number character at screen position | |
2983 screenchars({row}, {col}) List List of characters at screen position | |
2984 screencol() Number current cursor column | |
2985 screenpos({winid}, {lnum}, {col}) Dict screen row and col of a text character | |
2986 screenrow() Number current cursor row | |
2987 screenstring({row}, {col}) String characters at screen position | |
2988 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
2989 Number search for {pattern} | |
2990 searchcount([{options}]) Dict get or update search stats | |
2991 searchdecl({name} [, {global} [, {thisblock}]]) | |
2992 Number search for variable declaration | |
2993 searchpair({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) | |
2994 Number search for other end of start/end pair | |
2995 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} [...]]]) | |
2996 List search for other end of start/end pair | |
2997 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
2998 List search for {pattern} | |
2999 server2client({clientid}, {string}) | |
3000 Number send reply string | |
3001 serverlist() String get a list of available servers | |
3002 setbufline({expr}, {lnum}, {text}) | |
3003 Number set line {lnum} to {text} in buffer | |
3004 {expr} | |
3005 setbufvar({buf}, {varname}, {val}) | |
3006 none set {varname} in buffer {buf} to {val} | |
3007 setcellwidths({list}) none set character cell width overrides | |
3008 setcharpos({expr}, {list}) Number set the {expr} position to {list} | |
3009 setcharsearch({dict}) Dict set character search from {dict} | |
3010 setcmdpos({pos}) Number set cursor position in command-line | |
3011 setcursorcharpos({list}) Number move cursor to position in {list} | |
3012 setenv({name}, {val}) none set environment variable | |
3013 setfperm({fname}, {mode}) Number set {fname} file permissions to {mode} | |
3014 setline({lnum}, {line}) Number set line {lnum} to {line} | |
3015 setloclist({nr}, {list} [, {action}]) | |
3016 Number modify location list using {list} | |
3017 setloclist({nr}, {list}, {action}, {what}) | |
3018 Number modify specific location list props | |
3019 setmatches({list} [, {win}]) Number restore a list of matches | |
3020 setpos({expr}, {list}) Number set the {expr} position to {list} | |
3021 setqflist({list} [, {action}]) Number modify quickfix list using {list} | |
3022 setqflist({list}, {action}, {what}) | |
3023 Number modify specific quickfix list props | |
3024 setreg({n}, {v} [, {opt}]) Number set register to value and type | |
3025 settabvar({nr}, {varname}, {val}) none set {varname} in tab page {nr} to {val} | |
3026 settabwinvar({tabnr}, {winnr}, {varname}, {val}) | |
3027 none set {varname} in window {winnr} in tab | |
3028 page {tabnr} to {val} | |
3029 settagstack({nr}, {dict} [, {action}]) | |
3030 Number modify tag stack using {dict} | |
3031 setwinvar({nr}, {varname}, {val}) none set {varname} in window {nr} to {val} | |
3032 sha256({string}) String SHA256 checksum of {string} | |
3033 shellescape({string} [, {special}]) | |
3034 String escape {string} for use as shell | |
3035 command argument | |
3036 shiftwidth([{col}]) Number effective value of 'shiftwidth' | |
3037 sign_define({name} [, {dict}]) Number define or update a sign | |
3038 sign_define({list}) List define or update a list of signs | |
3039 sign_getdefined([{name}]) List get a list of defined signs | |
3040 sign_getplaced([{buf} [, {dict}]]) | |
3041 List get a list of placed signs | |
3042 sign_jump({id}, {group}, {buf}) | |
3043 Number jump to a sign | |
3044 sign_place({id}, {group}, {name}, {buf} [, {dict}]) | |
3045 Number place a sign | |
3046 sign_placelist({list}) List place a list of signs | |
3047 sign_undefine([{name}]) Number undefine a sign | |
3048 sign_undefine({list}) List undefine a list of signs | |
3049 sign_unplace({group} [, {dict}]) | |
3050 Number unplace a sign | |
3051 sign_unplacelist({list}) List unplace a list of signs | |
3052 simplify({filename}) String simplify filename as much as possible | |
3053 sin({expr}) Float sine of {expr} | |
3054 sinh({expr}) Float hyperbolic sine of {expr} | |
3055 slice({expr}, {start} [, {end}]) String, List or Blob | |
3056 slice of a String, List or Blob | |
3057 sort({list} [, {func} [, {dict}]]) | |
3058 List sort {list}, using {func} to compare | |
3059 sound_clear() none stop playing all sounds | |
3060 sound_playevent({name} [, {callback}]) | |
3061 Number play an event sound | |
3062 sound_playfile({path} [, {callback}]) | |
3063 Number play sound file {path} | |
3064 sound_stop({id}) none stop playing sound {id} | |
3065 soundfold({word}) String sound-fold {word} | |
3066 spellbadword() String badly spelled word at cursor | |
3067 spellsuggest({word} [, {max} [, {capital}]]) | |
3068 List spelling suggestions | |
3069 split({expr} [, {pat} [, {keepempty}]]) | |
3070 List make |List| from {pat} separated {expr} | |
3071 sqrt({expr}) Float square root of {expr} | |
3072 srand([{expr}]) List get seed for |rand()| | |
3073 state([{what}]) String current state of Vim | |
3074 str2float({expr} [, {quoted}]) Float convert String to Float | |
3075 str2list({expr} [, {utf8}]) List convert each character of {expr} to | |
3076 ASCII/UTF-8 value | |
3077 str2nr({expr} [, {base} [, {quoted}]]) | |
3078 Number convert String to Number | |
3079 strcharlen({expr}) Number character length of the String {expr} | |
3080 strcharpart({str}, {start} [, {len} [, {skipcc}]]) | |
3081 String {len} characters of {str} at | |
3082 character {start} | |
3083 strchars({expr} [, {skipcc}]) Number character count of the String {expr} | |
3084 strdisplaywidth({expr} [, {col}]) Number display length of the String {expr} | |
3085 strftime({format} [, {time}]) String format time with a specified format | |
3086 strgetchar({str}, {index}) Number get char {index} from {str} | |
3087 stridx({haystack}, {needle} [, {start}]) | |
3088 Number index of {needle} in {haystack} | |
3089 string({expr}) String String representation of {expr} value | |
3090 strlen({expr}) Number length of the String {expr} | |
3091 strpart({str}, {start} [, {len} [, {chars}]]) | |
3092 String {len} bytes/chars of {str} at | |
3093 byte {start} | |
3094 strptime({format}, {timestring}) | |
3095 Number Convert {timestring} to unix timestamp | |
3096 strridx({haystack}, {needle} [, {start}]) | |
3097 Number last index of {needle} in {haystack} | |
3098 strtrans({expr}) String translate string to make it printable | |
3099 strwidth({expr}) Number display cell length of the String {expr} | |
3100 submatch({nr} [, {list}]) String or List | |
3101 specific match in ":s" or substitute() | |
3102 substitute({expr}, {pat}, {sub}, {flags}) | |
3103 String all {pat} in {expr} replaced with {sub} | |
3104 swapinfo({fname}) Dict information about swap file {fname} | |
3105 swapname({buf}) String swap file of buffer {buf} | |
3106 synID({lnum}, {col}, {trans}) Number syntax ID at {lnum} and {col} | |
3107 synIDattr({synID}, {what} [, {mode}]) | |
3108 String attribute {what} of syntax ID {synID} | |
3109 synIDtrans({synID}) Number translated syntax ID of {synID} | |
3110 synconcealed({lnum}, {col}) List info about concealing | |
3111 synstack({lnum}, {col}) List stack of syntax IDs at {lnum} and {col} | |
3112 system({expr} [, {input}]) String output of shell command/filter {expr} | |
3113 systemlist({expr} [, {input}]) List output of shell command/filter {expr} | |
3114 tabpagebuflist([{arg}]) List list of buffer numbers in tab page | |
3115 tabpagenr([{arg}]) Number number of current or last tab page | |
3116 tabpagewinnr({tabarg} [, {arg}]) Number number of current window in tab page | |
3117 tagfiles() List tags files used | |
3118 taglist({expr} [, {filename}]) List list of tags matching {expr} | |
3119 tan({expr}) Float tangent of {expr} | |
3120 tanh({expr}) Float hyperbolic tangent of {expr} | |
3121 tempname() String name for a temporary file | |
3122 term_dumpdiff({filename}, {filename} [, {options}]) | |
3123 Number display difference between two dumps | |
3124 term_dumpload({filename} [, {options}]) | |
3125 Number displaying a screen dump | |
3126 term_dumpwrite({buf}, {filename} [, {options}]) | |
3127 none dump terminal window contents | |
3128 term_getaltscreen({buf}) Number get the alternate screen flag | |
3129 term_getansicolors({buf}) List get ANSI palette in GUI color mode | |
3130 term_getattr({attr}, {what}) Number get the value of attribute {what} | |
3131 term_getcursor({buf}) List get the cursor position of a terminal | |
3132 term_getjob({buf}) Job get the job associated with a terminal | |
3133 term_getline({buf}, {row}) String get a line of text from a terminal | |
3134 term_getscrolled({buf}) Number get the scroll count of a terminal | |
3135 term_getsize({buf}) List get the size of a terminal | |
3136 term_getstatus({buf}) String get the status of a terminal | |
3137 term_gettitle({buf}) String get the title of a terminal | |
3138 term_gettty({buf}, [{input}]) String get the tty name of a terminal | |
3139 term_list() List get the list of terminal buffers | |
3140 term_scrape({buf}, {row}) List get row of a terminal screen | |
3141 term_sendkeys({buf}, {keys}) none send keystrokes to a terminal | |
3142 term_setansicolors({buf}, {colors}) | |
3143 none set ANSI palette in GUI color mode | |
3144 term_setapi({buf}, {expr}) none set |terminal-api| function name prefix | |
3145 term_setkill({buf}, {how}) none set signal to stop job in terminal | |
3146 term_setrestore({buf}, {command}) none set command to restore terminal | |
3147 term_setsize({buf}, {rows}, {cols}) | |
3148 none set the size of a terminal | |
3149 term_start({cmd} [, {options}]) Number open a terminal window and run a job | |
3150 term_wait({buf} [, {time}]) Number wait for screen to be updated | |
3151 terminalprops() Dict properties of the terminal | |
3152 test_alloc_fail({id}, {countdown}, {repeat}) | |
3153 none make memory allocation fail | |
3154 test_autochdir() none enable 'autochdir' during startup | |
3155 test_feedinput({string}) none add key sequence to input buffer | |
3156 test_garbagecollect_now() none free memory right now for testing | |
3157 test_garbagecollect_soon() none free memory soon for testing | |
3158 test_getvalue({string}) any get value of an internal variable | |
3159 test_gui_drop_files({list}, {row}, {col}, {mods}) | |
3160 none drop a list of files in a window | |
3161 test_gui_mouse_event({button}, {row}, {col}, {repeated}, {mods}) | |
3162 none add a mouse event to the input buffer | |
3163 test_ignore_error({expr}) none ignore a specific error | |
3164 test_null_blob() Blob null value for testing | |
3165 test_null_channel() Channel null value for testing | |
3166 test_null_dict() Dict null value for testing | |
3167 test_null_function() Funcref null value for testing | |
3168 test_null_job() Job null value for testing | |
3169 test_null_list() List null value for testing | |
3170 test_null_partial() Funcref null value for testing | |
3171 test_null_string() String null value for testing | |
3172 test_option_not_set({name}) none reset flag indicating option was set | |
3173 test_override({expr}, {val}) none test with Vim internal overrides | |
3174 test_refcount({expr}) Number get the reference count of {expr} | |
3175 test_scrollbar({which}, {value}, {dragging}) | |
3176 none scroll in the GUI for testing | |
3177 test_setmouse({row}, {col}) none set the mouse position for testing | |
3178 test_settime({expr}) none set current time for testing | |
3179 test_srand_seed([seed]) none set seed for testing srand() | |
3180 test_unknown() any unknown value for testing | |
3181 test_void() any void value for testing | |
3182 timer_info([{id}]) List information about timers | |
3183 timer_pause({id}, {pause}) none pause or unpause a timer | |
3184 timer_start({time}, {callback} [, {options}]) | |
3185 Number create a timer | |
3186 timer_stop({timer}) none stop a timer | |
3187 timer_stopall() none stop all timers | |
3188 tolower({expr}) String the String {expr} switched to lowercase | |
3189 toupper({expr}) String the String {expr} switched to uppercase | |
3190 tr({src}, {fromstr}, {tostr}) String translate chars of {src} in {fromstr} | |
3191 to chars in {tostr} | |
3192 trim({text} [, {mask} [, {dir}]]) | |
3193 String trim characters in {mask} from {text} | |
3194 trunc({expr}) Float truncate Float {expr} | |
3195 type({expr}) Number type of value {expr} | |
3196 typename({expr}) String representation of the type of {expr} | |
3197 undofile({name}) String undo file name for {name} | |
3198 undotree() List undo file tree | |
3199 uniq({list} [, {func} [, {dict}]]) | |
3200 List remove adjacent duplicates from a list | |
3201 values({dict}) List values in {dict} | |
3202 virtcol({expr}) Number screen column of cursor or mark | |
3203 visualmode([expr]) String last visual mode used | |
3204 wildmenumode() Number whether 'wildmenu' mode is active | |
3205 win_execute({id}, {command} [, {silent}]) | |
3206 String execute {command} in window {id} | |
3207 win_findbuf({bufnr}) List find windows containing {bufnr} | |
3208 win_getid([{win} [, {tab}]]) Number get window ID for {win} in {tab} | |
3209 win_gettype([{nr}]) String type of window {nr} | |
3210 win_gotoid({expr}) Number go to window with ID {expr} | |
3211 win_id2tabwin({expr}) List get tab and window nr from window ID | |
3212 win_id2win({expr}) Number get window nr from window ID | |
3213 win_screenpos({nr}) List get screen position of window {nr} | |
3214 win_splitmove({nr}, {target} [, {options}]) | |
3215 Number move window {nr} to split of {target} | |
3216 winbufnr({nr}) Number buffer number of window {nr} | |
3217 wincol() Number window column of the cursor | |
3218 windowsversion() String MS-Windows OS version | |
3219 winheight({nr}) Number height of window {nr} | |
3220 winlayout([{tabnr}]) List layout of windows in tab {tabnr} | |
3221 winline() Number window line of the cursor | |
3222 winnr([{expr}]) Number number of current window | |
3223 winrestcmd() String returns command to restore window sizes | |
3224 winrestview({dict}) none restore view of current window | |
3225 winsaveview() Dict save view of current window | |
3226 winwidth({nr}) Number width of window {nr} | |
3227 wordcount() Dict get byte/char/word statistics | |
3228 writefile({object}, {fname} [, {flags}]) | |
3229 Number write |Blob| or |List| of lines to file | |
3230 xor({expr}, {expr}) Number bitwise XOR | |
3231 | |
3232 | |
3233 abs({expr}) *abs()* | |
3234 Return the absolute value of {expr}. When {expr} evaluates to | |
3235 a |Float| abs() returns a |Float|. When {expr} can be | |
3236 converted to a |Number| abs() returns a |Number|. Otherwise | |
3237 abs() gives an error message and returns -1. | |
3238 Examples: > | |
3239 echo abs(1.456) | |
3240 < 1.456 > | |
3241 echo abs(-5.456) | |
3242 < 5.456 > | |
3243 echo abs(-4) | |
3244 < 4 | |
3245 | |
3246 Can also be used as a |method|: > | |
3247 Compute()->abs() | |
3248 | |
3249 < {only available when compiled with the |+float| feature} | |
3250 | |
3251 | |
3252 acos({expr}) *acos()* | |
3253 Return the arc cosine of {expr} measured in radians, as a | |
3254 |Float| in the range of [0, pi]. | |
3255 {expr} must evaluate to a |Float| or a |Number| in the range | |
3256 [-1, 1]. | |
3257 Examples: > | |
3258 :echo acos(0) | |
3259 < 1.570796 > | |
3260 :echo acos(-0.5) | |
3261 < 2.094395 | |
3262 | |
3263 Can also be used as a |method|: > | |
3264 Compute()->acos() | |
3265 | |
3266 < {only available when compiled with the |+float| feature} | |
3267 | |
3268 | |
3269 add({object}, {expr}) *add()* | |
3270 Append the item {expr} to |List| or |Blob| {object}. Returns | |
3271 the resulting |List| or |Blob|. Examples: > | |
3272 :let alist = add([1, 2, 3], item) | |
3273 :call add(mylist, "woodstock") | |
3274 < Note that when {expr} is a |List| it is appended as a single | |
3275 item. Use |extend()| to concatenate |Lists|. | |
3276 When {object} is a |Blob| then {expr} must be a number. | |
3277 Use |insert()| to add an item at another position. | |
3278 | |
3279 Can also be used as a |method|: > | |
3280 mylist->add(val1)->add(val2) | |
3281 | |
3282 | |
3283 and({expr}, {expr}) *and()* | |
3284 Bitwise AND on the two arguments. The arguments are converted | |
3285 to a number. A List, Dict or Float argument causes an error. | |
3286 Example: > | |
3287 :let flag = and(bits, 0x80) | |
3288 < Can also be used as a |method|: > | |
3289 :let flag = bits->and(0x80) | |
3290 | |
3291 | |
3292 append({lnum}, {text}) *append()* | |
3293 When {text} is a |List|: Append each item of the |List| as a | |
3294 text line below line {lnum} in the current buffer. | |
3295 Otherwise append {text} as one text line below line {lnum} in | |
3296 the current buffer. | |
3297 Any type of item is accepted and converted to a String. | |
3298 {lnum} can be zero to insert a line before the first one. | |
3299 {lnum} is used like with |getline()|. | |
3300 Returns 1 for failure ({lnum} out of range or out of memory), | |
3301 0 for success. Example: > | |
3302 :let failed = append(line('$'), "# THE END") | |
3303 :let failed = append(0, ["Chapter 1", "the beginning"]) | |
3304 | |
3305 < Can also be used as a |method| after a List, the base is | |
3306 passed as the second argument: > | |
3307 mylist->append(lnum) | |
3308 | |
3309 | |
3310 appendbufline({buf}, {lnum}, {text}) *appendbufline()* | |
3311 Like |append()| but append the text in buffer {buf}. | |
3312 | |
3313 This function works only for loaded buffers. First call | |
3314 |bufload()| if needed. | |
3315 | |
3316 For the use of {buf}, see |bufname()|. | |
3317 | |
3318 {lnum} is used like with |append()|. Note that using |line()| | |
3319 would use the current buffer, not the one appending to. | |
3320 Use "$" to append at the end of the buffer. | |
3321 | |
3322 On success 0 is returned, on failure 1 is returned. | |
3323 | |
3324 If {buf} is not a valid buffer or {lnum} is not valid, an | |
3325 error message is given. Example: > | |
3326 :let failed = appendbufline(13, 0, "# THE START") | |
3327 < | |
3328 Can also be used as a |method| after a List, the base is | |
3329 passed as the second argument: > | |
3330 mylist->appendbufline(buf, lnum) | |
3331 | |
3332 | |
3333 argc([{winid}]) *argc()* | |
3334 The result is the number of files in the argument list. See | |
3335 |arglist|. | |
3336 If {winid} is not supplied, the argument list of the current | |
3337 window is used. | |
3338 If {winid} is -1, the global argument list is used. | |
3339 Otherwise {winid} specifies the window of which the argument | |
3340 list is used: either the window number or the window ID. | |
3341 Returns -1 if the {winid} argument is invalid. | |
3342 | |
3343 *argidx()* | |
3344 argidx() The result is the current index in the argument list. 0 is | |
3345 the first file. argc() - 1 is the last one. See |arglist|. | |
3346 | |
3347 *arglistid()* | |
3348 arglistid([{winnr} [, {tabnr}]]) | |
3349 Return the argument list ID. This is a number which | |
3350 identifies the argument list being used. Zero is used for the | |
3351 global argument list. See |arglist|. | |
3352 Returns -1 if the arguments are invalid. | |
3353 | |
3354 Without arguments use the current window. | |
3355 With {winnr} only use this window in the current tab page. | |
3356 With {winnr} and {tabnr} use the window in the specified tab | |
3357 page. | |
3358 {winnr} can be the window number or the |window-ID|. | |
3359 | |
3360 *argv()* | |
3361 argv([{nr} [, {winid}]]) | |
3362 The result is the {nr}th file in the argument list. See | |
3363 |arglist|. "argv(0)" is the first one. Example: > | |
3364 :let i = 0 | |
3365 :while i < argc() | |
3366 : let f = escape(fnameescape(argv(i)), '.') | |
3367 : exe 'amenu Arg.' . f . ' :e ' . f . '<CR>' | |
3368 : let i = i + 1 | |
3369 :endwhile | |
3370 < Without the {nr} argument, or when {nr} is -1, a |List| with | |
3371 the whole |arglist| is returned. | |
3372 | |
3373 The {winid} argument specifies the window ID, see |argc()|. | |
3374 For the Vim command line arguments see |v:argv|. | |
3375 | |
3376 asin({expr}) *asin()* | |
3377 Return the arc sine of {expr} measured in radians, as a |Float| | |
3378 in the range of [-pi/2, pi/2]. | |
3379 {expr} must evaluate to a |Float| or a |Number| in the range | |
3380 [-1, 1]. | |
3381 Examples: > | |
3382 :echo asin(0.8) | |
3383 < 0.927295 > | |
3384 :echo asin(-0.5) | |
3385 < -0.523599 | |
3386 | |
3387 Can also be used as a |method|: > | |
3388 Compute()->asin() | |
3389 < | |
3390 {only available when compiled with the |+float| feature} | |
3391 | |
3392 | |
3393 assert_ functions are documented here: |assert-functions-details| | |
3394 | |
3395 | |
3396 | |
3397 atan({expr}) *atan()* | |
3398 Return the principal value of the arc tangent of {expr}, in | |
3399 the range [-pi/2, +pi/2] radians, as a |Float|. | |
3400 {expr} must evaluate to a |Float| or a |Number|. | |
3401 Examples: > | |
3402 :echo atan(100) | |
3403 < 1.560797 > | |
3404 :echo atan(-4.01) | |
3405 < -1.326405 | |
3406 | |
3407 Can also be used as a |method|: > | |
3408 Compute()->atan() | |
3409 < | |
3410 {only available when compiled with the |+float| feature} | |
3411 | |
3412 | |
3413 atan2({expr1}, {expr2}) *atan2()* | |
3414 Return the arc tangent of {expr1} / {expr2}, measured in | |
3415 radians, as a |Float| in the range [-pi, pi]. | |
3416 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. | |
3417 Examples: > | |
3418 :echo atan2(-1, 1) | |
3419 < -0.785398 > | |
3420 :echo atan2(1, -1) | |
3421 < 2.356194 | |
3422 | |
3423 Can also be used as a |method|: > | |
3424 Compute()->atan2(1) | |
3425 < | |
3426 {only available when compiled with the |+float| feature} | |
3427 | |
3428 balloon_gettext() *balloon_gettext()* | |
3429 Return the current text in the balloon. Only for the string, | |
3430 not used for the List. | |
3431 | |
3432 balloon_show({expr}) *balloon_show()* | |
3433 Show {expr} inside the balloon. For the GUI {expr} is used as | |
3434 a string. For a terminal {expr} can be a list, which contains | |
3435 the lines of the balloon. If {expr} is not a list it will be | |
3436 split with |balloon_split()|. | |
3437 If {expr} is an empty string any existing balloon is removed. | |
3438 | |
3439 Example: > | |
3440 func GetBalloonContent() | |
3441 " ... initiate getting the content | |
3442 return '' | |
3443 endfunc | |
3444 set balloonexpr=GetBalloonContent() | |
3445 | |
3446 func BalloonCallback(result) | |
3447 call balloon_show(a:result) | |
3448 endfunc | |
3449 < Can also be used as a |method|: > | |
3450 GetText()->balloon_show() | |
3451 < | |
3452 The intended use is that fetching the content of the balloon | |
3453 is initiated from 'balloonexpr'. It will invoke an | |
3454 asynchronous method, in which a callback invokes | |
3455 balloon_show(). The 'balloonexpr' itself can return an | |
3456 empty string or a placeholder. | |
3457 | |
3458 When showing a balloon is not possible nothing happens, no | |
3459 error message. | |
3460 {only available when compiled with the |+balloon_eval| or | |
3461 |+balloon_eval_term| feature} | |
3462 | |
3463 balloon_split({msg}) *balloon_split()* | |
3464 Split String {msg} into lines to be displayed in a balloon. | |
3465 The splits are made for the current window size and optimize | |
3466 to show debugger output. | |
3467 Returns a |List| with the split lines. | |
3468 Can also be used as a |method|: > | |
3469 GetText()->balloon_split()->balloon_show() | |
3470 | |
3471 < {only available when compiled with the |+balloon_eval_term| | |
3472 feature} | |
3473 | |
3474 blob2list({blob}) *blob2list()* | |
3475 Return a List containing the number value of each byte in Blob | |
3476 {blob}. Examples: > | |
3477 blob2list(0z0102.0304) returns [1, 2, 3, 4] | |
3478 blob2list(0z) returns [] | |
3479 < Returns an empty List on error. |list2blob()| does the | |
3480 opposite. | |
3481 | |
3482 Can also be used as a |method|: > | |
3483 GetBlob()->blob2list() | |
3484 | |
3485 *browse()* | |
3486 browse({save}, {title}, {initdir}, {default}) | |
3487 Put up a file requester. This only works when "has("browse")" | |
3488 returns |TRUE| (only in some GUI versions). | |
3489 The input fields are: | |
3490 {save} when |TRUE|, select file to write | |
3491 {title} title for the requester | |
3492 {initdir} directory to start browsing in | |
3493 {default} default file name | |
3494 An empty string is returned when the "Cancel" button is hit, | |
3495 something went wrong, or browsing is not possible. | |
3496 | |
3497 *browsedir()* | |
3498 browsedir({title}, {initdir}) | |
3499 Put up a directory requester. This only works when | |
3500 "has("browse")" returns |TRUE| (only in some GUI versions). | |
3501 On systems where a directory browser is not supported a file | |
3502 browser is used. In that case: select a file in the directory | |
3503 to be used. | |
3504 The input fields are: | |
3505 {title} title for the requester | |
3506 {initdir} directory to start browsing in | |
3507 When the "Cancel" button is hit, something went wrong, or | |
3508 browsing is not possible, an empty string is returned. | |
3509 | |
3510 bufadd({name}) *bufadd()* | |
3511 Add a buffer to the buffer list with String {name}. | |
3512 If a buffer for file {name} already exists, return that buffer | |
3513 number. Otherwise return the buffer number of the newly | |
3514 created buffer. When {name} is an empty string then a new | |
3515 buffer is always created. | |
3516 The buffer will not have 'buflisted' set and not be loaded | |
3517 yet. To add some text to the buffer use this: > | |
3518 let bufnr = bufadd('someName') | |
3519 call bufload(bufnr) | |
3520 call setbufline(bufnr, 1, ['some', 'text']) | |
3521 < Can also be used as a |method|: > | |
3522 let bufnr = 'somename'->bufadd() | |
3523 | |
3524 bufexists({buf}) *bufexists()* | |
3525 The result is a Number, which is |TRUE| if a buffer called | |
3526 {buf} exists. | |
3527 If the {buf} argument is a number, buffer numbers are used. | |
3528 Number zero is the alternate buffer for the current window. | |
3529 | |
3530 If the {buf} argument is a string it must match a buffer name | |
3531 exactly. The name can be: | |
3532 - Relative to the current directory. | |
3533 - A full path. | |
3534 - The name of a buffer with 'buftype' set to "nofile". | |
3535 - A URL name. | |
3536 Unlisted buffers will be found. | |
3537 Note that help files are listed by their short name in the | |
3538 output of |:buffers|, but bufexists() requires using their | |
3539 long name to be able to find them. | |
3540 bufexists() may report a buffer exists, but to use the name | |
3541 with a |:buffer| command you may need to use |expand()|. Esp | |
3542 for MS-Windows 8.3 names in the form "c:\DOCUME~1" | |
3543 Use "bufexists(0)" to test for the existence of an alternate | |
3544 file name. | |
3545 | |
3546 Can also be used as a |method|: > | |
3547 let exists = 'somename'->bufexists() | |
3548 < | |
3549 Obsolete name: buffer_exists(). *buffer_exists()* | |
3550 | |
3551 buflisted({buf}) *buflisted()* | |
3552 The result is a Number, which is |TRUE| if a buffer called | |
3553 {buf} exists and is listed (has the 'buflisted' option set). | |
3554 The {buf} argument is used like with |bufexists()|. | |
3555 | |
3556 Can also be used as a |method|: > | |
3557 let listed = 'somename'->buflisted() | |
3558 | |
3559 bufload({buf}) *bufload()* | |
3560 Ensure the buffer {buf} is loaded. When the buffer name | |
3561 refers to an existing file then the file is read. Otherwise | |
3562 the buffer will be empty. If the buffer was already loaded | |
3563 then there is no change. | |
3564 If there is an existing swap file for the file of the buffer, | |
3565 there will be no dialog, the buffer will be loaded anyway. | |
3566 The {buf} argument is used like with |bufexists()|. | |
3567 | |
3568 Can also be used as a |method|: > | |
3569 eval 'somename'->bufload() | |
3570 | |
3571 bufloaded({buf}) *bufloaded()* | |
3572 The result is a Number, which is |TRUE| if a buffer called | |
3573 {buf} exists and is loaded (shown in a window or hidden). | |
3574 The {buf} argument is used like with |bufexists()|. | |
3575 | |
3576 Can also be used as a |method|: > | |
3577 let loaded = 'somename'->bufloaded() | |
3578 | |
3579 bufname([{buf}]) *bufname()* | |
3580 The result is the name of a buffer. Mostly as it is displayed | |
3581 by the `:ls` command, but not using special names such as | |
3582 "[No Name]". | |
3583 If {buf} is omitted the current buffer is used. | |
3584 If {buf} is a Number, that buffer number's name is given. | |
3585 Number zero is the alternate buffer for the current window. | |
3586 If {buf} is a String, it is used as a |file-pattern| to match | |
3587 with the buffer names. This is always done like 'magic' is | |
3588 set and 'cpoptions' is empty. When there is more than one | |
3589 match an empty string is returned. | |
3590 "" or "%" can be used for the current buffer, "#" for the | |
3591 alternate buffer. | |
3592 A full match is preferred, otherwise a match at the start, end | |
3593 or middle of the buffer name is accepted. If you only want a | |
3594 full match then put "^" at the start and "$" at the end of the | |
3595 pattern. | |
3596 Listed buffers are found first. If there is a single match | |
3597 with a listed buffer, that one is returned. Next unlisted | |
3598 buffers are searched for. | |
3599 If the {buf} is a String, but you want to use it as a buffer | |
3600 number, force it to be a Number by adding zero to it: > | |
3601 :echo bufname("3" + 0) | |
3602 < Can also be used as a |method|: > | |
3603 echo bufnr->bufname() | |
3604 | |
3605 < If the buffer doesn't exist, or doesn't have a name, an empty | |
3606 string is returned. > | |
3607 bufname("#") alternate buffer name | |
3608 bufname(3) name of buffer 3 | |
3609 bufname("%") name of current buffer | |
3610 bufname("file2") name of buffer where "file2" matches. | |
3611 < *buffer_name()* | |
3612 Obsolete name: buffer_name(). | |
3613 | |
3614 *bufnr()* | |
3615 bufnr([{buf} [, {create}]]) | |
3616 The result is the number of a buffer, as it is displayed by | |
3617 the `:ls` command. For the use of {buf}, see |bufname()| | |
3618 above. | |
3619 | |
3620 If the buffer doesn't exist, -1 is returned. Or, if the | |
3621 {create} argument is present and TRUE, a new, unlisted, | |
3622 buffer is created and its number is returned. Example: > | |
3623 let newbuf = bufnr('Scratch001', 1) | |
3624 < Using an empty name uses the current buffer. To create a new | |
3625 buffer with an empty name use |bufadd()|. | |
3626 | |
3627 bufnr("$") is the last buffer: > | |
3628 :let last_buffer = bufnr("$") | |
3629 < The result is a Number, which is the highest buffer number | |
3630 of existing buffers. Note that not all buffers with a smaller | |
3631 number necessarily exist, because ":bwipeout" may have removed | |
3632 them. Use bufexists() to test for the existence of a buffer. | |
3633 | |
3634 Can also be used as a |method|: > | |
3635 echo bufref->bufnr() | |
3636 < | |
3637 Obsolete name: buffer_number(). *buffer_number()* | |
3638 *last_buffer_nr()* | |
3639 Obsolete name for bufnr("$"): last_buffer_nr(). | |
3640 | |
3641 bufwinid({buf}) *bufwinid()* | |
3642 The result is a Number, which is the |window-ID| of the first | |
3643 window associated with buffer {buf}. For the use of {buf}, | |
3644 see |bufname()| above. If buffer {buf} doesn't exist or | |
3645 there is no such window, -1 is returned. Example: > | |
3646 | |
3647 echo "A window containing buffer 1 is " . (bufwinid(1)) | |
3648 < | |
3649 Only deals with the current tab page. | |
3650 | |
3651 Can also be used as a |method|: > | |
3652 FindBuffer()->bufwinid() | |
3653 | |
3654 bufwinnr({buf}) *bufwinnr()* | |
3655 Like |bufwinid()| but return the window number instead of the | |
3656 |window-ID|. | |
3657 If buffer {buf} doesn't exist or there is no such window, -1 | |
3658 is returned. Example: > | |
3659 | |
3660 echo "A window containing buffer 1 is " . (bufwinnr(1)) | |
3661 | |
3662 < The number can be used with |CTRL-W_w| and ":wincmd w" | |
3663 |:wincmd|. | |
3664 | |
3665 Can also be used as a |method|: > | |
3666 FindBuffer()->bufwinnr() | |
3667 | |
3668 byte2line({byte}) *byte2line()* | |
3669 Return the line number that contains the character at byte | |
3670 count {byte} in the current buffer. This includes the | |
3671 end-of-line character, depending on the 'fileformat' option | |
3672 for the current buffer. The first character has byte count | |
3673 one. | |
3674 Also see |line2byte()|, |go| and |:goto|. | |
3675 | |
3676 Can also be used as a |method|: > | |
3677 GetOffset()->byte2line() | |
3678 | |
3679 < {not available when compiled without the |+byte_offset| | |
3680 feature} | |
3681 | |
3682 byteidx({expr}, {nr}) *byteidx()* | |
3683 Return byte index of the {nr}'th character in the String | |
3684 {expr}. Use zero for the first character, it then returns | |
3685 zero. | |
3686 If there are no multibyte characters the returned value is | |
3687 equal to {nr}. | |
3688 Composing characters are not counted separately, their byte | |
3689 length is added to the preceding base character. See | |
3690 |byteidxcomp()| below for counting composing characters | |
3691 separately. | |
3692 Example : > | |
3693 echo matchstr(str, ".", byteidx(str, 3)) | |
3694 < will display the fourth character. Another way to do the | |
3695 same: > | |
3696 let s = strpart(str, byteidx(str, 3)) | |
3697 echo strpart(s, 0, byteidx(s, 1)) | |
3698 < Also see |strgetchar()| and |strcharpart()|. | |
3699 | |
3700 If there are less than {nr} characters -1 is returned. | |
3701 If there are exactly {nr} characters the length of the string | |
3702 in bytes is returned. | |
3703 | |
3704 Can also be used as a |method|: > | |
3705 GetName()->byteidx(idx) | |
3706 | |
3707 byteidxcomp({expr}, {nr}) *byteidxcomp()* | |
3708 Like byteidx(), except that a composing character is counted | |
3709 as a separate character. Example: > | |
3710 let s = 'e' . nr2char(0x301) | |
3711 echo byteidx(s, 1) | |
3712 echo byteidxcomp(s, 1) | |
3713 echo byteidxcomp(s, 2) | |
3714 < The first and third echo result in 3 ('e' plus composing | |
3715 character is 3 bytes), the second echo results in 1 ('e' is | |
3716 one byte). | |
3717 Only works differently from byteidx() when 'encoding' is set | |
3718 to a Unicode encoding. | |
3719 | |
3720 Can also be used as a |method|: > | |
3721 GetName()->byteidxcomp(idx) | |
3722 | |
3723 call({func}, {arglist} [, {dict}]) *call()* *E699* | |
3724 Call function {func} with the items in |List| {arglist} as | |
3725 arguments. | |
3726 {func} can either be a |Funcref| or the name of a function. | |
3727 a:firstline and a:lastline are set to the cursor line. | |
3728 Returns the return value of the called function. | |
3729 {dict} is for functions with the "dict" attribute. It will be | |
3730 used to set the local variable "self". |Dictionary-function| | |
3731 | |
3732 Can also be used as a |method|: > | |
3733 GetFunc()->call([arg, arg], dict) | |
3734 | |
3735 ceil({expr}) *ceil()* | |
3736 Return the smallest integral value greater than or equal to | |
3737 {expr} as a |Float| (round up). | |
3738 {expr} must evaluate to a |Float| or a |Number|. | |
3739 Examples: > | |
3740 echo ceil(1.456) | |
3741 < 2.0 > | |
3742 echo ceil(-5.456) | |
3743 < -5.0 > | |
3744 echo ceil(4.0) | |
3745 < 4.0 | |
3746 | |
3747 Can also be used as a |method|: > | |
3748 Compute()->ceil() | |
3749 < | |
3750 {only available when compiled with the |+float| feature} | |
3751 | |
3752 | |
3753 ch_ functions are documented here: |channel-functions-details| | |
3754 | |
3755 | |
3756 changenr() *changenr()* | |
3757 Return the number of the most recent change. This is the same | |
3758 number as what is displayed with |:undolist| and can be used | |
3759 with the |:undo| command. | |
3760 When a change was made it is the number of that change. After | |
3761 redo it is the number of the redone change. After undo it is | |
3762 one less than the number of the undone change. | |
3763 | |
3764 char2nr({string} [, {utf8}]) *char2nr()* | |
3765 Return number value of the first char in {string}. | |
3766 Examples: > | |
3767 char2nr(" ") returns 32 | |
3768 char2nr("ABC") returns 65 | |
3769 < When {utf8} is omitted or zero, the current 'encoding' is used. | |
3770 Example for "utf-8": > | |
3771 char2nr("á") returns 225 | |
3772 char2nr("á"[0]) returns 195 | |
3773 < When {utf8} is TRUE, always treat as UTF-8 characters. | |
3774 A combining character is a separate character. | |
3775 |nr2char()| does the opposite. | |
3776 To turn a string into a list of character numbers: > | |
3777 let str = "ABC" | |
3778 let list = map(split(str, '\zs'), {_, val -> char2nr(val)}) | |
3779 < Result: [65, 66, 67] | |
3780 | |
3781 Can also be used as a |method|: > | |
3782 GetChar()->char2nr() | |
3783 | |
3784 | |
3785 charclass({string}) *charclass()* | |
3786 Return the character class of the first character in {string}. | |
3787 The character class is one of: | |
3788 0 blank | |
3789 1 punctuation | |
3790 2 word character | |
3791 3 emoji | |
3792 other specific Unicode class | |
3793 The class is used in patterns and word motions. | |
3794 | |
3795 | |
3796 charcol({expr}) *charcol()* | |
3797 Same as |col()| but returns the character index of the column | |
3798 position given with {expr} instead of the byte position. | |
3799 | |
3800 Example: | |
3801 With the cursor on '세' in line 5 with text "여보세요": > | |
3802 charcol('.') returns 3 | |
3803 col('.') returns 7 | |
3804 | |
3805 < Can also be used as a |method|: > | |
3806 GetPos()->col() | |
3807 < | |
3808 *charidx()* | |
3809 charidx({string}, {idx} [, {countcc}]) | |
3810 Return the character index of the byte at {idx} in {string}. | |
3811 The index of the first character is zero. | |
3812 If there are no multibyte characters the returned value is | |
3813 equal to {idx}. | |
3814 When {countcc} is omitted or |FALSE|, then composing characters | |
3815 are not counted separately, their byte length is | |
3816 added to the preceding base character. | |
3817 When {countcc} is |TRUE|, then composing characters are | |
3818 counted as separate characters. | |
3819 Returns -1 if the arguments are invalid or if {idx} is greater | |
3820 than the index of the last byte in {string}. An error is | |
3821 given if the first argument is not a string, the second | |
3822 argument is not a number or when the third argument is present | |
3823 and is not zero or one. | |
3824 See |byteidx()| and |byteidxcomp()| for getting the byte index | |
3825 from the character index. | |
3826 Examples: > | |
3827 echo charidx('áb́ć', 3) returns 1 | |
3828 echo charidx('áb́ć', 6, 1) returns 4 | |
3829 echo charidx('áb́ć', 16) returns -1 | |
3830 < | |
3831 Can also be used as a |method|: > | |
3832 GetName()->charidx(idx) | |
3833 | |
3834 chdir({dir}) *chdir()* | |
3835 Change the current working directory to {dir}. The scope of | |
3836 the directory change depends on the directory of the current | |
3837 window: | |
3838 - If the current window has a window-local directory | |
3839 (|:lcd|), then changes the window local directory. | |
3840 - Otherwise, if the current tabpage has a local | |
3841 directory (|:tcd|) then changes the tabpage local | |
3842 directory. | |
3843 - Otherwise, changes the global directory. | |
3844 {dir} must be a String. | |
3845 If successful, returns the previous working directory. Pass | |
3846 this to another chdir() to restore the directory. | |
3847 On failure, returns an empty string. | |
3848 | |
3849 Example: > | |
3850 let save_dir = chdir(newdir) | |
3851 if save_dir != "" | |
3852 " ... do some work | |
3853 call chdir(save_dir) | |
3854 endif | |
3855 | |
3856 < Can also be used as a |method|: > | |
3857 GetDir()->chdir() | |
3858 < | |
3859 cindent({lnum}) *cindent()* | |
3860 Get the amount of indent for line {lnum} according the C | |
3861 indenting rules, as with 'cindent'. | |
3862 The indent is counted in spaces, the value of 'tabstop' is | |
3863 relevant. {lnum} is used just like in |getline()|. | |
3864 When {lnum} is invalid or Vim was not compiled the |+cindent| | |
3865 feature, -1 is returned. | |
3866 See |C-indenting|. | |
3867 | |
3868 Can also be used as a |method|: > | |
3869 GetLnum()->cindent() | |
3870 | |
3871 clearmatches([{win}]) *clearmatches()* | |
3872 Clears all matches previously defined for the current window | |
3873 by |matchadd()| and the |:match| commands. | |
3874 If {win} is specified, use the window with this number or | |
3875 window ID instead of the current window. | |
3876 | |
3877 Can also be used as a |method|: > | |
3878 GetWin()->clearmatches() | |
3879 < | |
3880 *col()* | |
3881 col({expr}) The result is a Number, which is the byte index of the column | |
3882 position given with {expr}. The accepted positions are: | |
3883 . the cursor position | |
3884 $ the end of the cursor line (the result is the | |
3885 number of bytes in the cursor line plus one) | |
3886 'x position of mark x (if the mark is not set, 0 is | |
3887 returned) | |
3888 v In Visual mode: the start of the Visual area (the | |
3889 cursor is the end). When not in Visual mode | |
3890 returns the cursor position. Differs from |'<| in | |
3891 that it's updated right away. | |
3892 Additionally {expr} can be [lnum, col]: a |List| with the line | |
3893 and column number. Most useful when the column is "$", to get | |
3894 the last column of a specific line. When "lnum" or "col" is | |
3895 out of range then col() returns zero. | |
3896 To get the line number use |line()|. To get both use | |
3897 |getpos()|. | |
3898 For the screen column position use |virtcol()|. For the | |
3899 character position use |charcol()|. | |
3900 Note that only marks in the current file can be used. | |
3901 Examples: > | |
3902 col(".") column of cursor | |
3903 col("$") length of cursor line plus one | |
3904 col("'t") column of mark t | |
3905 col("'" . markname) column of mark markname | |
3906 < The first column is 1. 0 is returned for an error. | |
3907 For an uppercase mark the column may actually be in another | |
3908 buffer. | |
3909 For the cursor position, when 'virtualedit' is active, the | |
3910 column is one higher if the cursor is after the end of the | |
3911 line. This can be used to obtain the column in Insert mode: > | |
3912 :imap <F2> <C-O>:let save_ve = &ve<CR> | |
3913 \<C-O>:set ve=all<CR> | |
3914 \<C-O>:echo col(".") . "\n" <Bar> | |
3915 \let &ve = save_ve<CR> | |
3916 | |
3917 < Can also be used as a |method|: > | |
3918 GetPos()->col() | |
3919 < | |
3920 | |
3921 complete({startcol}, {matches}) *complete()* *E785* | |
3922 Set the matches for Insert mode completion. | |
3923 Can only be used in Insert mode. You need to use a mapping | |
3924 with CTRL-R = (see |i_CTRL-R|). It does not work after CTRL-O | |
3925 or with an expression mapping. | |
3926 {startcol} is the byte offset in the line where the completed | |
3927 text start. The text up to the cursor is the original text | |
3928 that will be replaced by the matches. Use col('.') for an | |
3929 empty string. "col('.') - 1" will replace one character by a | |
3930 match. | |
3931 {matches} must be a |List|. Each |List| item is one match. | |
3932 See |complete-items| for the kind of items that are possible. | |
3933 "longest" in 'completeopt' is ignored. | |
3934 Note that the after calling this function you need to avoid | |
3935 inserting anything that would cause completion to stop. | |
3936 The match can be selected with CTRL-N and CTRL-P as usual with | |
3937 Insert mode completion. The popup menu will appear if | |
3938 specified, see |ins-completion-menu|. | |
3939 Example: > | |
3940 inoremap <F5> <C-R>=ListMonths()<CR> | |
3941 | |
3942 func! ListMonths() | |
3943 call complete(col('.'), ['January', 'February', 'March', | |
3944 \ 'April', 'May', 'June', 'July', 'August', 'September', | |
3945 \ 'October', 'November', 'December']) | |
3946 return '' | |
3947 endfunc | |
3948 < This isn't very useful, but it shows how it works. Note that | |
3949 an empty string is returned to avoid a zero being inserted. | |
3950 | |
3951 Can also be used as a |method|, the base is passed as the | |
3952 second argument: > | |
3953 GetMatches()->complete(col('.')) | |
3954 | |
3955 complete_add({expr}) *complete_add()* | |
3956 Add {expr} to the list of matches. Only to be used by the | |
3957 function specified with the 'completefunc' option. | |
3958 Returns 0 for failure (empty string or out of memory), | |
3959 1 when the match was added, 2 when the match was already in | |
3960 the list. | |
3961 See |complete-functions| for an explanation of {expr}. It is | |
3962 the same as one item in the list that 'omnifunc' would return. | |
3963 | |
3964 Can also be used as a |method|: > | |
3965 GetMoreMatches()->complete_add() | |
3966 | |
3967 complete_check() *complete_check()* | |
3968 Check for a key typed while looking for completion matches. | |
3969 This is to be used when looking for matches takes some time. | |
3970 Returns |TRUE| when searching for matches is to be aborted, | |
3971 zero otherwise. | |
3972 Only to be used by the function specified with the | |
3973 'completefunc' option. | |
3974 | |
3975 | |
3976 complete_info([{what}]) *complete_info()* | |
3977 Returns a |Dictionary| with information about Insert mode | |
3978 completion. See |ins-completion|. | |
3979 The items are: | |
3980 mode Current completion mode name string. | |
3981 See |complete_info_mode| for the values. | |
3982 pum_visible |TRUE| if popup menu is visible. | |
3983 See |pumvisible()|. | |
3984 items List of completion matches. Each item is a | |
3985 dictionary containing the entries "word", | |
3986 "abbr", "menu", "kind", "info" and "user_data". | |
3987 See |complete-items|. | |
3988 selected Selected item index. First index is zero. | |
3989 Index is -1 if no item is selected (showing | |
3990 typed text only, or the last completion after | |
3991 no item is selected when using the <Up> or | |
3992 <Down> keys) | |
3993 inserted Inserted string. [NOT IMPLEMENT YET] | |
3994 | |
3995 *complete_info_mode* | |
3996 mode values are: | |
3997 "" Not in completion mode | |
3998 "keyword" Keyword completion |i_CTRL-X_CTRL-N| | |
3999 "ctrl_x" Just pressed CTRL-X |i_CTRL-X| | |
4000 "scroll" Scrolling with |i_CTRL-X_CTRL-E| or | |
4001 |i_CTRL-X_CTRL-Y| | |
4002 "whole_line" Whole lines |i_CTRL-X_CTRL-L| | |
4003 "files" File names |i_CTRL-X_CTRL-F| | |
4004 "tags" Tags |i_CTRL-X_CTRL-]| | |
4005 "path_defines" Definition completion |i_CTRL-X_CTRL-D| | |
4006 "path_patterns" Include completion |i_CTRL-X_CTRL-I| | |
4007 "dictionary" Dictionary |i_CTRL-X_CTRL-K| | |
4008 "thesaurus" Thesaurus |i_CTRL-X_CTRL-T| | |
4009 "cmdline" Vim Command line |i_CTRL-X_CTRL-V| | |
4010 "function" User defined completion |i_CTRL-X_CTRL-U| | |
4011 "omni" Omni completion |i_CTRL-X_CTRL-O| | |
4012 "spell" Spelling suggestions |i_CTRL-X_s| | |
4013 "eval" |complete()| completion | |
4014 "unknown" Other internal modes | |
4015 | |
4016 If the optional {what} list argument is supplied, then only | |
4017 the items listed in {what} are returned. Unsupported items in | |
4018 {what} are silently ignored. | |
4019 | |
4020 To get the position and size of the popup menu, see | |
4021 |pum_getpos()|. It's also available in |v:event| during the | |
4022 |CompleteChanged| event. | |
4023 | |
4024 Examples: > | |
4025 " Get all items | |
4026 call complete_info() | |
4027 " Get only 'mode' | |
4028 call complete_info(['mode']) | |
4029 " Get only 'mode' and 'pum_visible' | |
4030 call complete_info(['mode', 'pum_visible']) | |
4031 | |
4032 < Can also be used as a |method|: > | |
4033 GetItems()->complete_info() | |
4034 < | |
4035 *confirm()* | |
4036 confirm({msg} [, {choices} [, {default} [, {type}]]]) | |
4037 confirm() offers the user a dialog, from which a choice can be | |
4038 made. It returns the number of the choice. For the first | |
4039 choice this is 1. | |
4040 Note: confirm() is only supported when compiled with dialog | |
4041 support, see |+dialog_con| and |+dialog_gui|. | |
4042 | |
4043 {msg} is displayed in a |dialog| with {choices} as the | |
4044 alternatives. When {choices} is missing or empty, "&OK" is | |
4045 used (and translated). | |
4046 {msg} is a String, use '\n' to include a newline. Only on | |
4047 some systems the string is wrapped when it doesn't fit. | |
4048 | |
4049 {choices} is a String, with the individual choices separated | |
4050 by '\n', e.g. > | |
4051 confirm("Save changes?", "&Yes\n&No\n&Cancel") | |
4052 < The letter after the '&' is the shortcut key for that choice. | |
4053 Thus you can type 'c' to select "Cancel". The shortcut does | |
4054 not need to be the first letter: > | |
4055 confirm("file has been modified", "&Save\nSave &All") | |
4056 < For the console, the first letter of each choice is used as | |
4057 the default shortcut key. Case is ignored. | |
4058 | |
4059 The optional {default} argument is the number of the choice | |
4060 that is made if the user hits <CR>. Use 1 to make the first | |
4061 choice the default one. Use 0 to not set a default. If | |
4062 {default} is omitted, 1 is used. | |
4063 | |
4064 The optional {type} String argument gives the type of dialog. | |
4065 This is only used for the icon of the GTK, Mac, Motif and | |
4066 Win32 GUI. It can be one of these values: "Error", | |
4067 "Question", "Info", "Warning" or "Generic". Only the first | |
4068 character is relevant. When {type} is omitted, "Generic" is | |
4069 used. | |
4070 | |
4071 If the user aborts the dialog by pressing <Esc>, CTRL-C, | |
4072 or another valid interrupt key, confirm() returns 0. | |
4073 | |
4074 An example: > | |
4075 :let choice = confirm("What do you want?", "&Apples\n&Oranges\n&Bananas", 2) | |
4076 :if choice == 0 | |
4077 : echo "make up your mind!" | |
4078 :elseif choice == 3 | |
4079 : echo "tasteful" | |
4080 :else | |
4081 : echo "I prefer bananas myself." | |
4082 :endif | |
4083 < In a GUI dialog, buttons are used. The layout of the buttons | |
4084 depends on the 'v' flag in 'guioptions'. If it is included, | |
4085 the buttons are always put vertically. Otherwise, confirm() | |
4086 tries to put the buttons in one horizontal line. If they | |
4087 don't fit, a vertical layout is used anyway. For some systems | |
4088 the horizontal layout is always used. | |
4089 | |
4090 Can also be used as a |method|in: > | |
4091 BuildMessage()->confirm("&Yes\n&No") | |
4092 < | |
4093 *copy()* | |
4094 copy({expr}) Make a copy of {expr}. For Numbers and Strings this isn't | |
4095 different from using {expr} directly. | |
4096 When {expr} is a |List| a shallow copy is created. This means | |
4097 that the original |List| can be changed without changing the | |
4098 copy, and vice versa. But the items are identical, thus | |
4099 changing an item changes the contents of both |Lists|. | |
4100 A |Dictionary| is copied in a similar way as a |List|. | |
4101 Also see |deepcopy()|. | |
4102 Can also be used as a |method|: > | |
4103 mylist->copy() | |
4104 | |
4105 cos({expr}) *cos()* | |
4106 Return the cosine of {expr}, measured in radians, as a |Float|. | |
4107 {expr} must evaluate to a |Float| or a |Number|. | |
4108 Examples: > | |
4109 :echo cos(100) | |
4110 < 0.862319 > | |
4111 :echo cos(-4.01) | |
4112 < -0.646043 | |
4113 | |
4114 Can also be used as a |method|: > | |
4115 Compute()->cos() | |
4116 < | |
4117 {only available when compiled with the |+float| feature} | |
4118 | |
4119 | |
4120 cosh({expr}) *cosh()* | |
4121 Return the hyperbolic cosine of {expr} as a |Float| in the range | |
4122 [1, inf]. | |
4123 {expr} must evaluate to a |Float| or a |Number|. | |
4124 Examples: > | |
4125 :echo cosh(0.5) | |
4126 < 1.127626 > | |
4127 :echo cosh(-0.5) | |
4128 < -1.127626 | |
4129 | |
4130 Can also be used as a |method|: > | |
4131 Compute()->cosh() | |
4132 < | |
4133 {only available when compiled with the |+float| feature} | |
4134 | |
4135 | |
4136 count({comp}, {expr} [, {ic} [, {start}]]) *count()* | |
4137 Return the number of times an item with value {expr} appears | |
4138 in |String|, |List| or |Dictionary| {comp}. | |
4139 | |
4140 If {start} is given then start with the item with this index. | |
4141 {start} can only be used with a |List|. | |
4142 | |
4143 When {ic} is given and it's |TRUE| then case is ignored. | |
4144 | |
4145 When {comp} is a string then the number of not overlapping | |
4146 occurrences of {expr} is returned. Zero is returned when | |
4147 {expr} is an empty string. | |
4148 | |
4149 Can also be used as a |method|: > | |
4150 mylist->count(val) | |
4151 < | |
4152 *cscope_connection()* | |
4153 cscope_connection([{num} , {dbpath} [, {prepend}]]) | |
4154 Checks for the existence of a |cscope| connection. If no | |
4155 parameters are specified, then the function returns: | |
4156 0, if cscope was not available (not compiled in), or | |
4157 if there are no cscope connections; | |
4158 1, if there is at least one cscope connection. | |
4159 | |
4160 If parameters are specified, then the value of {num} | |
4161 determines how existence of a cscope connection is checked: | |
4162 | |
4163 {num} Description of existence check | |
4164 ----- ------------------------------ | |
4165 0 Same as no parameters (e.g., "cscope_connection()"). | |
4166 1 Ignore {prepend}, and use partial string matches for | |
4167 {dbpath}. | |
4168 2 Ignore {prepend}, and use exact string matches for | |
4169 {dbpath}. | |
4170 3 Use {prepend}, use partial string matches for both | |
4171 {dbpath} and {prepend}. | |
4172 4 Use {prepend}, use exact string matches for both | |
4173 {dbpath} and {prepend}. | |
4174 | |
4175 Note: All string comparisons are case sensitive! | |
4176 | |
4177 Examples. Suppose we had the following (from ":cs show"): > | |
4178 | |
4179 # pid database name prepend path | |
4180 0 27664 cscope.out /usr/local | |
4181 < | |
4182 Invocation Return Val ~ | |
4183 ---------- ---------- > | |
4184 cscope_connection() 1 | |
4185 cscope_connection(1, "out") 1 | |
4186 cscope_connection(2, "out") 0 | |
4187 cscope_connection(3, "out") 0 | |
4188 cscope_connection(3, "out", "local") 1 | |
4189 cscope_connection(4, "out") 0 | |
4190 cscope_connection(4, "out", "local") 0 | |
4191 cscope_connection(4, "cscope.out", "/usr/local") 1 | |
4192 < | |
4193 cursor({lnum}, {col} [, {off}]) *cursor()* | |
4194 cursor({list}) | |
4195 Positions the cursor at the column (byte count) {col} in the | |
4196 line {lnum}. The first column is one. | |
4197 | |
4198 When there is one argument {list} this is used as a |List| | |
4199 with two, three or four item: | |
4200 [{lnum}, {col}] | |
4201 [{lnum}, {col}, {off}] | |
4202 [{lnum}, {col}, {off}, {curswant}] | |
4203 This is like the return value of |getpos()| or |getcurpos()|, | |
4204 but without the first item. | |
4205 | |
4206 To position the cursor using the character count, use | |
4207 |setcursorcharpos()|. | |
4208 | |
4209 Does not change the jumplist. | |
4210 {lnum} is used like with |getline()|. | |
4211 If {lnum} is greater than the number of lines in the buffer, | |
4212 the cursor will be positioned at the last line in the buffer. | |
4213 If {lnum} is zero, the cursor will stay in the current line. | |
4214 If {col} is greater than the number of bytes in the line, | |
4215 the cursor will be positioned at the last character in the | |
4216 line. | |
4217 If {col} is zero, the cursor will stay in the current column. | |
4218 If {curswant} is given it is used to set the preferred column | |
4219 for vertical movement. Otherwise {col} is used. | |
4220 | |
4221 When 'virtualedit' is used {off} specifies the offset in | |
4222 screen columns from the start of the character. E.g., a | |
4223 position within a <Tab> or after the last character. | |
4224 Returns 0 when the position could be set, -1 otherwise. | |
4225 | |
4226 Can also be used as a |method|: > | |
4227 GetCursorPos()->cursor() | |
4228 | |
4229 debugbreak({pid}) *debugbreak()* | |
4230 Specifically used to interrupt a program being debugged. It | |
4231 will cause process {pid} to get a SIGTRAP. Behavior for other | |
4232 processes is undefined. See |terminal-debugger|. | |
4233 {only available on MS-Windows} | |
4234 | |
4235 Can also be used as a |method|: > | |
4236 GetPid()->debugbreak() | |
4237 | |
4238 deepcopy({expr} [, {noref}]) *deepcopy()* *E698* | |
4239 Make a copy of {expr}. For Numbers and Strings this isn't | |
4240 different from using {expr} directly. | |
4241 When {expr} is a |List| a full copy is created. This means | |
4242 that the original |List| can be changed without changing the | |
4243 copy, and vice versa. When an item is a |List| or | |
4244 |Dictionary|, a copy for it is made, recursively. Thus | |
4245 changing an item in the copy does not change the contents of | |
4246 the original |List|. | |
4247 A |Dictionary| is copied in a similar way as a |List|. | |
4248 | |
4249 When {noref} is omitted or zero a contained |List| or | |
4250 |Dictionary| is only copied once. All references point to | |
4251 this single copy. With {noref} set to 1 every occurrence of a | |
4252 |List| or |Dictionary| results in a new copy. This also means | |
4253 that a cyclic reference causes deepcopy() to fail. | |
4254 *E724* | |
4255 Nesting is possible up to 100 levels. When there is an item | |
4256 that refers back to a higher level making a deep copy with | |
4257 {noref} set to 1 will fail. | |
4258 Also see |copy()|. | |
4259 | |
4260 Can also be used as a |method|: > | |
4261 GetObject()->deepcopy() | |
4262 | |
4263 delete({fname} [, {flags}]) *delete()* | |
4264 Without {flags} or with {flags} empty: Deletes the file by the | |
4265 name {fname}. This also works when {fname} is a symbolic link. | |
4266 | |
4267 When {flags} is "d": Deletes the directory by the name | |
4268 {fname}. This fails when directory {fname} is not empty. | |
4269 | |
4270 When {flags} is "rf": Deletes the directory by the name | |
4271 {fname} and everything in it, recursively. BE CAREFUL! | |
4272 Note: on MS-Windows it is not possible to delete a directory | |
4273 that is being used. | |
4274 | |
4275 A symbolic link itself is deleted, not what it points to. | |
4276 | |
4277 The result is a Number, which is 0/false if the delete | |
4278 operation was successful and -1/true when the deletion failed | |
4279 or partly failed. | |
4280 | |
4281 Use |remove()| to delete an item from a |List|. | |
4282 To delete a line from the buffer use |:delete| or | |
4283 |deletebufline()|. | |
4284 | |
4285 Can also be used as a |method|: > | |
4286 GetName()->delete() | |
4287 | |
4288 deletebufline({buf}, {first} [, {last}]) *deletebufline()* | |
4289 Delete lines {first} to {last} (inclusive) from buffer {buf}. | |
4290 If {last} is omitted then delete line {first} only. | |
4291 On success 0 is returned, on failure 1 is returned. | |
4292 | |
4293 This function works only for loaded buffers. First call | |
4294 |bufload()| if needed. | |
4295 | |
4296 For the use of {buf}, see |bufname()| above. | |
4297 | |
4298 {first} and {last} are used like with |getline()|. Note that | |
4299 when using |line()| this refers to the current buffer. Use "$" | |
4300 to refer to the last line in buffer {buf}. | |
4301 | |
4302 Can also be used as a |method|: > | |
4303 GetBuffer()->deletebufline(1) | |
4304 < | |
4305 *did_filetype()* | |
4306 did_filetype() Returns |TRUE| when autocommands are being executed and the | |
4307 FileType event has been triggered at least once. Can be used | |
4308 to avoid triggering the FileType event again in the scripts | |
4309 that detect the file type. |FileType| | |
4310 Returns |FALSE| when `:setf FALLBACK` was used. | |
4311 When editing another file, the counter is reset, thus this | |
4312 really checks if the FileType event has been triggered for the | |
4313 current buffer. This allows an autocommand that starts | |
4314 editing another buffer to set 'filetype' and load a syntax | |
4315 file. | |
4316 | |
4317 diff_filler({lnum}) *diff_filler()* | |
4318 Returns the number of filler lines above line {lnum}. | |
4319 These are the lines that were inserted at this point in | |
4320 another diff'ed window. These filler lines are shown in the | |
4321 display but don't exist in the buffer. | |
4322 {lnum} is used like with |getline()|. Thus "." is the current | |
4323 line, "'m" mark m, etc. | |
4324 Returns 0 if the current window is not in diff mode. | |
4325 | |
4326 Can also be used as a |method|: > | |
4327 GetLnum()->diff_filler() | |
4328 | |
4329 diff_hlID({lnum}, {col}) *diff_hlID()* | |
4330 Returns the highlight ID for diff mode at line {lnum} column | |
4331 {col} (byte index). When the current line does not have a | |
4332 diff change zero is returned. | |
4333 {lnum} is used like with |getline()|. Thus "." is the current | |
4334 line, "'m" mark m, etc. | |
4335 {col} is 1 for the leftmost column, {lnum} is 1 for the first | |
4336 line. | |
4337 The highlight ID can be used with |synIDattr()| to obtain | |
4338 syntax information about the highlighting. | |
4339 | |
4340 Can also be used as a |method|: > | |
4341 GetLnum()->diff_hlID(col) | |
4342 < | |
4343 | |
4344 digraph_get({chars}) *digraph_get()* *E1214* | |
4345 Return the digraph of {chars}. This should be a string with | |
4346 exactly two characters. If {chars} are not just two | |
4347 characters, or the digraph of {chars} does not exist, an error | |
4348 is given and an empty string is returned. | |
4349 | |
4350 The character will be converted from Unicode to 'encoding' | |
4351 when needed. This does require the conversion to be | |
4352 available, it might fail. | |
4353 | |
4354 Also see |digraph_getlist()|. | |
4355 | |
4356 Examples: > | |
4357 " Get a built-in digraph | |
4358 :echo digraph_get('00') " Returns '∞' | |
4359 | |
4360 " Get a user-defined digraph | |
4361 :call digraph_set('aa', 'あ') | |
4362 :echo digraph_get('aa') " Returns 'あ' | |
4363 < | |
4364 Can also be used as a |method|: > | |
4365 GetChars()->digraph_get() | |
4366 < | |
4367 This function works only when compiled with the |+digraphs| | |
4368 feature. If this feature is disabled, this function will | |
4369 display an error message. | |
4370 | |
4371 | |
4372 digraph_getlist([{listall}]) *digraph_getlist()* | |
4373 Return a list of digraphs. If the {listall} argument is given | |
4374 and it is TRUE, return all digraphs, including the default | |
4375 digraphs. Otherwise, return only user-defined digraphs. | |
4376 | |
4377 The characters will be converted from Unicode to 'encoding' | |
4378 when needed. This does require the conservation to be | |
4379 available, it might fail. | |
4380 | |
4381 Also see |digraph_get()|. | |
4382 | |
4383 Examples: > | |
4384 " Get user-defined digraphs | |
4385 :echo digraph_getlist() | |
4386 | |
4387 " Get all the digraphs, including default digraphs | |
4388 :echo digraph_getlist(1) | |
4389 < | |
4390 Can also be used as a |method|: > | |
4391 GetNumber()->digraph_getlist() | |
4392 < | |
4393 This function works only when compiled with the |+digraphs| | |
4394 feature. If this feature is disabled, this function will | |
4395 display an error message. | |
4396 | |
4397 | |
4398 digraph_set({chars}, {digraph}) *digraph_set()* *E1205* | |
4399 Add digraph {chars} to the list. {chars} must be a string | |
4400 with two characters. {digraph} is a string with one UTF-8 | |
4401 encoded character. Be careful, composing characters are NOT | |
4402 ignored. This function is similar to |:digraphs| command, but | |
4403 useful to add digraphs start with a white space. | |
4404 | |
4405 The function result is v:true if |digraph| is registered. If | |
4406 this fails an error message is given and v:false is returned. | |
4407 | |
4408 If you want to define multiple digraphs at once, you can use | |
4409 |digraph_setlist()|. | |
4410 | |
4411 Example: > | |
4412 call digraph_set(' ', 'あ') | |
4413 < | |
4414 Can be used as a |method|: > | |
4415 GetString()->digraph_set('あ') | |
4416 < | |
4417 This function works only when compiled with the |+digraphs| | |
4418 feature. If this feature is disabled, this function will | |
4419 display an error message. | |
4420 | |
4421 | |
4422 digraph_setlist({digraphlist}) *digraph_setlist()* | |
4423 Similar to |digraph_set()| but this function can add multiple | |
4424 digraphs at once. {digraphlist} is a list composed of lists, | |
4425 where each list contains two strings with {chars} and | |
4426 {digraph} as in |digraph_set()|. | |
4427 Example: > | |
4428 call digraph_setlist([['aa', 'あ'], ['ii', 'い']]) | |
4429 < | |
4430 It is similar to the following: > | |
4431 for [chars, digraph] in [['aa', 'あ'], ['ii', 'い']] | |
4432 call digraph_set(chars, digraph) | |
4433 endfor | |
4434 < Except that the function returns after the first error, | |
4435 following digraphs will not be added. | |
4436 | |
4437 Can be used as a |method|: > | |
4438 GetList()->digraph_setlist() | |
4439 < | |
4440 This function works only when compiled with the |+digraphs| | |
4441 feature. If this feature is disabled, this function will | |
4442 display an error message. | |
4443 | |
4444 | |
4445 echoraw({string}) *echoraw()* | |
4446 Output {string} as-is, including unprintable characters. | |
4447 This can be used to output a terminal code. For example, to | |
4448 disable modifyOtherKeys: > | |
4449 call echoraw(&t_TE) | |
4450 < and to enable it again: > | |
4451 call echoraw(&t_TI) | |
4452 < Use with care, you can mess up the terminal this way. | |
4453 | |
4454 | |
4455 empty({expr}) *empty()* | |
4456 Return the Number 1 if {expr} is empty, zero otherwise. | |
4457 - A |List| or |Dictionary| is empty when it does not have any | |
4458 items. | |
4459 - A |String| is empty when its length is zero. | |
4460 - A |Number| and |Float| are empty when their value is zero. | |
4461 - |v:false|, |v:none| and |v:null| are empty, |v:true| is not. | |
4462 - A |Job| is empty when it failed to start. | |
4463 - A |Channel| is empty when it is closed. | |
4464 - A |Blob| is empty when its length is zero. | |
4465 | |
4466 For a long |List| this is much faster than comparing the | |
4467 length with zero. | |
4468 | |
4469 Can also be used as a |method|: > | |
4470 mylist->empty() | |
4471 | |
4472 environ() *environ()* | |
4473 Return all of environment variables as dictionary. You can | |
4474 check if an environment variable exists like this: > | |
4475 :echo has_key(environ(), 'HOME') | |
4476 < Note that the variable name may be CamelCase; to ignore case | |
4477 use this: > | |
4478 :echo index(keys(environ()), 'HOME', 0, 1) != -1 | |
4479 | |
4480 escape({string}, {chars}) *escape()* | |
4481 Escape the characters in {chars} that occur in {string} with a | |
4482 backslash. Example: > | |
4483 :echo escape('c:\program files\vim', ' \') | |
4484 < results in: > | |
4485 c:\\program\ files\\vim | |
4486 < Also see |shellescape()| and |fnameescape()|. | |
4487 | |
4488 Can also be used as a |method|: > | |
4489 GetText()->escape(' \') | |
4490 < | |
4491 *eval()* | |
4492 eval({string}) Evaluate {string} and return the result. Especially useful to | |
4493 turn the result of |string()| back into the original value. | |
4494 This works for Numbers, Floats, Strings, Blobs and composites | |
4495 of them. Also works for |Funcref|s that refer to existing | |
4496 functions. | |
4497 | |
4498 Can also be used as a |method|: > | |
4499 argv->join()->eval() | |
4500 | |
4501 eventhandler() *eventhandler()* | |
4502 Returns 1 when inside an event handler. That is that Vim got | |
4503 interrupted while waiting for the user to type a character, | |
4504 e.g., when dropping a file on Vim. This means interactive | |
4505 commands cannot be used. Otherwise zero is returned. | |
4506 | |
4507 executable({expr}) *executable()* | |
4508 This function checks if an executable with the name {expr} | |
4509 exists. {expr} must be the name of the program without any | |
4510 arguments. | |
4511 executable() uses the value of $PATH and/or the normal | |
4512 searchpath for programs. *PATHEXT* | |
4513 On MS-Windows the ".exe", ".bat", etc. can optionally be | |
4514 included. Then the extensions in $PATHEXT are tried. Thus if | |
4515 "foo.exe" does not exist, "foo.exe.bat" can be found. If | |
4516 $PATHEXT is not set then ".com;.exe;.bat;.cmd" is used. A dot | |
4517 by itself can be used in $PATHEXT to try using the name | |
4518 without an extension. When 'shell' looks like a Unix shell, | |
4519 then the name is also tried without adding an extension. | |
4520 On MS-Windows it only checks if the file exists and is not a | |
4521 directory, not if it's really executable. | |
4522 On MS-Windows an executable in the same directory as Vim is | |
4523 always found. Since this directory is added to $PATH it | |
4524 should also work to execute it |win32-PATH|. | |
4525 The result is a Number: | |
4526 1 exists | |
4527 0 does not exist | |
4528 -1 not implemented on this system | |
4529 |exepath()| can be used to get the full path of an executable. | |
4530 | |
4531 Can also be used as a |method|: > | |
4532 GetCommand()->executable() | |
4533 | |
4534 execute({command} [, {silent}]) *execute()* | |
4535 Execute an Ex command or commands and return the output as a | |
4536 string. | |
4537 {command} can be a string or a List. In case of a List the | |
4538 lines are executed one by one. | |
4539 This is equivalent to: > | |
4540 redir => var | |
4541 {command} | |
4542 redir END | |
4543 < | |
4544 The optional {silent} argument can have these values: | |
4545 "" no `:silent` used | |
4546 "silent" `:silent` used | |
4547 "silent!" `:silent!` used | |
4548 The default is "silent". Note that with "silent!", unlike | |
4549 `:redir`, error messages are dropped. When using an external | |
4550 command the screen may be messed up, use `system()` instead. | |
4551 *E930* | |
4552 It is not possible to use `:redir` anywhere in {command}. | |
4553 | |
4554 To get a list of lines use |split()| on the result: > | |
4555 split(execute('args'), "\n") | |
4556 | |
4557 < To execute a command in another window than the current one | |
4558 use `win_execute()`. | |
4559 | |
4560 When used recursively the output of the recursive call is not | |
4561 included in the output of the higher level call. | |
4562 | |
4563 Can also be used as a |method|: > | |
4564 GetCommand()->execute() | |
4565 | |
4566 exepath({expr}) *exepath()* | |
4567 If {expr} is an executable and is either an absolute path, a | |
4568 relative path or found in $PATH, return the full path. | |
4569 Note that the current directory is used when {expr} starts | |
4570 with "./", which may be a problem for Vim: > | |
4571 echo exepath(v:progpath) | |
4572 < If {expr} cannot be found in $PATH or is not executable then | |
4573 an empty string is returned. | |
4574 | |
4575 Can also be used as a |method|: > | |
4576 GetCommand()->exepath() | |
4577 < | |
4578 *exists()* | |
4579 exists({expr}) The result is a Number, which is |TRUE| if {expr} is defined, | |
4580 zero otherwise. | |
4581 | |
4582 Note: In a compiled |:def| function the evaluation is done at | |
4583 runtime. Use `exists_compiled()` to evaluate the expression | |
4584 at compile time. | |
4585 | |
4586 For checking for a supported feature use |has()|. | |
4587 For checking if a file exists use |filereadable()|. | |
4588 | |
4589 The {expr} argument is a string, which contains one of these: | |
4590 &option-name Vim option (only checks if it exists, | |
4591 not if it really works) | |
4592 +option-name Vim option that works. | |
4593 $ENVNAME environment variable (could also be | |
4594 done by comparing with an empty | |
4595 string) | |
4596 *funcname built-in function (see |functions|) | |
4597 or user defined function (see | |
4598 |user-functions|) that is implemented. | |
4599 Also works for a variable that is a | |
4600 Funcref. | |
4601 ?funcname built-in function that could be | |
4602 implemented; to be used to check if | |
4603 "funcname" is valid | |
4604 varname internal variable (see | |
4605 |internal-variables|). Also works | |
4606 for |curly-braces-names|, |Dictionary| | |
4607 entries, |List| items, etc. | |
4608 Does not work for local variables in a | |
4609 compiled `:def` function. | |
4610 Beware that evaluating an index may | |
4611 cause an error message for an invalid | |
4612 expression. E.g.: > | |
4613 :let l = [1, 2, 3] | |
4614 :echo exists("l[5]") | |
4615 < 0 > | |
4616 :echo exists("l[xx]") | |
4617 < E121: Undefined variable: xx | |
4618 0 | |
4619 :cmdname Ex command: built-in command, user | |
4620 command or command modifier |:command|. | |
4621 Returns: | |
4622 1 for match with start of a command | |
4623 2 full match with a command | |
4624 3 matches several user commands | |
4625 To check for a supported command | |
4626 always check the return value to be 2. | |
4627 :2match The |:2match| command. | |
4628 :3match The |:3match| command. | |
4629 #event autocommand defined for this event | |
4630 #event#pattern autocommand defined for this event and | |
4631 pattern (the pattern is taken | |
4632 literally and compared to the | |
4633 autocommand patterns character by | |
4634 character) | |
4635 #group autocommand group exists | |
4636 #group#event autocommand defined for this group and | |
4637 event. | |
4638 #group#event#pattern | |
4639 autocommand defined for this group, | |
4640 event and pattern. | |
4641 ##event autocommand for this event is | |
4642 supported. | |
4643 | |
4644 Examples: > | |
4645 exists("&shortname") | |
4646 exists("$HOSTNAME") | |
4647 exists("*strftime") | |
4648 exists("*s:MyFunc") | |
4649 exists("bufcount") | |
4650 exists(":Make") | |
4651 exists("#CursorHold") | |
4652 exists("#BufReadPre#*.gz") | |
4653 exists("#filetypeindent") | |
4654 exists("#filetypeindent#FileType") | |
4655 exists("#filetypeindent#FileType#*") | |
4656 exists("##ColorScheme") | |
4657 < There must be no space between the symbol (&/$/*/#) and the | |
4658 name. | |
4659 There must be no extra characters after the name, although in | |
4660 a few cases this is ignored. That may become more strict in | |
4661 the future, thus don't count on it! | |
4662 Working example: > | |
4663 exists(":make") | |
4664 < NOT working example: > | |
4665 exists(":make install") | |
4666 | |
4667 < Note that the argument must be a string, not the name of the | |
4668 variable itself. For example: > | |
4669 exists(bufcount) | |
4670 < This doesn't check for existence of the "bufcount" variable, | |
4671 but gets the value of "bufcount", and checks if that exists. | |
4672 | |
4673 Can also be used as a |method|: > | |
4674 Varname()->exists() | |
4675 < | |
4676 | |
4677 exists_compiled({expr}) *exists_compiled()* | |
4678 Like `exists()` but evaluated at compile time. This is useful | |
4679 to skip a block where a function is used that would otherwise | |
4680 give an error: > | |
4681 if exists_compiled('*ThatFunction') | |
4682 ThatFunction('works') | |
4683 endif | |
4684 < If `exists()` were used then a compilation error would be | |
4685 given if ThatFunction() is not defined. | |
4686 | |
4687 {expr} must be a literal string. *E1232* | |
4688 Can only be used in a |:def| function. *E1233* | |
4689 This does not work to check for arguments or local variables. | |
4690 | |
4691 | |
4692 exp({expr}) *exp()* | |
4693 Return the exponential of {expr} as a |Float| in the range | |
4694 [0, inf]. | |
4695 {expr} must evaluate to a |Float| or a |Number|. | |
4696 Examples: > | |
4697 :echo exp(2) | |
4698 < 7.389056 > | |
4699 :echo exp(-1) | |
4700 < 0.367879 | |
4701 | |
4702 Can also be used as a |method|: > | |
4703 Compute()->exp() | |
4704 < | |
4705 {only available when compiled with the |+float| feature} | |
4706 | |
4707 | |
4708 expand({string} [, {nosuf} [, {list}]]) *expand()* | |
4709 Expand wildcards and the following special keywords in | |
4710 {string}. 'wildignorecase' applies. | |
4711 | |
4712 If {list} is given and it is |TRUE|, a List will be returned. | |
4713 Otherwise the result is a String and when there are several | |
4714 matches, they are separated by <NL> characters. [Note: in | |
4715 version 5.0 a space was used, which caused problems when a | |
4716 file name contains a space] | |
4717 | |
4718 If the expansion fails, the result is an empty string. A name | |
4719 for a non-existing file is not included, unless {string} does | |
4720 not start with '%', '#' or '<', see below. | |
4721 | |
4722 When {string} starts with '%', '#' or '<', the expansion is | |
4723 done like for the |cmdline-special| variables with their | |
4724 associated modifiers. Here is a short overview: | |
4725 | |
4726 % current file name | |
4727 # alternate file name | |
4728 #n alternate file name n | |
4729 <cfile> file name under the cursor | |
4730 <afile> autocmd file name | |
4731 <abuf> autocmd buffer number (as a String!) | |
4732 <amatch> autocmd matched name | |
4733 <cexpr> C expression under the cursor | |
4734 <sfile> sourced script file or function name | |
4735 <slnum> sourced script line number or function | |
4736 line number | |
4737 <sflnum> script file line number, also when in | |
4738 a function | |
4739 <SID> "<SNR>123_" where "123" is the | |
4740 current script ID |<SID>| | |
4741 <stack> call stack | |
4742 <cword> word under the cursor | |
4743 <cWORD> WORD under the cursor | |
4744 <client> the {clientid} of the last received | |
4745 message |server2client()| | |
4746 Modifiers: | |
4747 :p expand to full path | |
4748 :h head (last path component removed) | |
4749 :t tail (last path component only) | |
4750 :r root (one extension removed) | |
4751 :e extension only | |
4752 | |
4753 Example: > | |
4754 :let &tags = expand("%:p:h") . "/tags" | |
4755 < Note that when expanding a string that starts with '%', '#' or | |
4756 '<', any following text is ignored. This does NOT work: > | |
4757 :let doesntwork = expand("%:h.bak") | |
4758 < Use this: > | |
4759 :let doeswork = expand("%:h") . ".bak" | |
4760 < Also note that expanding "<cfile>" and others only returns the | |
4761 referenced file name without further expansion. If "<cfile>" | |
4762 is "~/.cshrc", you need to do another expand() to have the | |
4763 "~/" expanded into the path of the home directory: > | |
4764 :echo expand(expand("<cfile>")) | |
4765 < | |
4766 There cannot be white space between the variables and the | |
4767 following modifier. The |fnamemodify()| function can be used | |
4768 to modify normal file names. | |
4769 | |
4770 When using '%' or '#', and the current or alternate file name | |
4771 is not defined, an empty string is used. Using "%:p" in a | |
4772 buffer with no name, results in the current directory, with a | |
4773 '/' added. | |
4774 | |
4775 When {string} does not start with '%', '#' or '<', it is | |
4776 expanded like a file name is expanded on the command line. | |
4777 'suffixes' and 'wildignore' are used, unless the optional | |
4778 {nosuf} argument is given and it is |TRUE|. | |
4779 Names for non-existing files are included. The "**" item can | |
4780 be used to search in a directory tree. For example, to find | |
4781 all "README" files in the current directory and below: > | |
4782 :echo expand("**/README") | |
4783 < | |
4784 expand() can also be used to expand variables and environment | |
4785 variables that are only known in a shell. But this can be | |
4786 slow, because a shell may be used to do the expansion. See | |
4787 |expr-env-expand|. | |
4788 The expanded variable is still handled like a list of file | |
4789 names. When an environment variable cannot be expanded, it is | |
4790 left unchanged. Thus ":echo expand('$FOOBAR')" results in | |
4791 "$FOOBAR". | |
4792 | |
4793 See |glob()| for finding existing files. See |system()| for | |
4794 getting the raw output of an external command. | |
4795 | |
4796 Can also be used as a |method|: > | |
4797 Getpattern()->expand() | |
4798 | |
4799 expandcmd({string}) *expandcmd()* | |
4800 Expand special items in String {string} like what is done for | |
4801 an Ex command such as `:edit`. This expands special keywords, | |
4802 like with |expand()|, and environment variables, anywhere in | |
4803 {string}. "~user" and "~/path" are only expanded at the | |
4804 start. | |
4805 Returns the expanded string. Example: > | |
4806 :echo expandcmd('make %<.o') | |
4807 | |
4808 < Can also be used as a |method|: > | |
4809 GetCommand()->expandcmd() | |
4810 < | |
4811 extend({expr1}, {expr2} [, {expr3}]) *extend()* | |
4812 {expr1} and {expr2} must be both |Lists| or both | |
4813 |Dictionaries|. | |
4814 | |
4815 If they are |Lists|: Append {expr2} to {expr1}. | |
4816 If {expr3} is given insert the items of {expr2} before the | |
4817 item with index {expr3} in {expr1}. When {expr3} is zero | |
4818 insert before the first item. When {expr3} is equal to | |
4819 len({expr1}) then {expr2} is appended. | |
4820 Examples: > | |
4821 :echo sort(extend(mylist, [7, 5])) | |
4822 :call extend(mylist, [2, 3], 1) | |
4823 < When {expr1} is the same List as {expr2} then the number of | |
4824 items copied is equal to the original length of the List. | |
4825 E.g., when {expr3} is 1 you get N new copies of the first item | |
4826 (where N is the original length of the List). | |
4827 Use |add()| to concatenate one item to a list. To concatenate | |
4828 two lists into a new list use the + operator: > | |
4829 :let newlist = [1, 2, 3] + [4, 5] | |
4830 < | |
4831 If they are |Dictionaries|: | |
4832 Add all entries from {expr2} to {expr1}. | |
4833 If a key exists in both {expr1} and {expr2} then {expr3} is | |
4834 used to decide what to do: | |
4835 {expr3} = "keep": keep the value of {expr1} | |
4836 {expr3} = "force": use the value of {expr2} | |
4837 {expr3} = "error": give an error message *E737* | |
4838 When {expr3} is omitted then "force" is assumed. | |
4839 | |
4840 {expr1} is changed when {expr2} is not empty. If necessary | |
4841 make a copy of {expr1} first. | |
4842 {expr2} remains unchanged. | |
4843 When {expr1} is locked and {expr2} is not empty the operation | |
4844 fails. | |
4845 Returns {expr1}. | |
4846 | |
4847 Can also be used as a |method|: > | |
4848 mylist->extend(otherlist) | |
4849 | |
4850 | |
4851 extendnew({expr1}, {expr2} [, {expr3}]) *extendnew()* | |
4852 Like |extend()| but instead of adding items to {expr1} a new | |
4853 List or Dictionary is created and returned. {expr1} remains | |
4854 unchanged. Items can still be changed by {expr2}, if you | |
4855 don't want that use |deepcopy()| first. | |
4856 | |
4857 | |
4858 feedkeys({string} [, {mode}]) *feedkeys()* | |
4859 Characters in {string} are queued for processing as if they | |
4860 come from a mapping or were typed by the user. | |
4861 | |
4862 By default the string is added to the end of the typeahead | |
4863 buffer, thus if a mapping is still being executed the | |
4864 characters come after them. Use the 'i' flag to insert before | |
4865 other characters, they will be executed next, before any | |
4866 characters from a mapping. | |
4867 | |
4868 The function does not wait for processing of keys contained in | |
4869 {string}. | |
4870 | |
4871 To include special keys into {string}, use double-quotes | |
4872 and "\..." notation |expr-quote|. For example, | |
4873 feedkeys("\<CR>") simulates pressing of the <Enter> key. But | |
4874 feedkeys('\<CR>') pushes 5 characters. | |
4875 A special code that might be useful is <Ignore>, it exits the | |
4876 wait for a character without doing anything. *<Ignore>* | |
4877 | |
4878 {mode} is a String, which can contain these character flags: | |
4879 'm' Remap keys. This is default. If {mode} is absent, | |
4880 keys are remapped. | |
4881 'n' Do not remap keys. | |
4882 't' Handle keys as if typed; otherwise they are handled as | |
4883 if coming from a mapping. This matters for undo, | |
4884 opening folds, etc. | |
4885 'L' Lowlevel input. Only works for Unix or when using the | |
4886 GUI. Keys are used as if they were coming from the | |
4887 terminal. Other flags are not used. *E980* | |
4888 When a CTRL-C interrupts and 't' is included it sets | |
4889 the internal "got_int" flag. | |
4890 'i' Insert the string instead of appending (see above). | |
4891 'x' Execute commands until typeahead is empty. This is | |
4892 similar to using ":normal!". You can call feedkeys() | |
4893 several times without 'x' and then one time with 'x' | |
4894 (possibly with an empty {string}) to execute all the | |
4895 typeahead. Note that when Vim ends in Insert mode it | |
4896 will behave as if <Esc> is typed, to avoid getting | |
4897 stuck, waiting for a character to be typed before the | |
4898 script continues. | |
4899 Note that if you manage to call feedkeys() while | |
4900 executing commands, thus calling it recursively, then | |
4901 all typeahead will be consumed by the last call. | |
4902 '!' When used with 'x' will not end Insert mode. Can be | |
4903 used in a test when a timer is set to exit Insert mode | |
4904 a little later. Useful for testing CursorHoldI. | |
4905 | |
4906 Return value is always 0. | |
4907 | |
4908 Can also be used as a |method|: > | |
4909 GetInput()->feedkeys() | |
4910 | |
4911 filereadable({file}) *filereadable()* | |
4912 The result is a Number, which is |TRUE| when a file with the | |
4913 name {file} exists, and can be read. If {file} doesn't exist, | |
4914 or is a directory, the result is |FALSE|. {file} is any | |
4915 expression, which is used as a String. | |
4916 If you don't care about the file being readable you can use | |
4917 |glob()|. | |
4918 {file} is used as-is, you may want to expand wildcards first: > | |
4919 echo filereadable('~/.vimrc') | |
4920 0 | |
4921 echo filereadable(expand('~/.vimrc')) | |
4922 1 | |
4923 | |
4924 < Can also be used as a |method|: > | |
4925 GetName()->filereadable() | |
4926 < *file_readable()* | |
4927 Obsolete name: file_readable(). | |
4928 | |
4929 | |
4930 filewritable({file}) *filewritable()* | |
4931 The result is a Number, which is 1 when a file with the | |
4932 name {file} exists, and can be written. If {file} doesn't | |
4933 exist, or is not writable, the result is 0. If {file} is a | |
4934 directory, and we can write to it, the result is 2. | |
4935 | |
4936 Can also be used as a |method|: > | |
4937 GetName()->filewritable() | |
4938 | |
4939 | |
4940 filter({expr1}, {expr2}) *filter()* | |
4941 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. | |
4942 For each item in {expr1} evaluate {expr2} and when the result | |
4943 is zero or false remove the item from the |List| or | |
4944 |Dictionary|. Similarly for each byte in a |Blob| and each | |
4945 charactor in a |String|. | |
4946 | |
4947 {expr2} must be a |string| or |Funcref|. | |
4948 | |
4949 If {expr2} is a |string|, inside {expr2} |v:val| has the value | |
4950 of the current item. For a |Dictionary| |v:key| has the key | |
4951 of the current item and for a |List| |v:key| has the index of | |
4952 the current item. For a |Blob| |v:key| has the index of the | |
4953 current byte. For a |String| |v:key| has the index of the | |
4954 current character. | |
4955 Examples: > | |
4956 call filter(mylist, 'v:val !~ "OLD"') | |
4957 < Removes the items where "OLD" appears. > | |
4958 call filter(mydict, 'v:key >= 8') | |
4959 < Removes the items with a key below 8. > | |
4960 call filter(var, 0) | |
4961 < Removes all the items, thus clears the |List| or |Dictionary|. | |
4962 | |
4963 Note that {expr2} is the result of expression and is then | |
4964 used as an expression again. Often it is good to use a | |
4965 |literal-string| to avoid having to double backslashes. | |
4966 | |
4967 If {expr2} is a |Funcref| it must take two arguments: | |
4968 1. the key or the index of the current item. | |
4969 2. the value of the current item. | |
4970 The function must return |TRUE| if the item should be kept. | |
4971 Example that keeps the odd items of a list: > | |
4972 func Odd(idx, val) | |
4973 return a:idx % 2 == 1 | |
4974 endfunc | |
4975 call filter(mylist, function('Odd')) | |
4976 < It is shorter when using a |lambda|: > | |
4977 call filter(myList, {idx, val -> idx * val <= 42}) | |
4978 < If you do not use "val" you can leave it out: > | |
4979 call filter(myList, {idx -> idx % 2 == 1}) | |
4980 < | |
4981 In |Vim9| script the result must be true, false, zero or one. | |
4982 Other values will result in a type error. | |
4983 | |
4984 For a |List| and a |Dictionary| the operation is done | |
4985 in-place. If you want it to remain unmodified make a copy | |
4986 first: > | |
4987 :let l = filter(copy(mylist), 'v:val =~ "KEEP"') | |
4988 | |
4989 < Returns {expr1}, the |List| or |Dictionary| that was filtered, | |
4990 or a new |Blob| or |String|. | |
4991 When an error is encountered while evaluating {expr2} no | |
4992 further items in {expr1} are processed. | |
4993 When {expr2} is a Funcref errors inside a function are ignored, | |
4994 unless it was defined with the "abort" flag. | |
4995 | |
4996 Can also be used as a |method|: > | |
4997 mylist->filter(expr2) | |
4998 | |
4999 finddir({name} [, {path} [, {count}]]) *finddir()* | |
5000 Find directory {name} in {path}. Supports both downwards and | |
5001 upwards recursive directory searches. See |file-searching| | |
5002 for the syntax of {path}. | |
5003 | |
5004 Returns the path of the first found match. When the found | |
5005 directory is below the current directory a relative path is | |
5006 returned. Otherwise a full path is returned. | |
5007 If {path} is omitted or empty then 'path' is used. | |
5008 | |
5009 If the optional {count} is given, find {count}'s occurrence of | |
5010 {name} in {path} instead of the first one. | |
5011 When {count} is negative return all the matches in a |List|. | |
5012 | |
5013 This is quite similar to the ex-command `:find`. | |
5014 {only available when compiled with the |+file_in_path| | |
5015 feature} | |
5016 | |
5017 Can also be used as a |method|: > | |
5018 GetName()->finddir() | |
5019 | |
5020 findfile({name} [, {path} [, {count}]]) *findfile()* | |
5021 Just like |finddir()|, but find a file instead of a directory. | |
5022 Uses 'suffixesadd'. | |
5023 Example: > | |
5024 :echo findfile("tags.vim", ".;") | |
5025 < Searches from the directory of the current file upwards until | |
5026 it finds the file "tags.vim". | |
5027 | |
5028 Can also be used as a |method|: > | |
5029 GetName()->findfile() | |
5030 | |
5031 flatten({list} [, {maxdepth}]) *flatten()* | |
5032 Flatten {list} up to {maxdepth} levels. Without {maxdepth} | |
5033 the result is a |List| without nesting, as if {maxdepth} is | |
5034 a very large number. | |
5035 The {list} is changed in place, use |flattennew()| if you do | |
5036 not want that. | |
5037 In Vim9 script flatten() cannot be used, you must always use | |
5038 |flattennew()|. | |
5039 *E900* | |
5040 {maxdepth} means how deep in nested lists changes are made. | |
5041 {list} is not modified when {maxdepth} is 0. | |
5042 {maxdepth} must be positive number. | |
5043 | |
5044 If there is an error the number zero is returned. | |
5045 | |
5046 Example: > | |
5047 :echo flatten([1, [2, [3, 4]], 5]) | |
5048 < [1, 2, 3, 4, 5] > | |
5049 :echo flatten([1, [2, [3, 4]], 5], 1) | |
5050 < [1, 2, [3, 4], 5] | |
5051 | |
5052 Can also be used as a |method|: > | |
5053 mylist->flatten() | |
5054 < | |
5055 flattennew({list} [, {maxdepth}]) *flattennew()* | |
5056 Like |flatten()| but first make a copy of {list}. | |
5057 | |
5058 | |
5059 float2nr({expr}) *float2nr()* | |
5060 Convert {expr} to a Number by omitting the part after the | |
5061 decimal point. | |
5062 {expr} must evaluate to a |Float| or a Number. | |
5063 When the value of {expr} is out of range for a |Number| the | |
5064 result is truncated to 0x7fffffff or -0x7fffffff (or when | |
5065 64-bit Number support is enabled, 0x7fffffffffffffff or | |
5066 -0x7fffffffffffffff). NaN results in -0x80000000 (or when | |
5067 64-bit Number support is enabled, -0x8000000000000000). | |
5068 Examples: > | |
5069 echo float2nr(3.95) | |
5070 < 3 > | |
5071 echo float2nr(-23.45) | |
5072 < -23 > | |
5073 echo float2nr(1.0e100) | |
5074 < 2147483647 (or 9223372036854775807) > | |
5075 echo float2nr(-1.0e150) | |
5076 < -2147483647 (or -9223372036854775807) > | |
5077 echo float2nr(1.0e-100) | |
5078 < 0 | |
5079 | |
5080 Can also be used as a |method|: > | |
5081 Compute()->float2nr() | |
5082 < | |
5083 {only available when compiled with the |+float| feature} | |
5084 | |
5085 | |
5086 floor({expr}) *floor()* | |
5087 Return the largest integral value less than or equal to | |
5088 {expr} as a |Float| (round down). | |
5089 {expr} must evaluate to a |Float| or a |Number|. | |
5090 Examples: > | |
5091 echo floor(1.856) | |
5092 < 1.0 > | |
5093 echo floor(-5.456) | |
5094 < -6.0 > | |
5095 echo floor(4.0) | |
5096 < 4.0 | |
5097 | |
5098 Can also be used as a |method|: > | |
5099 Compute()->floor() | |
5100 < | |
5101 {only available when compiled with the |+float| feature} | |
5102 | |
5103 | |
5104 fmod({expr1}, {expr2}) *fmod()* | |
5105 Return the remainder of {expr1} / {expr2}, even if the | |
5106 division is not representable. Returns {expr1} - i * {expr2} | |
5107 for some integer i such that if {expr2} is non-zero, the | |
5108 result has the same sign as {expr1} and magnitude less than | |
5109 the magnitude of {expr2}. If {expr2} is zero, the value | |
5110 returned is zero. The value returned is a |Float|. | |
5111 {expr1} and {expr2} must evaluate to a |Float| or a |Number|. | |
5112 Examples: > | |
5113 :echo fmod(12.33, 1.22) | |
5114 < 0.13 > | |
5115 :echo fmod(-12.33, 1.22) | |
5116 < -0.13 | |
5117 | |
5118 Can also be used as a |method|: > | |
5119 Compute()->fmod(1.22) | |
5120 < | |
5121 {only available when compiled with |+float| feature} | |
5122 | |
5123 | |
5124 fnameescape({string}) *fnameescape()* | |
5125 Escape {string} for use as file name command argument. All | |
5126 characters that have a special meaning, such as '%' and '|' | |
5127 are escaped with a backslash. | |
5128 For most systems the characters escaped are | |
5129 " \t\n*?[{`$\\%#'\"|!<". For systems where a backslash | |
5130 appears in a filename, it depends on the value of 'isfname'. | |
5131 A leading '+' and '>' is also escaped (special after |:edit| | |
5132 and |:write|). And a "-" by itself (special after |:cd|). | |
5133 Example: > | |
5134 :let fname = '+some str%nge|name' | |
5135 :exe "edit " . fnameescape(fname) | |
5136 < results in executing: > | |
5137 edit \+some\ str\%nge\|name | |
5138 < | |
5139 Can also be used as a |method|: > | |
5140 GetName()->fnameescape() | |
5141 | |
5142 fnamemodify({fname}, {mods}) *fnamemodify()* | |
5143 Modify file name {fname} according to {mods}. {mods} is a | |
5144 string of characters like it is used for file names on the | |
5145 command line. See |filename-modifiers|. | |
5146 Example: > | |
5147 :echo fnamemodify("main.c", ":p:h") | |
5148 < results in: > | |
5149 /home/mool/vim/vim/src | |
5150 < If {mods} is empty then {fname} is returned. | |
5151 Note: Environment variables don't work in {fname}, use | |
5152 |expand()| first then. | |
5153 | |
5154 Can also be used as a |method|: > | |
5155 GetName()->fnamemodify(':p:h') | |
5156 | |
5157 foldclosed({lnum}) *foldclosed()* | |
5158 The result is a Number. If the line {lnum} is in a closed | |
5159 fold, the result is the number of the first line in that fold. | |
5160 If the line {lnum} is not in a closed fold, -1 is returned. | |
5161 {lnum} is used like with |getline()|. Thus "." is the current | |
5162 line, "'m" mark m, etc. | |
5163 | |
5164 Can also be used as a |method|: > | |
5165 GetLnum()->foldclosed() | |
5166 | |
5167 foldclosedend({lnum}) *foldclosedend()* | |
5168 The result is a Number. If the line {lnum} is in a closed | |
5169 fold, the result is the number of the last line in that fold. | |
5170 If the line {lnum} is not in a closed fold, -1 is returned. | |
5171 {lnum} is used like with |getline()|. Thus "." is the current | |
5172 line, "'m" mark m, etc. | |
5173 | |
5174 Can also be used as a |method|: > | |
5175 GetLnum()->foldclosedend() | |
5176 | |
5177 foldlevel({lnum}) *foldlevel()* | |
5178 The result is a Number, which is the foldlevel of line {lnum} | |
5179 in the current buffer. For nested folds the deepest level is | |
5180 returned. If there is no fold at line {lnum}, zero is | |
5181 returned. It doesn't matter if the folds are open or closed. | |
5182 When used while updating folds (from 'foldexpr') -1 is | |
5183 returned for lines where folds are still to be updated and the | |
5184 foldlevel is unknown. As a special case the level of the | |
5185 previous line is usually available. | |
5186 {lnum} is used like with |getline()|. Thus "." is the current | |
5187 line, "'m" mark m, etc. | |
5188 | |
5189 Can also be used as a |method|: > | |
5190 GetLnum()->foldlevel() | |
5191 < | |
5192 *foldtext()* | |
5193 foldtext() Returns a String, to be displayed for a closed fold. This is | |
5194 the default function used for the 'foldtext' option and should | |
5195 only be called from evaluating 'foldtext'. It uses the | |
5196 |v:foldstart|, |v:foldend| and |v:folddashes| variables. | |
5197 The returned string looks like this: > | |
5198 +-- 45 lines: abcdef | |
5199 < The number of leading dashes depends on the foldlevel. The | |
5200 "45" is the number of lines in the fold. "abcdef" is the text | |
5201 in the first non-blank line of the fold. Leading white space, | |
5202 "//" or "/*" and the text from the 'foldmarker' and | |
5203 'commentstring' options is removed. | |
5204 When used to draw the actual foldtext, the rest of the line | |
5205 will be filled with the fold char from the 'fillchars' | |
5206 setting. | |
5207 {not available when compiled without the |+folding| feature} | |
5208 | |
5209 foldtextresult({lnum}) *foldtextresult()* | |
5210 Returns the text that is displayed for the closed fold at line | |
5211 {lnum}. Evaluates 'foldtext' in the appropriate context. | |
5212 When there is no closed fold at {lnum} an empty string is | |
5213 returned. | |
5214 {lnum} is used like with |getline()|. Thus "." is the current | |
5215 line, "'m" mark m, etc. | |
5216 Useful when exporting folded text, e.g., to HTML. | |
5217 {not available when compiled without the |+folding| feature} | |
5218 | |
5219 | |
5220 Can also be used as a |method|: > | |
5221 GetLnum()->foldtextresult() | |
5222 < | |
5223 *foreground()* | |
5224 foreground() Move the Vim window to the foreground. Useful when sent from | |
5225 a client to a Vim server. |remote_send()| | |
5226 On Win32 systems this might not work, the OS does not always | |
5227 allow a window to bring itself to the foreground. Use | |
5228 |remote_foreground()| instead. | |
5229 {only in the Win32, Athena, Motif and GTK GUI versions and the | |
5230 Win32 console version} | |
5231 | |
5232 fullcommand({name}) *fullcommand()* | |
5233 Get the full command name from a short abbreviated command | |
5234 name; see |20.2| for details on command abbreviations. | |
5235 | |
5236 The string argument {name} may start with a `:` and can | |
5237 include a [range], these are skipped and not returned. | |
5238 Returns an empty string if a command doesn't exist or if it's | |
5239 ambiguous (for user-defined commands). | |
5240 | |
5241 For example `fullcommand('s')`, `fullcommand('sub')`, | |
5242 `fullcommand(':%substitute')` all return "substitute". | |
5243 | |
5244 Can also be used as a |method|: > | |
5245 GetName()->fullcommand() | |
5246 < | |
5247 *funcref()* | |
5248 funcref({name} [, {arglist}] [, {dict}]) | |
5249 Just like |function()|, but the returned Funcref will lookup | |
5250 the function by reference, not by name. This matters when the | |
5251 function {name} is redefined later. | |
5252 | |
5253 Unlike |function()|, {name} must be an existing user function. | |
5254 Also for autoloaded functions. {name} cannot be a builtin | |
5255 function. | |
5256 | |
5257 Can also be used as a |method|: > | |
5258 GetFuncname()->funcref([arg]) | |
5259 < | |
5260 *function()* *partial* *E700* *E922* *E923* | |
5261 function({name} [, {arglist}] [, {dict}]) | |
5262 Return a |Funcref| variable that refers to function {name}. | |
5263 {name} can be the name of a user defined function or an | |
5264 internal function. | |
5265 | |
5266 {name} can also be a Funcref or a partial. When it is a | |
5267 partial the dict stored in it will be used and the {dict} | |
5268 argument is not allowed. E.g.: > | |
5269 let FuncWithArg = function(dict.Func, [arg]) | |
5270 let Broken = function(dict.Func, [arg], dict) | |
5271 < | |
5272 When using the Funcref the function will be found by {name}, | |
5273 also when it was redefined later. Use |funcref()| to keep the | |
5274 same function. | |
5275 | |
5276 When {arglist} or {dict} is present this creates a partial. | |
5277 That means the argument list and/or the dictionary is stored in | |
5278 the Funcref and will be used when the Funcref is called. | |
5279 | |
5280 The arguments are passed to the function in front of other | |
5281 arguments, but after any argument from |method|. Example: > | |
5282 func Callback(arg1, arg2, name) | |
5283 ... | |
5284 let Partial = function('Callback', ['one', 'two']) | |
5285 ... | |
5286 call Partial('name') | |
5287 < Invokes the function as with: > | |
5288 call Callback('one', 'two', 'name') | |
5289 | |
5290 < With a |method|: > | |
5291 func Callback(one, two, three) | |
5292 ... | |
5293 let Partial = function('Callback', ['two']) | |
5294 ... | |
5295 eval 'one'->Partial('three') | |
5296 < Invokes the function as with: > | |
5297 call Callback('one', 'two', 'three') | |
5298 | |
5299 < The function() call can be nested to add more arguments to the | |
5300 Funcref. The extra arguments are appended to the list of | |
5301 arguments. Example: > | |
5302 func Callback(arg1, arg2, name) | |
5303 ... | |
5304 let Func = function('Callback', ['one']) | |
5305 let Func2 = function(Func, ['two']) | |
5306 ... | |
5307 call Func2('name') | |
5308 < Invokes the function as with: > | |
5309 call Callback('one', 'two', 'name') | |
5310 | |
5311 < The Dictionary is only useful when calling a "dict" function. | |
5312 In that case the {dict} is passed in as "self". Example: > | |
5313 function Callback() dict | |
5314 echo "called for " . self.name | |
5315 endfunction | |
5316 ... | |
5317 let context = {"name": "example"} | |
5318 let Func = function('Callback', context) | |
5319 ... | |
5320 call Func() " will echo: called for example | |
5321 < The use of function() is not needed when there are no extra | |
5322 arguments, these two are equivalent: > | |
5323 let Func = function('Callback', context) | |
5324 let Func = context.Callback | |
5325 | |
5326 < The argument list and the Dictionary can be combined: > | |
5327 function Callback(arg1, count) dict | |
5328 ... | |
5329 let context = {"name": "example"} | |
5330 let Func = function('Callback', ['one'], context) | |
5331 ... | |
5332 call Func(500) | |
5333 < Invokes the function as with: > | |
5334 call context.Callback('one', 500) | |
5335 < | |
5336 Can also be used as a |method|: > | |
5337 GetFuncname()->function([arg]) | |
5338 | |
5339 | |
5340 garbagecollect([{atexit}]) *garbagecollect()* | |
5341 Cleanup unused |Lists|, |Dictionaries|, |Channels| and |Jobs| | |
5342 that have circular references. | |
5343 | |
5344 There is hardly ever a need to invoke this function, as it is | |
5345 automatically done when Vim runs out of memory or is waiting | |
5346 for the user to press a key after 'updatetime'. Items without | |
5347 circular references are always freed when they become unused. | |
5348 This is useful if you have deleted a very big |List| and/or | |
5349 |Dictionary| with circular references in a script that runs | |
5350 for a long time. | |
5351 | |
5352 When the optional {atexit} argument is one, garbage | |
5353 collection will also be done when exiting Vim, if it wasn't | |
5354 done before. This is useful when checking for memory leaks. | |
5355 | |
5356 The garbage collection is not done immediately but only when | |
5357 it's safe to perform. This is when waiting for the user to | |
5358 type a character. To force garbage collection immediately use | |
5359 |test_garbagecollect_now()|. | |
5360 | |
5361 get({list}, {idx} [, {default}]) *get()* | |
5362 Get item {idx} from |List| {list}. When this item is not | |
5363 available return {default}. Return zero when {default} is | |
5364 omitted. | |
5365 Preferably used as a |method|: > | |
5366 mylist->get(idx) | |
5367 get({blob}, {idx} [, {default}]) | |
5368 Get byte {idx} from |Blob| {blob}. When this byte is not | |
5369 available return {default}. Return -1 when {default} is | |
5370 omitted. | |
5371 Preferably used as a |method|: > | |
5372 myblob->get(idx) | |
5373 get({dict}, {key} [, {default}]) | |
5374 Get item with key {key} from |Dictionary| {dict}. When this | |
5375 item is not available return {default}. Return zero when | |
5376 {default} is omitted. Useful example: > | |
5377 let val = get(g:, 'var_name', 'default') | |
5378 < This gets the value of g:var_name if it exists, and uses | |
5379 'default' when it does not exist. | |
5380 Preferably used as a |method|: > | |
5381 mydict->get(key) | |
5382 get({func}, {what}) | |
5383 Get an item with from Funcref {func}. Possible values for | |
5384 {what} are: | |
5385 "name" The function name | |
5386 "func" The function | |
5387 "dict" The dictionary | |
5388 "args" The list with arguments | |
5389 Preferably used as a |method|: > | |
5390 myfunc->get(what) | |
5391 < | |
5392 *getbufinfo()* | |
5393 getbufinfo([{buf}]) | |
5394 getbufinfo([{dict}]) | |
5395 Get information about buffers as a List of Dictionaries. | |
5396 | |
5397 Without an argument information about all the buffers is | |
5398 returned. | |
5399 | |
5400 When the argument is a |Dictionary| only the buffers matching | |
5401 the specified criteria are returned. The following keys can | |
5402 be specified in {dict}: | |
5403 buflisted include only listed buffers. | |
5404 bufloaded include only loaded buffers. | |
5405 bufmodified include only modified buffers. | |
5406 | |
5407 Otherwise, {buf} specifies a particular buffer to return | |
5408 information for. For the use of {buf}, see |bufname()| | |
5409 above. If the buffer is found the returned List has one item. | |
5410 Otherwise the result is an empty list. | |
5411 | |
5412 Each returned List item is a dictionary with the following | |
5413 entries: | |
5414 bufnr Buffer number. | |
5415 changed TRUE if the buffer is modified. | |
5416 changedtick Number of changes made to the buffer. | |
5417 hidden TRUE if the buffer is hidden. | |
5418 lastused Timestamp in seconds, like | |
5419 |localtime()|, when the buffer was | |
5420 last used. | |
5421 {only with the |+viminfo| feature} | |
5422 listed TRUE if the buffer is listed. | |
5423 lnum Line number used for the buffer when | |
5424 opened in the current window. | |
5425 Only valid if the buffer has been | |
5426 displayed in the window in the past. | |
5427 If you want the line number of the | |
5428 last known cursor position in a given | |
5429 window, use |line()|: > | |
5430 :echo line('.', {winid}) | |
5431 < | |
5432 linecount Number of lines in the buffer (only | |
5433 valid when loaded) | |
5434 loaded TRUE if the buffer is loaded. | |
5435 name Full path to the file in the buffer. | |
5436 signs List of signs placed in the buffer. | |
5437 Each list item is a dictionary with | |
5438 the following fields: | |
5439 id sign identifier | |
5440 lnum line number | |
5441 name sign name | |
5442 variables A reference to the dictionary with | |
5443 buffer-local variables. | |
5444 windows List of |window-ID|s that display this | |
5445 buffer | |
5446 popups List of popup |window-ID|s that | |
5447 display this buffer | |
5448 | |
5449 Examples: > | |
5450 for buf in getbufinfo() | |
5451 echo buf.name | |
5452 endfor | |
5453 for buf in getbufinfo({'buflisted':1}) | |
5454 if buf.changed | |
5455 .... | |
5456 endif | |
5457 endfor | |
5458 < | |
5459 To get buffer-local options use: > | |
5460 getbufvar({bufnr}, '&option_name') | |
5461 < | |
5462 Can also be used as a |method|: > | |
5463 GetBufnr()->getbufinfo() | |
5464 < | |
5465 | |
5466 *getbufline()* | |
5467 getbufline({buf}, {lnum} [, {end}]) | |
5468 Return a |List| with the lines starting from {lnum} to {end} | |
5469 (inclusive) in the buffer {buf}. If {end} is omitted, a | |
5470 |List| with only the line {lnum} is returned. | |
5471 | |
5472 For the use of {buf}, see |bufname()| above. | |
5473 | |
5474 For {lnum} and {end} "$" can be used for the last line of the | |
5475 buffer. Otherwise a number must be used. | |
5476 | |
5477 When {lnum} is smaller than 1 or bigger than the number of | |
5478 lines in the buffer, an empty |List| is returned. | |
5479 | |
5480 When {end} is greater than the number of lines in the buffer, | |
5481 it is treated as {end} is set to the number of lines in the | |
5482 buffer. When {end} is before {lnum} an empty |List| is | |
5483 returned. | |
5484 | |
5485 This function works only for loaded buffers. For unloaded and | |
5486 non-existing buffers, an empty |List| is returned. | |
5487 | |
5488 Example: > | |
5489 :let lines = getbufline(bufnr("myfile"), 1, "$") | |
5490 | |
5491 < Can also be used as a |method|: > | |
5492 GetBufnr()->getbufline(lnum) | |
5493 | |
5494 getbufvar({buf}, {varname} [, {def}]) *getbufvar()* | |
5495 The result is the value of option or local buffer variable | |
5496 {varname} in buffer {buf}. Note that the name without "b:" | |
5497 must be used. | |
5498 The {varname} argument is a string. | |
5499 When {varname} is empty returns a |Dictionary| with all the | |
5500 buffer-local variables. | |
5501 When {varname} is equal to "&" returns a |Dictionary| with all | |
5502 the buffer-local options. | |
5503 Otherwise, when {varname} starts with "&" returns the value of | |
5504 a buffer-local option. | |
5505 This also works for a global or buffer-local option, but it | |
5506 doesn't work for a global variable, window-local variable or | |
5507 window-local option. | |
5508 For the use of {buf}, see |bufname()| above. | |
5509 When the buffer or variable doesn't exist {def} or an empty | |
5510 string is returned, there is no error message. | |
5511 Examples: > | |
5512 :let bufmodified = getbufvar(1, "&mod") | |
5513 :echo "todo myvar = " . getbufvar("todo", "myvar") | |
5514 | |
5515 < Can also be used as a |method|: > | |
5516 GetBufnr()->getbufvar(varname) | |
5517 < | |
5518 getchangelist([{buf}]) *getchangelist()* | |
5519 Returns the |changelist| for the buffer {buf}. For the use | |
5520 of {buf}, see |bufname()| above. If buffer {buf} doesn't | |
5521 exist, an empty list is returned. | |
5522 | |
5523 The returned list contains two entries: a list with the change | |
5524 locations and the current position in the list. Each | |
5525 entry in the change list is a dictionary with the following | |
5526 entries: | |
5527 col column number | |
5528 coladd column offset for 'virtualedit' | |
5529 lnum line number | |
5530 If buffer {buf} is the current buffer, then the current | |
5531 position refers to the position in the list. For other | |
5532 buffers, it is set to the length of the list. | |
5533 | |
5534 Can also be used as a |method|: > | |
5535 GetBufnr()->getchangelist() | |
5536 | |
5537 getchar([expr]) *getchar()* | |
5538 Get a single character from the user or input stream. | |
5539 If [expr] is omitted, wait until a character is available. | |
5540 If [expr] is 0, only get a character when one is available. | |
5541 Return zero otherwise. | |
5542 If [expr] is 1, only check if a character is available, it is | |
5543 not consumed. Return zero if no character available. | |
5544 If you prefer always getting a string use |getcharstr()|. | |
5545 | |
5546 Without [expr] and when [expr] is 0 a whole character or | |
5547 special key is returned. If it is a single character, the | |
5548 result is a number. Use nr2char() to convert it to a String. | |
5549 Otherwise a String is returned with the encoded character. | |
5550 For a special key it's a String with a sequence of bytes | |
5551 starting with 0x80 (decimal: 128). This is the same value as | |
5552 the String "\<Key>", e.g., "\<Left>". The returned value is | |
5553 also a String when a modifier (shift, control, alt) was used | |
5554 that is not included in the character. | |
5555 | |
5556 When [expr] is 0 and Esc is typed, there will be a short delay | |
5557 while Vim waits to see if this is the start of an escape | |
5558 sequence. | |
5559 | |
5560 When [expr] is 1 only the first byte is returned. For a | |
5561 one-byte character it is the character itself as a number. | |
5562 Use nr2char() to convert it to a String. | |
5563 | |
5564 Use getcharmod() to obtain any additional modifiers. | |
5565 | |
5566 When the user clicks a mouse button, the mouse event will be | |
5567 returned. The position can then be found in |v:mouse_col|, | |
5568 |v:mouse_lnum|, |v:mouse_winid| and |v:mouse_win|. | |
5569 |getmousepos()| can also be used. Mouse move events will be | |
5570 ignored. | |
5571 This example positions the mouse as it would normally happen: > | |
5572 let c = getchar() | |
5573 if c == "\<LeftMouse>" && v:mouse_win > 0 | |
5574 exe v:mouse_win . "wincmd w" | |
5575 exe v:mouse_lnum | |
5576 exe "normal " . v:mouse_col . "|" | |
5577 endif | |
5578 < | |
5579 When using bracketed paste only the first character is | |
5580 returned, the rest of the pasted text is dropped. | |
5581 |xterm-bracketed-paste|. | |
5582 | |
5583 There is no prompt, you will somehow have to make clear to the | |
5584 user that a character has to be typed. The screen is not | |
5585 redrawn, e.g. when resizing the window. When using a popup | |
5586 window it should work better with a |popup-filter|. | |
5587 | |
5588 There is no mapping for the character. | |
5589 Key codes are replaced, thus when the user presses the <Del> | |
5590 key you get the code for the <Del> key, not the raw character | |
5591 sequence. Examples: > | |
5592 getchar() == "\<Del>" | |
5593 getchar() == "\<S-Left>" | |
5594 < This example redefines "f" to ignore case: > | |
5595 :nmap f :call FindChar()<CR> | |
5596 :function FindChar() | |
5597 : let c = nr2char(getchar()) | |
5598 : while col('.') < col('$') - 1 | |
5599 : normal l | |
5600 : if getline('.')[col('.') - 1] ==? c | |
5601 : break | |
5602 : endif | |
5603 : endwhile | |
5604 :endfunction | |
5605 < | |
5606 You may also receive synthetic characters, such as | |
5607 |<CursorHold>|. Often you will want to ignore this and get | |
5608 another character: > | |
5609 :function GetKey() | |
5610 : let c = getchar() | |
5611 : while c == "\<CursorHold>" | |
5612 : let c = getchar() | |
5613 : endwhile | |
5614 : return c | |
5615 :endfunction | |
5616 | |
5617 getcharmod() *getcharmod()* | |
5618 The result is a Number which is the state of the modifiers for | |
5619 the last obtained character with getchar() or in another way. | |
5620 These values are added together: | |
5621 2 shift | |
5622 4 control | |
5623 8 alt (meta) | |
5624 16 meta (when it's different from ALT) | |
5625 32 mouse double click | |
5626 64 mouse triple click | |
5627 96 mouse quadruple click (== 32 + 64) | |
5628 128 command (Macintosh only) | |
5629 Only the modifiers that have not been included in the | |
5630 character itself are obtained. Thus Shift-a results in "A" | |
5631 without a modifier. | |
5632 | |
5633 *getcharpos()* | |
5634 getcharpos({expr}) | |
5635 Get the position for String {expr}. Same as |getpos()| but the | |
5636 column number in the returned List is a character index | |
5637 instead of a byte index. | |
5638 If |getpos()| returns a very large column number, such as | |
5639 2147483647, then getcharpos() will return the character index | |
5640 of the last character. | |
5641 | |
5642 Example: | |
5643 With the cursor on '세' in line 5 with text "여보세요": > | |
5644 getcharpos('.') returns [0, 5, 3, 0] | |
5645 getpos('.') returns [0, 5, 7, 0] | |
5646 < | |
5647 Can also be used as a |method|: > | |
5648 GetMark()->getcharpos() | |
5649 | |
5650 getcharsearch() *getcharsearch()* | |
5651 Return the current character search information as a {dict} | |
5652 with the following entries: | |
5653 | |
5654 char character previously used for a character | |
5655 search (|t|, |f|, |T|, or |F|); empty string | |
5656 if no character search has been performed | |
5657 forward direction of character search; 1 for forward, | |
5658 0 for backward | |
5659 until type of character search; 1 for a |t| or |T| | |
5660 character search, 0 for an |f| or |F| | |
5661 character search | |
5662 | |
5663 This can be useful to always have |;| and |,| search | |
5664 forward/backward regardless of the direction of the previous | |
5665 character search: > | |
5666 :nnoremap <expr> ; getcharsearch().forward ? ';' : ',' | |
5667 :nnoremap <expr> , getcharsearch().forward ? ',' : ';' | |
5668 < Also see |setcharsearch()|. | |
5669 | |
5670 | |
5671 getcharstr([expr]) *getcharstr()* | |
5672 Get a single character from the user or input stream as a | |
5673 string. | |
5674 If [expr] is omitted, wait until a character is available. | |
5675 If [expr] is 0 or false, only get a character when one is | |
5676 available. Return an empty string otherwise. | |
5677 If [expr] is 1 or true, only check if a character is | |
5678 available, it is not consumed. Return an empty string | |
5679 if no character is available. | |
5680 Otherwise this works like |getchar()|, except that a number | |
5681 result is converted to a string. | |
5682 | |
5683 | |
5684 getcmdline() *getcmdline()* | |
5685 Return the current command-line. Only works when the command | |
5686 line is being edited, thus requires use of |c_CTRL-\_e| or | |
5687 |c_CTRL-R_=|. | |
5688 Example: > | |
5689 :cmap <F7> <C-\>eescape(getcmdline(), ' \')<CR> | |
5690 < Also see |getcmdtype()|, |getcmdpos()| and |setcmdpos()|. | |
5691 Returns an empty string when entering a password or using | |
5692 |inputsecret()|. | |
5693 | |
5694 getcmdpos() *getcmdpos()* | |
5695 Return the position of the cursor in the command line as a | |
5696 byte count. The first column is 1. | |
5697 Only works when editing the command line, thus requires use of | |
5698 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. | |
5699 Returns 0 otherwise. | |
5700 Also see |getcmdtype()|, |setcmdpos()| and |getcmdline()|. | |
5701 | |
5702 getcmdtype() *getcmdtype()* | |
5703 Return the current command-line type. Possible return values | |
5704 are: | |
5705 : normal Ex command | |
5706 > debug mode command |debug-mode| | |
5707 / forward search command | |
5708 ? backward search command | |
5709 @ |input()| command | |
5710 - |:insert| or |:append| command | |
5711 = |i_CTRL-R_=| | |
5712 Only works when editing the command line, thus requires use of | |
5713 |c_CTRL-\_e| or |c_CTRL-R_=| or an expression mapping. | |
5714 Returns an empty string otherwise. | |
5715 Also see |getcmdpos()|, |setcmdpos()| and |getcmdline()|. | |
5716 | |
5717 getcmdwintype() *getcmdwintype()* | |
5718 Return the current |command-line-window| type. Possible return | |
5719 values are the same as |getcmdtype()|. Returns an empty string | |
5720 when not in the command-line window. | |
5721 | |
5722 getcompletion({pat}, {type} [, {filtered}]) *getcompletion()* | |
5723 Return a list of command-line completion matches. The String | |
5724 {type} argument specifies what for. The following completion | |
5725 types are supported: | |
5726 | |
5727 arglist file names in argument list | |
5728 augroup autocmd groups | |
5729 buffer buffer names | |
5730 behave :behave suboptions | |
5731 color color schemes | |
5732 command Ex command | |
5733 cmdline |cmdline-completion| result | |
5734 compiler compilers | |
5735 cscope |:cscope| suboptions | |
5736 diff_buffer |:diffget| and |:diffput| completion | |
5737 dir directory names | |
5738 environment environment variable names | |
5739 event autocommand events | |
5740 expression Vim expression | |
5741 file file and directory names | |
5742 file_in_path file and directory names in |'path'| | |
5743 filetype filetype names |'filetype'| | |
5744 function function name | |
5745 help help subjects | |
5746 highlight highlight groups | |
5747 history :history suboptions | |
5748 locale locale names (as output of locale -a) | |
5749 mapclear buffer argument | |
5750 mapping mapping name | |
5751 menu menus | |
5752 messages |:messages| suboptions | |
5753 option options | |
5754 packadd optional package |pack-add| names | |
5755 shellcmd Shell command | |
5756 sign |:sign| suboptions | |
5757 syntax syntax file names |'syntax'| | |
5758 syntime |:syntime| suboptions | |
5759 tag tags | |
5760 tag_listfiles tags, file names | |
5761 user user names | |
5762 var user variables | |
5763 | |
5764 If {pat} is an empty string, then all the matches are | |
5765 returned. Otherwise only items matching {pat} are returned. | |
5766 See |wildcards| for the use of special characters in {pat}. | |
5767 | |
5768 If the optional {filtered} flag is set to 1, then 'wildignore' | |
5769 is applied to filter the results. Otherwise all the matches | |
5770 are returned. The 'wildignorecase' option always applies. | |
5771 | |
5772 If {type} is "cmdline", then the |cmdline-completion| result is | |
5773 returned. For example, to complete the possible values after | |
5774 a ":call" command: > | |
5775 echo getcompletion('call ', 'cmdline') | |
5776 < | |
5777 If there are no matches, an empty list is returned. An | |
5778 invalid value for {type} produces an error. | |
5779 | |
5780 Can also be used as a |method|: > | |
5781 GetPattern()->getcompletion('color') | |
5782 < | |
5783 *getcurpos()* | |
5784 getcurpos([{winid}]) | |
5785 Get the position of the cursor. This is like getpos('.'), but | |
5786 includes an extra "curswant" item in the list: | |
5787 [0, lnum, col, off, curswant] ~ | |
5788 The "curswant" number is the preferred column when moving the | |
5789 cursor vertically. Also see |getcursorcharpos()| and | |
5790 |getpos()|. | |
5791 The first "bufnum" item is always zero. The byte position of | |
5792 the cursor is returned in 'col'. To get the character | |
5793 position, use |getcursorcharpos()|. | |
5794 | |
5795 The optional {winid} argument can specify the window. It can | |
5796 be the window number or the |window-ID|. The last known | |
5797 cursor position is returned, this may be invalid for the | |
5798 current value of the buffer if it is not the current window. | |
5799 If {winid} is invalid a list with zeroes is returned. | |
5800 | |
5801 This can be used to save and restore the cursor position: > | |
5802 let save_cursor = getcurpos() | |
5803 MoveTheCursorAround | |
5804 call setpos('.', save_cursor) | |
5805 < Note that this only works within the window. See | |
5806 |winrestview()| for restoring more state. | |
5807 | |
5808 Can also be used as a |method|: > | |
5809 GetWinid()->getcurpos() | |
5810 < | |
5811 *getcursorcharpos()* | |
5812 getcursorcharpos([{winid}]) | |
5813 Same as |getcurpos()| but the column number in the returned | |
5814 List is a character index instead of a byte index. | |
5815 | |
5816 Example: | |
5817 With the cursor on '보' in line 3 with text "여보세요": > | |
5818 getcursorcharpos() returns [0, 3, 2, 0, 3] | |
5819 getcurpos() returns [0, 3, 4, 0, 3] | |
5820 < | |
5821 Can also be used as a |method|: > | |
5822 GetWinid()->getcursorcharpos() | |
5823 | |
5824 < *getcwd()* | |
5825 getcwd([{winnr} [, {tabnr}]]) | |
5826 The result is a String, which is the name of the current | |
5827 working directory. 'autochdir' is ignored. | |
5828 | |
5829 With {winnr} return the local current directory of this window | |
5830 in the current tab page. {winnr} can be the window number or | |
5831 the |window-ID|. | |
5832 If {winnr} is -1 return the name of the global working | |
5833 directory. See also |haslocaldir()|. | |
5834 | |
5835 With {winnr} and {tabnr} return the local current directory of | |
5836 the window in the specified tab page. If {winnr} is -1 return | |
5837 the working directory of the tabpage. | |
5838 If {winnr} is zero use the current window, if {tabnr} is zero | |
5839 use the current tabpage. | |
5840 Without any arguments, return the actual working directory of | |
5841 the current window. | |
5842 Return an empty string if the arguments are invalid. | |
5843 | |
5844 Examples: > | |
5845 " Get the working directory of the current window | |
5846 :echo getcwd() | |
5847 :echo getcwd(0) | |
5848 :echo getcwd(0, 0) | |
5849 " Get the working directory of window 3 in tabpage 2 | |
5850 :echo getcwd(3, 2) | |
5851 " Get the global working directory | |
5852 :echo getcwd(-1) | |
5853 " Get the working directory of tabpage 3 | |
5854 :echo getcwd(-1, 3) | |
5855 " Get the working directory of current tabpage | |
5856 :echo getcwd(-1, 0) | |
5857 | |
5858 < Can also be used as a |method|: > | |
5859 GetWinnr()->getcwd() | |
5860 | |
5861 getenv({name}) *getenv()* | |
5862 Return the value of environment variable {name}. The {name} | |
5863 argument is a string, without a leading '$'. Example: > | |
5864 myHome = getenv('HOME') | |
5865 | |
5866 < When the variable does not exist |v:null| is returned. That | |
5867 is different from a variable set to an empty string, although | |
5868 some systems interpret the empty value as the variable being | |
5869 deleted. See also |expr-env|. | |
5870 | |
5871 Can also be used as a |method|: > | |
5872 GetVarname()->getenv() | |
5873 | |
5874 getfontname([{name}]) *getfontname()* | |
5875 Without an argument returns the name of the normal font being | |
5876 used. Like what is used for the Normal highlight group | |
5877 |hl-Normal|. | |
5878 With an argument a check is done whether String {name} is a | |
5879 valid font name. If not then an empty string is returned. | |
5880 Otherwise the actual font name is returned, or {name} if the | |
5881 GUI does not support obtaining the real name. | |
5882 Only works when the GUI is running, thus not in your vimrc or | |
5883 gvimrc file. Use the |GUIEnter| autocommand to use this | |
5884 function just after the GUI has started. | |
5885 Note that the GTK GUI accepts any font name, thus checking for | |
5886 a valid name does not work. | |
5887 | |
5888 getfperm({fname}) *getfperm()* | |
5889 The result is a String, which is the read, write, and execute | |
5890 permissions of the given file {fname}. | |
5891 If {fname} does not exist or its directory cannot be read, an | |
5892 empty string is returned. | |
5893 The result is of the form "rwxrwxrwx", where each group of | |
5894 "rwx" flags represent, in turn, the permissions of the owner | |
5895 of the file, the group the file belongs to, and other users. | |
5896 If a user does not have a given permission the flag for this | |
5897 is replaced with the string "-". Examples: > | |
5898 :echo getfperm("/etc/passwd") | |
5899 :echo getfperm(expand("~/.vimrc")) | |
5900 < This will hopefully (from a security point of view) display | |
5901 the string "rw-r--r--" or even "rw-------". | |
5902 | |
5903 Can also be used as a |method|: > | |
5904 GetFilename()->getfperm() | |
5905 < | |
5906 For setting permissions use |setfperm()|. | |
5907 | |
5908 getfsize({fname}) *getfsize()* | |
5909 The result is a Number, which is the size in bytes of the | |
5910 given file {fname}. | |
5911 If {fname} is a directory, 0 is returned. | |
5912 If the file {fname} can't be found, -1 is returned. | |
5913 If the size of {fname} is too big to fit in a Number then -2 | |
5914 is returned. | |
5915 | |
5916 Can also be used as a |method|: > | |
5917 GetFilename()->getfsize() | |
5918 | |
5919 getftime({fname}) *getftime()* | |
5920 The result is a Number, which is the last modification time of | |
5921 the given file {fname}. The value is measured as seconds | |
5922 since 1st Jan 1970, and may be passed to strftime(). See also | |
5923 |localtime()| and |strftime()|. | |
5924 If the file {fname} can't be found -1 is returned. | |
5925 | |
5926 Can also be used as a |method|: > | |
5927 GetFilename()->getftime() | |
5928 | |
5929 getftype({fname}) *getftype()* | |
5930 The result is a String, which is a description of the kind of | |
5931 file of the given file {fname}. | |
5932 If {fname} does not exist an empty string is returned. | |
5933 Here is a table over different kinds of files and their | |
5934 results: | |
5935 Normal file "file" | |
5936 Directory "dir" | |
5937 Symbolic link "link" | |
5938 Block device "bdev" | |
5939 Character device "cdev" | |
5940 Socket "socket" | |
5941 FIFO "fifo" | |
5942 All other "other" | |
5943 Example: > | |
5944 getftype("/home") | |
5945 < Note that a type such as "link" will only be returned on | |
5946 systems that support it. On some systems only "dir" and | |
5947 "file" are returned. On MS-Windows a symbolic link to a | |
5948 directory returns "dir" instead of "link". | |
5949 | |
5950 Can also be used as a |method|: > | |
5951 GetFilename()->getftype() | |
5952 | |
5953 getimstatus() *getimstatus()* | |
5954 The result is a Number, which is |TRUE| when the IME status is | |
5955 active. | |
5956 See 'imstatusfunc'. | |
5957 | |
5958 getjumplist([{winnr} [, {tabnr}]]) *getjumplist()* | |
5959 Returns the |jumplist| for the specified window. | |
5960 | |
5961 Without arguments use the current window. | |
5962 With {winnr} only use this window in the current tab page. | |
5963 {winnr} can also be a |window-ID|. | |
5964 With {winnr} and {tabnr} use the window in the specified tab | |
5965 page. | |
5966 | |
5967 The returned list contains two entries: a list with the jump | |
5968 locations and the last used jump position number in the list. | |
5969 Each entry in the jump location list is a dictionary with | |
5970 the following entries: | |
5971 bufnr buffer number | |
5972 col column number | |
5973 coladd column offset for 'virtualedit' | |
5974 filename filename if available | |
5975 lnum line number | |
5976 | |
5977 Can also be used as a |method|: > | |
5978 GetWinnr()->getjumplist() | |
5979 | |
5980 < *getline()* | |
5981 getline({lnum} [, {end}]) | |
5982 Without {end} the result is a String, which is line {lnum} | |
5983 from the current buffer. Example: > | |
5984 getline(1) | |
5985 < When {lnum} is a String that doesn't start with a | |
5986 digit, |line()| is called to translate the String into a Number. | |
5987 To get the line under the cursor: > | |
5988 getline(".") | |
5989 < When {lnum} is a number smaller than 1 or bigger than the | |
5990 number of lines in the buffer, an empty string is returned. | |
5991 | |
5992 When {end} is given the result is a |List| where each item is | |
5993 a line from the current buffer in the range {lnum} to {end}, | |
5994 including line {end}. | |
5995 {end} is used in the same way as {lnum}. | |
5996 Non-existing lines are silently omitted. | |
5997 When {end} is before {lnum} an empty |List| is returned. | |
5998 Example: > | |
5999 :let start = line('.') | |
6000 :let end = search("^$") - 1 | |
6001 :let lines = getline(start, end) | |
6002 | |
6003 < Can also be used as a |method|: > | |
6004 ComputeLnum()->getline() | |
6005 | |
6006 < To get lines from another buffer see |getbufline()| | |
6007 | |
6008 getloclist({nr} [, {what}]) *getloclist()* | |
6009 Returns a |List| with all the entries in the location list for | |
6010 window {nr}. {nr} can be the window number or the |window-ID|. | |
6011 When {nr} is zero the current window is used. | |
6012 | |
6013 For a location list window, the displayed location list is | |
6014 returned. For an invalid window number {nr}, an empty list is | |
6015 returned. Otherwise, same as |getqflist()|. | |
6016 | |
6017 If the optional {what} dictionary argument is supplied, then | |
6018 returns the items listed in {what} as a dictionary. Refer to | |
6019 |getqflist()| for the supported items in {what}. | |
6020 | |
6021 In addition to the items supported by |getqflist()| in {what}, | |
6022 the following item is supported by |getloclist()|: | |
6023 | |
6024 filewinid id of the window used to display files | |
6025 from the location list. This field is | |
6026 applicable only when called from a | |
6027 location list window. See | |
6028 |location-list-file-window| for more | |
6029 details. | |
6030 | |
6031 Returns a |Dictionary| with default values if there is no | |
6032 location list for the window {nr}. | |
6033 Returns an empty Dictionary if window {nr} does not exist. | |
6034 | |
6035 Examples (See also |getqflist-examples|): > | |
6036 :echo getloclist(3, {'all': 0}) | |
6037 :echo getloclist(5, {'filewinid': 0}) | |
6038 | |
6039 | |
6040 getmarklist([{buf}]) *getmarklist()* | |
6041 Without the {buf} argument returns a |List| with information | |
6042 about all the global marks. |mark| | |
6043 | |
6044 If the optional {buf} argument is specified, returns the | |
6045 local marks defined in buffer {buf}. For the use of {buf}, | |
6046 see |bufname()|. | |
6047 | |
6048 Each item in the returned List is a |Dict| with the following: | |
6049 mark name of the mark prefixed by "'" | |
6050 pos a |List| with the position of the mark: | |
6051 [bufnum, lnum, col, off] | |
6052 Refer to |getpos()| for more information. | |
6053 file file name | |
6054 | |
6055 Refer to |getpos()| for getting information about a specific | |
6056 mark. | |
6057 | |
6058 Can also be used as a |method|: > | |
6059 GetBufnr()->getmarklist() | |
6060 | |
6061 getmatches([{win}]) *getmatches()* | |
6062 Returns a |List| with all matches previously defined for the | |
6063 current window by |matchadd()| and the |:match| commands. | |
6064 |getmatches()| is useful in combination with |setmatches()|, | |
6065 as |setmatches()| can restore a list of matches saved by | |
6066 |getmatches()|. | |
6067 If {win} is specified, use the window with this number or | |
6068 window ID instead of the current window. | |
6069 Example: > | |
6070 :echo getmatches() | |
6071 < [{'group': 'MyGroup1', 'pattern': 'TODO', | |
6072 'priority': 10, 'id': 1}, {'group': 'MyGroup2', | |
6073 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > | |
6074 :let m = getmatches() | |
6075 :call clearmatches() | |
6076 :echo getmatches() | |
6077 < [] > | |
6078 :call setmatches(m) | |
6079 :echo getmatches() | |
6080 < [{'group': 'MyGroup1', 'pattern': 'TODO', | |
6081 'priority': 10, 'id': 1}, {'group': 'MyGroup2', | |
6082 'pattern': 'FIXME', 'priority': 10, 'id': 2}] > | |
6083 :unlet m | |
6084 < | |
6085 getmousepos() *getmousepos()* | |
6086 Returns a |Dictionary| with the last known position of the | |
6087 mouse. This can be used in a mapping for a mouse click or in | |
6088 a filter of a popup window. The items are: | |
6089 screenrow screen row | |
6090 screencol screen column | |
6091 winid Window ID of the click | |
6092 winrow row inside "winid" | |
6093 wincol column inside "winid" | |
6094 line text line inside "winid" | |
6095 column text column inside "winid" | |
6096 All numbers are 1-based. | |
6097 | |
6098 If not over a window, e.g. when in the command line, then only | |
6099 "screenrow" and "screencol" are valid, the others are zero. | |
6100 | |
6101 When on the status line below a window or the vertical | |
6102 separator right of a window, the "line" and "column" values | |
6103 are zero. | |
6104 | |
6105 When the position is after the text then "column" is the | |
6106 length of the text in bytes plus one. | |
6107 | |
6108 If the mouse is over a popup window then that window is used. | |
6109 | |
6110 When using |getchar()| the Vim variables |v:mouse_lnum|, | |
6111 |v:mouse_col| and |v:mouse_winid| also provide these values. | |
6112 | |
6113 *getpid()* | |
6114 getpid() Return a Number which is the process ID of the Vim process. | |
6115 On Unix and MS-Windows this is a unique number, until Vim | |
6116 exits. | |
6117 | |
6118 *getpos()* | |
6119 getpos({expr}) Get the position for String {expr}. For possible values of | |
6120 {expr} see |line()|. For getting the cursor position see | |
6121 |getcurpos()|. | |
6122 The result is a |List| with four numbers: | |
6123 [bufnum, lnum, col, off] | |
6124 "bufnum" is zero, unless a mark like '0 or 'A is used, then it | |
6125 is the buffer number of the mark. | |
6126 "lnum" and "col" are the position in the buffer. The first | |
6127 column is 1. | |
6128 The "off" number is zero, unless 'virtualedit' is used. Then | |
6129 it is the offset in screen columns from the start of the | |
6130 character. E.g., a position within a <Tab> or after the last | |
6131 character. | |
6132 Note that for '< and '> Visual mode matters: when it is "V" | |
6133 (visual line mode) the column of '< is zero and the column of | |
6134 '> is a large number. | |
6135 The column number in the returned List is the byte position | |
6136 within the line. To get the character position in the line, | |
6137 use |getcharpos()|. | |
6138 The column number can be very large, e.g. 2147483647, in which | |
6139 case it means "after the end of the line". | |
6140 This can be used to save and restore the position of a mark: > | |
6141 let save_a_mark = getpos("'a") | |
6142 ... | |
6143 call setpos("'a", save_a_mark) | |
6144 < Also see |getcharpos()|, |getcurpos()| and |setpos()|. | |
6145 | |
6146 Can also be used as a |method|: > | |
6147 GetMark()->getpos() | |
6148 | |
6149 getqflist([{what}]) *getqflist()* | |
6150 Returns a |List| with all the current quickfix errors. Each | |
6151 list item is a dictionary with these entries: | |
6152 bufnr number of buffer that has the file name, use | |
6153 bufname() to get the name | |
6154 module module name | |
6155 lnum line number in the buffer (first line is 1) | |
6156 end_lnum | |
6157 end of line number if the item is multiline | |
6158 col column number (first column is 1) | |
6159 end_col end of column number if the item has range | |
6160 vcol |TRUE|: "col" is visual column | |
6161 |FALSE|: "col" is byte index | |
6162 nr error number | |
6163 pattern search pattern used to locate the error | |
6164 text description of the error | |
6165 type type of the error, 'E', '1', etc. | |
6166 valid |TRUE|: recognized error message | |
6167 | |
6168 When there is no error list or it's empty, an empty list is | |
6169 returned. Quickfix list entries with a non-existing buffer | |
6170 number are returned with "bufnr" set to zero (Note: some | |
6171 functions accept buffer number zero for the alternate buffer, | |
6172 you may need to explicitly check for zero). | |
6173 | |
6174 Useful application: Find pattern matches in multiple files and | |
6175 do something with them: > | |
6176 :vimgrep /theword/jg *.c | |
6177 :for d in getqflist() | |
6178 : echo bufname(d.bufnr) ':' d.lnum '=' d.text | |
6179 :endfor | |
6180 < | |
6181 If the optional {what} dictionary argument is supplied, then | |
6182 returns only the items listed in {what} as a dictionary. The | |
6183 following string items are supported in {what}: | |
6184 changedtick get the total number of changes made | |
6185 to the list |quickfix-changedtick| | |
6186 context get the |quickfix-context| | |
6187 efm errorformat to use when parsing "lines". If | |
6188 not present, then the 'errorformat' option | |
6189 value is used. | |
6190 id get information for the quickfix list with | |
6191 |quickfix-ID|; zero means the id for the | |
6192 current list or the list specified by "nr" | |
6193 idx get information for the quickfix entry at this | |
6194 index in the list specified by 'id' or 'nr'. | |
6195 If set to zero, then uses the current entry. | |
6196 See |quickfix-index| | |
6197 items quickfix list entries | |
6198 lines parse a list of lines using 'efm' and return | |
6199 the resulting entries. Only a |List| type is | |
6200 accepted. The current quickfix list is not | |
6201 modified. See |quickfix-parse|. | |
6202 nr get information for this quickfix list; zero | |
6203 means the current quickfix list and "$" means | |
6204 the last quickfix list | |
6205 qfbufnr number of the buffer displayed in the quickfix | |
6206 window. Returns 0 if the quickfix buffer is | |
6207 not present. See |quickfix-buffer|. | |
6208 size number of entries in the quickfix list | |
6209 title get the list title |quickfix-title| | |
6210 winid get the quickfix |window-ID| | |
6211 all all of the above quickfix properties | |
6212 Non-string items in {what} are ignored. To get the value of a | |
6213 particular item, set it to zero. | |
6214 If "nr" is not present then the current quickfix list is used. | |
6215 If both "nr" and a non-zero "id" are specified, then the list | |
6216 specified by "id" is used. | |
6217 To get the number of lists in the quickfix stack, set "nr" to | |
6218 "$" in {what}. The "nr" value in the returned dictionary | |
6219 contains the quickfix stack size. | |
6220 When "lines" is specified, all the other items except "efm" | |
6221 are ignored. The returned dictionary contains the entry | |
6222 "items" with the list of entries. | |
6223 | |
6224 The returned dictionary contains the following entries: | |
6225 changedtick total number of changes made to the | |
6226 list |quickfix-changedtick| | |
6227 context quickfix list context. See |quickfix-context| | |
6228 If not present, set to "". | |
6229 id quickfix list ID |quickfix-ID|. If not | |
6230 present, set to 0. | |
6231 idx index of the quickfix entry in the list. If not | |
6232 present, set to 0. | |
6233 items quickfix list entries. If not present, set to | |
6234 an empty list. | |
6235 nr quickfix list number. If not present, set to 0 | |
6236 qfbufnr number of the buffer displayed in the quickfix | |
6237 window. If not present, set to 0. | |
6238 size number of entries in the quickfix list. If not | |
6239 present, set to 0. | |
6240 title quickfix list title text. If not present, set | |
6241 to "". | |
6242 winid quickfix |window-ID|. If not present, set to 0 | |
6243 | |
6244 Examples (See also |getqflist-examples|): > | |
6245 :echo getqflist({'all': 1}) | |
6246 :echo getqflist({'nr': 2, 'title': 1}) | |
6247 :echo getqflist({'lines' : ["F1:10:L10"]}) | |
6248 < | |
6249 getreg([{regname} [, 1 [, {list}]]]) *getreg()* | |
6250 The result is a String, which is the contents of register | |
6251 {regname}. Example: > | |
6252 :let cliptext = getreg('*') | |
6253 < When register {regname} was not set the result is an empty | |
6254 string. | |
6255 The {regname} argument must be a string. | |
6256 | |
6257 getreg('=') returns the last evaluated value of the expression | |
6258 register. (For use in maps.) | |
6259 getreg('=', 1) returns the expression itself, so that it can | |
6260 be restored with |setreg()|. For other registers the extra | |
6261 argument is ignored, thus you can always give it. | |
6262 | |
6263 If {list} is present and |TRUE|, the result type is changed | |
6264 to |List|. Each list item is one text line. Use it if you care | |
6265 about zero bytes possibly present inside register: without | |
6266 third argument both NLs and zero bytes are represented as NLs | |
6267 (see |NL-used-for-Nul|). | |
6268 When the register was not set an empty list is returned. | |
6269 | |
6270 If {regname} is "", the unnamed register '"' is used. | |
6271 If {regname} is not specified, |v:register| is used. | |
6272 In |Vim9-script| {regname} must be one character. | |
6273 | |
6274 Can also be used as a |method|: > | |
6275 GetRegname()->getreg() | |
6276 | |
6277 getreginfo([{regname}]) *getreginfo()* | |
6278 Returns detailed information about register {regname} as a | |
6279 Dictionary with the following entries: | |
6280 regcontents List of lines contained in register | |
6281 {regname}, like | |
6282 |getreg|({regname}, 1, 1). | |
6283 regtype the type of register {regname}, as in | |
6284 |getregtype()|. | |
6285 isunnamed Boolean flag, v:true if this register | |
6286 is currently pointed to by the unnamed | |
6287 register. | |
6288 points_to for the unnamed register, gives the | |
6289 single letter name of the register | |
6290 currently pointed to (see |quotequote|). | |
6291 For example, after deleting a line | |
6292 with `dd`, this field will be "1", | |
6293 which is the register that got the | |
6294 deleted text. | |
6295 | |
6296 The {regname} argument is a string. If {regname} is invalid | |
6297 or not set, an empty Dictionary will be returned. | |
6298 If {regname} is "" or "@", the unnamed register '"' is used. | |
6299 If {regname} is not specified, |v:register| is used. | |
6300 The returned Dictionary can be passed to |setreg()|. | |
6301 In |Vim9-script| {regname} must be one character. | |
6302 | |
6303 Can also be used as a |method|: > | |
6304 GetRegname()->getreginfo() | |
6305 | |
6306 getregtype([{regname}]) *getregtype()* | |
6307 The result is a String, which is type of register {regname}. | |
6308 The value will be one of: | |
6309 "v" for |characterwise| text | |
6310 "V" for |linewise| text | |
6311 "<CTRL-V>{width}" for |blockwise-visual| text | |
6312 "" for an empty or unknown register | |
6313 <CTRL-V> is one character with value 0x16. | |
6314 The {regname} argument is a string. If {regname} is "", the | |
6315 unnamed register '"' is used. If {regname} is not specified, | |
6316 |v:register| is used. | |
6317 In |Vim9-script| {regname} must be one character. | |
6318 | |
6319 Can also be used as a |method|: > | |
6320 GetRegname()->getregtype() | |
6321 | |
6322 gettabinfo([{tabnr}]) *gettabinfo()* | |
6323 If {tabnr} is not specified, then information about all the | |
6324 tab pages is returned as a |List|. Each List item is a | |
6325 |Dictionary|. Otherwise, {tabnr} specifies the tab page | |
6326 number and information about that one is returned. If the tab | |
6327 page does not exist an empty List is returned. | |
6328 | |
6329 Each List item is a |Dictionary| with the following entries: | |
6330 tabnr tab page number. | |
6331 variables a reference to the dictionary with | |
6332 tabpage-local variables | |
6333 windows List of |window-ID|s in the tab page. | |
6334 | |
6335 Can also be used as a |method|: > | |
6336 GetTabnr()->gettabinfo() | |
6337 | |
6338 gettabvar({tabnr}, {varname} [, {def}]) *gettabvar()* | |
6339 Get the value of a tab-local variable {varname} in tab page | |
6340 {tabnr}. |t:var| | |
6341 Tabs are numbered starting with one. | |
6342 The {varname} argument is a string. When {varname} is empty a | |
6343 dictionary with all tab-local variables is returned. | |
6344 Note that the name without "t:" must be used. | |
6345 When the tab or variable doesn't exist {def} or an empty | |
6346 string is returned, there is no error message. | |
6347 | |
6348 Can also be used as a |method|: > | |
6349 GetTabnr()->gettabvar(varname) | |
6350 | |
6351 gettabwinvar({tabnr}, {winnr}, {varname} [, {def}]) *gettabwinvar()* | |
6352 Get the value of window-local variable {varname} in window | |
6353 {winnr} in tab page {tabnr}. | |
6354 The {varname} argument is a string. When {varname} is empty a | |
6355 dictionary with all window-local variables is returned. | |
6356 When {varname} is equal to "&" get the values of all | |
6357 window-local options in a |Dictionary|. | |
6358 Otherwise, when {varname} starts with "&" get the value of a | |
6359 window-local option. | |
6360 Note that {varname} must be the name without "w:". | |
6361 Tabs are numbered starting with one. For the current tabpage | |
6362 use |getwinvar()|. | |
6363 {winnr} can be the window number or the |window-ID|. | |
6364 When {winnr} is zero the current window is used. | |
6365 This also works for a global option, buffer-local option and | |
6366 window-local option, but it doesn't work for a global variable | |
6367 or buffer-local variable. | |
6368 When the tab, window or variable doesn't exist {def} or an | |
6369 empty string is returned, there is no error message. | |
6370 Examples: > | |
6371 :let list_is_on = gettabwinvar(1, 2, '&list') | |
6372 :echo "myvar = " . gettabwinvar(3, 1, 'myvar') | |
6373 < | |
6374 To obtain all window-local variables use: > | |
6375 gettabwinvar({tabnr}, {winnr}, '&') | |
6376 | |
6377 < Can also be used as a |method|: > | |
6378 GetTabnr()->gettabwinvar(winnr, varname) | |
6379 | |
6380 gettagstack([{winnr}]) *gettagstack()* | |
6381 The result is a Dict, which is the tag stack of window {winnr}. | |
6382 {winnr} can be the window number or the |window-ID|. | |
6383 When {winnr} is not specified, the current window is used. | |
6384 When window {winnr} doesn't exist, an empty Dict is returned. | |
6385 | |
6386 The returned dictionary contains the following entries: | |
6387 curidx Current index in the stack. When at | |
6388 top of the stack, set to (length + 1). | |
6389 Index of bottom of the stack is 1. | |
6390 items List of items in the stack. Each item | |
6391 is a dictionary containing the | |
6392 entries described below. | |
6393 length Number of entries in the stack. | |
6394 | |
6395 Each item in the stack is a dictionary with the following | |
6396 entries: | |
6397 bufnr buffer number of the current jump | |
6398 from cursor position before the tag jump. | |
6399 See |getpos()| for the format of the | |
6400 returned list. | |
6401 matchnr current matching tag number. Used when | |
6402 multiple matching tags are found for a | |
6403 name. | |
6404 tagname name of the tag | |
6405 | |
6406 See |tagstack| for more information about the tag stack. | |
6407 | |
6408 Can also be used as a |method|: > | |
6409 GetWinnr()->gettagstack() | |
6410 | |
6411 | |
6412 gettext({text}) *gettext()* | |
6413 Translate String {text} if possible. | |
6414 This is mainly for use in the distributed Vim scripts. When | |
6415 generating message translations the {text} is extracted by | |
6416 xgettext, the translator can add the translated message in the | |
6417 .po file and Vim will lookup the translation when gettext() is | |
6418 called. | |
6419 For {text} double quoted strings are preferred, because | |
6420 xgettext does not understand escaping in single quoted | |
6421 strings. | |
6422 | |
6423 | |
6424 getwininfo([{winid}]) *getwininfo()* | |
6425 Returns information about windows as a |List| with Dictionaries. | |
6426 | |
6427 If {winid} is given Information about the window with that ID | |
6428 is returned, as a |List| with one item. If the window does not | |
6429 exist the result is an empty list. | |
6430 | |
6431 Without {winid} information about all the windows in all the | |
6432 tab pages is returned. | |
6433 | |
6434 Each List item is a |Dictionary| with the following entries: | |
6435 botline last complete displayed buffer line | |
6436 bufnr number of buffer in the window | |
6437 height window height (excluding winbar) | |
6438 loclist 1 if showing a location list | |
6439 {only with the +quickfix feature} | |
6440 quickfix 1 if quickfix or location list window | |
6441 {only with the +quickfix feature} | |
6442 terminal 1 if a terminal window | |
6443 {only with the +terminal feature} | |
6444 tabnr tab page number | |
6445 topline first displayed buffer line | |
6446 variables a reference to the dictionary with | |
6447 window-local variables | |
6448 width window width | |
6449 winbar 1 if the window has a toolbar, 0 | |
6450 otherwise | |
6451 wincol leftmost screen column of the window; | |
6452 "col" from |win_screenpos()| | |
6453 textoff number of columns occupied by any | |
6454 'foldcolumn', 'signcolumn' and line | |
6455 number in front of the text | |
6456 winid |window-ID| | |
6457 winnr window number | |
6458 winrow topmost screen line of the window; | |
6459 "row" from |win_screenpos()| | |
6460 | |
6461 Can also be used as a |method|: > | |
6462 GetWinnr()->getwininfo() | |
6463 | |
6464 getwinpos([{timeout}]) *getwinpos()* | |
6465 The result is a |List| with two numbers, the result of | |
6466 |getwinposx()| and |getwinposy()| combined: | |
6467 [x-pos, y-pos] | |
6468 {timeout} can be used to specify how long to wait in msec for | |
6469 a response from the terminal. When omitted 100 msec is used. | |
6470 Use a longer time for a remote terminal. | |
6471 When using a value less than 10 and no response is received | |
6472 within that time, a previously reported position is returned, | |
6473 if available. This can be used to poll for the position and | |
6474 do some work in the meantime: > | |
6475 while 1 | |
6476 let res = getwinpos(1) | |
6477 if res[0] >= 0 | |
6478 break | |
6479 endif | |
6480 " Do some work here | |
6481 endwhile | |
6482 < | |
6483 | |
6484 Can also be used as a |method|: > | |
6485 GetTimeout()->getwinpos() | |
6486 < | |
6487 *getwinposx()* | |
6488 getwinposx() The result is a Number, which is the X coordinate in pixels of | |
6489 the left hand side of the GUI Vim window. Also works for an | |
6490 xterm (uses a timeout of 100 msec). | |
6491 The result will be -1 if the information is not available. | |
6492 The value can be used with `:winpos`. | |
6493 | |
6494 *getwinposy()* | |
6495 getwinposy() The result is a Number, which is the Y coordinate in pixels of | |
6496 the top of the GUI Vim window. Also works for an xterm (uses | |
6497 a timeout of 100 msec). | |
6498 The result will be -1 if the information is not available. | |
6499 The value can be used with `:winpos`. | |
6500 | |
6501 getwinvar({winnr}, {varname} [, {def}]) *getwinvar()* | |
6502 Like |gettabwinvar()| for the current tabpage. | |
6503 Examples: > | |
6504 :let list_is_on = getwinvar(2, '&list') | |
6505 :echo "myvar = " . getwinvar(1, 'myvar') | |
6506 | |
6507 < Can also be used as a |method|: > | |
6508 GetWinnr()->getwinvar(varname) | |
6509 < | |
6510 glob({expr} [, {nosuf} [, {list} [, {alllinks}]]]) *glob()* | |
6511 Expand the file wildcards in {expr}. See |wildcards| for the | |
6512 use of special characters. | |
6513 | |
6514 Unless the optional {nosuf} argument is given and is |TRUE|, | |
6515 the 'suffixes' and 'wildignore' options apply: Names matching | |
6516 one of the patterns in 'wildignore' will be skipped and | |
6517 'suffixes' affect the ordering of matches. | |
6518 'wildignorecase' always applies. | |
6519 | |
6520 When {list} is present and it is |TRUE| the result is a |List| | |
6521 with all matching files. The advantage of using a List is, | |
6522 you also get filenames containing newlines correctly. | |
6523 Otherwise the result is a String and when there are several | |
6524 matches, they are separated by <NL> characters. | |
6525 | |
6526 If the expansion fails, the result is an empty String or List. | |
6527 | |
6528 You can also use |readdir()| if you need to do complicated | |
6529 things, such as limiting the number of matches. | |
6530 | |
6531 A name for a non-existing file is not included. A symbolic | |
6532 link is only included if it points to an existing file. | |
6533 However, when the {alllinks} argument is present and it is | |
6534 |TRUE| then all symbolic links are included. | |
6535 | |
6536 For most systems backticks can be used to get files names from | |
6537 any external command. Example: > | |
6538 :let tagfiles = glob("`find . -name tags -print`") | |
6539 :let &tags = substitute(tagfiles, "\n", ",", "g") | |
6540 < The result of the program inside the backticks should be one | |
6541 item per line. Spaces inside an item are allowed. | |
6542 | |
6543 See |expand()| for expanding special Vim variables. See | |
6544 |system()| for getting the raw output of an external command. | |
6545 | |
6546 Can also be used as a |method|: > | |
6547 GetExpr()->glob() | |
6548 | |
6549 glob2regpat({string}) *glob2regpat()* | |
6550 Convert a file pattern, as used by glob(), into a search | |
6551 pattern. The result can be used to match with a string that | |
6552 is a file name. E.g. > | |
6553 if filename =~ glob2regpat('Make*.mak') | |
6554 < This is equivalent to: > | |
6555 if filename =~ '^Make.*\.mak$' | |
6556 < When {string} is an empty string the result is "^$", match an | |
6557 empty string. | |
6558 Note that the result depends on the system. On MS-Windows | |
6559 a backslash usually means a path separator. | |
6560 | |
6561 Can also be used as a |method|: > | |
6562 GetExpr()->glob2regpat() | |
6563 < *globpath()* | |
6564 globpath({path}, {expr} [, {nosuf} [, {list} [, {alllinks}]]]) | |
6565 Perform glob() for String {expr} on all directories in {path} | |
6566 and concatenate the results. Example: > | |
6567 :echo globpath(&rtp, "syntax/c.vim") | |
6568 < | |
6569 {path} is a comma-separated list of directory names. Each | |
6570 directory name is prepended to {expr} and expanded like with | |
6571 |glob()|. A path separator is inserted when needed. | |
6572 To add a comma inside a directory name escape it with a | |
6573 backslash. Note that on MS-Windows a directory may have a | |
6574 trailing backslash, remove it if you put a comma after it. | |
6575 If the expansion fails for one of the directories, there is no | |
6576 error message. | |
6577 | |
6578 Unless the optional {nosuf} argument is given and is |TRUE|, | |
6579 the 'suffixes' and 'wildignore' options apply: Names matching | |
6580 one of the patterns in 'wildignore' will be skipped and | |
6581 'suffixes' affect the ordering of matches. | |
6582 | |
6583 When {list} is present and it is |TRUE| the result is a |List| | |
6584 with all matching files. The advantage of using a List is, you | |
6585 also get filenames containing newlines correctly. Otherwise | |
6586 the result is a String and when there are several matches, | |
6587 they are separated by <NL> characters. Example: > | |
6588 :echo globpath(&rtp, "syntax/c.vim", 0, 1) | |
6589 < | |
6590 {alllinks} is used as with |glob()|. | |
6591 | |
6592 The "**" item can be used to search in a directory tree. | |
6593 For example, to find all "README.txt" files in the directories | |
6594 in 'runtimepath' and below: > | |
6595 :echo globpath(&rtp, "**/README.txt") | |
6596 < Upwards search and limiting the depth of "**" is not | |
6597 supported, thus using 'path' will not always work properly. | |
6598 | |
6599 Can also be used as a |method|, the base is passed as the | |
6600 second argument: > | |
6601 GetExpr()->globpath(&rtp) | |
6602 < | |
6603 *has()* | |
6604 has({feature} [, {check}]) | |
6605 When {check} is omitted or is zero: The result is a Number, | |
6606 which is 1 if the feature {feature} is supported, zero | |
6607 otherwise. The {feature} argument is a string, case is | |
6608 ignored. See |feature-list| below. | |
6609 | |
6610 When {check} is present and not zero: The result is a Number, | |
6611 which is 1 if the feature {feature} could ever be supported, | |
6612 zero otherwise. This is useful to check for a typo in | |
6613 {feature} and to detect dead code. Keep in mind that an older | |
6614 Vim version will not know about a feature added later and | |
6615 features that have been abandoned will not be known by the | |
6616 current Vim version. | |
6617 | |
6618 Also see |exists()| and |exists_compiled()|. | |
6619 | |
6620 Note that to skip code that has a syntax error when the | |
6621 feature is not available, Vim may skip the rest of the line | |
6622 and miss a following `endif`. Therefore put the `endif` on a | |
6623 separate line: > | |
6624 if has('feature') | |
6625 let x = this->breaks->without->the->feature | |
6626 endif | |
6627 < If the `endif` would be moved to the second line as "| endif" it | |
6628 would not be found. | |
6629 | |
6630 | |
6631 has_key({dict}, {key}) *has_key()* | |
6632 The result is a Number, which is TRUE if |Dictionary| {dict} | |
6633 has an entry with key {key}. FALSE otherwise. The {key} | |
6634 argument is a string. | |
6635 | |
6636 Can also be used as a |method|: > | |
6637 mydict->has_key(key) | |
6638 | |
6639 haslocaldir([{winnr} [, {tabnr}]]) *haslocaldir()* | |
6640 The result is a Number: | |
6641 1 when the window has set a local directory via |:lcd| | |
6642 2 when the tab-page has set a local directory via |:tcd| | |
6643 0 otherwise. | |
6644 | |
6645 Without arguments use the current window. | |
6646 With {winnr} use this window in the current tab page. | |
6647 With {winnr} and {tabnr} use the window in the specified tab | |
6648 page. | |
6649 {winnr} can be the window number or the |window-ID|. | |
6650 If {winnr} is -1 it is ignored and only the tabpage is used. | |
6651 Return 0 if the arguments are invalid. | |
6652 Examples: > | |
6653 if haslocaldir() == 1 | |
6654 " window local directory case | |
6655 elseif haslocaldir() == 2 | |
6656 " tab-local directory case | |
6657 else | |
6658 " global directory case | |
6659 endif | |
6660 | |
6661 " current window | |
6662 :echo haslocaldir() | |
6663 :echo haslocaldir(0) | |
6664 :echo haslocaldir(0, 0) | |
6665 " window n in current tab page | |
6666 :echo haslocaldir(n) | |
6667 :echo haslocaldir(n, 0) | |
6668 " window n in tab page m | |
6669 :echo haslocaldir(n, m) | |
6670 " tab page m | |
6671 :echo haslocaldir(-1, m) | |
6672 < | |
6673 Can also be used as a |method|: > | |
6674 GetWinnr()->haslocaldir() | |
6675 | |
6676 hasmapto({what} [, {mode} [, {abbr}]]) *hasmapto()* | |
6677 The result is a Number, which is TRUE if there is a mapping | |
6678 that contains {what} in somewhere in the rhs (what it is | |
6679 mapped to) and this mapping exists in one of the modes | |
6680 indicated by {mode}. | |
6681 The arguments {what} and {mode} are strings. | |
6682 When {abbr} is there and it is |TRUE| use abbreviations | |
6683 instead of mappings. Don't forget to specify Insert and/or | |
6684 Command-line mode. | |
6685 Both the global mappings and the mappings local to the current | |
6686 buffer are checked for a match. | |
6687 If no matching mapping is found FALSE is returned. | |
6688 The following characters are recognized in {mode}: | |
6689 n Normal mode | |
6690 v Visual and Select mode | |
6691 x Visual mode | |
6692 s Select mode | |
6693 o Operator-pending mode | |
6694 i Insert mode | |
6695 l Language-Argument ("r", "f", "t", etc.) | |
6696 c Command-line mode | |
6697 When {mode} is omitted, "nvo" is used. | |
6698 | |
6699 This function is useful to check if a mapping already exists | |
6700 to a function in a Vim script. Example: > | |
6701 :if !hasmapto('\ABCdoit') | |
6702 : map <Leader>d \ABCdoit | |
6703 :endif | |
6704 < This installs the mapping to "\ABCdoit" only if there isn't | |
6705 already a mapping to "\ABCdoit". | |
6706 | |
6707 Can also be used as a |method|: > | |
6708 GetRHS()->hasmapto() | |
6709 | |
6710 histadd({history}, {item}) *histadd()* | |
6711 Add the String {item} to the history {history} which can be | |
6712 one of: *hist-names* | |
6713 "cmd" or ":" command line history | |
6714 "search" or "/" search pattern history | |
6715 "expr" or "=" typed expression history | |
6716 "input" or "@" input line history | |
6717 "debug" or ">" debug command history | |
6718 empty the current or last used history | |
6719 The {history} string does not need to be the whole name, one | |
6720 character is sufficient. | |
6721 If {item} does already exist in the history, it will be | |
6722 shifted to become the newest entry. | |
6723 The result is a Number: TRUE if the operation was successful, | |
6724 otherwise FALSE is returned. | |
6725 | |
6726 Example: > | |
6727 :call histadd("input", strftime("%Y %b %d")) | |
6728 :let date=input("Enter date: ") | |
6729 < This function is not available in the |sandbox|. | |
6730 | |
6731 Can also be used as a |method|, the base is passed as the | |
6732 second argument: > | |
6733 GetHistory()->histadd('search') | |
6734 | |
6735 histdel({history} [, {item}]) *histdel()* | |
6736 Clear {history}, i.e. delete all its entries. See |hist-names| | |
6737 for the possible values of {history}. | |
6738 | |
6739 If the parameter {item} evaluates to a String, it is used as a | |
6740 regular expression. All entries matching that expression will | |
6741 be removed from the history (if there are any). | |
6742 Upper/lowercase must match, unless "\c" is used |/\c|. | |
6743 If {item} evaluates to a Number, it will be interpreted as | |
6744 an index, see |:history-indexing|. The respective entry will | |
6745 be removed if it exists. | |
6746 | |
6747 The result is TRUE for a successful operation, otherwise FALSE | |
6748 is returned. | |
6749 | |
6750 Examples: | |
6751 Clear expression register history: > | |
6752 :call histdel("expr") | |
6753 < | |
6754 Remove all entries starting with "*" from the search history: > | |
6755 :call histdel("/", '^\*') | |
6756 < | |
6757 The following three are equivalent: > | |
6758 :call histdel("search", histnr("search")) | |
6759 :call histdel("search", -1) | |
6760 :call histdel("search", '^'.histget("search", -1).'$') | |
6761 < | |
6762 To delete the last search pattern and use the last-but-one for | |
6763 the "n" command and 'hlsearch': > | |
6764 :call histdel("search", -1) | |
6765 :let @/ = histget("search", -1) | |
6766 < | |
6767 Can also be used as a |method|: > | |
6768 GetHistory()->histdel() | |
6769 | |
6770 histget({history} [, {index}]) *histget()* | |
6771 The result is a String, the entry with Number {index} from | |
6772 {history}. See |hist-names| for the possible values of | |
6773 {history}, and |:history-indexing| for {index}. If there is | |
6774 no such entry, an empty String is returned. When {index} is | |
6775 omitted, the most recent item from the history is used. | |
6776 | |
6777 Examples: | |
6778 Redo the second last search from history. > | |
6779 :execute '/' . histget("search", -2) | |
6780 | |
6781 < Define an Ex command ":H {num}" that supports re-execution of | |
6782 the {num}th entry from the output of |:history|. > | |
6783 :command -nargs=1 H execute histget("cmd", 0+<args>) | |
6784 < | |
6785 Can also be used as a |method|: > | |
6786 GetHistory()->histget() | |
6787 | |
6788 histnr({history}) *histnr()* | |
6789 The result is the Number of the current entry in {history}. | |
6790 See |hist-names| for the possible values of {history}. | |
6791 If an error occurred, -1 is returned. | |
6792 | |
6793 Example: > | |
6794 :let inp_index = histnr("expr") | |
6795 | |
6796 < Can also be used as a |method|: > | |
6797 GetHistory()->histnr() | |
6798 < | |
6799 hlexists({name}) *hlexists()* | |
6800 The result is a Number, which is TRUE if a highlight group | |
6801 called {name} exists. This is when the group has been | |
6802 defined in some way. Not necessarily when highlighting has | |
6803 been defined for it, it may also have been used for a syntax | |
6804 item. | |
6805 *highlight_exists()* | |
6806 Obsolete name: highlight_exists(). | |
6807 | |
6808 Can also be used as a |method|: > | |
6809 GetName()->hlexists() | |
6810 < | |
6811 hlget([{name} [, {resolve}]]) *hlget()* | |
6812 Returns a List of all the highlight group attributes. If the | |
6813 optional {name} is specified, then returns a List with only | |
6814 the attributes of the specified highlight group. Returns an | |
6815 empty List if the highlight group {name} is not present. | |
6816 | |
6817 If the optional {resolve} argument is set to v:true and the | |
6818 highlight group {name} is linked to another group, then the | |
6819 link is resolved recursively and the attributes of the | |
6820 resolved highlight group are returned. | |
6821 | |
6822 Each entry in the returned List is a Dictionary with the | |
6823 following items: | |
6824 cleared boolean flag, set to v:true if the highlight | |
6825 group attributes are cleared or not yet | |
6826 specified. See |highlight-clear|. | |
6827 cterm cterm attributes. See |highlight-cterm|. | |
6828 ctermbg cterm background color. | |
6829 See |highlight-ctermbg|. | |
6830 ctermfg cterm foreground color. | |
6831 See |highlight-ctermfg|. | |
6832 ctermul cterm underline color. See |highlight-ctermul|. | |
6833 default boolean flag, set to v:true if the highlight | |
6834 group link is a default link. See | |
6835 |highlight-default|. | |
6836 font highlight group font. See |highlight-font|. | |
6837 gui gui attributes. See |highlight-gui|. | |
6838 guibg gui background color. See |highlight-guibg|. | |
6839 guifg gui foreground color. See |highlight-guifg|. | |
6840 guisp gui special color. See |highlight-guisp|. | |
6841 id highlight group ID. | |
6842 linksto linked highlight group name. | |
6843 See |:highlight-link|. | |
6844 name highlight group name. See |group-name|. | |
6845 start start terminal keycode. See |highlight-start|. | |
6846 stop stop terminal keycode. See |highlight-stop|. | |
6847 term term attributes. See |highlight-term|. | |
6848 | |
6849 The 'term', 'cterm' and 'gui' items in the above Dictionary | |
6850 have a dictionary value with the following optional boolean | |
6851 items: 'bold', 'standout', 'underline', 'undercurl', 'italic', | |
6852 'reverse', 'inverse' and 'strikethrough'. | |
6853 | |
6854 Example(s): > | |
6855 :echo hlget() | |
6856 :echo hlget('ModeMsg') | |
6857 :echo hlget('Number', v:true) | |
6858 < | |
6859 Can also be used as a |method|: > | |
6860 GetName()->hlget() | |
6861 < | |
6862 hlset({list}) *hlset()* | |
6863 Creates or modifies the attributes of a List of highlight | |
6864 groups. Each item in {list} is a dictionary containing the | |
6865 attributes of a highlight group. See |hlget()| for the list of | |
6866 supported items in this dictionary. | |
6867 | |
6868 In addition to the items described in |hlget()|, the following | |
6869 additional items are supported in the dictionary: | |
6870 | |
6871 force boolean flag to force the creation of | |
6872 a link for an existing highlight group | |
6873 with attributes. | |
6874 | |
6875 The highlight group is identified using the 'name' item and | |
6876 the 'id' item (if supplied) is ignored. If a highlight group | |
6877 with a specified name doesn't exist, then it is created. | |
6878 Otherwise the attributes of an existing highlight group are | |
6879 modified. | |
6880 | |
6881 If an empty dictionary value is used for the 'term' or 'cterm' | |
6882 or 'gui' entries, then the corresponding attributes are | |
6883 cleared. If the 'cleared' item is set to v:true, then all the | |
6884 attributes of the highlight group are cleared. | |
6885 | |
6886 The 'linksto' item can be used to link a highlight group to | |
6887 another highlight group. See |:highlight-link|. | |
6888 | |
6889 Returns zero for success, -1 for failure. | |
6890 | |
6891 Example(s): > | |
6892 " add bold attribute to the Visual highlight group | |
6893 :call hlset([#{name: 'Visual', | |
6894 \ term: #{reverse: 1 , bold: 1}}]) | |
6895 :call hlset([#{name: 'Type', guifg: 'DarkGreen'}]) | |
6896 :let l = hlget() | |
6897 :call hlset(l) | |
6898 " clear the Search highlight group | |
6899 :call hlset([#{name: 'Search', cleared: v:true}]) | |
6900 " clear the 'term' attributes for a highlight group | |
6901 :call hlset([#{name: 'Title', term: {}}]) | |
6902 " create the MyHlg group linking it to DiffAdd | |
6903 :call hlset([#{name: 'MyHlg', linksto: 'DiffAdd'}]) | |
6904 " remove the MyHlg group link | |
6905 :call hlset([#{name: 'MyHlg', linksto: 'NONE'}]) | |
6906 " clear the attributes and a link | |
6907 :call hlset([#{name: 'MyHlg', cleared: v:true, | |
6908 \ linksto: 'NONE'}]) | |
6909 < | |
6910 Can also be used as a |method|: > | |
6911 GetAttrList()->hlset() | |
6912 < | |
6913 *hlID()* | |
6914 hlID({name}) The result is a Number, which is the ID of the highlight group | |
6915 with name {name}. When the highlight group doesn't exist, | |
6916 zero is returned. | |
6917 This can be used to retrieve information about the highlight | |
6918 group. For example, to get the background color of the | |
6919 "Comment" group: > | |
6920 :echo synIDattr(synIDtrans(hlID("Comment")), "bg") | |
6921 < *highlightID()* | |
6922 Obsolete name: highlightID(). | |
6923 | |
6924 Can also be used as a |method|: > | |
6925 GetName()->hlID() | |
6926 | |
6927 hostname() *hostname()* | |
6928 The result is a String, which is the name of the machine on | |
6929 which Vim is currently running. Machine names greater than | |
6930 256 characters long are truncated. | |
6931 | |
6932 iconv({string}, {from}, {to}) *iconv()* | |
6933 The result is a String, which is the text {string} converted | |
6934 from encoding {from} to encoding {to}. | |
6935 When the conversion completely fails an empty string is | |
6936 returned. When some characters could not be converted they | |
6937 are replaced with "?". | |
6938 The encoding names are whatever the iconv() library function | |
6939 can accept, see ":!man 3 iconv". | |
6940 Most conversions require Vim to be compiled with the |+iconv| | |
6941 feature. Otherwise only UTF-8 to latin1 conversion and back | |
6942 can be done. | |
6943 This can be used to display messages with special characters, | |
6944 no matter what 'encoding' is set to. Write the message in | |
6945 UTF-8 and use: > | |
6946 echo iconv(utf8_str, "utf-8", &enc) | |
6947 < Note that Vim uses UTF-8 for all Unicode encodings, conversion | |
6948 from/to UCS-2 is automatically changed to use UTF-8. You | |
6949 cannot use UCS-2 in a string anyway, because of the NUL bytes. | |
6950 | |
6951 Can also be used as a |method|: > | |
6952 GetText()->iconv('latin1', 'utf-8') | |
6953 < | |
6954 *indent()* | |
6955 indent({lnum}) The result is a Number, which is indent of line {lnum} in the | |
6956 current buffer. The indent is counted in spaces, the value | |
6957 of 'tabstop' is relevant. {lnum} is used just like in | |
6958 |getline()|. | |
6959 When {lnum} is invalid -1 is returned. | |
6960 | |
6961 Can also be used as a |method|: > | |
6962 GetLnum()->indent() | |
6963 | |
6964 index({object}, {expr} [, {start} [, {ic}]]) *index()* | |
6965 If {object} is a |List| return the lowest index where the item | |
6966 has a value equal to {expr}. There is no automatic | |
6967 conversion, so the String "4" is different from the Number 4. | |
6968 And the number 4 is different from the Float 4.0. The value | |
6969 of 'ignorecase' is not used here, case always matters. | |
6970 | |
6971 If {object} is |Blob| return the lowest index where the byte | |
6972 value is equal to {expr}. | |
6973 | |
6974 If {start} is given then start looking at the item with index | |
6975 {start} (may be negative for an item relative to the end). | |
6976 When {ic} is given and it is |TRUE|, ignore case. Otherwise | |
6977 case must match. | |
6978 -1 is returned when {expr} is not found in {object}. | |
6979 Example: > | |
6980 :let idx = index(words, "the") | |
6981 :if index(numbers, 123) >= 0 | |
6982 | |
6983 < Can also be used as a |method|: > | |
6984 GetObject()->index(what) | |
6985 | |
6986 input({prompt} [, {text} [, {completion}]]) *input()* | |
6987 The result is a String, which is whatever the user typed on | |
6988 the command-line. The {prompt} argument is either a prompt | |
6989 string, or a blank string (for no prompt). A '\n' can be used | |
6990 in the prompt to start a new line. | |
6991 The highlighting set with |:echohl| is used for the prompt. | |
6992 The input is entered just like a command-line, with the same | |
6993 editing commands and mappings. There is a separate history | |
6994 for lines typed for input(). | |
6995 Example: > | |
6996 :if input("Coffee or beer? ") == "beer" | |
6997 : echo "Cheers!" | |
6998 :endif | |
6999 < | |
7000 If the optional {text} argument is present and not empty, this | |
7001 is used for the default reply, as if the user typed this. | |
7002 Example: > | |
7003 :let color = input("Color? ", "white") | |
7004 | |
7005 < The optional {completion} argument specifies the type of | |
7006 completion supported for the input. Without it completion is | |
7007 not performed. The supported completion types are the same as | |
7008 that can be supplied to a user-defined command using the | |
7009 "-complete=" argument. Refer to |:command-completion| for | |
7010 more information. Example: > | |
7011 let fname = input("File: ", "", "file") | |
7012 < | |
7013 NOTE: This function must not be used in a startup file, for | |
7014 the versions that only run in GUI mode (e.g., the Win32 GUI). | |
7015 Note: When input() is called from within a mapping it will | |
7016 consume remaining characters from that mapping, because a | |
7017 mapping is handled like the characters were typed. | |
7018 Use |inputsave()| before input() and |inputrestore()| | |
7019 after input() to avoid that. Another solution is to avoid | |
7020 that further characters follow in the mapping, e.g., by using | |
7021 |:execute| or |:normal|. | |
7022 | |
7023 Example with a mapping: > | |
7024 :nmap \x :call GetFoo()<CR>:exe "/" . Foo<CR> | |
7025 :function GetFoo() | |
7026 : call inputsave() | |
7027 : let g:Foo = input("enter search pattern: ") | |
7028 : call inputrestore() | |
7029 :endfunction | |
7030 | |
7031 < Can also be used as a |method|: > | |
7032 GetPrompt()->input() | |
7033 | |
7034 inputdialog({prompt} [, {text} [, {cancelreturn}]]) *inputdialog()* | |
7035 Like |input()|, but when the GUI is running and text dialogs | |
7036 are supported, a dialog window pops up to input the text. | |
7037 Example: > | |
7038 :let n = inputdialog("value for shiftwidth", shiftwidth()) | |
7039 :if n != "" | |
7040 : let &sw = n | |
7041 :endif | |
7042 < When the dialog is cancelled {cancelreturn} is returned. When | |
7043 omitted an empty string is returned. | |
7044 Hitting <Enter> works like pressing the OK button. Hitting | |
7045 <Esc> works like pressing the Cancel button. | |
7046 NOTE: Command-line completion is not supported. | |
7047 | |
7048 Can also be used as a |method|: > | |
7049 GetPrompt()->inputdialog() | |
7050 | |
7051 inputlist({textlist}) *inputlist()* | |
7052 {textlist} must be a |List| of strings. This |List| is | |
7053 displayed, one string per line. The user will be prompted to | |
7054 enter a number, which is returned. | |
7055 The user can also select an item by clicking on it with the | |
7056 mouse, if the mouse is enabled in the command line ('mouse' is | |
7057 "a" or includes "c"). For the first string 0 is returned. | |
7058 When clicking above the first item a negative number is | |
7059 returned. When clicking on the prompt one more than the | |
7060 length of {textlist} is returned. | |
7061 Make sure {textlist} has less than 'lines' entries, otherwise | |
7062 it won't work. It's a good idea to put the entry number at | |
7063 the start of the string. And put a prompt in the first item. | |
7064 Example: > | |
7065 let color = inputlist(['Select color:', '1. red', | |
7066 \ '2. green', '3. blue']) | |
7067 | |
7068 < Can also be used as a |method|: > | |
7069 GetChoices()->inputlist() | |
7070 | |
7071 inputrestore() *inputrestore()* | |
7072 Restore typeahead that was saved with a previous |inputsave()|. | |
7073 Should be called the same number of times inputsave() is | |
7074 called. Calling it more often is harmless though. | |
7075 Returns TRUE when there is nothing to restore, FALSE otherwise. | |
7076 | |
7077 inputsave() *inputsave()* | |
7078 Preserve typeahead (also from mappings) and clear it, so that | |
7079 a following prompt gets input from the user. Should be | |
7080 followed by a matching inputrestore() after the prompt. Can | |
7081 be used several times, in which case there must be just as | |
7082 many inputrestore() calls. | |
7083 Returns TRUE when out of memory, FALSE otherwise. | |
7084 | |
7085 inputsecret({prompt} [, {text}]) *inputsecret()* | |
7086 This function acts much like the |input()| function with but | |
7087 two exceptions: | |
7088 a) the user's response will be displayed as a sequence of | |
7089 asterisks ("*") thereby keeping the entry secret, and | |
7090 b) the user's response will not be recorded on the input | |
7091 |history| stack. | |
7092 The result is a String, which is whatever the user actually | |
7093 typed on the command-line in response to the issued prompt. | |
7094 NOTE: Command-line completion is not supported. | |
7095 | |
7096 Can also be used as a |method|: > | |
7097 GetPrompt()->inputsecret() | |
7098 | |
7099 insert({object}, {item} [, {idx}]) *insert()* | |
7100 When {object} is a |List| or a |Blob| insert {item} at the start | |
7101 of it. | |
7102 | |
7103 If {idx} is specified insert {item} before the item with index | |
7104 {idx}. If {idx} is zero it goes before the first item, just | |
7105 like omitting {idx}. A negative {idx} is also possible, see | |
7106 |list-index|. -1 inserts just before the last item. | |
7107 | |
7108 Returns the resulting |List| or |Blob|. Examples: > | |
7109 :let mylist = insert([2, 3, 5], 1) | |
7110 :call insert(mylist, 4, -1) | |
7111 :call insert(mylist, 6, len(mylist)) | |
7112 < The last example can be done simpler with |add()|. | |
7113 Note that when {item} is a |List| it is inserted as a single | |
7114 item. Use |extend()| to concatenate |Lists|. | |
7115 | |
7116 Can also be used as a |method|: > | |
7117 mylist->insert(item) | |
7118 | |
7119 interrupt() *interrupt()* | |
7120 Interrupt script execution. It works more or less like the | |
7121 user typing CTRL-C, most commands won't execute and control | |
7122 returns to the user. This is useful to abort execution | |
7123 from lower down, e.g. in an autocommand. Example: > | |
7124 :function s:check_typoname(file) | |
7125 : if fnamemodify(a:file, ':t') == '[' | |
7126 : echomsg 'Maybe typo' | |
7127 : call interrupt() | |
7128 : endif | |
7129 :endfunction | |
7130 :au BufWritePre * call s:check_typoname(expand('<amatch>')) | |
7131 | |
7132 invert({expr}) *invert()* | |
7133 Bitwise invert. The argument is converted to a number. A | |
7134 List, Dict or Float argument causes an error. Example: > | |
7135 :let bits = invert(bits) | |
7136 < Can also be used as a |method|: > | |
7137 :let bits = bits->invert() | |
7138 | |
7139 isdirectory({directory}) *isdirectory()* | |
7140 The result is a Number, which is |TRUE| when a directory | |
7141 with the name {directory} exists. If {directory} doesn't | |
7142 exist, or isn't a directory, the result is |FALSE|. {directory} | |
7143 is any expression, which is used as a String. | |
7144 | |
7145 Can also be used as a |method|: > | |
7146 GetName()->isdirectory() | |
7147 | |
7148 isinf({expr}) *isinf()* | |
7149 Return 1 if {expr} is a positive infinity, or -1 a negative | |
7150 infinity, otherwise 0. > | |
7151 :echo isinf(1.0 / 0.0) | |
7152 < 1 > | |
7153 :echo isinf(-1.0 / 0.0) | |
7154 < -1 | |
7155 | |
7156 Can also be used as a |method|: > | |
7157 Compute()->isinf() | |
7158 < | |
7159 {only available when compiled with the |+float| feature} | |
7160 | |
7161 islocked({expr}) *islocked()* *E786* | |
7162 The result is a Number, which is |TRUE| when {expr} is the | |
7163 name of a locked variable. | |
7164 The string argument {expr} must be the name of a variable, | |
7165 |List| item or |Dictionary| entry, not the variable itself! | |
7166 Example: > | |
7167 :let alist = [0, ['a', 'b'], 2, 3] | |
7168 :lockvar 1 alist | |
7169 :echo islocked('alist') " 1 | |
7170 :echo islocked('alist[1]') " 0 | |
7171 | |
7172 < When {expr} is a variable that does not exist you get an error | |
7173 message. Use |exists()| to check for existence. | |
7174 In Vim9 script it does not work for local variables. | |
7175 | |
7176 Can also be used as a |method|: > | |
7177 GetName()->islocked() | |
7178 | |
7179 isnan({expr}) *isnan()* | |
7180 Return |TRUE| if {expr} is a float with value NaN. > | |
7181 echo isnan(0.0 / 0.0) | |
7182 < 1 | |
7183 | |
7184 Can also be used as a |method|: > | |
7185 Compute()->isnan() | |
7186 < | |
7187 {only available when compiled with the |+float| feature} | |
7188 | |
7189 items({dict}) *items()* | |
7190 Return a |List| with all the key-value pairs of {dict}. Each | |
7191 |List| item is a list with two items: the key of a {dict} | |
7192 entry and the value of this entry. The |List| is in arbitrary | |
7193 order. Also see |keys()| and |values()|. | |
7194 Example: > | |
7195 for [key, value] in items(mydict) | |
7196 echo key . ': ' . value | |
7197 endfor | |
7198 | |
7199 < Can also be used as a |method|: > | |
7200 mydict->items() | |
7201 | |
7202 job_ functions are documented here: |job-functions-details| | |
7203 | |
7204 | |
7205 join({list} [, {sep}]) *join()* | |
7206 Join the items in {list} together into one String. | |
7207 When {sep} is specified it is put in between the items. If | |
7208 {sep} is omitted a single space is used. | |
7209 Note that {sep} is not added at the end. You might want to | |
7210 add it there too: > | |
7211 let lines = join(mylist, "\n") . "\n" | |
7212 < String items are used as-is. |Lists| and |Dictionaries| are | |
7213 converted into a string like with |string()|. | |
7214 The opposite function is |split()|. | |
7215 | |
7216 Can also be used as a |method|: > | |
7217 mylist->join() | |
7218 | |
7219 js_decode({string}) *js_decode()* | |
7220 This is similar to |json_decode()| with these differences: | |
7221 - Object key names do not have to be in quotes. | |
7222 - Strings can be in single quotes. | |
7223 - Empty items in an array (between two commas) are allowed and | |
7224 result in v:none items. | |
7225 | |
7226 Can also be used as a |method|: > | |
7227 ReadObject()->js_decode() | |
7228 | |
7229 js_encode({expr}) *js_encode()* | |
7230 This is similar to |json_encode()| with these differences: | |
7231 - Object key names are not in quotes. | |
7232 - v:none items in an array result in an empty item between | |
7233 commas. | |
7234 For example, the Vim object: | |
7235 [1,v:none,{"one":1},v:none] ~ | |
7236 Will be encoded as: | |
7237 [1,,{one:1},,] ~ | |
7238 While json_encode() would produce: | |
7239 [1,null,{"one":1},null] ~ | |
7240 This encoding is valid for JavaScript. It is more efficient | |
7241 than JSON, especially when using an array with optional items. | |
7242 | |
7243 Can also be used as a |method|: > | |
7244 GetObject()->js_encode() | |
7245 | |
7246 json_decode({string}) *json_decode()* | |
7247 This parses a JSON formatted string and returns the equivalent | |
7248 in Vim values. See |json_encode()| for the relation between | |
7249 JSON and Vim values. | |
7250 The decoding is permissive: | |
7251 - A trailing comma in an array and object is ignored, e.g. | |
7252 "[1, 2, ]" is the same as "[1, 2]". | |
7253 - Integer keys are accepted in objects, e.g. {1:2} is the | |
7254 same as {"1":2}. | |
7255 - More floating point numbers are recognized, e.g. "1." for | |
7256 "1.0", or "001.2" for "1.2". Special floating point values | |
7257 "Infinity", "-Infinity" and "NaN" (capitalization ignored) | |
7258 are accepted. | |
7259 - Leading zeroes in integer numbers are ignored, e.g. "012" | |
7260 for "12" or "-012" for "-12". | |
7261 - Capitalization is ignored in literal names null, true or | |
7262 false, e.g. "NULL" for "null", "True" for "true". | |
7263 - Control characters U+0000 through U+001F which are not | |
7264 escaped in strings are accepted, e.g. " " (tab | |
7265 character in string) for "\t". | |
7266 - An empty JSON expression or made of only spaces is accepted | |
7267 and results in v:none. | |
7268 - Backslash in an invalid 2-character sequence escape is | |
7269 ignored, e.g. "\a" is decoded as "a". | |
7270 - A correct surrogate pair in JSON strings should normally be | |
7271 a 12 character sequence such as "\uD834\uDD1E", but | |
7272 json_decode() silently accepts truncated surrogate pairs | |
7273 such as "\uD834" or "\uD834\u" | |
7274 *E938* | |
7275 A duplicate key in an object, valid in rfc7159, is not | |
7276 accepted by json_decode() as the result must be a valid Vim | |
7277 type, e.g. this fails: {"a":"b", "a":"c"} | |
7278 | |
7279 Can also be used as a |method|: > | |
7280 ReadObject()->json_decode() | |
7281 | |
7282 json_encode({expr}) *json_encode()* | |
7283 Encode {expr} as JSON and return this as a string. | |
7284 The encoding is specified in: | |
7285 https://tools.ietf.org/html/rfc7159.html | |
7286 Vim values are converted as follows: | |
7287 |Number| decimal number | |
7288 |Float| floating point number | |
7289 Float nan "NaN" | |
7290 Float inf "Infinity" | |
7291 Float -inf "-Infinity" | |
7292 |String| in double quotes (possibly null) | |
7293 |Funcref| not possible, error | |
7294 |List| as an array (possibly null); when | |
7295 used recursively: [] | |
7296 |Dict| as an object (possibly null); when | |
7297 used recursively: {} | |
7298 |Blob| as an array of the individual bytes | |
7299 v:false "false" | |
7300 v:true "true" | |
7301 v:none "null" | |
7302 v:null "null" | |
7303 Note that NaN and Infinity are passed on as values. This is | |
7304 missing in the JSON standard, but several implementations do | |
7305 allow it. If not then you will get an error. | |
7306 | |
7307 Can also be used as a |method|: > | |
7308 GetObject()->json_encode() | |
7309 | |
7310 keys({dict}) *keys()* | |
7311 Return a |List| with all the keys of {dict}. The |List| is in | |
7312 arbitrary order. Also see |items()| and |values()|. | |
7313 | |
7314 Can also be used as a |method|: > | |
7315 mydict->keys() | |
7316 | |
7317 < *len()* *E701* | |
7318 len({expr}) The result is a Number, which is the length of the argument. | |
7319 When {expr} is a String or a Number the length in bytes is | |
7320 used, as with |strlen()|. | |
7321 When {expr} is a |List| the number of items in the |List| is | |
7322 returned. | |
7323 When {expr} is a |Blob| the number of bytes is returned. | |
7324 When {expr} is a |Dictionary| the number of entries in the | |
7325 |Dictionary| is returned. | |
7326 Otherwise an error is given. | |
7327 | |
7328 Can also be used as a |method|: > | |
7329 mylist->len() | |
7330 | |
7331 < *libcall()* *E364* *E368* | |
7332 libcall({libname}, {funcname}, {argument}) | |
7333 Call function {funcname} in the run-time library {libname} | |
7334 with single argument {argument}. | |
7335 This is useful to call functions in a library that you | |
7336 especially made to be used with Vim. Since only one argument | |
7337 is possible, calling standard library functions is rather | |
7338 limited. | |
7339 The result is the String returned by the function. If the | |
7340 function returns NULL, this will appear as an empty string "" | |
7341 to Vim. | |
7342 If the function returns a number, use libcallnr()! | |
7343 If {argument} is a number, it is passed to the function as an | |
7344 int; if {argument} is a string, it is passed as a | |
7345 null-terminated string. | |
7346 This function will fail in |restricted-mode|. | |
7347 | |
7348 libcall() allows you to write your own 'plug-in' extensions to | |
7349 Vim without having to recompile the program. It is NOT a | |
7350 means to call system functions! If you try to do so Vim will | |
7351 very probably crash. | |
7352 | |
7353 For Win32, the functions you write must be placed in a DLL | |
7354 and use the normal C calling convention (NOT Pascal which is | |
7355 used in Windows System DLLs). The function must take exactly | |
7356 one parameter, either a character pointer or a long integer, | |
7357 and must return a character pointer or NULL. The character | |
7358 pointer returned must point to memory that will remain valid | |
7359 after the function has returned (e.g. in static data in the | |
7360 DLL). If it points to allocated memory, that memory will | |
7361 leak away. Using a static buffer in the function should work, | |
7362 it's then freed when the DLL is unloaded. | |
7363 | |
7364 WARNING: If the function returns a non-valid pointer, Vim may | |
7365 crash! This also happens if the function returns a number, | |
7366 because Vim thinks it's a pointer. | |
7367 For Win32 systems, {libname} should be the filename of the DLL | |
7368 without the ".DLL" suffix. A full path is only required if | |
7369 the DLL is not in the usual places. | |
7370 For Unix: When compiling your own plugins, remember that the | |
7371 object code must be compiled as position-independent ('PIC'). | |
7372 {only in Win32 and some Unix versions, when the |+libcall| | |
7373 feature is present} | |
7374 Examples: > | |
7375 :echo libcall("libc.so", "getenv", "HOME") | |
7376 | |
7377 < Can also be used as a |method|, the base is passed as the | |
7378 third argument: > | |
7379 GetValue()->libcall("libc.so", "getenv") | |
7380 < | |
7381 *libcallnr()* | |
7382 libcallnr({libname}, {funcname}, {argument}) | |
7383 Just like |libcall()|, but used for a function that returns an | |
7384 int instead of a string. | |
7385 {only in Win32 on some Unix versions, when the |+libcall| | |
7386 feature is present} | |
7387 Examples: > | |
7388 :echo libcallnr("/usr/lib/libc.so", "getpid", "") | |
7389 :call libcallnr("libc.so", "printf", "Hello World!\n") | |
7390 :call libcallnr("libc.so", "sleep", 10) | |
7391 < | |
7392 Can also be used as a |method|, the base is passed as the | |
7393 third argument: > | |
7394 GetValue()->libcallnr("libc.so", "printf") | |
7395 < | |
7396 | |
7397 line({expr} [, {winid}]) *line()* | |
7398 The result is a Number, which is the line number of the file | |
7399 position given with {expr}. The {expr} argument is a string. | |
7400 The accepted positions are: | |
7401 . the cursor position | |
7402 $ the last line in the current buffer | |
7403 'x position of mark x (if the mark is not set, 0 is | |
7404 returned) | |
7405 w0 first line visible in current window (one if the | |
7406 display isn't updated, e.g. in silent Ex mode) | |
7407 w$ last line visible in current window (this is one | |
7408 less than "w0" if no lines are visible) | |
7409 v In Visual mode: the start of the Visual area (the | |
7410 cursor is the end). When not in Visual mode | |
7411 returns the cursor position. Differs from |'<| in | |
7412 that it's updated right away. | |
7413 Note that a mark in another file can be used. The line number | |
7414 then applies to another buffer. | |
7415 To get the column number use |col()|. To get both use | |
7416 |getpos()|. | |
7417 With the optional {winid} argument the values are obtained for | |
7418 that window instead of the current window. | |
7419 Examples: > | |
7420 line(".") line number of the cursor | |
7421 line(".", winid) idem, in window "winid" | |
7422 line("'t") line number of mark t | |
7423 line("'" . marker) line number of mark marker | |
7424 < | |
7425 To jump to the last known position when opening a file see | |
7426 |last-position-jump|. | |
7427 | |
7428 Can also be used as a |method|: > | |
7429 GetValue()->line() | |
7430 | |
7431 line2byte({lnum}) *line2byte()* | |
7432 Return the byte count from the start of the buffer for line | |
7433 {lnum}. This includes the end-of-line character, depending on | |
7434 the 'fileformat' option for the current buffer. The first | |
7435 line returns 1. 'encoding' matters, 'fileencoding' is ignored. | |
7436 This can also be used to get the byte count for the line just | |
7437 below the last line: > | |
7438 line2byte(line("$") + 1) | |
7439 < This is the buffer size plus one. If 'fileencoding' is empty | |
7440 it is the file size plus one. {lnum} is used like with | |
7441 |getline()|. When {lnum} is invalid, or the |+byte_offset| | |
7442 feature has been disabled at compile time, -1 is returned. | |
7443 Also see |byte2line()|, |go| and |:goto|. | |
7444 | |
7445 Can also be used as a |method|: > | |
7446 GetLnum()->line2byte() | |
7447 | |
7448 lispindent({lnum}) *lispindent()* | |
7449 Get the amount of indent for line {lnum} according the lisp | |
7450 indenting rules, as with 'lisp'. | |
7451 The indent is counted in spaces, the value of 'tabstop' is | |
7452 relevant. {lnum} is used just like in |getline()|. | |
7453 When {lnum} is invalid or Vim was not compiled the | |
7454 |+lispindent| feature, -1 is returned. | |
7455 | |
7456 Can also be used as a |method|: > | |
7457 GetLnum()->lispindent() | |
7458 | |
7459 list2blob({list}) *list2blob()* | |
7460 Return a Blob concatenating all the number values in {list}. | |
7461 Examples: > | |
7462 list2blob([1, 2, 3, 4]) returns 0z01020304 | |
7463 list2blob([]) returns 0z | |
7464 < Returns an empty Blob on error. If one of the numbers is | |
7465 negative or more than 255 error *E1239* is given. | |
7466 | |
7467 |blob2list()| does the opposite. | |
7468 | |
7469 Can also be used as a |method|: > | |
7470 GetList()->list2blob() | |
7471 | |
7472 list2str({list} [, {utf8}]) *list2str()* | |
7473 Convert each number in {list} to a character string can | |
7474 concatenate them all. Examples: > | |
7475 list2str([32]) returns " " | |
7476 list2str([65, 66, 67]) returns "ABC" | |
7477 < The same can be done (slowly) with: > | |
7478 join(map(list, {nr, val -> nr2char(val)}), '') | |
7479 < |str2list()| does the opposite. | |
7480 | |
7481 When {utf8} is omitted or zero, the current 'encoding' is used. | |
7482 When {utf8} is TRUE, always return UTF-8 characters. | |
7483 With UTF-8 composing characters work as expected: > | |
7484 list2str([97, 769]) returns "á" | |
7485 < | |
7486 Can also be used as a |method|: > | |
7487 GetList()->list2str() | |
7488 | |
7489 listener_add({callback} [, {buf}]) *listener_add()* | |
7490 Add a callback function that will be invoked when changes have | |
7491 been made to buffer {buf}. | |
7492 {buf} refers to a buffer name or number. For the accepted | |
7493 values, see |bufname()|. When {buf} is omitted the current | |
7494 buffer is used. | |
7495 Returns a unique ID that can be passed to |listener_remove()|. | |
7496 | |
7497 The {callback} is invoked with five arguments: | |
7498 a:bufnr the buffer that was changed | |
7499 a:start first changed line number | |
7500 a:end first line number below the change | |
7501 a:added number of lines added, negative if lines were | |
7502 deleted | |
7503 a:changes a List of items with details about the changes | |
7504 | |
7505 Example: > | |
7506 func Listener(bufnr, start, end, added, changes) | |
7507 echo 'lines ' .. a:start .. ' until ' .. a:end .. ' changed' | |
7508 endfunc | |
7509 call listener_add('Listener', bufnr) | |
7510 | |
7511 < The List cannot be changed. Each item in a:changes is a | |
7512 dictionary with these entries: | |
7513 lnum the first line number of the change | |
7514 end the first line below the change | |
7515 added number of lines added; negative if lines were | |
7516 deleted | |
7517 col first column in "lnum" that was affected by | |
7518 the change; one if unknown or the whole line | |
7519 was affected; this is a byte index, first | |
7520 character has a value of one. | |
7521 When lines are inserted the values are: | |
7522 lnum line above which the new line is added | |
7523 end equal to "lnum" | |
7524 added number of lines inserted | |
7525 col 1 | |
7526 When lines are deleted the values are: | |
7527 lnum the first deleted line | |
7528 end the line below the first deleted line, before | |
7529 the deletion was done | |
7530 added negative, number of lines deleted | |
7531 col 1 | |
7532 When lines are changed: | |
7533 lnum the first changed line | |
7534 end the line below the last changed line | |
7535 added 0 | |
7536 col first column with a change or 1 | |
7537 | |
7538 The entries are in the order the changes were made, thus the | |
7539 most recent change is at the end. The line numbers are valid | |
7540 when the callback is invoked, but later changes may make them | |
7541 invalid, thus keeping a copy for later might not work. | |
7542 | |
7543 The {callback} is invoked just before the screen is updated, | |
7544 when |listener_flush()| is called or when a change is being | |
7545 made that changes the line count in a way it causes a line | |
7546 number in the list of changes to become invalid. | |
7547 | |
7548 The {callback} is invoked with the text locked, see | |
7549 |textlock|. If you do need to make changes to the buffer, use | |
7550 a timer to do this later |timer_start()|. | |
7551 | |
7552 The {callback} is not invoked when the buffer is first loaded. | |
7553 Use the |BufReadPost| autocmd event to handle the initial text | |
7554 of a buffer. | |
7555 The {callback} is also not invoked when the buffer is | |
7556 unloaded, use the |BufUnload| autocmd event for that. | |
7557 | |
7558 Can also be used as a |method|, the base is passed as the | |
7559 second argument: > | |
7560 GetBuffer()->listener_add(callback) | |
7561 | |
7562 listener_flush([{buf}]) *listener_flush()* | |
7563 Invoke listener callbacks for buffer {buf}. If there are no | |
7564 pending changes then no callbacks are invoked. | |
7565 | |
7566 {buf} refers to a buffer name or number. For the accepted | |
7567 values, see |bufname()|. When {buf} is omitted the current | |
7568 buffer is used. | |
7569 | |
7570 Can also be used as a |method|: > | |
7571 GetBuffer()->listener_flush() | |
7572 | |
7573 listener_remove({id}) *listener_remove()* | |
7574 Remove a listener previously added with listener_add(). | |
7575 Returns FALSE when {id} could not be found, TRUE when {id} was | |
7576 removed. | |
7577 | |
7578 Can also be used as a |method|: > | |
7579 GetListenerId()->listener_remove() | |
7580 | |
7581 localtime() *localtime()* | |
7582 Return the current time, measured as seconds since 1st Jan | |
7583 1970. See also |strftime()|, |strptime()| and |getftime()|. | |
7584 | |
7585 | |
7586 log({expr}) *log()* | |
7587 Return the natural logarithm (base e) of {expr} as a |Float|. | |
7588 {expr} must evaluate to a |Float| or a |Number| in the range | |
7589 (0, inf]. | |
7590 Examples: > | |
7591 :echo log(10) | |
7592 < 2.302585 > | |
7593 :echo log(exp(5)) | |
7594 < 5.0 | |
7595 | |
7596 Can also be used as a |method|: > | |
7597 Compute()->log() | |
7598 < | |
7599 {only available when compiled with the |+float| feature} | |
7600 | |
7601 | |
7602 log10({expr}) *log10()* | |
7603 Return the logarithm of Float {expr} to base 10 as a |Float|. | |
7604 {expr} must evaluate to a |Float| or a |Number|. | |
7605 Examples: > | |
7606 :echo log10(1000) | |
7607 < 3.0 > | |
7608 :echo log10(0.01) | |
7609 < -2.0 | |
7610 | |
7611 Can also be used as a |method|: > | |
7612 Compute()->log10() | |
7613 < | |
7614 {only available when compiled with the |+float| feature} | |
7615 | |
7616 luaeval({expr} [, {expr}]) *luaeval()* | |
7617 Evaluate Lua expression {expr} and return its result converted | |
7618 to Vim data structures. Second {expr} may hold additional | |
7619 argument accessible as _A inside first {expr}. | |
7620 Strings are returned as they are. | |
7621 Boolean objects are converted to numbers. | |
7622 Numbers are converted to |Float| values if vim was compiled | |
7623 with |+float| and to numbers otherwise. | |
7624 Dictionaries and lists obtained by vim.eval() are returned | |
7625 as-is. | |
7626 Other objects are returned as zero without any errors. | |
7627 See |lua-luaeval| for more details. | |
7628 Note that in a `:def` function local variables are not visible | |
7629 to {expr}. | |
7630 | |
7631 Can also be used as a |method|: > | |
7632 GetExpr()->luaeval() | |
7633 | |
7634 < {only available when compiled with the |+lua| feature} | |
7635 | |
7636 map({expr1}, {expr2}) *map()* | |
7637 {expr1} must be a |List|, |String|, |Blob| or |Dictionary|. | |
7638 When {expr1} is a |List|| or |Dictionary|, replace each | |
7639 item in {expr1} with the result of evaluating {expr2}. | |
7640 For a |Blob| each byte is replaced. | |
7641 For a |String|, each character, including composing | |
7642 characters, is replaced. | |
7643 If the item type changes you may want to use |mapnew()| to | |
7644 create a new List or Dictionary. This is required when using | |
7645 Vim9 script. | |
7646 | |
7647 {expr2} must be a |String| or |Funcref|. | |
7648 | |
7649 If {expr2} is a |String|, inside {expr2} |v:val| has the value | |
7650 of the current item. For a |Dictionary| |v:key| has the key | |
7651 of the current item and for a |List| |v:key| has the index of | |
7652 the current item. For a |Blob| |v:key| has the index of the | |
7653 current byte. For a |String| |v:key| has the index of the | |
7654 current character. | |
7655 Example: > | |
7656 :call map(mylist, '"> " . v:val . " <"') | |
7657 < This puts "> " before and " <" after each item in "mylist". | |
7658 | |
7659 Note that {expr2} is the result of an expression and is then | |
7660 used as an expression again. Often it is good to use a | |
7661 |literal-string| to avoid having to double backslashes. You | |
7662 still have to double ' quotes | |
7663 | |
7664 If {expr2} is a |Funcref| it is called with two arguments: | |
7665 1. The key or the index of the current item. | |
7666 2. the value of the current item. | |
7667 The function must return the new value of the item. Example | |
7668 that changes each value by "key-value": > | |
7669 func KeyValue(key, val) | |
7670 return a:key . '-' . a:val | |
7671 endfunc | |
7672 call map(myDict, function('KeyValue')) | |
7673 < It is shorter when using a |lambda|: > | |
7674 call map(myDict, {key, val -> key . '-' . val}) | |
7675 < If you do not use "val" you can leave it out: > | |
7676 call map(myDict, {key -> 'item: ' . key}) | |
7677 < If you do not use "key" you can use a short name: > | |
7678 call map(myDict, {_, val -> 'item: ' . val}) | |
7679 < | |
7680 The operation is done in-place for a |List| and |Dictionary|. | |
7681 If you want it to remain unmodified make a copy first: > | |
7682 :let tlist = map(copy(mylist), ' v:val . "\t"') | |
7683 | |
7684 < Returns {expr1}, the |List| or |Dictionary| that was filtered, | |
7685 or a new |Blob| or |String|. | |
7686 When an error is encountered while evaluating {expr2} no | |
7687 further items in {expr1} are processed. | |
7688 When {expr2} is a Funcref errors inside a function are ignored, | |
7689 unless it was defined with the "abort" flag. | |
7690 | |
7691 Can also be used as a |method|: > | |
7692 mylist->map(expr2) | |
7693 | |
7694 | |
7695 maparg({name} [, {mode} [, {abbr} [, {dict}]]]) *maparg()* | |
7696 When {dict} is omitted or zero: Return the rhs of mapping | |
7697 {name} in mode {mode}. The returned String has special | |
7698 characters translated like in the output of the ":map" command | |
7699 listing. | |
7700 | |
7701 When there is no mapping for {name}, an empty String is | |
7702 returned. When the mapping for {name} is empty, then "<Nop>" | |
7703 is returned. | |
7704 | |
7705 The {name} can have special key names, like in the ":map" | |
7706 command. | |
7707 | |
7708 {mode} can be one of these strings: | |
7709 "n" Normal | |
7710 "v" Visual (including Select) | |
7711 "o" Operator-pending | |
7712 "i" Insert | |
7713 "c" Cmd-line | |
7714 "s" Select | |
7715 "x" Visual | |
7716 "l" langmap |language-mapping| | |
7717 "t" Terminal-Job | |
7718 "" Normal, Visual and Operator-pending | |
7719 When {mode} is omitted, the modes for "" are used. | |
7720 | |
7721 When {abbr} is there and it is |TRUE| use abbreviations | |
7722 instead of mappings. | |
7723 | |
7724 When {dict} is there and it is |TRUE| return a dictionary | |
7725 containing all the information of the mapping with the | |
7726 following items: | |
7727 "lhs" The {lhs} of the mapping as it would be typed | |
7728 "lhsraw" The {lhs} of the mapping as raw bytes | |
7729 "lhsrawalt" The {lhs} of the mapping as raw bytes, alternate | |
7730 form, only present when it differs from "lhsraw" | |
7731 "rhs" The {rhs} of the mapping as typed. | |
7732 "silent" 1 for a |:map-silent| mapping, else 0. | |
7733 "noremap" 1 if the {rhs} of the mapping is not remappable. | |
7734 "script" 1 if mapping was defined with <script>. | |
7735 "expr" 1 for an expression mapping (|:map-<expr>|). | |
7736 "buffer" 1 for a buffer local mapping (|:map-local|). | |
7737 "mode" Modes for which the mapping is defined. In | |
7738 addition to the modes mentioned above, these | |
7739 characters will be used: | |
7740 " " Normal, Visual and Operator-pending | |
7741 "!" Insert and Commandline mode | |
7742 (|mapmode-ic|) | |
7743 "sid" The script local ID, used for <sid> mappings | |
7744 (|<SID>|). | |
7745 "lnum" The line number in "sid", zero if unknown. | |
7746 "nowait" Do not wait for other, longer mappings. | |
7747 (|:map-<nowait>|). | |
7748 | |
7749 The dictionary can be used to restore a mapping with | |
7750 |mapset()|. | |
7751 | |
7752 The mappings local to the current buffer are checked first, | |
7753 then the global mappings. | |
7754 This function can be used to map a key even when it's already | |
7755 mapped, and have it do the original mapping too. Sketch: > | |
7756 exe 'nnoremap <Tab> ==' . maparg('<Tab>', 'n') | |
7757 | |
7758 < Can also be used as a |method|: > | |
7759 GetKey()->maparg('n') | |
7760 | |
7761 mapcheck({name} [, {mode} [, {abbr}]]) *mapcheck()* | |
7762 Check if there is a mapping that matches with {name} in mode | |
7763 {mode}. See |maparg()| for {mode} and special names in | |
7764 {name}. | |
7765 When {abbr} is there and it is |TRUE| use abbreviations | |
7766 instead of mappings. | |
7767 A match happens with a mapping that starts with {name} and | |
7768 with a mapping which is equal to the start of {name}. | |
7769 | |
7770 matches mapping "a" "ab" "abc" ~ | |
7771 mapcheck("a") yes yes yes | |
7772 mapcheck("abc") yes yes yes | |
7773 mapcheck("ax") yes no no | |
7774 mapcheck("b") no no no | |
7775 | |
7776 The difference with maparg() is that mapcheck() finds a | |
7777 mapping that matches with {name}, while maparg() only finds a | |
7778 mapping for {name} exactly. | |
7779 When there is no mapping that starts with {name}, an empty | |
7780 String is returned. If there is one, the RHS of that mapping | |
7781 is returned. If there are several mappings that start with | |
7782 {name}, the RHS of one of them is returned. This will be | |
7783 "<Nop>" if the RHS is empty. | |
7784 The mappings local to the current buffer are checked first, | |
7785 then the global mappings. | |
7786 This function can be used to check if a mapping can be added | |
7787 without being ambiguous. Example: > | |
7788 :if mapcheck("_vv") == "" | |
7789 : map _vv :set guifont=7x13<CR> | |
7790 :endif | |
7791 < This avoids adding the "_vv" mapping when there already is a | |
7792 mapping for "_v" or for "_vvv". | |
7793 | |
7794 Can also be used as a |method|: > | |
7795 GetKey()->mapcheck('n') | |
7796 | |
7797 | |
7798 mapnew({expr1}, {expr2}) *mapnew()* | |
7799 Like |map()| but instead of replacing items in {expr1} a new | |
7800 List or Dictionary is created and returned. {expr1} remains | |
7801 unchanged. Items can still be changed by {expr2}, if you | |
7802 don't want that use |deepcopy()| first. | |
7803 | |
7804 | |
7805 mapset({mode}, {abbr}, {dict}) *mapset()* | |
7806 Restore a mapping from a dictionary returned by |maparg()|. | |
7807 {mode} and {abbr} should be the same as for the call to | |
7808 |maparg()|. *E460* | |
7809 {mode} is used to define the mode in which the mapping is set, | |
7810 not the "mode" entry in {dict}. | |
7811 Example for saving and restoring a mapping: > | |
7812 let save_map = maparg('K', 'n', 0, 1) | |
7813 nnoremap K somethingelse | |
7814 ... | |
7815 call mapset('n', 0, save_map) | |
7816 < Note that if you are going to replace a map in several modes, | |
7817 e.g. with `:map!`, you need to save the mapping for all of | |
7818 them, since they can differ. | |
7819 | |
7820 | |
7821 match({expr}, {pat} [, {start} [, {count}]]) *match()* | |
7822 When {expr} is a |List| then this returns the index of the | |
7823 first item where {pat} matches. Each item is used as a | |
7824 String, |Lists| and |Dictionaries| are used as echoed. | |
7825 | |
7826 Otherwise, {expr} is used as a String. The result is a | |
7827 Number, which gives the index (byte offset) in {expr} where | |
7828 {pat} matches. | |
7829 | |
7830 A match at the first character or |List| item returns zero. | |
7831 If there is no match -1 is returned. | |
7832 | |
7833 For getting submatches see |matchlist()|. | |
7834 Example: > | |
7835 :echo match("testing", "ing") " results in 4 | |
7836 :echo match([1, 'x'], '\a') " results in 1 | |
7837 < See |string-match| for how {pat} is used. | |
7838 *strpbrk()* | |
7839 Vim doesn't have a strpbrk() function. But you can do: > | |
7840 :let sepidx = match(line, '[.,;: \t]') | |
7841 < *strcasestr()* | |
7842 Vim doesn't have a strcasestr() function. But you can add | |
7843 "\c" to the pattern to ignore case: > | |
7844 :let idx = match(haystack, '\cneedle') | |
7845 < | |
7846 If {start} is given, the search starts from byte index | |
7847 {start} in a String or item {start} in a |List|. | |
7848 The result, however, is still the index counted from the | |
7849 first character/item. Example: > | |
7850 :echo match("testing", "ing", 2) | |
7851 < result is again "4". > | |
7852 :echo match("testing", "ing", 4) | |
7853 < result is again "4". > | |
7854 :echo match("testing", "t", 2) | |
7855 < result is "3". | |
7856 For a String, if {start} > 0 then it is like the string starts | |
7857 {start} bytes later, thus "^" will match at {start}. Except | |
7858 when {count} is given, then it's like matches before the | |
7859 {start} byte are ignored (this is a bit complicated to keep it | |
7860 backwards compatible). | |
7861 For a String, if {start} < 0, it will be set to 0. For a list | |
7862 the index is counted from the end. | |
7863 If {start} is out of range ({start} > strlen({expr}) for a | |
7864 String or {start} > len({expr}) for a |List|) -1 is returned. | |
7865 | |
7866 When {count} is given use the {count}'th match. When a match | |
7867 is found in a String the search for the next one starts one | |
7868 character further. Thus this example results in 1: > | |
7869 echo match("testing", "..", 0, 2) | |
7870 < In a |List| the search continues in the next item. | |
7871 Note that when {count} is added the way {start} works changes, | |
7872 see above. | |
7873 | |
7874 See |pattern| for the patterns that are accepted. | |
7875 The 'ignorecase' option is used to set the ignore-caseness of | |
7876 the pattern. 'smartcase' is NOT used. The matching is always | |
7877 done like 'magic' is set and 'cpoptions' is empty. | |
7878 Note that a match at the start is preferred, thus when the | |
7879 pattern is using "*" (any number of matches) it tends to find | |
7880 zero matches at the start instead of a number of matches | |
7881 further down in the text. | |
7882 | |
7883 Can also be used as a |method|: > | |
7884 GetText()->match('word') | |
7885 GetList()->match('word') | |
7886 < | |
7887 *matchadd()* *E798* *E799* *E801* *E957* | |
7888 matchadd({group}, {pattern} [, {priority} [, {id} [, {dict}]]]) | |
7889 Defines a pattern to be highlighted in the current window (a | |
7890 "match"). It will be highlighted with {group}. Returns an | |
7891 identification number (ID), which can be used to delete the | |
7892 match using |matchdelete()|. The ID is bound to the window. | |
7893 Matching is case sensitive and magic, unless case sensitivity | |
7894 or magicness are explicitly overridden in {pattern}. The | |
7895 'magic', 'smartcase' and 'ignorecase' options are not used. | |
7896 The "Conceal" value is special, it causes the match to be | |
7897 concealed. | |
7898 | |
7899 The optional {priority} argument assigns a priority to the | |
7900 match. A match with a high priority will have its | |
7901 highlighting overrule that of a match with a lower priority. | |
7902 A priority is specified as an integer (negative numbers are no | |
7903 exception). If the {priority} argument is not specified, the | |
7904 default priority is 10. The priority of 'hlsearch' is zero, | |
7905 hence all matches with a priority greater than zero will | |
7906 overrule it. Syntax highlighting (see 'syntax') is a separate | |
7907 mechanism, and regardless of the chosen priority a match will | |
7908 always overrule syntax highlighting. | |
7909 | |
7910 The optional {id} argument allows the request for a specific | |
7911 match ID. If a specified ID is already taken, an error | |
7912 message will appear and the match will not be added. An ID | |
7913 is specified as a positive integer (zero excluded). IDs 1, 2 | |
7914 and 3 are reserved for |:match|, |:2match| and |:3match|, | |
7915 respectively. If the {id} argument is not specified or -1, | |
7916 |matchadd()| automatically chooses a free ID. | |
7917 | |
7918 The optional {dict} argument allows for further custom | |
7919 values. Currently this is used to specify a match specific | |
7920 conceal character that will be shown for |hl-Conceal| | |
7921 highlighted matches. The dict can have the following members: | |
7922 | |
7923 conceal Special character to show instead of the | |
7924 match (only for |hl-Conceal| highlighted | |
7925 matches, see |:syn-cchar|) | |
7926 window Instead of the current window use the | |
7927 window with this number or window ID. | |
7928 | |
7929 The number of matches is not limited, as it is the case with | |
7930 the |:match| commands. | |
7931 | |
7932 Example: > | |
7933 :highlight MyGroup ctermbg=green guibg=green | |
7934 :let m = matchadd("MyGroup", "TODO") | |
7935 < Deletion of the pattern: > | |
7936 :call matchdelete(m) | |
7937 | |
7938 < A list of matches defined by |matchadd()| and |:match| are | |
7939 available from |getmatches()|. All matches can be deleted in | |
7940 one operation by |clearmatches()|. | |
7941 | |
7942 Can also be used as a |method|: > | |
7943 GetGroup()->matchadd('TODO') | |
7944 < | |
7945 *matchaddpos()* | |
7946 matchaddpos({group}, {pos} [, {priority} [, {id} [, {dict}]]]) | |
7947 Same as |matchadd()|, but requires a list of positions {pos} | |
7948 instead of a pattern. This command is faster than |matchadd()| | |
7949 because it does not require to handle regular expressions and | |
7950 sets buffer line boundaries to redraw screen. It is supposed | |
7951 to be used when fast match additions and deletions are | |
7952 required, for example to highlight matching parentheses. | |
7953 | |
7954 {pos} is a list of positions. Each position can be one of | |
7955 these: | |
7956 - A number. This whole line will be highlighted. The first | |
7957 line has number 1. | |
7958 - A list with one number, e.g., [23]. The whole line with this | |
7959 number will be highlighted. | |
7960 - A list with two numbers, e.g., [23, 11]. The first number is | |
7961 the line number, the second one is the column number (first | |
7962 column is 1, the value must correspond to the byte index as | |
7963 |col()| would return). The character at this position will | |
7964 be highlighted. | |
7965 - A list with three numbers, e.g., [23, 11, 3]. As above, but | |
7966 the third number gives the length of the highlight in bytes. | |
7967 | |
7968 The maximum number of positions in {pos} is 8. | |
7969 | |
7970 Example: > | |
7971 :highlight MyGroup ctermbg=green guibg=green | |
7972 :let m = matchaddpos("MyGroup", [[23, 24], 34]) | |
7973 < Deletion of the pattern: > | |
7974 :call matchdelete(m) | |
7975 | |
7976 < Matches added by |matchaddpos()| are returned by | |
7977 |getmatches()|. | |
7978 | |
7979 Can also be used as a |method|: > | |
7980 GetGroup()->matchaddpos([23, 11]) | |
7981 | |
7982 matcharg({nr}) *matcharg()* | |
7983 Selects the {nr} match item, as set with a |:match|, | |
7984 |:2match| or |:3match| command. | |
7985 Return a |List| with two elements: | |
7986 The name of the highlight group used | |
7987 The pattern used. | |
7988 When {nr} is not 1, 2 or 3 returns an empty |List|. | |
7989 When there is no match item set returns ['', '']. | |
7990 This is useful to save and restore a |:match|. | |
7991 Highlighting matches using the |:match| commands are limited | |
7992 to three matches. |matchadd()| does not have this limitation. | |
7993 | |
7994 Can also be used as a |method|: > | |
7995 GetMatch()->matcharg() | |
7996 | |
7997 matchdelete({id} [, {win}) *matchdelete()* *E802* *E803* | |
7998 Deletes a match with ID {id} previously defined by |matchadd()| | |
7999 or one of the |:match| commands. Returns 0 if successful, | |
8000 otherwise -1. See example for |matchadd()|. All matches can | |
8001 be deleted in one operation by |clearmatches()|. | |
8002 If {win} is specified, use the window with this number or | |
8003 window ID instead of the current window. | |
8004 | |
8005 Can also be used as a |method|: > | |
8006 GetMatch()->matchdelete() | |
8007 | |
8008 matchend({expr}, {pat} [, {start} [, {count}]]) *matchend()* | |
8009 Same as |match()|, but return the index of first character | |
8010 after the match. Example: > | |
8011 :echo matchend("testing", "ing") | |
8012 < results in "7". | |
8013 *strspn()* *strcspn()* | |
8014 Vim doesn't have a strspn() or strcspn() function, but you can | |
8015 do it with matchend(): > | |
8016 :let span = matchend(line, '[a-zA-Z]') | |
8017 :let span = matchend(line, '[^a-zA-Z]') | |
8018 < Except that -1 is returned when there are no matches. | |
8019 | |
8020 The {start}, if given, has the same meaning as for |match()|. > | |
8021 :echo matchend("testing", "ing", 2) | |
8022 < results in "7". > | |
8023 :echo matchend("testing", "ing", 5) | |
8024 < result is "-1". | |
8025 When {expr} is a |List| the result is equal to |match()|. | |
8026 | |
8027 Can also be used as a |method|: > | |
8028 GetText()->matchend('word') | |
8029 | |
8030 | |
8031 matchfuzzy({list}, {str} [, {dict}]) *matchfuzzy()* | |
8032 If {list} is a list of strings, then returns a |List| with all | |
8033 the strings in {list} that fuzzy match {str}. The strings in | |
8034 the returned list are sorted based on the matching score. | |
8035 | |
8036 The optional {dict} argument always supports the following | |
8037 items: | |
8038 matchseq When this item is present and {str} contains | |
8039 multiple words separated by white space, then | |
8040 returns only matches that contain the words in | |
8041 the given sequence. | |
8042 | |
8043 If {list} is a list of dictionaries, then the optional {dict} | |
8044 argument supports the following additional items: | |
8045 key key of the item which is fuzzy matched against | |
8046 {str}. The value of this item should be a | |
8047 string. | |
8048 text_cb |Funcref| that will be called for every item | |
8049 in {list} to get the text for fuzzy matching. | |
8050 This should accept a dictionary item as the | |
8051 argument and return the text for that item to | |
8052 use for fuzzy matching. | |
8053 | |
8054 {str} is treated as a literal string and regular expression | |
8055 matching is NOT supported. The maximum supported {str} length | |
8056 is 256. | |
8057 | |
8058 When {str} has multiple words each separated by white space, | |
8059 then the list of strings that have all the words is returned. | |
8060 | |
8061 If there are no matching strings or there is an error, then an | |
8062 empty list is returned. If length of {str} is greater than | |
8063 256, then returns an empty list. | |
8064 | |
8065 Refer to |fuzzy-match| for more information about fuzzy | |
8066 matching strings. | |
8067 | |
8068 Example: > | |
8069 :echo matchfuzzy(["clay", "crow"], "cay") | |
8070 < results in ["clay"]. > | |
8071 :echo getbufinfo()->map({_, v -> v.name})->matchfuzzy("ndl") | |
8072 < results in a list of buffer names fuzzy matching "ndl". > | |
8073 :echo getbufinfo()->matchfuzzy("ndl", {'key' : 'name'}) | |
8074 < results in a list of buffer information dicts with buffer | |
8075 names fuzzy matching "ndl". > | |
8076 :echo getbufinfo()->matchfuzzy("spl", | |
8077 \ {'text_cb' : {v -> v.name}}) | |
8078 < results in a list of buffer information dicts with buffer | |
8079 names fuzzy matching "spl". > | |
8080 :echo v:oldfiles->matchfuzzy("test") | |
8081 < results in a list of file names fuzzy matching "test". > | |
8082 :let l = readfile("buffer.c")->matchfuzzy("str") | |
8083 < results in a list of lines in "buffer.c" fuzzy matching "str". > | |
8084 :echo ['one two', 'two one']->matchfuzzy('two one') | |
8085 < results in ['two one', 'one two']. > | |
8086 :echo ['one two', 'two one']->matchfuzzy('two one', | |
8087 \ {'matchseq': 1}) | |
8088 < results in ['two one']. | |
8089 | |
8090 matchfuzzypos({list}, {str} [, {dict}]) *matchfuzzypos()* | |
8091 Same as |matchfuzzy()|, but returns the list of matched | |
8092 strings, the list of character positions where characters | |
8093 in {str} matches and a list of matching scores. You can | |
8094 use |byteidx()| to convert a character position to a byte | |
8095 position. | |
8096 | |
8097 If {str} matches multiple times in a string, then only the | |
8098 positions for the best match is returned. | |
8099 | |
8100 If there are no matching strings or there is an error, then a | |
8101 list with three empty list items is returned. | |
8102 | |
8103 Example: > | |
8104 :echo matchfuzzypos(['testing'], 'tsg') | |
8105 < results in [['testing'], [[0, 2, 6]], [99]] > | |
8106 :echo matchfuzzypos(['clay', 'lacy'], 'la') | |
8107 < results in [['lacy', 'clay'], [[0, 1], [1, 2]], [153, 133]] > | |
8108 :echo [{'text': 'hello', 'id' : 10}]->matchfuzzypos('ll', {'key' : 'text'}) | |
8109 < results in [[{'id': 10, 'text': 'hello'}], [[2, 3]], [127]] | |
8110 | |
8111 matchlist({expr}, {pat} [, {start} [, {count}]]) *matchlist()* | |
8112 Same as |match()|, but return a |List|. The first item in the | |
8113 list is the matched string, same as what matchstr() would | |
8114 return. Following items are submatches, like "\1", "\2", etc. | |
8115 in |:substitute|. When an optional submatch didn't match an | |
8116 empty string is used. Example: > | |
8117 echo matchlist('acd', '\(a\)\?\(b\)\?\(c\)\?\(.*\)') | |
8118 < Results in: ['acd', 'a', '', 'c', 'd', '', '', '', '', ''] | |
8119 When there is no match an empty list is returned. | |
8120 | |
8121 You can pass in a List, but that is not very useful. | |
8122 | |
8123 Can also be used as a |method|: > | |
8124 GetText()->matchlist('word') | |
8125 | |
8126 matchstr({expr}, {pat} [, {start} [, {count}]]) *matchstr()* | |
8127 Same as |match()|, but return the matched string. Example: > | |
8128 :echo matchstr("testing", "ing") | |
8129 < results in "ing". | |
8130 When there is no match "" is returned. | |
8131 The {start}, if given, has the same meaning as for |match()|. > | |
8132 :echo matchstr("testing", "ing", 2) | |
8133 < results in "ing". > | |
8134 :echo matchstr("testing", "ing", 5) | |
8135 < result is "". | |
8136 When {expr} is a |List| then the matching item is returned. | |
8137 The type isn't changed, it's not necessarily a String. | |
8138 | |
8139 Can also be used as a |method|: > | |
8140 GetText()->matchstr('word') | |
8141 | |
8142 matchstrpos({expr}, {pat} [, {start} [, {count}]]) *matchstrpos()* | |
8143 Same as |matchstr()|, but return the matched string, the start | |
8144 position and the end position of the match. Example: > | |
8145 :echo matchstrpos("testing", "ing") | |
8146 < results in ["ing", 4, 7]. | |
8147 When there is no match ["", -1, -1] is returned. | |
8148 The {start}, if given, has the same meaning as for |match()|. > | |
8149 :echo matchstrpos("testing", "ing", 2) | |
8150 < results in ["ing", 4, 7]. > | |
8151 :echo matchstrpos("testing", "ing", 5) | |
8152 < result is ["", -1, -1]. | |
8153 When {expr} is a |List| then the matching item, the index | |
8154 of first item where {pat} matches, the start position and the | |
8155 end position of the match are returned. > | |
8156 :echo matchstrpos([1, '__x'], '\a') | |
8157 < result is ["x", 1, 2, 3]. | |
8158 The type isn't changed, it's not necessarily a String. | |
8159 | |
8160 Can also be used as a |method|: > | |
8161 GetText()->matchstrpos('word') | |
8162 < | |
8163 | |
8164 *max()* | |
8165 max({expr}) Return the maximum value of all items in {expr}. Example: > | |
8166 echo max([apples, pears, oranges]) | |
8167 | |
8168 < {expr} can be a |List| or a |Dictionary|. For a Dictionary, | |
8169 it returns the maximum of all values in the Dictionary. | |
8170 If {expr} is neither a List nor a Dictionary, or one of the | |
8171 items in {expr} cannot be used as a Number this results in | |
8172 an error. An empty |List| or |Dictionary| results in zero. | |
8173 | |
8174 Can also be used as a |method|: > | |
8175 mylist->max() | |
8176 | |
8177 | |
8178 menu_info({name} [, {mode}]) *menu_info()* | |
8179 Return information about the specified menu {name} in | |
8180 mode {mode}. The menu name should be specified without the | |
8181 shortcut character ('&'). If {name} is "", then the top-level | |
8182 menu names are returned. | |
8183 | |
8184 {mode} can be one of these strings: | |
8185 "n" Normal | |
8186 "v" Visual (including Select) | |
8187 "o" Operator-pending | |
8188 "i" Insert | |
8189 "c" Cmd-line | |
8190 "s" Select | |
8191 "x" Visual | |
8192 "t" Terminal-Job | |
8193 "" Normal, Visual and Operator-pending | |
8194 "!" Insert and Cmd-line | |
8195 When {mode} is omitted, the modes for "" are used. | |
8196 | |
8197 Returns a |Dictionary| containing the following items: | |
8198 accel menu item accelerator text |menu-text| | |
8199 display display name (name without '&') | |
8200 enabled v:true if this menu item is enabled | |
8201 Refer to |:menu-enable| | |
8202 icon name of the icon file (for toolbar) | |
8203 |toolbar-icon| | |
8204 iconidx index of a built-in icon | |
8205 modes modes for which the menu is defined. In | |
8206 addition to the modes mentioned above, these | |
8207 characters will be used: | |
8208 " " Normal, Visual and Operator-pending | |
8209 name menu item name. | |
8210 noremenu v:true if the {rhs} of the menu item is not | |
8211 remappable else v:false. | |
8212 priority menu order priority |menu-priority| | |
8213 rhs right-hand-side of the menu item. The returned | |
8214 string has special characters translated like | |
8215 in the output of the ":menu" command listing. | |
8216 When the {rhs} of a menu item is empty, then | |
8217 "<Nop>" is returned. | |
8218 script v:true if script-local remapping of {rhs} is | |
8219 allowed else v:false. See |:menu-script|. | |
8220 shortcut shortcut key (character after '&' in | |
8221 the menu name) |menu-shortcut| | |
8222 silent v:true if the menu item is created | |
8223 with <silent> argument |:menu-silent| | |
8224 submenus |List| containing the names of | |
8225 all the submenus. Present only if the menu | |
8226 item has submenus. | |
8227 | |
8228 Returns an empty dictionary if the menu item is not found. | |
8229 | |
8230 Examples: > | |
8231 :echo menu_info('Edit.Cut') | |
8232 :echo menu_info('File.Save', 'n') | |
8233 | |
8234 " Display the entire menu hierarchy in a buffer | |
8235 func ShowMenu(name, pfx) | |
8236 let m = menu_info(a:name) | |
8237 call append(line('$'), a:pfx .. m.display) | |
8238 for child in m->get('submenus', []) | |
8239 call ShowMenu(a:name .. '.' .. escape(child, '.'), | |
8240 \ a:pfx .. ' ') | |
8241 endfor | |
8242 endfunc | |
8243 new | |
8244 for topmenu in menu_info('').submenus | |
8245 call ShowMenu(topmenu, '') | |
8246 endfor | |
8247 < | |
8248 Can also be used as a |method|: > | |
8249 GetMenuName()->menu_info('v') | |
8250 | |
8251 | |
8252 < *min()* | |
8253 min({expr}) Return the minimum value of all items in {expr}. Example: > | |
8254 echo min([apples, pears, oranges]) | |
8255 | |
8256 < {expr} can be a |List| or a |Dictionary|. For a Dictionary, | |
8257 it returns the minimum of all values in the Dictionary. | |
8258 If {expr} is neither a List nor a Dictionary, or one of the | |
8259 items in {expr} cannot be used as a Number this results in | |
8260 an error. An empty |List| or |Dictionary| results in zero. | |
8261 | |
8262 Can also be used as a |method|: > | |
8263 mylist->min() | |
8264 | |
8265 < *mkdir()* *E739* | |
8266 mkdir({name} [, {path} [, {prot}]]) | |
8267 Create directory {name}. | |
8268 | |
8269 If {path} is "p" then intermediate directories are created as | |
8270 necessary. Otherwise it must be "". | |
8271 | |
8272 If {prot} is given it is used to set the protection bits of | |
8273 the new directory. The default is 0o755 (rwxr-xr-x: r/w for | |
8274 the user, readable for others). Use 0o700 to make it | |
8275 unreadable for others. This is only used for the last part of | |
8276 {name}. Thus if you create /tmp/foo/bar then /tmp/foo will be | |
8277 created with 0o755. | |
8278 Example: > | |
8279 :call mkdir($HOME . "/tmp/foo/bar", "p", 0o700) | |
8280 | |
8281 < This function is not available in the |sandbox|. | |
8282 | |
8283 There is no error if the directory already exists and the "p" | |
8284 flag is passed (since patch 8.0.1708). However, without the | |
8285 "p" option the call will fail. | |
8286 | |
8287 The function result is a Number, which is TRUE if the call was | |
8288 successful or FALSE if the directory creation failed or partly | |
8289 failed. | |
8290 | |
8291 Not available on all systems. To check use: > | |
8292 :if exists("*mkdir") | |
8293 | |
8294 < Can also be used as a |method|: > | |
8295 GetName()->mkdir() | |
8296 < | |
8297 *mode()* | |
8298 mode([expr]) Return a string that indicates the current mode. | |
8299 If [expr] is supplied and it evaluates to a non-zero Number or | |
8300 a non-empty String (|non-zero-arg|), then the full mode is | |
8301 returned, otherwise only the first letter is returned. | |
8302 Also see |state()|. | |
8303 | |
8304 n Normal | |
8305 no Operator-pending | |
8306 nov Operator-pending (forced characterwise |o_v|) | |
8307 noV Operator-pending (forced linewise |o_V|) | |
8308 noCTRL-V Operator-pending (forced blockwise |o_CTRL-V|); | |
8309 CTRL-V is one character | |
8310 niI Normal using |i_CTRL-O| in |Insert-mode| | |
8311 niR Normal using |i_CTRL-O| in |Replace-mode| | |
8312 niV Normal using |i_CTRL-O| in |Virtual-Replace-mode| | |
8313 nt Terminal-Normal (insert goes to Terminal-Job mode) | |
8314 v Visual by character | |
8315 vs Visual by character using |v_CTRL-O| in Select mode | |
8316 V Visual by line | |
8317 Vs Visual by line using |v_CTRL-O| in Select mode | |
8318 CTRL-V Visual blockwise | |
8319 CTRL-Vs Visual blockwise using |v_CTRL-O| in Select mode | |
8320 s Select by character | |
8321 S Select by line | |
8322 CTRL-S Select blockwise | |
8323 i Insert | |
8324 ic Insert mode completion |compl-generic| | |
8325 ix Insert mode |i_CTRL-X| completion | |
8326 R Replace |R| | |
8327 Rc Replace mode completion |compl-generic| | |
8328 Rx Replace mode |i_CTRL-X| completion | |
8329 Rv Virtual Replace |gR| | |
8330 Rvc Virtual Replace mode completion |compl-generic| | |
8331 Rvx Virtual Replace mode |i_CTRL-X| completion | |
8332 c Command-line editing | |
8333 cv Vim Ex mode |gQ| | |
8334 ce Normal Ex mode |Q| | |
8335 r Hit-enter prompt | |
8336 rm The -- more -- prompt | |
8337 r? A |:confirm| query of some sort | |
8338 ! Shell or external command is executing | |
8339 t Terminal-Job mode: keys go to the job | |
8340 | |
8341 This is useful in the 'statusline' option or when used | |
8342 with |remote_expr()| In most other places it always returns | |
8343 "c" or "n". | |
8344 Note that in the future more modes and more specific modes may | |
8345 be added. It's better not to compare the whole string but only | |
8346 the leading character(s). | |
8347 Also see |visualmode()|. | |
8348 | |
8349 Can also be used as a |method|: > | |
8350 DoFull()->mode() | |
8351 | |
8352 mzeval({expr}) *mzeval()* | |
8353 Evaluate MzScheme expression {expr} and return its result | |
8354 converted to Vim data structures. | |
8355 Numbers and strings are returned as they are. | |
8356 Pairs (including lists and improper lists) and vectors are | |
8357 returned as Vim |Lists|. | |
8358 Hash tables are represented as Vim |Dictionary| type with keys | |
8359 converted to strings. | |
8360 All other types are converted to string with display function. | |
8361 Examples: > | |
8362 :mz (define l (list 1 2 3)) | |
8363 :mz (define h (make-hash)) (hash-set! h "list" l) | |
8364 :echo mzeval("l") | |
8365 :echo mzeval("h") | |
8366 < | |
8367 Note that in a `:def` function local variables are not visible | |
8368 to {expr}. | |
8369 | |
8370 Can also be used as a |method|: > | |
8371 GetExpr()->mzeval() | |
8372 < | |
8373 {only available when compiled with the |+mzscheme| feature} | |
8374 | |
8375 nextnonblank({lnum}) *nextnonblank()* | |
8376 Return the line number of the first line at or below {lnum} | |
8377 that is not blank. Example: > | |
8378 if getline(nextnonblank(1)) =~ "Java" | |
8379 < When {lnum} is invalid or there is no non-blank line at or | |
8380 below it, zero is returned. | |
8381 {lnum} is used like with |getline()|. | |
8382 See also |prevnonblank()|. | |
8383 | |
8384 Can also be used as a |method|: > | |
8385 GetLnum()->nextnonblank() | |
8386 | |
8387 nr2char({expr} [, {utf8}]) *nr2char()* | |
8388 Return a string with a single character, which has the number | |
8389 value {expr}. Examples: > | |
8390 nr2char(64) returns "@" | |
8391 nr2char(32) returns " " | |
8392 < When {utf8} is omitted or zero, the current 'encoding' is used. | |
8393 Example for "utf-8": > | |
8394 nr2char(300) returns I with bow character | |
8395 < When {utf8} is TRUE, always return UTF-8 characters. | |
8396 Note that a NUL character in the file is specified with | |
8397 nr2char(10), because NULs are represented with newline | |
8398 characters. nr2char(0) is a real NUL and terminates the | |
8399 string, thus results in an empty string. | |
8400 To turn a list of character numbers into a string: > | |
8401 let list = [65, 66, 67] | |
8402 let str = join(map(list, {_, val -> nr2char(val)}), '') | |
8403 < Result: "ABC" | |
8404 | |
8405 Can also be used as a |method|: > | |
8406 GetNumber()->nr2char() | |
8407 | |
8408 or({expr}, {expr}) *or()* | |
8409 Bitwise OR on the two arguments. The arguments are converted | |
8410 to a number. A List, Dict or Float argument causes an error. | |
8411 Example: > | |
8412 :let bits = or(bits, 0x80) | |
8413 < Can also be used as a |method|: > | |
8414 :let bits = bits->or(0x80) | |
8415 | |
8416 | |
8417 pathshorten({path} [, {len}]) *pathshorten()* | |
8418 Shorten directory names in the path {path} and return the | |
8419 result. The tail, the file name, is kept as-is. The other | |
8420 components in the path are reduced to {len} letters in length. | |
8421 If {len} is omitted or smaller than 1 then 1 is used (single | |
8422 letters). Leading '~' and '.' characters are kept. Examples: > | |
8423 :echo pathshorten('~/.vim/autoload/myfile.vim') | |
8424 < ~/.v/a/myfile.vim ~ | |
8425 > | |
8426 :echo pathshorten('~/.vim/autoload/myfile.vim', 2) | |
8427 < ~/.vi/au/myfile.vim ~ | |
8428 It doesn't matter if the path exists or not. | |
8429 | |
8430 Can also be used as a |method|: > | |
8431 GetDirectories()->pathshorten() | |
8432 | |
8433 perleval({expr}) *perleval()* | |
8434 Evaluate Perl expression {expr} in scalar context and return | |
8435 its result converted to Vim data structures. If value can't be | |
8436 converted, it is returned as a string Perl representation. | |
8437 Note: If you want an array or hash, {expr} must return a | |
8438 reference to it. | |
8439 Example: > | |
8440 :echo perleval('[1 .. 4]') | |
8441 < [1, 2, 3, 4] | |
8442 | |
8443 Note that in a `:def` function local variables are not visible | |
8444 to {expr}. | |
8445 | |
8446 Can also be used as a |method|: > | |
8447 GetExpr()->perleval() | |
8448 | |
8449 < {only available when compiled with the |+perl| feature} | |
8450 | |
8451 | |
8452 popup_ functions are documented here: |popup-functions| | |
8453 | |
8454 | |
8455 pow({x}, {y}) *pow()* | |
8456 Return the power of {x} to the exponent {y} as a |Float|. | |
8457 {x} and {y} must evaluate to a |Float| or a |Number|. | |
8458 Examples: > | |
8459 :echo pow(3, 3) | |
8460 < 27.0 > | |
8461 :echo pow(2, 16) | |
8462 < 65536.0 > | |
8463 :echo pow(32, 0.20) | |
8464 < 2.0 | |
8465 | |
8466 Can also be used as a |method|: > | |
8467 Compute()->pow(3) | |
8468 < | |
8469 {only available when compiled with the |+float| feature} | |
8470 | |
8471 prevnonblank({lnum}) *prevnonblank()* | |
8472 Return the line number of the first line at or above {lnum} | |
8473 that is not blank. Example: > | |
8474 let ind = indent(prevnonblank(v:lnum - 1)) | |
8475 < When {lnum} is invalid or there is no non-blank line at or | |
8476 above it, zero is returned. | |
8477 {lnum} is used like with |getline()|. | |
8478 Also see |nextnonblank()|. | |
8479 | |
8480 Can also be used as a |method|: > | |
8481 GetLnum()->prevnonblank() | |
8482 | |
8483 printf({fmt}, {expr1} ...) *printf()* | |
8484 Return a String with {fmt}, where "%" items are replaced by | |
8485 the formatted form of their respective arguments. Example: > | |
8486 printf("%4d: E%d %.30s", lnum, errno, msg) | |
8487 < May result in: | |
8488 " 99: E42 asdfasdfasdfasdfasdfasdfasdfas" ~ | |
8489 | |
8490 When used as a |method| the base is passed as the second | |
8491 argument: > | |
8492 Compute()->printf("result: %d") | |
8493 | |
8494 < Often used items are: | |
8495 %s string | |
8496 %6S string right-aligned in 6 display cells | |
8497 %6s string right-aligned in 6 bytes | |
8498 %.9s string truncated to 9 bytes | |
8499 %c single byte | |
8500 %d decimal number | |
8501 %5d decimal number padded with spaces to 5 characters | |
8502 %x hex number | |
8503 %04x hex number padded with zeros to at least 4 characters | |
8504 %X hex number using upper case letters | |
8505 %o octal number | |
8506 %08b binary number padded with zeros to at least 8 chars | |
8507 %f floating point number as 12.23, inf, -inf or nan | |
8508 %F floating point number as 12.23, INF, -INF or NAN | |
8509 %e floating point number as 1.23e3, inf, -inf or nan | |
8510 %E floating point number as 1.23E3, INF, -INF or NAN | |
8511 %g floating point number, as %f or %e depending on value | |
8512 %G floating point number, as %F or %E depending on value | |
8513 %% the % character itself | |
8514 | |
8515 Conversion specifications start with '%' and end with the | |
8516 conversion type. All other characters are copied unchanged to | |
8517 the result. | |
8518 | |
8519 The "%" starts a conversion specification. The following | |
8520 arguments appear in sequence: | |
8521 | |
8522 % [flags] [field-width] [.precision] type | |
8523 | |
8524 flags | |
8525 Zero or more of the following flags: | |
8526 | |
8527 # The value should be converted to an "alternate | |
8528 form". For c, d, and s conversions, this option | |
8529 has no effect. For o conversions, the precision | |
8530 of the number is increased to force the first | |
8531 character of the output string to a zero (except | |
8532 if a zero value is printed with an explicit | |
8533 precision of zero). | |
8534 For b and B conversions, a non-zero result has | |
8535 the string "0b" (or "0B" for B conversions) | |
8536 prepended to it. | |
8537 For x and X conversions, a non-zero result has | |
8538 the string "0x" (or "0X" for X conversions) | |
8539 prepended to it. | |
8540 | |
8541 0 (zero) Zero padding. For all conversions the converted | |
8542 value is padded on the left with zeros rather | |
8543 than blanks. If a precision is given with a | |
8544 numeric conversion (d, b, B, o, x, and X), the 0 | |
8545 flag is ignored. | |
8546 | |
8547 - A negative field width flag; the converted value | |
8548 is to be left adjusted on the field boundary. | |
8549 The converted value is padded on the right with | |
8550 blanks, rather than on the left with blanks or | |
8551 zeros. A - overrides a 0 if both are given. | |
8552 | |
8553 ' ' (space) A blank should be left before a positive | |
8554 number produced by a signed conversion (d). | |
8555 | |
8556 + A sign must always be placed before a number | |
8557 produced by a signed conversion. A + overrides | |
8558 a space if both are used. | |
8559 | |
8560 field-width | |
8561 An optional decimal digit string specifying a minimum | |
8562 field width. If the converted value has fewer bytes | |
8563 than the field width, it will be padded with spaces on | |
8564 the left (or right, if the left-adjustment flag has | |
8565 been given) to fill out the field width. For the S | |
8566 conversion the count is in cells. | |
8567 | |
8568 .precision | |
8569 An optional precision, in the form of a period '.' | |
8570 followed by an optional digit string. If the digit | |
8571 string is omitted, the precision is taken as zero. | |
8572 This gives the minimum number of digits to appear for | |
8573 d, o, x, and X conversions, the maximum number of | |
8574 bytes to be printed from a string for s conversions, | |
8575 or the maximum number of cells to be printed from a | |
8576 string for S conversions. | |
8577 For floating point it is the number of digits after | |
8578 the decimal point. | |
8579 | |
8580 type | |
8581 A character that specifies the type of conversion to | |
8582 be applied, see below. | |
8583 | |
8584 A field width or precision, or both, may be indicated by an | |
8585 asterisk '*' instead of a digit string. In this case, a | |
8586 Number argument supplies the field width or precision. A | |
8587 negative field width is treated as a left adjustment flag | |
8588 followed by a positive field width; a negative precision is | |
8589 treated as though it were missing. Example: > | |
8590 :echo printf("%d: %.*s", nr, width, line) | |
8591 < This limits the length of the text used from "line" to | |
8592 "width" bytes. | |
8593 | |
8594 The conversion specifiers and their meanings are: | |
8595 | |
8596 *printf-d* *printf-b* *printf-B* *printf-o* | |
8597 *printf-x* *printf-X* | |
8598 dbBoxX The Number argument is converted to signed decimal | |
8599 (d), unsigned binary (b and B), unsigned octal (o), or | |
8600 unsigned hexadecimal (x and X) notation. The letters | |
8601 "abcdef" are used for x conversions; the letters | |
8602 "ABCDEF" are used for X conversions. | |
8603 The precision, if any, gives the minimum number of | |
8604 digits that must appear; if the converted value | |
8605 requires fewer digits, it is padded on the left with | |
8606 zeros. | |
8607 In no case does a non-existent or small field width | |
8608 cause truncation of a numeric field; if the result of | |
8609 a conversion is wider than the field width, the field | |
8610 is expanded to contain the conversion result. | |
8611 The 'h' modifier indicates the argument is 16 bits. | |
8612 The 'l' modifier indicates the argument is 32 bits. | |
8613 The 'L' modifier indicates the argument is 64 bits. | |
8614 Generally, these modifiers are not useful. They are | |
8615 ignored when type is known from the argument. | |
8616 | |
8617 i alias for d | |
8618 D alias for ld | |
8619 U alias for lu | |
8620 O alias for lo | |
8621 | |
8622 *printf-c* | |
8623 c The Number argument is converted to a byte, and the | |
8624 resulting character is written. | |
8625 | |
8626 *printf-s* | |
8627 s The text of the String argument is used. If a | |
8628 precision is specified, no more bytes than the number | |
8629 specified are used. | |
8630 If the argument is not a String type, it is | |
8631 automatically converted to text with the same format | |
8632 as ":echo". | |
8633 *printf-S* | |
8634 S The text of the String argument is used. If a | |
8635 precision is specified, no more display cells than the | |
8636 number specified are used. | |
8637 | |
8638 *printf-f* *E807* | |
8639 f F The Float argument is converted into a string of the | |
8640 form 123.456. The precision specifies the number of | |
8641 digits after the decimal point. When the precision is | |
8642 zero the decimal point is omitted. When the precision | |
8643 is not specified 6 is used. A really big number | |
8644 (out of range or dividing by zero) results in "inf" | |
8645 or "-inf" with %f (INF or -INF with %F). | |
8646 "0.0 / 0.0" results in "nan" with %f (NAN with %F). | |
8647 Example: > | |
8648 echo printf("%.2f", 12.115) | |
8649 < 12.12 | |
8650 Note that roundoff depends on the system libraries. | |
8651 Use |round()| when in doubt. | |
8652 | |
8653 *printf-e* *printf-E* | |
8654 e E The Float argument is converted into a string of the | |
8655 form 1.234e+03 or 1.234E+03 when using 'E'. The | |
8656 precision specifies the number of digits after the | |
8657 decimal point, like with 'f'. | |
8658 | |
8659 *printf-g* *printf-G* | |
8660 g G The Float argument is converted like with 'f' if the | |
8661 value is between 0.001 (inclusive) and 10000000.0 | |
8662 (exclusive). Otherwise 'e' is used for 'g' and 'E' | |
8663 for 'G'. When no precision is specified superfluous | |
8664 zeroes and '+' signs are removed, except for the zero | |
8665 immediately after the decimal point. Thus 10000000.0 | |
8666 results in 1.0e7. | |
8667 | |
8668 *printf-%* | |
8669 % A '%' is written. No argument is converted. The | |
8670 complete conversion specification is "%%". | |
8671 | |
8672 When a Number argument is expected a String argument is also | |
8673 accepted and automatically converted. | |
8674 When a Float or String argument is expected a Number argument | |
8675 is also accepted and automatically converted. | |
8676 Any other argument type results in an error message. | |
8677 | |
8678 *E766* *E767* | |
8679 The number of {exprN} arguments must exactly match the number | |
8680 of "%" items. If there are not sufficient or too many | |
8681 arguments an error is given. Up to 18 arguments can be used. | |
8682 | |
8683 | |
8684 prompt_getprompt({buf}) *prompt_getprompt()* | |
8685 Returns the effective prompt text for buffer {buf}. {buf} can | |
8686 be a buffer name or number. See |prompt-buffer|. | |
8687 | |
8688 If the buffer doesn't exist or isn't a prompt buffer, an empty | |
8689 string is returned. | |
8690 | |
8691 Can also be used as a |method|: > | |
8692 GetBuffer()->prompt_getprompt() | |
8693 | |
8694 < {only available when compiled with the |+channel| feature} | |
8695 | |
8696 | |
8697 prompt_setcallback({buf}, {expr}) *prompt_setcallback()* | |
8698 Set prompt callback for buffer {buf} to {expr}. When {expr} | |
8699 is an empty string the callback is removed. This has only | |
8700 effect if {buf} has 'buftype' set to "prompt". | |
8701 | |
8702 The callback is invoked when pressing Enter. The current | |
8703 buffer will always be the prompt buffer. A new line for a | |
8704 prompt is added before invoking the callback, thus the prompt | |
8705 for which the callback was invoked will be in the last but one | |
8706 line. | |
8707 If the callback wants to add text to the buffer, it must | |
8708 insert it above the last line, since that is where the current | |
8709 prompt is. This can also be done asynchronously. | |
8710 The callback is invoked with one argument, which is the text | |
8711 that was entered at the prompt. This can be an empty string | |
8712 if the user only typed Enter. | |
8713 Example: > | |
8714 call prompt_setcallback(bufnr(), function('s:TextEntered')) | |
8715 func s:TextEntered(text) | |
8716 if a:text == 'exit' || a:text == 'quit' | |
8717 stopinsert | |
8718 close | |
8719 else | |
8720 call append(line('$') - 1, 'Entered: "' . a:text . '"') | |
8721 " Reset 'modified' to allow the buffer to be closed. | |
8722 set nomodified | |
8723 endif | |
8724 endfunc | |
8725 | |
8726 < Can also be used as a |method|: > | |
8727 GetBuffer()->prompt_setcallback(callback) | |
8728 | |
8729 < {only available when compiled with the |+channel| feature} | |
8730 | |
8731 prompt_setinterrupt({buf}, {expr}) *prompt_setinterrupt()* | |
8732 Set a callback for buffer {buf} to {expr}. When {expr} is an | |
8733 empty string the callback is removed. This has only effect if | |
8734 {buf} has 'buftype' set to "prompt". | |
8735 | |
8736 This callback will be invoked when pressing CTRL-C in Insert | |
8737 mode. Without setting a callback Vim will exit Insert mode, | |
8738 as in any buffer. | |
8739 | |
8740 Can also be used as a |method|: > | |
8741 GetBuffer()->prompt_setinterrupt(callback) | |
8742 | |
8743 < {only available when compiled with the |+channel| feature} | |
8744 | |
8745 prompt_setprompt({buf}, {text}) *prompt_setprompt()* | |
8746 Set prompt for buffer {buf} to {text}. You most likely want | |
8747 {text} to end in a space. | |
8748 The result is only visible if {buf} has 'buftype' set to | |
8749 "prompt". Example: > | |
8750 call prompt_setprompt(bufnr(), 'command: ') | |
8751 < | |
8752 Can also be used as a |method|: > | |
8753 GetBuffer()->prompt_setprompt('command: ') | |
8754 | |
8755 < {only available when compiled with the |+channel| feature} | |
8756 | |
8757 prop_ functions are documented here: |text-prop-functions| | |
8758 | |
8759 pum_getpos() *pum_getpos()* | |
8760 If the popup menu (see |ins-completion-menu|) is not visible, | |
8761 returns an empty |Dictionary|, otherwise, returns a | |
8762 |Dictionary| with the following keys: | |
8763 height nr of items visible | |
8764 width screen cells | |
8765 row top screen row (0 first row) | |
8766 col leftmost screen column (0 first col) | |
8767 size total nr of items | |
8768 scrollbar |TRUE| if scrollbar is visible | |
8769 | |
8770 The values are the same as in |v:event| during | |
8771 |CompleteChanged|. | |
8772 | |
8773 pumvisible() *pumvisible()* | |
8774 Returns non-zero when the popup menu is visible, zero | |
8775 otherwise. See |ins-completion-menu|. | |
8776 This can be used to avoid some things that would remove the | |
8777 popup menu. | |
8778 | |
8779 py3eval({expr}) *py3eval()* | |
8780 Evaluate Python expression {expr} and return its result | |
8781 converted to Vim data structures. | |
8782 Numbers and strings are returned as they are (strings are | |
8783 copied though, Unicode strings are additionally converted to | |
8784 'encoding'). | |
8785 Lists are represented as Vim |List| type. | |
8786 Dictionaries are represented as Vim |Dictionary| type with | |
8787 keys converted to strings. | |
8788 Note that in a `:def` function local variables are not visible | |
8789 to {expr}. | |
8790 | |
8791 Can also be used as a |method|: > | |
8792 GetExpr()->py3eval() | |
8793 | |
8794 < {only available when compiled with the |+python3| feature} | |
8795 | |
8796 *E858* *E859* | |
8797 pyeval({expr}) *pyeval()* | |
8798 Evaluate Python expression {expr} and return its result | |
8799 converted to Vim data structures. | |
8800 Numbers and strings are returned as they are (strings are | |
8801 copied though). | |
8802 Lists are represented as Vim |List| type. | |
8803 Dictionaries are represented as Vim |Dictionary| type, | |
8804 non-string keys result in error. | |
8805 Note that in a `:def` function local variables are not visible | |
8806 to {expr}. | |
8807 | |
8808 Can also be used as a |method|: > | |
8809 GetExpr()->pyeval() | |
8810 | |
8811 < {only available when compiled with the |+python| feature} | |
8812 | |
8813 pyxeval({expr}) *pyxeval()* | |
8814 Evaluate Python expression {expr} and return its result | |
8815 converted to Vim data structures. | |
8816 Uses Python 2 or 3, see |python_x| and 'pyxversion'. | |
8817 See also: |pyeval()|, |py3eval()| | |
8818 | |
8819 Can also be used as a |method|: > | |
8820 GetExpr()->pyxeval() | |
8821 | |
8822 < {only available when compiled with the |+python| or the | |
8823 |+python3| feature} | |
8824 | |
8825 rand([{expr}]) *rand()* *random* | |
8826 Return a pseudo-random Number generated with an xoshiro128** | |
8827 algorithm using seed {expr}. The returned number is 32 bits, | |
8828 also on 64 bits systems, for consistency. | |
8829 {expr} can be initialized by |srand()| and will be updated by | |
8830 rand(). If {expr} is omitted, an internal seed value is used | |
8831 and updated. | |
8832 | |
8833 Examples: > | |
8834 :echo rand() | |
8835 :let seed = srand() | |
8836 :echo rand(seed) | |
8837 :echo rand(seed) % 16 " random number 0 - 15 | |
8838 < | |
8839 | |
8840 *E726* *E727* | |
8841 range({expr} [, {max} [, {stride}]]) *range()* | |
8842 Returns a |List| with Numbers: | |
8843 - If only {expr} is specified: [0, 1, ..., {expr} - 1] | |
8844 - If {max} is specified: [{expr}, {expr} + 1, ..., {max}] | |
8845 - If {stride} is specified: [{expr}, {expr} + {stride}, ..., | |
8846 {max}] (increasing {expr} with {stride} each time, not | |
8847 producing a value past {max}). | |
8848 When the maximum is one before the start the result is an | |
8849 empty list. When the maximum is more than one before the | |
8850 start this is an error. | |
8851 Examples: > | |
8852 range(4) " [0, 1, 2, 3] | |
8853 range(2, 4) " [2, 3, 4] | |
8854 range(2, 9, 3) " [2, 5, 8] | |
8855 range(2, -2, -1) " [2, 1, 0, -1, -2] | |
8856 range(0) " [] | |
8857 range(2, 0) " error! | |
8858 < | |
8859 Can also be used as a |method|: > | |
8860 GetExpr()->range() | |
8861 < | |
8862 | |
8863 readblob({fname}) *readblob()* | |
8864 Read file {fname} in binary mode and return a |Blob|. | |
8865 When the file can't be opened an error message is given and | |
8866 the result is an empty |Blob|. | |
8867 Also see |readfile()| and |writefile()|. | |
8868 | |
8869 | |
8870 readdir({directory} [, {expr} [, {dict}]]) *readdir()* | |
8871 Return a list with file and directory names in {directory}. | |
8872 You can also use |glob()| if you don't need to do complicated | |
8873 things, such as limiting the number of matches. | |
8874 The list will be sorted (case sensitive), see the {dict} | |
8875 argument below for changing the sort order. | |
8876 | |
8877 When {expr} is omitted all entries are included. | |
8878 When {expr} is given, it is evaluated to check what to do: | |
8879 If {expr} results in -1 then no further entries will | |
8880 be handled. | |
8881 If {expr} results in 0 then this entry will not be | |
8882 added to the list. | |
8883 If {expr} results in 1 then this entry will be added | |
8884 to the list. | |
8885 The entries "." and ".." are always excluded. | |
8886 Each time {expr} is evaluated |v:val| is set to the entry name. | |
8887 When {expr} is a function the name is passed as the argument. | |
8888 For example, to get a list of files ending in ".txt": > | |
8889 readdir(dirname, {n -> n =~ '.txt$'}) | |
8890 < To skip hidden and backup files: > | |
8891 readdir(dirname, {n -> n !~ '^\.\|\~$'}) | |
8892 | |
8893 < The optional {dict} argument allows for further custom | |
8894 values. Currently this is used to specify if and how sorting | |
8895 should be performed. The dict can have the following members: | |
8896 | |
8897 sort How to sort the result returned from the system. | |
8898 Valid values are: | |
8899 "none" do not sort (fastest method) | |
8900 "case" sort case sensitive (byte value of | |
8901 each character, technically, using | |
8902 strcmp()) (default) | |
8903 "icase" sort case insensitive (technically | |
8904 using strcasecmp()) | |
8905 "collate" sort using the collation order | |
8906 of the "POSIX" or "C" |locale| | |
8907 (technically using strcoll()) | |
8908 Other values are silently ignored. | |
8909 | |
8910 For example, to get a list of all files in the current | |
8911 directory without sorting the individual entries: > | |
8912 readdir('.', '1', #{sort: 'none'}) | |
8913 < If you want to get a directory tree: > | |
8914 function! s:tree(dir) | |
8915 return {a:dir : map(readdir(a:dir), | |
8916 \ {_, x -> isdirectory(x) ? | |
8917 \ {x : s:tree(a:dir . '/' . x)} : x})} | |
8918 endfunction | |
8919 echo s:tree(".") | |
8920 < | |
8921 Can also be used as a |method|: > | |
8922 GetDirName()->readdir() | |
8923 < | |
8924 readdirex({directory} [, {expr} [, {dict}]]) *readdirex()* | |
8925 Extended version of |readdir()|. | |
8926 Return a list of Dictionaries with file and directory | |
8927 information in {directory}. | |
8928 This is useful if you want to get the attributes of file and | |
8929 directory at the same time as getting a list of a directory. | |
8930 This is much faster than calling |readdir()| then calling | |
8931 |getfperm()|, |getfsize()|, |getftime()| and |getftype()| for | |
8932 each file and directory especially on MS-Windows. | |
8933 The list will by default be sorted by name (case sensitive), | |
8934 the sorting can be changed by using the optional {dict} | |
8935 argument, see |readdir()|. | |
8936 | |
8937 The Dictionary for file and directory information has the | |
8938 following items: | |
8939 group Group name of the entry. (Only on Unix) | |
8940 name Name of the entry. | |
8941 perm Permissions of the entry. See |getfperm()|. | |
8942 size Size of the entry. See |getfsize()|. | |
8943 time Timestamp of the entry. See |getftime()|. | |
8944 type Type of the entry. | |
8945 On Unix, almost same as |getftype()| except: | |
8946 Symlink to a dir "linkd" | |
8947 Other symlink "link" | |
8948 On MS-Windows: | |
8949 Normal file "file" | |
8950 Directory "dir" | |
8951 Junction "junction" | |
8952 Symlink to a dir "linkd" | |
8953 Other symlink "link" | |
8954 Other reparse point "reparse" | |
8955 user User name of the entry's owner. (Only on Unix) | |
8956 On Unix, if the entry is a symlink, the Dictionary includes | |
8957 the information of the target (except the "type" item). | |
8958 On MS-Windows, it includes the information of the symlink | |
8959 itself because of performance reasons. | |
8960 | |
8961 When {expr} is omitted all entries are included. | |
8962 When {expr} is given, it is evaluated to check what to do: | |
8963 If {expr} results in -1 then no further entries will | |
8964 be handled. | |
8965 If {expr} results in 0 then this entry will not be | |
8966 added to the list. | |
8967 If {expr} results in 1 then this entry will be added | |
8968 to the list. | |
8969 The entries "." and ".." are always excluded. | |
8970 Each time {expr} is evaluated |v:val| is set to a |Dictionary| | |
8971 of the entry. | |
8972 When {expr} is a function the entry is passed as the argument. | |
8973 For example, to get a list of files ending in ".txt": > | |
8974 readdirex(dirname, {e -> e.name =~ '.txt$'}) | |
8975 < | |
8976 For example, to get a list of all files in the current | |
8977 directory without sorting the individual entries: > | |
8978 readdirex(dirname, '1', #{sort: 'none'}) | |
8979 | |
8980 < | |
8981 Can also be used as a |method|: > | |
8982 GetDirName()->readdirex() | |
8983 < | |
8984 | |
8985 *readfile()* | |
8986 readfile({fname} [, {type} [, {max}]]) | |
8987 Read file {fname} and return a |List|, each line of the file | |
8988 as an item. Lines are broken at NL characters. Macintosh | |
8989 files separated with CR will result in a single long line | |
8990 (unless a NL appears somewhere). | |
8991 All NUL characters are replaced with a NL character. | |
8992 When {type} contains "b" binary mode is used: | |
8993 - When the last line ends in a NL an extra empty list item is | |
8994 added. | |
8995 - No CR characters are removed. | |
8996 Otherwise: | |
8997 - CR characters that appear before a NL are removed. | |
8998 - Whether the last line ends in a NL or not does not matter. | |
8999 - When 'encoding' is Unicode any UTF-8 byte order mark is | |
9000 removed from the text. | |
9001 When {max} is given this specifies the maximum number of lines | |
9002 to be read. Useful if you only want to check the first ten | |
9003 lines of a file: > | |
9004 :for line in readfile(fname, '', 10) | |
9005 : if line =~ 'Date' | echo line | endif | |
9006 :endfor | |
9007 < When {max} is negative -{max} lines from the end of the file | |
9008 are returned, or as many as there are. | |
9009 When {max} is zero the result is an empty list. | |
9010 Note that without {max} the whole file is read into memory. | |
9011 Also note that there is no recognition of encoding. Read a | |
9012 file into a buffer if you need to. | |
9013 Deprecated (use |readblob()| instead): When {type} contains | |
9014 "B" a |Blob| is returned with the binary data of the file | |
9015 unmodified. | |
9016 When the file can't be opened an error message is given and | |
9017 the result is an empty list. | |
9018 Also see |writefile()|. | |
9019 | |
9020 Can also be used as a |method|: > | |
9021 GetFileName()->readfile() | |
9022 | |
9023 reduce({object}, {func} [, {initial}]) *reduce()* *E998* | |
9024 {func} is called for every item in {object}, which can be a | |
9025 |String|, |List| or a |Blob|. {func} is called with two | |
9026 arguments: the result so far and current item. After | |
9027 processing all items the result is returned. | |
9028 | |
9029 {initial} is the initial result. When omitted, the first item | |
9030 in {object} is used and {func} is first called for the second | |
9031 item. If {initial} is not given and {object} is empty no | |
9032 result can be computed, an E998 error is given. | |
9033 | |
9034 Examples: > | |
9035 echo reduce([1, 3, 5], { acc, val -> acc + val }) | |
9036 echo reduce(['x', 'y'], { acc, val -> acc .. val }, 'a') | |
9037 echo reduce(0z1122, { acc, val -> 2 * acc + val }) | |
9038 echo reduce('xyz', { acc, val -> acc .. ',' .. val }) | |
9039 < | |
9040 Can also be used as a |method|: > | |
9041 echo mylist->reduce({ acc, val -> acc + val }, 0) | |
9042 | |
9043 | |
9044 reg_executing() *reg_executing()* | |
9045 Returns the single letter name of the register being executed. | |
9046 Returns an empty string when no register is being executed. | |
9047 See |@|. | |
9048 | |
9049 reg_recording() *reg_recording()* | |
9050 Returns the single letter name of the register being recorded. | |
9051 Returns an empty string when not recording. See |q|. | |
9052 | |
9053 reltime([{start} [, {end}]]) *reltime()* | |
9054 Return an item that represents a time value. The item is a | |
9055 list with items that depend on the system. In Vim 9 script | |
9056 list<any> can be used. | |
9057 The item can be passed to |reltimestr()| to convert it to a | |
9058 string or |reltimefloat()| to convert to a Float. | |
9059 | |
9060 Without an argument reltime() returns the current time. | |
9061 With one argument is returns the time passed since the time | |
9062 specified in the argument. | |
9063 With two arguments it returns the time passed between {start} | |
9064 and {end}. | |
9065 | |
9066 The {start} and {end} arguments must be values returned by | |
9067 reltime(). If there is an error zero is returned in legacy | |
9068 script, in Vim9 script an error is given. | |
9069 | |
9070 Can also be used as a |method|: > | |
9071 GetStart()->reltime() | |
9072 < | |
9073 {only available when compiled with the |+reltime| feature} | |
9074 | |
9075 reltimefloat({time}) *reltimefloat()* | |
9076 Return a Float that represents the time value of {time}. | |
9077 Example: > | |
9078 let start = reltime() | |
9079 call MyFunction() | |
9080 let seconds = reltimefloat(reltime(start)) | |
9081 < See the note of reltimestr() about overhead. | |
9082 Also see |profiling|. | |
9083 If there is an error 0.0 is returned in legacy script, in Vim9 | |
9084 script an error is given. | |
9085 | |
9086 Can also be used as a |method|: > | |
9087 reltime(start)->reltimefloat() | |
9088 | |
9089 < {only available when compiled with the |+reltime| feature} | |
9090 | |
9091 reltimestr({time}) *reltimestr()* | |
9092 Return a String that represents the time value of {time}. | |
9093 This is the number of seconds, a dot and the number of | |
9094 microseconds. Example: > | |
9095 let start = reltime() | |
9096 call MyFunction() | |
9097 echo reltimestr(reltime(start)) | |
9098 < Note that overhead for the commands will be added to the time. | |
9099 The accuracy depends on the system. | |
9100 Leading spaces are used to make the string align nicely. You | |
9101 can use split() to remove it. > | |
9102 echo split(reltimestr(reltime(start)))[0] | |
9103 < Also see |profiling|. | |
9104 If there is an error an empty string is returned in legacy | |
9105 script, in Vim9 script an error is given. | |
9106 | |
9107 Can also be used as a |method|: > | |
9108 reltime(start)->reltimestr() | |
9109 | |
9110 < {only available when compiled with the |+reltime| feature} | |
9111 | |
9112 *remote_expr()* *E449* | |
9113 remote_expr({server}, {string} [, {idvar} [, {timeout}]]) | |
9114 Send the {string} to {server}. The string is sent as an | |
9115 expression and the result is returned after evaluation. | |
9116 The result must be a String or a |List|. A |List| is turned | |
9117 into a String by joining the items with a line break in | |
9118 between (not at the end), like with join(expr, "\n"). | |
9119 If {idvar} is present and not empty, it is taken as the name | |
9120 of a variable and a {serverid} for later use with | |
9121 |remote_read()| is stored there. | |
9122 If {timeout} is given the read times out after this many | |
9123 seconds. Otherwise a timeout of 600 seconds is used. | |
9124 See also |clientserver| |RemoteReply|. | |
9125 This function is not available in the |sandbox|. | |
9126 {only available when compiled with the |+clientserver| feature} | |
9127 Note: Any errors will cause a local error message to be issued | |
9128 and the result will be the empty string. | |
9129 | |
9130 Variables will be evaluated in the global namespace, | |
9131 independent of a function currently being active. Except | |
9132 when in debug mode, then local function variables and | |
9133 arguments can be evaluated. | |
9134 | |
9135 Examples: > | |
9136 :echo remote_expr("gvim", "2+2") | |
9137 :echo remote_expr("gvim1", "b:current_syntax") | |
9138 < | |
9139 Can also be used as a |method|: > | |
9140 ServerName()->remote_expr(expr) | |
9141 | |
9142 remote_foreground({server}) *remote_foreground()* | |
9143 Move the Vim server with the name {server} to the foreground. | |
9144 The {server} argument is a string. | |
9145 This works like: > | |
9146 remote_expr({server}, "foreground()") | |
9147 < Except that on Win32 systems the client does the work, to work | |
9148 around the problem that the OS doesn't always allow the server | |
9149 to bring itself to the foreground. | |
9150 Note: This does not restore the window if it was minimized, | |
9151 like foreground() does. | |
9152 This function is not available in the |sandbox|. | |
9153 | |
9154 Can also be used as a |method|: > | |
9155 ServerName()->remote_foreground() | |
9156 | |
9157 < {only in the Win32, Athena, Motif and GTK GUI versions and the | |
9158 Win32 console version} | |
9159 | |
9160 | |
9161 remote_peek({serverid} [, {retvar}]) *remote_peek()* | |
9162 Returns a positive number if there are available strings | |
9163 from {serverid}. Copies any reply string into the variable | |
9164 {retvar} if specified. {retvar} must be a string with the | |
9165 name of a variable. | |
9166 Returns zero if none are available. | |
9167 Returns -1 if something is wrong. | |
9168 See also |clientserver|. | |
9169 This function is not available in the |sandbox|. | |
9170 {only available when compiled with the |+clientserver| feature} | |
9171 Examples: > | |
9172 :let repl = "" | |
9173 :echo "PEEK: ".remote_peek(id, "repl").": ".repl | |
9174 | |
9175 < Can also be used as a |method|: > | |
9176 ServerId()->remote_peek() | |
9177 | |
9178 remote_read({serverid}, [{timeout}]) *remote_read()* | |
9179 Return the oldest available reply from {serverid} and consume | |
9180 it. Unless a {timeout} in seconds is given, it blocks until a | |
9181 reply is available. | |
9182 See also |clientserver|. | |
9183 This function is not available in the |sandbox|. | |
9184 {only available when compiled with the |+clientserver| feature} | |
9185 Example: > | |
9186 :echo remote_read(id) | |
9187 | |
9188 < Can also be used as a |method|: > | |
9189 ServerId()->remote_read() | |
9190 < | |
9191 *remote_send()* *E241* | |
9192 remote_send({server}, {string} [, {idvar}]) | |
9193 Send the {string} to {server}. The string is sent as input | |
9194 keys and the function returns immediately. At the Vim server | |
9195 the keys are not mapped |:map|. | |
9196 If {idvar} is present, it is taken as the name of a variable | |
9197 and a {serverid} for later use with remote_read() is stored | |
9198 there. | |
9199 See also |clientserver| |RemoteReply|. | |
9200 This function is not available in the |sandbox|. | |
9201 {only available when compiled with the |+clientserver| feature} | |
9202 | |
9203 Note: Any errors will be reported in the server and may mess | |
9204 up the display. | |
9205 Examples: > | |
9206 :echo remote_send("gvim", ":DropAndReply ".file, "serverid"). | |
9207 \ remote_read(serverid) | |
9208 | |
9209 :autocmd NONE RemoteReply * | |
9210 \ echo remote_read(expand("<amatch>")) | |
9211 :echo remote_send("gvim", ":sleep 10 | echo ". | |
9212 \ 'server2client(expand("<client>"), "HELLO")<CR>') | |
9213 < | |
9214 Can also be used as a |method|: > | |
9215 ServerName()->remote_send(keys) | |
9216 < | |
9217 *remote_startserver()* *E941* *E942* | |
9218 remote_startserver({name}) | |
9219 Become the server {name}. This fails if already running as a | |
9220 server, when |v:servername| is not empty. | |
9221 | |
9222 Can also be used as a |method|: > | |
9223 ServerName()->remote_startserver() | |
9224 | |
9225 < {only available when compiled with the |+clientserver| feature} | |
9226 | |
9227 remove({list}, {idx} [, {end}]) *remove()* | |
9228 Without {end}: Remove the item at {idx} from |List| {list} and | |
9229 return the item. | |
9230 With {end}: Remove items from {idx} to {end} (inclusive) and | |
9231 return a |List| with these items. When {idx} points to the same | |
9232 item as {end} a list with one item is returned. When {end} | |
9233 points to an item before {idx} this is an error. | |
9234 See |list-index| for possible values of {idx} and {end}. | |
9235 Example: > | |
9236 :echo "last item: " . remove(mylist, -1) | |
9237 :call remove(mylist, 0, 9) | |
9238 < | |
9239 Use |delete()| to remove a file. | |
9240 | |
9241 Can also be used as a |method|: > | |
9242 mylist->remove(idx) | |
9243 | |
9244 remove({blob}, {idx} [, {end}]) | |
9245 Without {end}: Remove the byte at {idx} from |Blob| {blob} and | |
9246 return the byte. | |
9247 With {end}: Remove bytes from {idx} to {end} (inclusive) and | |
9248 return a |Blob| with these bytes. When {idx} points to the same | |
9249 byte as {end} a |Blob| with one byte is returned. When {end} | |
9250 points to a byte before {idx} this is an error. | |
9251 Example: > | |
9252 :echo "last byte: " . remove(myblob, -1) | |
9253 :call remove(mylist, 0, 9) | |
9254 | |
9255 remove({dict}, {key}) | |
9256 Remove the entry from {dict} with key {key} and return it. | |
9257 Example: > | |
9258 :echo "removed " . remove(dict, "one") | |
9259 < If there is no {key} in {dict} this is an error. | |
9260 | |
9261 rename({from}, {to}) *rename()* | |
9262 Rename the file by the name {from} to the name {to}. This | |
9263 should also work to move files across file systems. The | |
9264 result is a Number, which is 0 if the file was renamed | |
9265 successfully, and non-zero when the renaming failed. | |
9266 NOTE: If {to} exists it is overwritten without warning. | |
9267 This function is not available in the |sandbox|. | |
9268 | |
9269 Can also be used as a |method|: > | |
9270 GetOldName()->rename(newname) | |
9271 | |
9272 repeat({expr}, {count}) *repeat()* | |
9273 Repeat {expr} {count} times and return the concatenated | |
9274 result. Example: > | |
9275 :let separator = repeat('-', 80) | |
9276 < When {count} is zero or negative the result is empty. | |
9277 When {expr} is a |List| the result is {expr} concatenated | |
9278 {count} times. Example: > | |
9279 :let longlist = repeat(['a', 'b'], 3) | |
9280 < Results in ['a', 'b', 'a', 'b', 'a', 'b']. | |
9281 | |
9282 Can also be used as a |method|: > | |
9283 mylist->repeat(count) | |
9284 | |
9285 resolve({filename}) *resolve()* *E655* | |
9286 On MS-Windows, when {filename} is a shortcut (a .lnk file), | |
9287 returns the path the shortcut points to in a simplified form. | |
9288 When {filename} is a symbolic link or junction point, return | |
9289 the full path to the target. If the target of junction is | |
9290 removed, return {filename}. | |
9291 On Unix, repeat resolving symbolic links in all path | |
9292 components of {filename} and return the simplified result. | |
9293 To cope with link cycles, resolving of symbolic links is | |
9294 stopped after 100 iterations. | |
9295 On other systems, return the simplified {filename}. | |
9296 The simplification step is done as by |simplify()|. | |
9297 resolve() keeps a leading path component specifying the | |
9298 current directory (provided the result is still a relative | |
9299 path name) and also keeps a trailing path separator. | |
9300 | |
9301 Can also be used as a |method|: > | |
9302 GetName()->resolve() | |
9303 | |
9304 reverse({object}) *reverse()* | |
9305 Reverse the order of items in {object} in-place. | |
9306 {object} can be a |List| or a |Blob|. | |
9307 Returns {object}. | |
9308 If you want an object to remain unmodified make a copy first: > | |
9309 :let revlist = reverse(copy(mylist)) | |
9310 < Can also be used as a |method|: > | |
9311 mylist->reverse() | |
9312 | |
9313 round({expr}) *round()* | |
9314 Round off {expr} to the nearest integral value and return it | |
9315 as a |Float|. If {expr} lies halfway between two integral | |
9316 values, then use the larger one (away from zero). | |
9317 {expr} must evaluate to a |Float| or a |Number|. | |
9318 Examples: > | |
9319 echo round(0.456) | |
9320 < 0.0 > | |
9321 echo round(4.5) | |
9322 < 5.0 > | |
9323 echo round(-4.5) | |
9324 < -5.0 | |
9325 | |
9326 Can also be used as a |method|: > | |
9327 Compute()->round() | |
9328 < | |
9329 {only available when compiled with the |+float| feature} | |
9330 | |
9331 rubyeval({expr}) *rubyeval()* | |
9332 Evaluate Ruby expression {expr} and return its result | |
9333 converted to Vim data structures. | |
9334 Numbers, floats and strings are returned as they are (strings | |
9335 are copied though). | |
9336 Arrays are represented as Vim |List| type. | |
9337 Hashes are represented as Vim |Dictionary| type. | |
9338 Other objects are represented as strings resulted from their | |
9339 "Object#to_s" method. | |
9340 Note that in a `:def` function local variables are not visible | |
9341 to {expr}. | |
9342 | |
9343 Can also be used as a |method|: > | |
9344 GetRubyExpr()->rubyeval() | |
9345 | |
9346 < {only available when compiled with the |+ruby| feature} | |
9347 | |
9348 screenattr({row}, {col}) *screenattr()* | |
9349 Like |screenchar()|, but return the attribute. This is a rather | |
9350 arbitrary number that can only be used to compare to the | |
9351 attribute at other positions. | |
9352 | |
9353 Can also be used as a |method|: > | |
9354 GetRow()->screenattr(col) | |
9355 | |
9356 screenchar({row}, {col}) *screenchar()* | |
9357 The result is a Number, which is the character at position | |
9358 [row, col] on the screen. This works for every possible | |
9359 screen position, also status lines, window separators and the | |
9360 command line. The top left position is row one, column one | |
9361 The character excludes composing characters. For double-byte | |
9362 encodings it may only be the first byte. | |
9363 This is mainly to be used for testing. | |
9364 Returns -1 when row or col is out of range. | |
9365 | |
9366 Can also be used as a |method|: > | |
9367 GetRow()->screenchar(col) | |
9368 | |
9369 screenchars({row}, {col}) *screenchars()* | |
9370 The result is a |List| of Numbers. The first number is the same | |
9371 as what |screenchar()| returns. Further numbers are | |
9372 composing characters on top of the base character. | |
9373 This is mainly to be used for testing. | |
9374 Returns an empty List when row or col is out of range. | |
9375 | |
9376 Can also be used as a |method|: > | |
9377 GetRow()->screenchars(col) | |
9378 | |
9379 screencol() *screencol()* | |
9380 The result is a Number, which is the current screen column of | |
9381 the cursor. The leftmost column has number 1. | |
9382 This function is mainly used for testing. | |
9383 | |
9384 Note: Always returns the current screen column, thus if used | |
9385 in a command (e.g. ":echo screencol()") it will return the | |
9386 column inside the command line, which is 1 when the command is | |
9387 executed. To get the cursor position in the file use one of | |
9388 the following mappings: > | |
9389 nnoremap <expr> GG ":echom ".screencol()."\n" | |
9390 nnoremap <silent> GG :echom screencol()<CR> | |
9391 nnoremap GG <Cmd>echom screencol()<CR> | |
9392 < | |
9393 screenpos({winid}, {lnum}, {col}) *screenpos()* | |
9394 The result is a Dict with the screen position of the text | |
9395 character in window {winid} at buffer line {lnum} and column | |
9396 {col}. {col} is a one-based byte index. | |
9397 The Dict has these members: | |
9398 row screen row | |
9399 col first screen column | |
9400 endcol last screen column | |
9401 curscol cursor screen column | |
9402 If the specified position is not visible, all values are zero. | |
9403 The "endcol" value differs from "col" when the character | |
9404 occupies more than one screen cell. E.g. for a Tab "col" can | |
9405 be 1 and "endcol" can be 8. | |
9406 The "curscol" value is where the cursor would be placed. For | |
9407 a Tab it would be the same as "endcol", while for a double | |
9408 width character it would be the same as "col". | |
9409 The |conceal| feature is ignored here, the column numbers are | |
9410 as if 'conceallevel' is zero. You can set the cursor to the | |
9411 right position and use |screencol()| to get the value with | |
9412 |conceal| taken into account. | |
9413 | |
9414 Can also be used as a |method|: > | |
9415 GetWinid()->screenpos(lnum, col) | |
9416 | |
9417 screenrow() *screenrow()* | |
9418 The result is a Number, which is the current screen row of the | |
9419 cursor. The top line has number one. | |
9420 This function is mainly used for testing. | |
9421 Alternatively you can use |winline()|. | |
9422 | |
9423 Note: Same restrictions as with |screencol()|. | |
9424 | |
9425 screenstring({row}, {col}) *screenstring()* | |
9426 The result is a String that contains the base character and | |
9427 any composing characters at position [row, col] on the screen. | |
9428 This is like |screenchars()| but returning a String with the | |
9429 characters. | |
9430 This is mainly to be used for testing. | |
9431 Returns an empty String when row or col is out of range. | |
9432 | |
9433 Can also be used as a |method|: > | |
9434 GetRow()->screenstring(col) | |
9435 < | |
9436 *search()* | |
9437 search({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
9438 Search for regexp pattern {pattern}. The search starts at the | |
9439 cursor position (you can use |cursor()| to set it). | |
9440 | |
9441 When a match has been found its line number is returned. | |
9442 If there is no match a 0 is returned and the cursor doesn't | |
9443 move. No error message is given. | |
9444 | |
9445 {flags} is a String, which can contain these character flags: | |
9446 'b' search Backward instead of forward | |
9447 'c' accept a match at the Cursor position | |
9448 'e' move to the End of the match | |
9449 'n' do Not move the cursor | |
9450 'p' return number of matching sub-Pattern (see below) | |
9451 's' Set the ' mark at the previous location of the cursor | |
9452 'w' Wrap around the end of the file | |
9453 'W' don't Wrap around the end of the file | |
9454 'z' start searching at the cursor column instead of zero | |
9455 If neither 'w' or 'W' is given, the 'wrapscan' option applies. | |
9456 | |
9457 If the 's' flag is supplied, the ' mark is set, only if the | |
9458 cursor is moved. The 's' flag cannot be combined with the 'n' | |
9459 flag. | |
9460 | |
9461 'ignorecase', 'smartcase' and 'magic' are used. | |
9462 | |
9463 When the 'z' flag is not given, forward searching always | |
9464 starts in column zero and then matches before the cursor are | |
9465 skipped. When the 'c' flag is present in 'cpo' the next | |
9466 search starts after the match. Without the 'c' flag the next | |
9467 search starts one column further. This matters for | |
9468 overlapping matches. | |
9469 When searching backwards and the 'z' flag is given then the | |
9470 search starts in column zero, thus no match in the current | |
9471 line will be found (unless wrapping around the end of the | |
9472 file). | |
9473 | |
9474 When the {stopline} argument is given then the search stops | |
9475 after searching this line. This is useful to restrict the | |
9476 search to a range of lines. Examples: > | |
9477 let match = search('(', 'b', line("w0")) | |
9478 let end = search('END', '', line("w$")) | |
9479 < When {stopline} is used and it is not zero this also implies | |
9480 that the search does not wrap around the end of the file. | |
9481 A zero value is equal to not giving the argument. | |
9482 | |
9483 When the {timeout} argument is given the search stops when | |
9484 more than this many milliseconds have passed. Thus when | |
9485 {timeout} is 500 the search stops after half a second. | |
9486 The value must not be negative. A zero value is like not | |
9487 giving the argument. | |
9488 {only available when compiled with the |+reltime| feature} | |
9489 | |
9490 If the {skip} expression is given it is evaluated with the | |
9491 cursor positioned on the start of a match. If it evaluates to | |
9492 non-zero this match is skipped. This can be used, for | |
9493 example, to skip a match in a comment or a string. | |
9494 {skip} can be a string, which is evaluated as an expression, a | |
9495 function reference or a lambda. | |
9496 When {skip} is omitted or empty, every match is accepted. | |
9497 When evaluating {skip} causes an error the search is aborted | |
9498 and -1 returned. | |
9499 *search()-sub-match* | |
9500 With the 'p' flag the returned value is one more than the | |
9501 first sub-match in \(\). One if none of them matched but the | |
9502 whole pattern did match. | |
9503 To get the column number too use |searchpos()|. | |
9504 | |
9505 The cursor will be positioned at the match, unless the 'n' | |
9506 flag is used. | |
9507 | |
9508 Example (goes over all files in the argument list): > | |
9509 :let n = 1 | |
9510 :while n <= argc() " loop over all files in arglist | |
9511 : exe "argument " . n | |
9512 : " start at the last char in the file and wrap for the | |
9513 : " first search to find match at start of file | |
9514 : normal G$ | |
9515 : let flags = "w" | |
9516 : while search("foo", flags) > 0 | |
9517 : s/foo/bar/g | |
9518 : let flags = "W" | |
9519 : endwhile | |
9520 : update " write the file if modified | |
9521 : let n = n + 1 | |
9522 :endwhile | |
9523 < | |
9524 Example for using some flags: > | |
9525 :echo search('\<if\|\(else\)\|\(endif\)', 'ncpe') | |
9526 < This will search for the keywords "if", "else", and "endif" | |
9527 under or after the cursor. Because of the 'p' flag, it | |
9528 returns 1, 2, or 3 depending on which keyword is found, or 0 | |
9529 if the search fails. With the cursor on the first word of the | |
9530 line: | |
9531 if (foo == 0) | let foo = foo + 1 | endif ~ | |
9532 the function returns 1. Without the 'c' flag, the function | |
9533 finds the "endif" and returns 3. The same thing happens | |
9534 without the 'e' flag if the cursor is on the "f" of "if". | |
9535 The 'n' flag tells the function not to move the cursor. | |
9536 | |
9537 Can also be used as a |method|: > | |
9538 GetPattern()->search() | |
9539 | |
9540 searchcount([{options}]) *searchcount()* | |
9541 Get or update the last search count, like what is displayed | |
9542 without the "S" flag in 'shortmess'. This works even if | |
9543 'shortmess' does contain the "S" flag. | |
9544 | |
9545 This returns a |Dictionary|. The dictionary is empty if the | |
9546 previous pattern was not set and "pattern" was not specified. | |
9547 | |
9548 key type meaning ~ | |
9549 current |Number| current position of match; | |
9550 0 if the cursor position is | |
9551 before the first match | |
9552 exact_match |Boolean| 1 if "current" is matched on | |
9553 "pos", otherwise 0 | |
9554 total |Number| total count of matches found | |
9555 incomplete |Number| 0: search was fully completed | |
9556 1: recomputing was timed out | |
9557 2: max count exceeded | |
9558 | |
9559 For {options} see further down. | |
9560 | |
9561 To get the last search count when |n| or |N| was pressed, call | |
9562 this function with `recompute: 0` . This sometimes returns | |
9563 wrong information because |n| and |N|'s maximum count is 99. | |
9564 If it exceeded 99 the result must be max count + 1 (100). If | |
9565 you want to get correct information, specify `recompute: 1`: > | |
9566 | |
9567 " result == maxcount + 1 (100) when many matches | |
9568 let result = searchcount(#{recompute: 0}) | |
9569 | |
9570 " Below returns correct result (recompute defaults | |
9571 " to 1) | |
9572 let result = searchcount() | |
9573 < | |
9574 The function is useful to add the count to |statusline|: > | |
9575 function! LastSearchCount() abort | |
9576 let result = searchcount(#{recompute: 0}) | |
9577 if empty(result) | |
9578 return '' | |
9579 endif | |
9580 if result.incomplete ==# 1 " timed out | |
9581 return printf(' /%s [?/??]', @/) | |
9582 elseif result.incomplete ==# 2 " max count exceeded | |
9583 if result.total > result.maxcount && | |
9584 \ result.current > result.maxcount | |
9585 return printf(' /%s [>%d/>%d]', @/, | |
9586 \ result.current, result.total) | |
9587 elseif result.total > result.maxcount | |
9588 return printf(' /%s [%d/>%d]', @/, | |
9589 \ result.current, result.total) | |
9590 endif | |
9591 endif | |
9592 return printf(' /%s [%d/%d]', @/, | |
9593 \ result.current, result.total) | |
9594 endfunction | |
9595 let &statusline .= '%{LastSearchCount()}' | |
9596 | |
9597 " Or if you want to show the count only when | |
9598 " 'hlsearch' was on | |
9599 " let &statusline .= | |
9600 " \ '%{v:hlsearch ? LastSearchCount() : ""}' | |
9601 < | |
9602 You can also update the search count, which can be useful in a | |
9603 |CursorMoved| or |CursorMovedI| autocommand: > | |
9604 | |
9605 autocmd CursorMoved,CursorMovedI * | |
9606 \ let s:searchcount_timer = timer_start( | |
9607 \ 200, function('s:update_searchcount')) | |
9608 function! s:update_searchcount(timer) abort | |
9609 if a:timer ==# s:searchcount_timer | |
9610 call searchcount(#{ | |
9611 \ recompute: 1, maxcount: 0, timeout: 100}) | |
9612 redrawstatus | |
9613 endif | |
9614 endfunction | |
9615 < | |
9616 This can also be used to count matched texts with specified | |
9617 pattern in the current buffer using "pattern": > | |
9618 | |
9619 " Count '\<foo\>' in this buffer | |
9620 " (Note that it also updates search count) | |
9621 let result = searchcount(#{pattern: '\<foo\>'}) | |
9622 | |
9623 " To restore old search count by old pattern, | |
9624 " search again | |
9625 call searchcount() | |
9626 < | |
9627 {options} must be a |Dictionary|. It can contain: | |
9628 key type meaning ~ | |
9629 recompute |Boolean| if |TRUE|, recompute the count | |
9630 like |n| or |N| was executed. | |
9631 otherwise returns the last | |
9632 computed result (when |n| or | |
9633 |N| was used when "S" is not | |
9634 in 'shortmess', or this | |
9635 function was called). | |
9636 (default: |TRUE|) | |
9637 pattern |String| recompute if this was given | |
9638 and different with |@/|. | |
9639 this works as same as the | |
9640 below command is executed | |
9641 before calling this function > | |
9642 let @/ = pattern | |
9643 < (default: |@/|) | |
9644 timeout |Number| 0 or negative number is no | |
9645 timeout. timeout milliseconds | |
9646 for recomputing the result | |
9647 (default: 0) | |
9648 maxcount |Number| 0 or negative number is no | |
9649 limit. max count of matched | |
9650 text while recomputing the | |
9651 result. if search exceeded | |
9652 total count, "total" value | |
9653 becomes `maxcount + 1` | |
9654 (default: 99) | |
9655 pos |List| `[lnum, col, off]` value | |
9656 when recomputing the result. | |
9657 this changes "current" result | |
9658 value. see |cursor()|, | |
9659 |getpos()| | |
9660 (default: cursor's position) | |
9661 | |
9662 Can also be used as a |method|: > | |
9663 GetSearchOpts()->searchcount() | |
9664 < | |
9665 searchdecl({name} [, {global} [, {thisblock}]]) *searchdecl()* | |
9666 Search for the declaration of {name}. | |
9667 | |
9668 With a non-zero {global} argument it works like |gD|, find | |
9669 first match in the file. Otherwise it works like |gd|, find | |
9670 first match in the function. | |
9671 | |
9672 With a non-zero {thisblock} argument matches in a {} block | |
9673 that ends before the cursor position are ignored. Avoids | |
9674 finding variable declarations only valid in another scope. | |
9675 | |
9676 Moves the cursor to the found match. | |
9677 Returns zero for success, non-zero for failure. | |
9678 Example: > | |
9679 if searchdecl('myvar') == 0 | |
9680 echo getline('.') | |
9681 endif | |
9682 < | |
9683 Can also be used as a |method|: > | |
9684 GetName()->searchdecl() | |
9685 < | |
9686 *searchpair()* | |
9687 searchpair({start}, {middle}, {end} [, {flags} [, {skip} | |
9688 [, {stopline} [, {timeout}]]]]) | |
9689 Search for the match of a nested start-end pair. This can be | |
9690 used to find the "endif" that matches an "if", while other | |
9691 if/endif pairs in between are ignored. | |
9692 The search starts at the cursor. The default is to search | |
9693 forward, include 'b' in {flags} to search backward. | |
9694 If a match is found, the cursor is positioned at it and the | |
9695 line number is returned. If no match is found 0 or -1 is | |
9696 returned and the cursor doesn't move. No error message is | |
9697 given. | |
9698 | |
9699 {start}, {middle} and {end} are patterns, see |pattern|. They | |
9700 must not contain \( \) pairs. Use of \%( \) is allowed. When | |
9701 {middle} is not empty, it is found when searching from either | |
9702 direction, but only when not in a nested start-end pair. A | |
9703 typical use is: > | |
9704 searchpair('\<if\>', '\<else\>', '\<endif\>') | |
9705 < By leaving {middle} empty the "else" is skipped. | |
9706 | |
9707 {flags} 'b', 'c', 'n', 's', 'w' and 'W' are used like with | |
9708 |search()|. Additionally: | |
9709 'r' Repeat until no more matches found; will find the | |
9710 outer pair. Implies the 'W' flag. | |
9711 'm' Return number of matches instead of line number with | |
9712 the match; will be > 1 when 'r' is used. | |
9713 Note: it's nearly always a good idea to use the 'W' flag, to | |
9714 avoid wrapping around the end of the file. | |
9715 | |
9716 When a match for {start}, {middle} or {end} is found, the | |
9717 {skip} expression is evaluated with the cursor positioned on | |
9718 the start of the match. It should return non-zero if this | |
9719 match is to be skipped. E.g., because it is inside a comment | |
9720 or a string. | |
9721 When {skip} is omitted or empty, every match is accepted. | |
9722 When evaluating {skip} causes an error the search is aborted | |
9723 and -1 returned. | |
9724 {skip} can be a string, a lambda, a funcref or a partial. | |
9725 Anything else makes the function fail. | |
9726 In a `:def` function when the {skip} argument is a string | |
9727 constant it is compiled into instructions. | |
9728 | |
9729 For {stopline} and {timeout} see |search()|. | |
9730 | |
9731 The value of 'ignorecase' is used. 'magic' is ignored, the | |
9732 patterns are used like it's on. | |
9733 | |
9734 The search starts exactly at the cursor. A match with | |
9735 {start}, {middle} or {end} at the next character, in the | |
9736 direction of searching, is the first one found. Example: > | |
9737 if 1 | |
9738 if 2 | |
9739 endif 2 | |
9740 endif 1 | |
9741 < When starting at the "if 2", with the cursor on the "i", and | |
9742 searching forwards, the "endif 2" is found. When starting on | |
9743 the character just before the "if 2", the "endif 1" will be | |
9744 found. That's because the "if 2" will be found first, and | |
9745 then this is considered to be a nested if/endif from "if 2" to | |
9746 "endif 2". | |
9747 When searching backwards and {end} is more than one character, | |
9748 it may be useful to put "\zs" at the end of the pattern, so | |
9749 that when the cursor is inside a match with the end it finds | |
9750 the matching start. | |
9751 | |
9752 Example, to find the "endif" command in a Vim script: > | |
9753 | |
9754 :echo searchpair('\<if\>', '\<el\%[seif]\>', '\<en\%[dif]\>', 'W', | |
9755 \ 'getline(".") =~ "^\\s*\""') | |
9756 | |
9757 < The cursor must be at or after the "if" for which a match is | |
9758 to be found. Note that single-quote strings are used to avoid | |
9759 having to double the backslashes. The skip expression only | |
9760 catches comments at the start of a line, not after a command. | |
9761 Also, a word "en" or "if" halfway a line is considered a | |
9762 match. | |
9763 Another example, to search for the matching "{" of a "}": > | |
9764 | |
9765 :echo searchpair('{', '', '}', 'bW') | |
9766 | |
9767 < This works when the cursor is at or before the "}" for which a | |
9768 match is to be found. To reject matches that syntax | |
9769 highlighting recognized as strings: > | |
9770 | |
9771 :echo searchpair('{', '', '}', 'bW', | |
9772 \ 'synIDattr(synID(line("."), col("."), 0), "name") =~? "string"') | |
9773 < | |
9774 *searchpairpos()* | |
9775 searchpairpos({start}, {middle}, {end} [, {flags} [, {skip} | |
9776 [, {stopline} [, {timeout}]]]]) | |
9777 Same as |searchpair()|, but returns a |List| with the line and | |
9778 column position of the match. The first element of the |List| | |
9779 is the line number and the second element is the byte index of | |
9780 the column position of the match. If no match is found, | |
9781 returns [0, 0]. > | |
9782 | |
9783 :let [lnum,col] = searchpairpos('{', '', '}', 'n') | |
9784 < | |
9785 See |match-parens| for a bigger and more useful example. | |
9786 | |
9787 *searchpos()* | |
9788 searchpos({pattern} [, {flags} [, {stopline} [, {timeout} [, {skip}]]]]) | |
9789 Same as |search()|, but returns a |List| with the line and | |
9790 column position of the match. The first element of the |List| | |
9791 is the line number and the second element is the byte index of | |
9792 the column position of the match. If no match is found, | |
9793 returns [0, 0]. | |
9794 Example: > | |
9795 :let [lnum, col] = searchpos('mypattern', 'n') | |
9796 | |
9797 < When the 'p' flag is given then there is an extra item with | |
9798 the sub-pattern match number |search()-sub-match|. Example: > | |
9799 :let [lnum, col, submatch] = searchpos('\(\l\)\|\(\u\)', 'np') | |
9800 < In this example "submatch" is 2 when a lowercase letter is | |
9801 found |/\l|, 3 when an uppercase letter is found |/\u|. | |
9802 | |
9803 Can also be used as a |method|: > | |
9804 GetPattern()->searchpos() | |
9805 | |
9806 server2client({clientid}, {string}) *server2client()* | |
9807 Send a reply string to {clientid}. The most recent {clientid} | |
9808 that sent a string can be retrieved with expand("<client>"). | |
9809 {only available when compiled with the |+clientserver| feature} | |
9810 Returns zero for success, -1 for failure. | |
9811 Note: | |
9812 This id has to be stored before the next command can be | |
9813 received. I.e. before returning from the received command and | |
9814 before calling any commands that waits for input. | |
9815 See also |clientserver|. | |
9816 Example: > | |
9817 :echo server2client(expand("<client>"), "HELLO") | |
9818 | |
9819 < Can also be used as a |method|: > | |
9820 GetClientId()->server2client(string) | |
9821 < | |
9822 serverlist() *serverlist()* | |
9823 Return a list of available server names, one per line. | |
9824 When there are no servers or the information is not available | |
9825 an empty string is returned. See also |clientserver|. | |
9826 {only available when compiled with the |+clientserver| feature} | |
9827 Example: > | |
9828 :echo serverlist() | |
9829 < | |
9830 setbufline({buf}, {lnum}, {text}) *setbufline()* | |
9831 Set line {lnum} to {text} in buffer {buf}. This works like | |
9832 |setline()| for the specified buffer. | |
9833 | |
9834 This function works only for loaded buffers. First call | |
9835 |bufload()| if needed. | |
9836 | |
9837 To insert lines use |appendbufline()|. | |
9838 Any text properties in {lnum} are cleared. | |
9839 | |
9840 {text} can be a string to set one line, or a list of strings | |
9841 to set multiple lines. If the list extends below the last | |
9842 line then those lines are added. | |
9843 | |
9844 For the use of {buf}, see |bufname()| above. | |
9845 | |
9846 {lnum} is used like with |setline()|. | |
9847 Use "$" to refer to the last line in buffer {buf}. | |
9848 When {lnum} is just below the last line the {text} will be | |
9849 added below the last line. | |
9850 | |
9851 When {buf} is not a valid buffer, the buffer is not loaded or | |
9852 {lnum} is not valid then 1 is returned. On success 0 is | |
9853 returned. | |
9854 | |
9855 Can also be used as a |method|, the base is passed as the | |
9856 third argument: > | |
9857 GetText()->setbufline(buf, lnum) | |
9858 | |
9859 setbufvar({buf}, {varname}, {val}) *setbufvar()* | |
9860 Set option or local variable {varname} in buffer {buf} to | |
9861 {val}. | |
9862 This also works for a global or local window option, but it | |
9863 doesn't work for a global or local window variable. | |
9864 For a local window option the global value is unchanged. | |
9865 For the use of {buf}, see |bufname()| above. | |
9866 The {varname} argument is a string. | |
9867 Note that the variable name without "b:" must be used. | |
9868 Examples: > | |
9869 :call setbufvar(1, "&mod", 1) | |
9870 :call setbufvar("todo", "myvar", "foobar") | |
9871 < This function is not available in the |sandbox|. | |
9872 | |
9873 Can also be used as a |method|, the base is passed as the | |
9874 third argument: > | |
9875 GetValue()->setbufvar(buf, varname) | |
9876 | |
9877 | |
9878 setcellwidths({list}) *setcellwidths()* | |
9879 Specify overrides for cell widths of character ranges. This | |
9880 tells Vim how wide characters are, counted in screen cells. | |
9881 This overrides 'ambiwidth'. Example: > | |
9882 setcellwidths([[0xad, 0xad, 1], | |
9883 \ [0x2194, 0x2199, 2]]) | |
9884 | |
9885 < *E1109* *E1110* *E1111* *E1112* *E1113* | |
9886 The {list} argument is a list of lists with each three | |
9887 numbers. These three numbers are [low, high, width]. "low" | |
9888 and "high" can be the same, in which case this refers to one | |
9889 character. Otherwise it is the range of characters from "low" | |
9890 to "high" (inclusive). "width" is either 1 or 2, indicating | |
9891 the character width in screen cells. | |
9892 An error is given if the argument is invalid, also when a | |
9893 range overlaps with another. | |
9894 Only characters with value 0x100 and higher can be used. | |
9895 | |
9896 If the new value causes 'fillchars' or 'listchars' to become | |
9897 invalid it is rejected and an error is given. | |
9898 | |
9899 To clear the overrides pass an empty list: > | |
9900 setcellwidths([]); | |
9901 < You can use the script $VIMRUNTIME/tools/emoji_list.vim to see | |
9902 the effect for known emoji characters. | |
9903 | |
9904 setcharpos({expr}, {list}) *setcharpos()* | |
9905 Same as |setpos()| but uses the specified column number as the | |
9906 character index instead of the byte index in the line. | |
9907 | |
9908 Example: | |
9909 With the text "여보세요" in line 8: > | |
9910 call setcharpos('.', [0, 8, 4, 0]) | |
9911 < positions the cursor on the fourth character '요'. > | |
9912 call setpos('.', [0, 8, 4, 0]) | |
9913 < positions the cursor on the second character '보'. | |
9914 | |
9915 Can also be used as a |method|: > | |
9916 GetPosition()->setcharpos('.') | |
9917 | |
9918 setcharsearch({dict}) *setcharsearch()* | |
9919 Set the current character search information to {dict}, | |
9920 which contains one or more of the following entries: | |
9921 | |
9922 char character which will be used for a subsequent | |
9923 |,| or |;| command; an empty string clears the | |
9924 character search | |
9925 forward direction of character search; 1 for forward, | |
9926 0 for backward | |
9927 until type of character search; 1 for a |t| or |T| | |
9928 character search, 0 for an |f| or |F| | |
9929 character search | |
9930 | |
9931 This can be useful to save/restore a user's character search | |
9932 from a script: > | |
9933 :let prevsearch = getcharsearch() | |
9934 :" Perform a command which clobbers user's search | |
9935 :call setcharsearch(prevsearch) | |
9936 < Also see |getcharsearch()|. | |
9937 | |
9938 Can also be used as a |method|: > | |
9939 SavedSearch()->setcharsearch() | |
9940 | |
9941 setcmdpos({pos}) *setcmdpos()* | |
9942 Set the cursor position in the command line to byte position | |
9943 {pos}. The first position is 1. | |
9944 Use |getcmdpos()| to obtain the current position. | |
9945 Only works while editing the command line, thus you must use | |
9946 |c_CTRL-\_e|, |c_CTRL-R_=| or |c_CTRL-R_CTRL-R| with '='. For | |
9947 |c_CTRL-\_e| and |c_CTRL-R_CTRL-R| with '=' the position is | |
9948 set after the command line is set to the expression. For | |
9949 |c_CTRL-R_=| it is set after evaluating the expression but | |
9950 before inserting the resulting text. | |
9951 When the number is too big the cursor is put at the end of the | |
9952 line. A number smaller than one has undefined results. | |
9953 Returns FALSE when successful, TRUE when not editing the | |
9954 command line. | |
9955 | |
9956 Can also be used as a |method|: > | |
9957 GetPos()->setcmdpos() | |
9958 | |
9959 setcursorcharpos({lnum}, {col} [, {off}]) *setcursorcharpos()* | |
9960 setcursorcharpos({list}) | |
9961 Same as |cursor()| but uses the specified column number as the | |
9962 character index instead of the byte index in the line. | |
9963 | |
9964 Example: | |
9965 With the text "여보세요" in line 4: > | |
9966 call setcursorcharpos(4, 3) | |
9967 < positions the cursor on the third character '세'. > | |
9968 call cursor(4, 3) | |
9969 < positions the cursor on the first character '여'. | |
9970 | |
9971 Can also be used as a |method|: > | |
9972 GetCursorPos()->setcursorcharpos() | |
9973 | |
9974 | |
9975 setenv({name}, {val}) *setenv()* | |
9976 Set environment variable {name} to {val}. Example: > | |
9977 call setenv('HOME', '/home/myhome') | |
9978 | |
9979 < When {val} is |v:null| the environment variable is deleted. | |
9980 See also |expr-env|. | |
9981 | |
9982 Can also be used as a |method|, the base is passed as the | |
9983 second argument: > | |
9984 GetPath()->setenv('PATH') | |
9985 | |
9986 setfperm({fname}, {mode}) *setfperm()* *chmod* | |
9987 Set the file permissions for {fname} to {mode}. | |
9988 {mode} must be a string with 9 characters. It is of the form | |
9989 "rwxrwxrwx", where each group of "rwx" flags represent, in | |
9990 turn, the permissions of the owner of the file, the group the | |
9991 file belongs to, and other users. A '-' character means the | |
9992 permission is off, any other character means on. Multi-byte | |
9993 characters are not supported. | |
9994 | |
9995 For example "rw-r-----" means read-write for the user, | |
9996 readable by the group, not accessible by others. "xx-x-----" | |
9997 would do the same thing. | |
9998 | |
9999 Returns non-zero for success, zero for failure. | |
10000 | |
10001 Can also be used as a |method|: > | |
10002 GetFilename()->setfperm(mode) | |
10003 < | |
10004 To read permissions see |getfperm()|. | |
10005 | |
10006 | |
10007 setline({lnum}, {text}) *setline()* | |
10008 Set line {lnum} of the current buffer to {text}. To insert | |
10009 lines use |append()|. To set lines in another buffer use | |
10010 |setbufline()|. Any text properties in {lnum} are cleared. | |
10011 | |
10012 {lnum} is used like with |getline()|. | |
10013 When {lnum} is just below the last line the {text} will be | |
10014 added below the last line. | |
10015 {text} can be any type or a List of any type, each item is | |
10016 converted to a String. | |
10017 | |
10018 If this succeeds, FALSE is returned. If this fails (most likely | |
10019 because {lnum} is invalid) TRUE is returned. | |
10020 | |
10021 Example: > | |
10022 :call setline(5, strftime("%c")) | |
10023 | |
10024 < When {text} is a |List| then line {lnum} and following lines | |
10025 will be set to the items in the list. Example: > | |
10026 :call setline(5, ['aaa', 'bbb', 'ccc']) | |
10027 < This is equivalent to: > | |
10028 :for [n, l] in [[5, 'aaa'], [6, 'bbb'], [7, 'ccc']] | |
10029 : call setline(n, l) | |
10030 :endfor | |
10031 | |
10032 < Note: The '[ and '] marks are not set. | |
10033 | |
10034 Can also be used as a |method|, the base is passed as the | |
10035 second argument: > | |
10036 GetText()->setline(lnum) | |
10037 | |
10038 setloclist({nr}, {list} [, {action} [, {what}]]) *setloclist()* | |
10039 Create or replace or add to the location list for window {nr}. | |
10040 {nr} can be the window number or the |window-ID|. | |
10041 When {nr} is zero the current window is used. | |
10042 | |
10043 For a location list window, the displayed location list is | |
10044 modified. For an invalid window number {nr}, -1 is returned. | |
10045 Otherwise, same as |setqflist()|. | |
10046 Also see |location-list|. | |
10047 | |
10048 For {action} see |setqflist-action|. | |
10049 | |
10050 If the optional {what} dictionary argument is supplied, then | |
10051 only the items listed in {what} are set. Refer to |setqflist()| | |
10052 for the list of supported keys in {what}. | |
10053 | |
10054 Can also be used as a |method|, the base is passed as the | |
10055 second argument: > | |
10056 GetLoclist()->setloclist(winnr) | |
10057 | |
10058 setmatches({list} [, {win}]) *setmatches()* | |
10059 Restores a list of matches saved by |getmatches()| for the | |
10060 current window. Returns 0 if successful, otherwise -1. All | |
10061 current matches are cleared before the list is restored. See | |
10062 example for |getmatches()|. | |
10063 If {win} is specified, use the window with this number or | |
10064 window ID instead of the current window. | |
10065 | |
10066 Can also be used as a |method|: > | |
10067 GetMatches()->setmatches() | |
10068 < | |
10069 *setpos()* | |
10070 setpos({expr}, {list}) | |
10071 Set the position for String {expr}. Possible values: | |
10072 . the cursor | |
10073 'x mark x | |
10074 | |
10075 {list} must be a |List| with four or five numbers: | |
10076 [bufnum, lnum, col, off] | |
10077 [bufnum, lnum, col, off, curswant] | |
10078 | |
10079 "bufnum" is the buffer number. Zero can be used for the | |
10080 current buffer. When setting an uppercase mark "bufnum" is | |
10081 used for the mark position. For other marks it specifies the | |
10082 buffer to set the mark in. You can use the |bufnr()| function | |
10083 to turn a file name into a buffer number. | |
10084 For setting the cursor and the ' mark "bufnum" is ignored, | |
10085 since these are associated with a window, not a buffer. | |
10086 Does not change the jumplist. | |
10087 | |
10088 "lnum" and "col" are the position in the buffer. The first | |
10089 column is 1. Use a zero "lnum" to delete a mark. If "col" is | |
10090 smaller than 1 then 1 is used. To use the character count | |
10091 instead of the byte count, use |setcharpos()|. | |
10092 | |
10093 The "off" number is only used when 'virtualedit' is set. Then | |
10094 it is the offset in screen columns from the start of the | |
10095 character. E.g., a position within a <Tab> or after the last | |
10096 character. | |
10097 | |
10098 The "curswant" number is only used when setting the cursor | |
10099 position. It sets the preferred column for when moving the | |
10100 cursor vertically. When the "curswant" number is missing the | |
10101 preferred column is not set. When it is present and setting a | |
10102 mark position it is not used. | |
10103 | |
10104 Note that for '< and '> changing the line number may result in | |
10105 the marks to be effectively be swapped, so that '< is always | |
10106 before '>. | |
10107 | |
10108 Returns 0 when the position could be set, -1 otherwise. | |
10109 An error message is given if {expr} is invalid. | |
10110 | |
10111 Also see |setcharpos()|, |getpos()| and |getcurpos()|. | |
10112 | |
10113 This does not restore the preferred column for moving | |
10114 vertically; if you set the cursor position with this, |j| and | |
10115 |k| motions will jump to previous columns! Use |cursor()| to | |
10116 also set the preferred column. Also see the "curswant" key in | |
10117 |winrestview()|. | |
10118 | |
10119 Can also be used as a |method|: > | |
10120 GetPosition()->setpos('.') | |
10121 | |
10122 setqflist({list} [, {action} [, {what}]]) *setqflist()* | |
10123 Create or replace or add to the quickfix list. | |
10124 | |
10125 If the optional {what} dictionary argument is supplied, then | |
10126 only the items listed in {what} are set. The first {list} | |
10127 argument is ignored. See below for the supported items in | |
10128 {what}. | |
10129 *setqflist-what* | |
10130 When {what} is not present, the items in {list} are used. Each | |
10131 item must be a dictionary. Non-dictionary items in {list} are | |
10132 ignored. Each dictionary item can contain the following | |
10133 entries: | |
10134 | |
10135 bufnr buffer number; must be the number of a valid | |
10136 buffer | |
10137 filename name of a file; only used when "bufnr" is not | |
10138 present or it is invalid. | |
10139 module name of a module; if given it will be used in | |
10140 quickfix error window instead of the filename. | |
10141 lnum line number in the file | |
10142 pattern search pattern used to locate the error | |
10143 col column number | |
10144 vcol when non-zero: "col" is visual column | |
10145 when zero: "col" is byte index | |
10146 nr error number | |
10147 text description of the error | |
10148 type single-character error type, 'E', 'W', etc. | |
10149 valid recognized error message | |
10150 | |
10151 The "col", "vcol", "nr", "type" and "text" entries are | |
10152 optional. Either "lnum" or "pattern" entry can be used to | |
10153 locate a matching error line. | |
10154 If the "filename" and "bufnr" entries are not present or | |
10155 neither the "lnum" or "pattern" entries are present, then the | |
10156 item will not be handled as an error line. | |
10157 If both "pattern" and "lnum" are present then "pattern" will | |
10158 be used. | |
10159 If the "valid" entry is not supplied, then the valid flag is | |
10160 set when "bufnr" is a valid buffer or "filename" exists. | |
10161 If you supply an empty {list}, the quickfix list will be | |
10162 cleared. | |
10163 Note that the list is not exactly the same as what | |
10164 |getqflist()| returns. | |
10165 | |
10166 {action} values: *setqflist-action* *E927* | |
10167 'a' The items from {list} are added to the existing | |
10168 quickfix list. If there is no existing list, then a | |
10169 new list is created. | |
10170 | |
10171 'r' The items from the current quickfix list are replaced | |
10172 with the items from {list}. This can also be used to | |
10173 clear the list: > | |
10174 :call setqflist([], 'r') | |
10175 < | |
10176 'f' All the quickfix lists in the quickfix stack are | |
10177 freed. | |
10178 | |
10179 If {action} is not present or is set to ' ', then a new list | |
10180 is created. The new quickfix list is added after the current | |
10181 quickfix list in the stack and all the following lists are | |
10182 freed. To add a new quickfix list at the end of the stack, | |
10183 set "nr" in {what} to "$". | |
10184 | |
10185 The following items can be specified in dictionary {what}: | |
10186 context quickfix list context. See |quickfix-context| | |
10187 efm errorformat to use when parsing text from | |
10188 "lines". If this is not present, then the | |
10189 'errorformat' option value is used. | |
10190 See |quickfix-parse| | |
10191 id quickfix list identifier |quickfix-ID| | |
10192 idx index of the current entry in the quickfix | |
10193 list specified by 'id' or 'nr'. If set to '$', | |
10194 then the last entry in the list is set as the | |
10195 current entry. See |quickfix-index| | |
10196 items list of quickfix entries. Same as the {list} | |
10197 argument. | |
10198 lines use 'errorformat' to parse a list of lines and | |
10199 add the resulting entries to the quickfix list | |
10200 {nr} or {id}. Only a |List| value is supported. | |
10201 See |quickfix-parse| | |
10202 nr list number in the quickfix stack; zero | |
10203 means the current quickfix list and "$" means | |
10204 the last quickfix list. | |
10205 quickfixtextfunc | |
10206 function to get the text to display in the | |
10207 quickfix window. The value can be the name of | |
10208 a function or a funcref or a lambda. Refer to | |
10209 |quickfix-window-function| for an explanation | |
10210 of how to write the function and an example. | |
10211 title quickfix list title text. See |quickfix-title| | |
10212 Unsupported keys in {what} are ignored. | |
10213 If the "nr" item is not present, then the current quickfix list | |
10214 is modified. When creating a new quickfix list, "nr" can be | |
10215 set to a value one greater than the quickfix stack size. | |
10216 When modifying a quickfix list, to guarantee that the correct | |
10217 list is modified, "id" should be used instead of "nr" to | |
10218 specify the list. | |
10219 | |
10220 Examples (See also |setqflist-examples|): > | |
10221 :call setqflist([], 'r', {'title': 'My search'}) | |
10222 :call setqflist([], 'r', {'nr': 2, 'title': 'Errors'}) | |
10223 :call setqflist([], 'a', {'id':qfid, 'lines':["F1:10:L10"]}) | |
10224 < | |
10225 Returns zero for success, -1 for failure. | |
10226 | |
10227 This function can be used to create a quickfix list | |
10228 independent of the 'errorformat' setting. Use a command like | |
10229 `:cc 1` to jump to the first position. | |
10230 | |
10231 Can also be used as a |method|, the base is passed as the | |
10232 second argument: > | |
10233 GetErrorlist()->setqflist() | |
10234 < | |
10235 *setreg()* | |
10236 setreg({regname}, {value} [, {options}]) | |
10237 Set the register {regname} to {value}. | |
10238 If {regname} is "" or "@", the unnamed register '"' is used. | |
10239 The {regname} argument is a string. In |Vim9-script| | |
10240 {regname} must be one character. | |
10241 | |
10242 {value} may be any value returned by |getreg()| or | |
10243 |getreginfo()|, including a |List| or |Dict|. | |
10244 If {options} contains "a" or {regname} is upper case, | |
10245 then the value is appended. | |
10246 | |
10247 {options} can also contain a register type specification: | |
10248 "c" or "v" |characterwise| mode | |
10249 "l" or "V" |linewise| mode | |
10250 "b" or "<CTRL-V>" |blockwise-visual| mode | |
10251 If a number immediately follows "b" or "<CTRL-V>" then this is | |
10252 used as the width of the selection - if it is not specified | |
10253 then the width of the block is set to the number of characters | |
10254 in the longest line (counting a <Tab> as 1 character). | |
10255 | |
10256 If {options} contains no register settings, then the default | |
10257 is to use character mode unless {value} ends in a <NL> for | |
10258 string {value} and linewise mode for list {value}. Blockwise | |
10259 mode is never selected automatically. | |
10260 Returns zero for success, non-zero for failure. | |
10261 | |
10262 *E883* | |
10263 Note: you may not use |List| containing more than one item to | |
10264 set search and expression registers. Lists containing no | |
10265 items act like empty strings. | |
10266 | |
10267 Examples: > | |
10268 :call setreg(v:register, @*) | |
10269 :call setreg('*', @%, 'ac') | |
10270 :call setreg('a', "1\n2\n3", 'b5') | |
10271 :call setreg('"', { 'points_to': 'a'}) | |
10272 | |
10273 < This example shows using the functions to save and restore a | |
10274 register: > | |
10275 :let var_a = getreginfo() | |
10276 :call setreg('a', var_a) | |
10277 < or: > | |
10278 :let var_a = getreg('a', 1, 1) | |
10279 :let var_amode = getregtype('a') | |
10280 .... | |
10281 :call setreg('a', var_a, var_amode) | |
10282 < Note: you may not reliably restore register value | |
10283 without using the third argument to |getreg()| as without it | |
10284 newlines are represented as newlines AND Nul bytes are | |
10285 represented as newlines as well, see |NL-used-for-Nul|. | |
10286 | |
10287 You can also change the type of a register by appending | |
10288 nothing: > | |
10289 :call setreg('a', '', 'al') | |
10290 | |
10291 < Can also be used as a |method|, the base is passed as the | |
10292 second argument: > | |
10293 GetText()->setreg('a') | |
10294 | |
10295 settabvar({tabnr}, {varname}, {val}) *settabvar()* | |
10296 Set tab-local variable {varname} to {val} in tab page {tabnr}. | |
10297 |t:var| | |
10298 The {varname} argument is a string. | |
10299 Note that autocommands are blocked, side effects may not be | |
10300 triggered, e.g. when setting 'filetype'. | |
10301 Note that the variable name without "t:" must be used. | |
10302 Tabs are numbered starting with one. | |
10303 This function is not available in the |sandbox|. | |
10304 | |
10305 Can also be used as a |method|, the base is passed as the | |
10306 third argument: > | |
10307 GetValue()->settabvar(tab, name) | |
10308 | |
10309 settabwinvar({tabnr}, {winnr}, {varname}, {val}) *settabwinvar()* | |
10310 Set option or local variable {varname} in window {winnr} to | |
10311 {val}. | |
10312 Tabs are numbered starting with one. For the current tabpage | |
10313 use |setwinvar()|. | |
10314 {winnr} can be the window number or the |window-ID|. | |
10315 When {winnr} is zero the current window is used. | |
10316 Note that autocommands are blocked, side effects may not be | |
10317 triggered, e.g. when setting 'filetype' or 'syntax'. | |
10318 This also works for a global or local buffer option, but it | |
10319 doesn't work for a global or local buffer variable. | |
10320 For a local buffer option the global value is unchanged. | |
10321 Note that the variable name without "w:" must be used. | |
10322 Examples: > | |
10323 :call settabwinvar(1, 1, "&list", 0) | |
10324 :call settabwinvar(3, 2, "myvar", "foobar") | |
10325 < This function is not available in the |sandbox|. | |
10326 | |
10327 Can also be used as a |method|, the base is passed as the | |
10328 fourth argument: > | |
10329 GetValue()->settabwinvar(tab, winnr, name) | |
10330 | |
10331 settagstack({nr}, {dict} [, {action}]) *settagstack()* | |
10332 Modify the tag stack of the window {nr} using {dict}. | |
10333 {nr} can be the window number or the |window-ID|. | |
10334 | |
10335 For a list of supported items in {dict}, refer to | |
10336 |gettagstack()|. "curidx" takes effect before changing the tag | |
10337 stack. | |
10338 *E962* | |
10339 How the tag stack is modified depends on the {action} | |
10340 argument: | |
10341 - If {action} is not present or is set to 'r', then the tag | |
10342 stack is replaced. | |
10343 - If {action} is set to 'a', then new entries from {dict} are | |
10344 pushed (added) onto the tag stack. | |
10345 - If {action} is set to 't', then all the entries from the | |
10346 current entry in the tag stack or "curidx" in {dict} are | |
10347 removed and then new entries are pushed to the stack. | |
10348 | |
10349 The current index is set to one after the length of the tag | |
10350 stack after the modification. | |
10351 | |
10352 Returns zero for success, -1 for failure. | |
10353 | |
10354 Examples (for more examples see |tagstack-examples|): | |
10355 Empty the tag stack of window 3: > | |
10356 call settagstack(3, {'items' : []}) | |
10357 | |
10358 < Save and restore the tag stack: > | |
10359 let stack = gettagstack(1003) | |
10360 " do something else | |
10361 call settagstack(1003, stack) | |
10362 unlet stack | |
10363 < | |
10364 Can also be used as a |method|, the base is passed as the | |
10365 second argument: > | |
10366 GetStack()->settagstack(winnr) | |
10367 | |
10368 setwinvar({winnr}, {varname}, {val}) *setwinvar()* | |
10369 Like |settabwinvar()| for the current tab page. | |
10370 Examples: > | |
10371 :call setwinvar(1, "&list", 0) | |
10372 :call setwinvar(2, "myvar", "foobar") | |
10373 | |
10374 < Can also be used as a |method|, the base is passed as the | |
10375 third argument: > | |
10376 GetValue()->setwinvar(winnr, name) | |
10377 | |
10378 sha256({string}) *sha256()* | |
10379 Returns a String with 64 hex characters, which is the SHA256 | |
10380 checksum of {string}. | |
10381 | |
10382 Can also be used as a |method|: > | |
10383 GetText()->sha256() | |
10384 | |
10385 < {only available when compiled with the |+cryptv| feature} | |
10386 | |
10387 shellescape({string} [, {special}]) *shellescape()* | |
10388 Escape {string} for use as a shell command argument. | |
10389 When the 'shell' contains powershell (MS-Windows) or pwsh | |
10390 (MS-Windows, Linux, and MacOS) then it will enclose {string} | |
10391 in single quotes and will double up all internal single | |
10392 quotes. | |
10393 On MS-Windows, when 'shellslash' is not set, it will enclose | |
10394 {string} in double quotes and double all double quotes within | |
10395 {string}. | |
10396 Otherwise it will enclose {string} in single quotes and | |
10397 replace all "'" with "'\''". | |
10398 | |
10399 When the {special} argument is present and it's a non-zero | |
10400 Number or a non-empty String (|non-zero-arg|), then special | |
10401 items such as "!", "%", "#" and "<cword>" will be preceded by | |
10402 a backslash. This backslash will be removed again by the |:!| | |
10403 command. | |
10404 | |
10405 The "!" character will be escaped (again with a |non-zero-arg| | |
10406 {special}) when 'shell' contains "csh" in the tail. That is | |
10407 because for csh and tcsh "!" is used for history replacement | |
10408 even when inside single quotes. | |
10409 | |
10410 With a |non-zero-arg| {special} the <NL> character is also | |
10411 escaped. When 'shell' containing "csh" in the tail it's | |
10412 escaped a second time. | |
10413 | |
10414 The "\" character will be escaped when 'shell' contains "fish" | |
10415 in the tail. That is because for fish "\" is used as an escape | |
10416 character inside single quotes. | |
10417 | |
10418 Example of use with a |:!| command: > | |
10419 :exe '!dir ' . shellescape(expand('<cfile>'), 1) | |
10420 < This results in a directory listing for the file under the | |
10421 cursor. Example of use with |system()|: > | |
10422 :call system("chmod +w -- " . shellescape(expand("%"))) | |
10423 < See also |::S|. | |
10424 | |
10425 Can also be used as a |method|: > | |
10426 GetCommand()->shellescape() | |
10427 | |
10428 shiftwidth([{col}]) *shiftwidth()* | |
10429 Returns the effective value of 'shiftwidth'. This is the | |
10430 'shiftwidth' value unless it is zero, in which case it is the | |
10431 'tabstop' value. This function was introduced with patch | |
10432 7.3.694 in 2012, everybody should have it by now (however it | |
10433 did not allow for the optional {col} argument until 8.1.542). | |
10434 | |
10435 When there is one argument {col} this is used as column number | |
10436 for which to return the 'shiftwidth' value. This matters for the | |
10437 'vartabstop' feature. If the 'vartabstop' setting is enabled and | |
10438 no {col} argument is given, column 1 will be assumed. | |
10439 | |
10440 Can also be used as a |method|: > | |
10441 GetColumn()->shiftwidth() | |
10442 | |
10443 sign_ functions are documented here: |sign-functions-details| | |
10444 | |
10445 | |
10446 simplify({filename}) *simplify()* | |
10447 Simplify the file name as much as possible without changing | |
10448 the meaning. Shortcuts (on MS-Windows) or symbolic links (on | |
10449 Unix) are not resolved. If the first path component in | |
10450 {filename} designates the current directory, this will be | |
10451 valid for the result as well. A trailing path separator is | |
10452 not removed either. On Unix "//path" is unchanged, but | |
10453 "///path" is simplified to "/path" (this follows the Posix | |
10454 standard). | |
10455 Example: > | |
10456 simplify("./dir/.././/file/") == "./file/" | |
10457 < Note: The combination "dir/.." is only removed if "dir" is | |
10458 a searchable directory or does not exist. On Unix, it is also | |
10459 removed when "dir" is a symbolic link within the same | |
10460 directory. In order to resolve all the involved symbolic | |
10461 links before simplifying the path name, use |resolve()|. | |
10462 | |
10463 Can also be used as a |method|: > | |
10464 GetName()->simplify() | |
10465 | |
10466 sin({expr}) *sin()* | |
10467 Return the sine of {expr}, measured in radians, as a |Float|. | |
10468 {expr} must evaluate to a |Float| or a |Number|. | |
10469 Examples: > | |
10470 :echo sin(100) | |
10471 < -0.506366 > | |
10472 :echo sin(-4.01) | |
10473 < 0.763301 | |
10474 | |
10475 Can also be used as a |method|: > | |
10476 Compute()->sin() | |
10477 < | |
10478 {only available when compiled with the |+float| feature} | |
10479 | |
10480 | |
10481 sinh({expr}) *sinh()* | |
10482 Return the hyperbolic sine of {expr} as a |Float| in the range | |
10483 [-inf, inf]. | |
10484 {expr} must evaluate to a |Float| or a |Number|. | |
10485 Examples: > | |
10486 :echo sinh(0.5) | |
10487 < 0.521095 > | |
10488 :echo sinh(-0.9) | |
10489 < -1.026517 | |
10490 | |
10491 Can also be used as a |method|: > | |
10492 Compute()->sinh() | |
10493 < | |
10494 {only available when compiled with the |+float| feature} | |
10495 | |
10496 | |
10497 slice({expr}, {start} [, {end}]) *slice()* | |
10498 Similar to using a |slice| "expr[start : end]", but "end" is | |
10499 used exclusive. And for a string the indexes are used as | |
10500 character indexes instead of byte indexes, like in | |
10501 |vim9script|. Also, composing characters are not counted. | |
10502 When {end} is omitted the slice continues to the last item. | |
10503 When {end} is -1 the last item is omitted. | |
10504 | |
10505 Can also be used as a |method|: > | |
10506 GetList()->slice(offset) | |
10507 | |
10508 | |
10509 sort({list} [, {func} [, {dict}]]) *sort()* *E702* | |
10510 Sort the items in {list} in-place. Returns {list}. | |
10511 | |
10512 If you want a list to remain unmodified make a copy first: > | |
10513 :let sortedlist = sort(copy(mylist)) | |
10514 | |
10515 < When {func} is omitted, is empty or zero, then sort() uses the | |
10516 string representation of each item to sort on. Numbers sort | |
10517 after Strings, |Lists| after Numbers. For sorting text in the | |
10518 current buffer use |:sort|. | |
10519 | |
10520 When {func} is given and it is '1' or 'i' then case is | |
10521 ignored. | |
10522 | |
10523 When {func} is given and it is 'l' then the current collation | |
10524 locale is used for ordering. Implementation details: strcoll() | |
10525 is used to compare strings. See |:language| check or set the | |
10526 collation locale. |v:collate| can also be used to check the | |
10527 current locale. Sorting using the locale typically ignores | |
10528 case. Example: > | |
10529 " ö is sorted similarly to o with English locale. | |
10530 :language collate en_US.UTF8 | |
10531 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') | |
10532 < ['n', 'o', 'O', 'ö', 'p', 'z'] ~ | |
10533 > | |
10534 " ö is sorted after z with Swedish locale. | |
10535 :language collate sv_SE.UTF8 | |
10536 :echo sort(['n', 'o', 'O', 'ö', 'p', 'z'], 'l') | |
10537 < ['n', 'o', 'O', 'p', 'z', 'ö'] ~ | |
10538 This does not work properly on Mac. | |
10539 | |
10540 When {func} is given and it is 'n' then all items will be | |
10541 sorted numerical (Implementation detail: this uses the | |
10542 strtod() function to parse numbers, Strings, Lists, Dicts and | |
10543 Funcrefs will be considered as being 0). | |
10544 | |
10545 When {func} is given and it is 'N' then all items will be | |
10546 sorted numerical. This is like 'n' but a string containing | |
10547 digits will be used as the number they represent. | |
10548 | |
10549 When {func} is given and it is 'f' then all items will be | |
10550 sorted numerical. All values must be a Number or a Float. | |
10551 | |
10552 When {func} is a |Funcref| or a function name, this function | |
10553 is called to compare items. The function is invoked with two | |
10554 items as argument and must return zero if they are equal, 1 or | |
10555 bigger if the first one sorts after the second one, -1 or | |
10556 smaller if the first one sorts before the second one. | |
10557 | |
10558 {dict} is for functions with the "dict" attribute. It will be | |
10559 used to set the local variable "self". |Dictionary-function| | |
10560 | |
10561 The sort is stable, items which compare equal (as number or as | |
10562 string) will keep their relative position. E.g., when sorting | |
10563 on numbers, text strings will sort next to each other, in the | |
10564 same order as they were originally. | |
10565 | |
10566 Can also be used as a |method|: > | |
10567 mylist->sort() | |
10568 | |
10569 < Also see |uniq()|. | |
10570 | |
10571 Example: > | |
10572 func MyCompare(i1, i2) | |
10573 return a:i1 == a:i2 ? 0 : a:i1 > a:i2 ? 1 : -1 | |
10574 endfunc | |
10575 eval mylist->sort("MyCompare") | |
10576 < A shorter compare version for this specific simple case, which | |
10577 ignores overflow: > | |
10578 func MyCompare(i1, i2) | |
10579 return a:i1 - a:i2 | |
10580 endfunc | |
10581 < For a simple expression you can use a lambda: > | |
10582 eval mylist->sort({i1, i2 -> i1 - i2}) | |
10583 < | |
10584 sound_clear() *sound_clear()* | |
10585 Stop playing all sounds. | |
10586 | |
10587 On some Linux systems you may need the libcanberra-pulse | |
10588 package, otherwise sound may not stop. | |
10589 | |
10590 {only available when compiled with the |+sound| feature} | |
10591 | |
10592 *sound_playevent()* | |
10593 sound_playevent({name} [, {callback}]) | |
10594 Play a sound identified by {name}. Which event names are | |
10595 supported depends on the system. Often the XDG sound names | |
10596 are used. On Ubuntu they may be found in | |
10597 /usr/share/sounds/freedesktop/stereo. Example: > | |
10598 call sound_playevent('bell') | |
10599 < On MS-Windows, {name} can be SystemAsterisk, SystemDefault, | |
10600 SystemExclamation, SystemExit, SystemHand, SystemQuestion, | |
10601 SystemStart, SystemWelcome, etc. | |
10602 | |
10603 When {callback} is specified it is invoked when the sound is | |
10604 finished. The first argument is the sound ID, the second | |
10605 argument is the status: | |
10606 0 sound was played to the end | |
10607 1 sound was interrupted | |
10608 2 error occurred after sound started | |
10609 Example: > | |
10610 func Callback(id, status) | |
10611 echomsg "sound " .. a:id .. " finished with " .. a:status | |
10612 endfunc | |
10613 call sound_playevent('bell', 'Callback') | |
10614 | |
10615 < MS-Windows: {callback} doesn't work for this function. | |
10616 | |
10617 Returns the sound ID, which can be passed to `sound_stop()`. | |
10618 Returns zero if the sound could not be played. | |
10619 | |
10620 Can also be used as a |method|: > | |
10621 GetSoundName()->sound_playevent() | |
10622 | |
10623 < {only available when compiled with the |+sound| feature} | |
10624 | |
10625 *sound_playfile()* | |
10626 sound_playfile({path} [, {callback}]) | |
10627 Like `sound_playevent()` but play sound file {path}. {path} | |
10628 must be a full path. On Ubuntu you may find files to play | |
10629 with this command: > | |
10630 :!find /usr/share/sounds -type f | grep -v index.theme | |
10631 | |
10632 < Can also be used as a |method|: > | |
10633 GetSoundPath()->sound_playfile() | |
10634 | |
10635 < {only available when compiled with the |+sound| feature} | |
10636 | |
10637 | |
10638 sound_stop({id}) *sound_stop()* | |
10639 Stop playing sound {id}. {id} must be previously returned by | |
10640 `sound_playevent()` or `sound_playfile()`. | |
10641 | |
10642 On some Linux systems you may need the libcanberra-pulse | |
10643 package, otherwise sound may not stop. | |
10644 | |
10645 On MS-Windows, this does not work for event sound started by | |
10646 `sound_playevent()`. To stop event sounds, use `sound_clear()`. | |
10647 | |
10648 Can also be used as a |method|: > | |
10649 soundid->sound_stop() | |
10650 | |
10651 < {only available when compiled with the |+sound| feature} | |
10652 | |
10653 *soundfold()* | |
10654 soundfold({word}) | |
10655 Return the sound-folded equivalent of {word}. Uses the first | |
10656 language in 'spelllang' for the current window that supports | |
10657 soundfolding. 'spell' must be set. When no sound folding is | |
10658 possible the {word} is returned unmodified. | |
10659 This can be used for making spelling suggestions. Note that | |
10660 the method can be quite slow. | |
10661 | |
10662 Can also be used as a |method|: > | |
10663 GetWord()->soundfold() | |
10664 < | |
10665 *spellbadword()* | |
10666 spellbadword([{sentence}]) | |
10667 Without argument: The result is the badly spelled word under | |
10668 or after the cursor. The cursor is moved to the start of the | |
10669 bad word. When no bad word is found in the cursor line the | |
10670 result is an empty string and the cursor doesn't move. | |
10671 | |
10672 With argument: The result is the first word in {sentence} that | |
10673 is badly spelled. If there are no spelling mistakes the | |
10674 result is an empty string. | |
10675 | |
10676 The return value is a list with two items: | |
10677 - The badly spelled word or an empty string. | |
10678 - The type of the spelling error: | |
10679 "bad" spelling mistake | |
10680 "rare" rare word | |
10681 "local" word only valid in another region | |
10682 "caps" word should start with Capital | |
10683 Example: > | |
10684 echo spellbadword("the quik brown fox") | |
10685 < ['quik', 'bad'] ~ | |
10686 | |
10687 The spelling information for the current window and the value | |
10688 of 'spelllang' are used. | |
10689 | |
10690 Can also be used as a |method|: > | |
10691 GetText()->spellbadword() | |
10692 < | |
10693 *spellsuggest()* | |
10694 spellsuggest({word} [, {max} [, {capital}]]) | |
10695 Return a |List| with spelling suggestions to replace {word}. | |
10696 When {max} is given up to this number of suggestions are | |
10697 returned. Otherwise up to 25 suggestions are returned. | |
10698 | |
10699 When the {capital} argument is given and it's non-zero only | |
10700 suggestions with a leading capital will be given. Use this | |
10701 after a match with 'spellcapcheck'. | |
10702 | |
10703 {word} can be a badly spelled word followed by other text. | |
10704 This allows for joining two words that were split. The | |
10705 suggestions also include the following text, thus you can | |
10706 replace a line. | |
10707 | |
10708 {word} may also be a good word. Similar words will then be | |
10709 returned. {word} itself is not included in the suggestions, | |
10710 although it may appear capitalized. | |
10711 | |
10712 The spelling information for the current window is used. The | |
10713 values of 'spelllang' and 'spellsuggest' are used. | |
10714 | |
10715 Can also be used as a |method|: > | |
10716 GetWord()->spellsuggest() | |
10717 | |
10718 split({string} [, {pattern} [, {keepempty}]]) *split()* | |
10719 Make a |List| out of {string}. When {pattern} is omitted or | |
10720 empty each white-separated sequence of characters becomes an | |
10721 item. | |
10722 Otherwise the string is split where {pattern} matches, | |
10723 removing the matched characters. 'ignorecase' is not used | |
10724 here, add \c to ignore case. |/\c| | |
10725 When the first or last item is empty it is omitted, unless the | |
10726 {keepempty} argument is given and it's non-zero. | |
10727 Other empty items are kept when {pattern} matches at least one | |
10728 character or when {keepempty} is non-zero. | |
10729 Example: > | |
10730 :let words = split(getline('.'), '\W\+') | |
10731 < To split a string in individual characters: > | |
10732 :for c in split(mystring, '\zs') | |
10733 < If you want to keep the separator you can also use '\zs' at | |
10734 the end of the pattern: > | |
10735 :echo split('abc:def:ghi', ':\zs') | |
10736 < ['abc:', 'def:', 'ghi'] ~ | |
10737 Splitting a table where the first element can be empty: > | |
10738 :let items = split(line, ':', 1) | |
10739 < The opposite function is |join()|. | |
10740 | |
10741 Can also be used as a |method|: > | |
10742 GetString()->split() | |
10743 | |
10744 sqrt({expr}) *sqrt()* | |
10745 Return the non-negative square root of Float {expr} as a | |
10746 |Float|. | |
10747 {expr} must evaluate to a |Float| or a |Number|. When {expr} | |
10748 is negative the result is NaN (Not a Number). | |
10749 Examples: > | |
10750 :echo sqrt(100) | |
10751 < 10.0 > | |
10752 :echo sqrt(-4.01) | |
10753 < nan | |
10754 "nan" may be different, it depends on system libraries. | |
10755 | |
10756 Can also be used as a |method|: > | |
10757 Compute()->sqrt() | |
10758 < | |
10759 {only available when compiled with the |+float| feature} | |
10760 | |
10761 | |
10762 srand([{expr}]) *srand()* | |
10763 Initialize seed used by |rand()|: | |
10764 - If {expr} is not given, seed values are initialized by | |
10765 reading from /dev/urandom, if possible, or using time(NULL) | |
10766 a.k.a. epoch time otherwise; this only has second accuracy. | |
10767 - If {expr} is given it must be a Number. It is used to | |
10768 initialize the seed values. This is useful for testing or | |
10769 when a predictable sequence is intended. | |
10770 | |
10771 Examples: > | |
10772 :let seed = srand() | |
10773 :let seed = srand(userinput) | |
10774 :echo rand(seed) | |
10775 | |
10776 state([{what}]) *state()* | |
10777 Return a string which contains characters indicating the | |
10778 current state. Mostly useful in callbacks that want to do | |
10779 work that may not always be safe. Roughly this works like: | |
10780 - callback uses state() to check if work is safe to do. | |
10781 Yes: then do it right away. | |
10782 No: add to work queue and add a |SafeState| and/or | |
10783 |SafeStateAgain| autocommand (|SafeState| triggers at | |
10784 toplevel, |SafeStateAgain| triggers after handling | |
10785 messages and callbacks). | |
10786 - When SafeState or SafeStateAgain is triggered and executes | |
10787 your autocommand, check with `state()` if the work can be | |
10788 done now, and if yes remove it from the queue and execute. | |
10789 Remove the autocommand if the queue is now empty. | |
10790 Also see |mode()|. | |
10791 | |
10792 When {what} is given only characters in this string will be | |
10793 added. E.g, this checks if the screen has scrolled: > | |
10794 if state('s') == '' | |
10795 " screen has not scrolled | |
10796 < | |
10797 These characters indicate the state, generally indicating that | |
10798 something is busy: | |
10799 m halfway a mapping, :normal command, feedkeys() or | |
10800 stuffed command | |
10801 o operator pending, e.g. after |d| | |
10802 a Insert mode autocomplete active | |
10803 x executing an autocommand | |
10804 w blocked on waiting, e.g. ch_evalexpr(), ch_read() and | |
10805 ch_readraw() when reading json | |
10806 S not triggering SafeState or SafeStateAgain, e.g. after | |
10807 |f| or a count | |
10808 c callback invoked, including timer (repeats for | |
10809 recursiveness up to "ccc") | |
10810 s screen has scrolled for messages | |
10811 | |
10812 str2float({string} [, {quoted}]) *str2float()* | |
10813 Convert String {string} to a Float. This mostly works the | |
10814 same as when using a floating point number in an expression, | |
10815 see |floating-point-format|. But it's a bit more permissive. | |
10816 E.g., "1e40" is accepted, while in an expression you need to | |
10817 write "1.0e40". The hexadecimal form "0x123" is also | |
10818 accepted, but not others, like binary or octal. | |
10819 When {quoted} is present and non-zero then embedded single | |
10820 quotes before the dot are ignored, thus "1'000.0" is a | |
10821 thousand. | |
10822 Text after the number is silently ignored. | |
10823 The decimal point is always '.', no matter what the locale is | |
10824 set to. A comma ends the number: "12,345.67" is converted to | |
10825 12.0. You can strip out thousands separators with | |
10826 |substitute()|: > | |
10827 let f = str2float(substitute(text, ',', '', 'g')) | |
10828 < | |
10829 Can also be used as a |method|: > | |
10830 let f = text->substitute(',', '', 'g')->str2float() | |
10831 < | |
10832 {only available when compiled with the |+float| feature} | |
10833 | |
10834 str2list({string} [, {utf8}]) *str2list()* | |
10835 Return a list containing the number values which represent | |
10836 each character in String {string}. Examples: > | |
10837 str2list(" ") returns [32] | |
10838 str2list("ABC") returns [65, 66, 67] | |
10839 < |list2str()| does the opposite. | |
10840 | |
10841 When {utf8} is omitted or zero, the current 'encoding' is used. | |
10842 When {utf8} is TRUE, always treat the String as UTF-8 | |
10843 characters. With UTF-8 composing characters are handled | |
10844 properly: > | |
10845 str2list("á") returns [97, 769] | |
10846 | |
10847 < Can also be used as a |method|: > | |
10848 GetString()->str2list() | |
10849 | |
10850 | |
10851 str2nr({string} [, {base} [, {quoted}]]) *str2nr()* | |
10852 Convert string {string} to a number. | |
10853 {base} is the conversion base, it can be 2, 8, 10 or 16. | |
10854 When {quoted} is present and non-zero then embedded single | |
10855 quotes are ignored, thus "1'000'000" is a million. | |
10856 | |
10857 When {base} is omitted base 10 is used. This also means that | |
10858 a leading zero doesn't cause octal conversion to be used, as | |
10859 with the default String to Number conversion. Example: > | |
10860 let nr = str2nr('0123') | |
10861 < | |
10862 When {base} is 16 a leading "0x" or "0X" is ignored. With a | |
10863 different base the result will be zero. Similarly, when | |
10864 {base} is 8 a leading "0", "0o" or "0O" is ignored, and when | |
10865 {base} is 2 a leading "0b" or "0B" is ignored. | |
10866 Text after the number is silently ignored. | |
10867 | |
10868 Can also be used as a |method|: > | |
10869 GetText()->str2nr() | |
10870 | |
10871 | |
10872 strcharlen({string}) *strcharlen()* | |
10873 The result is a Number, which is the number of characters | |
10874 in String {string}. Composing characters are ignored. | |
10875 |strchars()| can count the number of characters, counting | |
10876 composing characters separately. | |
10877 | |
10878 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. | |
10879 | |
10880 Can also be used as a |method|: > | |
10881 GetText()->strcharlen() | |
10882 | |
10883 | |
10884 strcharpart({src}, {start} [, {len} [, {skipcc}]]) *strcharpart()* | |
10885 Like |strpart()| but using character index and length instead | |
10886 of byte index and length. | |
10887 When {skipcc} is omitted or zero, composing characters are | |
10888 counted separately. | |
10889 When {skipcc} set to 1, Composing characters are ignored, | |
10890 similar to |slice()|. | |
10891 When a character index is used where a character does not | |
10892 exist it is omitted and counted as one character. For | |
10893 example: > | |
10894 strcharpart('abc', -1, 2) | |
10895 < results in 'a'. | |
10896 | |
10897 Can also be used as a |method|: > | |
10898 GetText()->strcharpart(5) | |
10899 | |
10900 | |
10901 strchars({string} [, {skipcc}]) *strchars()* | |
10902 The result is a Number, which is the number of characters | |
10903 in String {string}. | |
10904 When {skipcc} is omitted or zero, composing characters are | |
10905 counted separately. | |
10906 When {skipcc} set to 1, Composing characters are ignored. | |
10907 |strcharlen()| always does this. | |
10908 | |
10909 Also see |strlen()|, |strdisplaywidth()| and |strwidth()|. | |
10910 | |
10911 {skipcc} is only available after 7.4.755. For backward | |
10912 compatibility, you can define a wrapper function: > | |
10913 if has("patch-7.4.755") | |
10914 function s:strchars(str, skipcc) | |
10915 return strchars(a:str, a:skipcc) | |
10916 endfunction | |
10917 else | |
10918 function s:strchars(str, skipcc) | |
10919 if a:skipcc | |
10920 return strlen(substitute(a:str, ".", "x", "g")) | |
10921 else | |
10922 return strchars(a:str) | |
10923 endif | |
10924 endfunction | |
10925 endif | |
10926 < | |
10927 Can also be used as a |method|: > | |
10928 GetText()->strchars() | |
10929 | |
10930 strdisplaywidth({string} [, {col}]) *strdisplaywidth()* | |
10931 The result is a Number, which is the number of display cells | |
10932 String {string} occupies on the screen when it starts at {col} | |
10933 (first column is zero). When {col} is omitted zero is used. | |
10934 Otherwise it is the screen column where to start. This | |
10935 matters for Tab characters. | |
10936 The option settings of the current window are used. This | |
10937 matters for anything that's displayed differently, such as | |
10938 'tabstop' and 'display'. | |
10939 When {string} contains characters with East Asian Width Class | |
10940 Ambiguous, this function's return value depends on 'ambiwidth'. | |
10941 Also see |strlen()|, |strwidth()| and |strchars()|. | |
10942 | |
10943 Can also be used as a |method|: > | |
10944 GetText()->strdisplaywidth() | |
10945 | |
10946 strftime({format} [, {time}]) *strftime()* | |
10947 The result is a String, which is a formatted date and time, as | |
10948 specified by the {format} string. The given {time} is used, | |
10949 or the current time if no time is given. The accepted | |
10950 {format} depends on your system, thus this is not portable! | |
10951 See the manual page of the C function strftime() for the | |
10952 format. The maximum length of the result is 80 characters. | |
10953 See also |localtime()|, |getftime()| and |strptime()|. | |
10954 The language can be changed with the |:language| command. | |
10955 Examples: > | |
10956 :echo strftime("%c") Sun Apr 27 11:49:23 1997 | |
10957 :echo strftime("%Y %b %d %X") 1997 Apr 27 11:53:25 | |
10958 :echo strftime("%y%m%d %T") 970427 11:53:55 | |
10959 :echo strftime("%H:%M") 11:55 | |
10960 :echo strftime("%c", getftime("file.c")) | |
10961 Show mod time of file.c. | |
10962 < Not available on all systems. To check use: > | |
10963 :if exists("*strftime") | |
10964 | |
10965 < Can also be used as a |method|: > | |
10966 GetFormat()->strftime() | |
10967 | |
10968 strgetchar({str}, {index}) *strgetchar()* | |
10969 Get character {index} from {str}. This uses a character | |
10970 index, not a byte index. Composing characters are considered | |
10971 separate characters here. | |
10972 Also see |strcharpart()| and |strchars()|. | |
10973 | |
10974 Can also be used as a |method|: > | |
10975 GetText()->strgetchar(5) | |
10976 | |
10977 stridx({haystack}, {needle} [, {start}]) *stridx()* | |
10978 The result is a Number, which gives the byte index in | |
10979 {haystack} of the first occurrence of the String {needle}. | |
10980 If {start} is specified, the search starts at index {start}. | |
10981 This can be used to find a second match: > | |
10982 :let colon1 = stridx(line, ":") | |
10983 :let colon2 = stridx(line, ":", colon1 + 1) | |
10984 < The search is done case-sensitive. | |
10985 For pattern searches use |match()|. | |
10986 -1 is returned if the {needle} does not occur in {haystack}. | |
10987 See also |strridx()|. | |
10988 Examples: > | |
10989 :echo stridx("An Example", "Example") 3 | |
10990 :echo stridx("Starting point", "Start") 0 | |
10991 :echo stridx("Starting point", "start") -1 | |
10992 < *strstr()* *strchr()* | |
10993 stridx() works similar to the C function strstr(). When used | |
10994 with a single character it works similar to strchr(). | |
10995 | |
10996 Can also be used as a |method|: > | |
10997 GetHaystack()->stridx(needle) | |
10998 < | |
10999 *string()* | |
11000 string({expr}) Return {expr} converted to a String. If {expr} is a Number, | |
11001 Float, String, Blob or a composition of them, then the result | |
11002 can be parsed back with |eval()|. | |
11003 {expr} type result ~ | |
11004 String 'string' (single quotes are doubled) | |
11005 Number 123 | |
11006 Float 123.123456 or 1.123456e8 | |
11007 Funcref function('name') | |
11008 Blob 0z00112233.44556677.8899 | |
11009 List [item, item] | |
11010 Dictionary {key: value, key: value} | |
11011 | |
11012 When a |List| or |Dictionary| has a recursive reference it is | |
11013 replaced by "[...]" or "{...}". Using eval() on the result | |
11014 will then fail. | |
11015 | |
11016 Can also be used as a |method|: > | |
11017 mylist->string() | |
11018 | |
11019 < Also see |strtrans()|. | |
11020 | |
11021 | |
11022 strlen({string}) *strlen()* | |
11023 The result is a Number, which is the length of the String | |
11024 {string} in bytes. | |
11025 If the argument is a Number it is first converted to a String. | |
11026 For other types an error is given. | |
11027 If you want to count the number of multibyte characters use | |
11028 |strchars()|. | |
11029 Also see |len()|, |strdisplaywidth()| and |strwidth()|. | |
11030 | |
11031 Can also be used as a |method|: > | |
11032 GetString()->strlen() | |
11033 | |
11034 strpart({src}, {start} [, {len} [, {chars}]]) *strpart()* | |
11035 The result is a String, which is part of {src}, starting from | |
11036 byte {start}, with the byte length {len}. | |
11037 When {chars} is present and TRUE then {len} is the number of | |
11038 characters positions (composing characters are not counted | |
11039 separately, thus "1" means one base character and any | |
11040 following composing characters). | |
11041 To count {start} as characters instead of bytes use | |
11042 |strcharpart()|. | |
11043 | |
11044 When bytes are selected which do not exist, this doesn't | |
11045 result in an error, the bytes are simply omitted. | |
11046 If {len} is missing, the copy continues from {start} till the | |
11047 end of the {src}. > | |
11048 strpart("abcdefg", 3, 2) == "de" | |
11049 strpart("abcdefg", -2, 4) == "ab" | |
11050 strpart("abcdefg", 5, 4) == "fg" | |
11051 strpart("abcdefg", 3) == "defg" | |
11052 | |
11053 < Note: To get the first character, {start} must be 0. For | |
11054 example, to get the character under the cursor: > | |
11055 strpart(getline("."), col(".") - 1, 1, v:true) | |
11056 < | |
11057 Can also be used as a |method|: > | |
11058 GetText()->strpart(5) | |
11059 | |
11060 strptime({format}, {timestring}) *strptime()* | |
11061 The result is a Number, which is a unix timestamp representing | |
11062 the date and time in {timestring}, which is expected to match | |
11063 the format specified in {format}. | |
11064 | |
11065 The accepted {format} depends on your system, thus this is not | |
11066 portable! See the manual page of the C function strptime() | |
11067 for the format. Especially avoid "%c". The value of $TZ also | |
11068 matters. | |
11069 | |
11070 If the {timestring} cannot be parsed with {format} zero is | |
11071 returned. If you do not know the format of {timestring} you | |
11072 can try different {format} values until you get a non-zero | |
11073 result. | |
11074 | |
11075 See also |strftime()|. | |
11076 Examples: > | |
11077 :echo strptime("%Y %b %d %X", "1997 Apr 27 11:49:23") | |
11078 < 862156163 > | |
11079 :echo strftime("%c", strptime("%y%m%d %T", "970427 11:53:55")) | |
11080 < Sun Apr 27 11:53:55 1997 > | |
11081 :echo strftime("%c", strptime("%Y%m%d%H%M%S", "19970427115355") + 3600) | |
11082 < Sun Apr 27 12:53:55 1997 | |
11083 | |
11084 Can also be used as a |method|: > | |
11085 GetFormat()->strptime(timestring) | |
11086 < | |
11087 Not available on all systems. To check use: > | |
11088 :if exists("*strptime") | |
11089 | |
11090 strridx({haystack}, {needle} [, {start}]) *strridx()* | |
11091 The result is a Number, which gives the byte index in | |
11092 {haystack} of the last occurrence of the String {needle}. | |
11093 When {start} is specified, matches beyond this index are | |
11094 ignored. This can be used to find a match before a previous | |
11095 match: > | |
11096 :let lastcomma = strridx(line, ",") | |
11097 :let comma2 = strridx(line, ",", lastcomma - 1) | |
11098 < The search is done case-sensitive. | |
11099 For pattern searches use |match()|. | |
11100 -1 is returned if the {needle} does not occur in {haystack}. | |
11101 If the {needle} is empty the length of {haystack} is returned. | |
11102 See also |stridx()|. Examples: > | |
11103 :echo strridx("an angry armadillo", "an") 3 | |
11104 < *strrchr()* | |
11105 When used with a single character it works similar to the C | |
11106 function strrchr(). | |
11107 | |
11108 Can also be used as a |method|: > | |
11109 GetHaystack()->strridx(needle) | |
11110 | |
11111 strtrans({string}) *strtrans()* | |
11112 The result is a String, which is {string} with all unprintable | |
11113 characters translated into printable characters |'isprint'|. | |
11114 Like they are shown in a window. Example: > | |
11115 echo strtrans(@a) | |
11116 < This displays a newline in register a as "^@" instead of | |
11117 starting a new line. | |
11118 | |
11119 Can also be used as a |method|: > | |
11120 GetString()->strtrans() | |
11121 | |
11122 strwidth({string}) *strwidth()* | |
11123 The result is a Number, which is the number of display cells | |
11124 String {string} occupies. A Tab character is counted as one | |
11125 cell, alternatively use |strdisplaywidth()|. | |
11126 When {string} contains characters with East Asian Width Class | |
11127 Ambiguous, this function's return value depends on 'ambiwidth'. | |
11128 Also see |strlen()|, |strdisplaywidth()| and |strchars()|. | |
11129 | |
11130 Can also be used as a |method|: > | |
11131 GetString()->strwidth() | |
11132 | |
11133 submatch({nr} [, {list}]) *submatch()* *E935* | |
11134 Only for an expression in a |:substitute| command or | |
11135 substitute() function. | |
11136 Returns the {nr}'th submatch of the matched text. When {nr} | |
11137 is 0 the whole matched text is returned. | |
11138 Note that a NL in the string can stand for a line break of a | |
11139 multi-line match or a NUL character in the text. | |
11140 Also see |sub-replace-expression|. | |
11141 | |
11142 If {list} is present and non-zero then submatch() returns | |
11143 a list of strings, similar to |getline()| with two arguments. | |
11144 NL characters in the text represent NUL characters in the | |
11145 text. | |
11146 Only returns more than one item for |:substitute|, inside | |
11147 |substitute()| this list will always contain one or zero | |
11148 items, since there are no real line breaks. | |
11149 | |
11150 When substitute() is used recursively only the submatches in | |
11151 the current (deepest) call can be obtained. | |
11152 | |
11153 Examples: > | |
11154 :s/\d\+/\=submatch(0) + 1/ | |
11155 :echo substitute(text, '\d\+', '\=submatch(0) + 1', '') | |
11156 < This finds the first number in the line and adds one to it. | |
11157 A line break is included as a newline character. | |
11158 | |
11159 Can also be used as a |method|: > | |
11160 GetNr()->submatch() | |
11161 | |
11162 substitute({string}, {pat}, {sub}, {flags}) *substitute()* | |
11163 The result is a String, which is a copy of {string}, in which | |
11164 the first match of {pat} is replaced with {sub}. | |
11165 When {flags} is "g", all matches of {pat} in {string} are | |
11166 replaced. Otherwise {flags} should be "". | |
11167 | |
11168 This works like the ":substitute" command (without any flags). | |
11169 But the matching with {pat} is always done like the 'magic' | |
11170 option is set and 'cpoptions' is empty (to make scripts | |
11171 portable). 'ignorecase' is still relevant, use |/\c| or |/\C| | |
11172 if you want to ignore or match case and ignore 'ignorecase'. | |
11173 'smartcase' is not used. See |string-match| for how {pat} is | |
11174 used. | |
11175 | |
11176 A "~" in {sub} is not replaced with the previous {sub}. | |
11177 Note that some codes in {sub} have a special meaning | |
11178 |sub-replace-special|. For example, to replace something with | |
11179 "\n" (two characters), use "\\\\n" or '\\n'. | |
11180 | |
11181 When {pat} does not match in {string}, {string} is returned | |
11182 unmodified. | |
11183 | |
11184 Example: > | |
11185 :let &path = substitute(&path, ",\\=[^,]*$", "", "") | |
11186 < This removes the last component of the 'path' option. > | |
11187 :echo substitute("testing", ".*", "\\U\\0", "") | |
11188 < results in "TESTING". | |
11189 | |
11190 When {sub} starts with "\=", the remainder is interpreted as | |
11191 an expression. See |sub-replace-expression|. Example: > | |
11192 :echo substitute(s, '%\(\x\x\)', | |
11193 \ '\=nr2char("0x" . submatch(1))', 'g') | |
11194 | |
11195 < When {sub} is a Funcref that function is called, with one | |
11196 optional argument. Example: > | |
11197 :echo substitute(s, '%\(\x\x\)', SubNr, 'g') | |
11198 < The optional argument is a list which contains the whole | |
11199 matched string and up to nine submatches, like what | |
11200 |submatch()| returns. Example: > | |
11201 :echo substitute(s, '%\(\x\x\)', {m -> '0x' . m[1]}, 'g') | |
11202 | |
11203 < Can also be used as a |method|: > | |
11204 GetString()->substitute(pat, sub, flags) | |
11205 | |
11206 swapinfo({fname}) *swapinfo()* | |
11207 The result is a dictionary, which holds information about the | |
11208 swapfile {fname}. The available fields are: | |
11209 version Vim version | |
11210 user user name | |
11211 host host name | |
11212 fname original file name | |
11213 pid PID of the Vim process that created the swap | |
11214 file | |
11215 mtime last modification time in seconds | |
11216 inode Optional: INODE number of the file | |
11217 dirty 1 if file was modified, 0 if not | |
11218 Note that "user" and "host" are truncated to at most 39 bytes. | |
11219 In case of failure an "error" item is added with the reason: | |
11220 Cannot open file: file not found or in accessible | |
11221 Cannot read file: cannot read first block | |
11222 Not a swap file: does not contain correct block ID | |
11223 Magic number mismatch: Info in first block is invalid | |
11224 | |
11225 Can also be used as a |method|: > | |
11226 GetFilename()->swapinfo() | |
11227 | |
11228 swapname({buf}) *swapname()* | |
11229 The result is the swap file path of the buffer {expr}. | |
11230 For the use of {buf}, see |bufname()| above. | |
11231 If buffer {buf} is the current buffer, the result is equal to | |
11232 |:swapname| (unless there is no swap file). | |
11233 If buffer {buf} has no swap file, returns an empty string. | |
11234 | |
11235 Can also be used as a |method|: > | |
11236 GetBufname()->swapname() | |
11237 | |
11238 synID({lnum}, {col}, {trans}) *synID()* | |
11239 The result is a Number, which is the syntax ID at the position | |
11240 {lnum} and {col} in the current window. | |
11241 The syntax ID can be used with |synIDattr()| and | |
11242 |synIDtrans()| to obtain syntax information about text. | |
11243 | |
11244 {col} is 1 for the leftmost column, {lnum} is 1 for the first | |
11245 line. 'synmaxcol' applies, in a longer line zero is returned. | |
11246 Note that when the position is after the last character, | |
11247 that's where the cursor can be in Insert mode, synID() returns | |
11248 zero. {lnum} is used like with |getline()|. | |
11249 | |
11250 When {trans} is |TRUE|, transparent items are reduced to the | |
11251 item that they reveal. This is useful when wanting to know | |
11252 the effective color. When {trans} is |FALSE|, the transparent | |
11253 item is returned. This is useful when wanting to know which | |
11254 syntax item is effective (e.g. inside parens). | |
11255 Warning: This function can be very slow. Best speed is | |
11256 obtained by going through the file in forward direction. | |
11257 | |
11258 Example (echoes the name of the syntax item under the cursor): > | |
11259 :echo synIDattr(synID(line("."), col("."), 1), "name") | |
11260 < | |
11261 | |
11262 synIDattr({synID}, {what} [, {mode}]) *synIDattr()* | |
11263 The result is a String, which is the {what} attribute of | |
11264 syntax ID {synID}. This can be used to obtain information | |
11265 about a syntax item. | |
11266 {mode} can be "gui", "cterm" or "term", to get the attributes | |
11267 for that mode. When {mode} is omitted, or an invalid value is | |
11268 used, the attributes for the currently active highlighting are | |
11269 used (GUI, cterm or term). | |
11270 Use synIDtrans() to follow linked highlight groups. | |
11271 {what} result | |
11272 "name" the name of the syntax item | |
11273 "fg" foreground color (GUI: color name used to set | |
11274 the color, cterm: color number as a string, | |
11275 term: empty string) | |
11276 "bg" background color (as with "fg") | |
11277 "font" font name (only available in the GUI) | |
11278 |highlight-font| | |
11279 "sp" special color for the GUI (as with "fg") | |
11280 |highlight-guisp| | |
11281 "ul" underline color for cterm: number as a string | |
11282 "fg#" like "fg", but for the GUI and the GUI is | |
11283 running the name in "#RRGGBB" form | |
11284 "bg#" like "fg#" for "bg" | |
11285 "sp#" like "fg#" for "sp" | |
11286 "bold" "1" if bold | |
11287 "italic" "1" if italic | |
11288 "reverse" "1" if reverse | |
11289 "inverse" "1" if inverse (= reverse) | |
11290 "standout" "1" if standout | |
11291 "underline" "1" if underlined | |
11292 "undercurl" "1" if undercurled | |
11293 "strike" "1" if strikethrough | |
11294 | |
11295 Example (echoes the color of the syntax item under the | |
11296 cursor): > | |
11297 :echo synIDattr(synIDtrans(synID(line("."), col("."), 1)), "fg") | |
11298 < | |
11299 Can also be used as a |method|: > | |
11300 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") | |
11301 | |
11302 | |
11303 synIDtrans({synID}) *synIDtrans()* | |
11304 The result is a Number, which is the translated syntax ID of | |
11305 {synID}. This is the syntax group ID of what is being used to | |
11306 highlight the character. Highlight links given with | |
11307 ":highlight link" are followed. | |
11308 | |
11309 Can also be used as a |method|: > | |
11310 :echo synID(line("."), col("."), 1)->synIDtrans()->synIDattr("fg") | |
11311 | |
11312 synconcealed({lnum}, {col}) *synconcealed()* | |
11313 The result is a |List| with currently three items: | |
11314 1. The first item in the list is 0 if the character at the | |
11315 position {lnum} and {col} is not part of a concealable | |
11316 region, 1 if it is. {lnum} is used like with |getline()|. | |
11317 2. The second item in the list is a string. If the first item | |
11318 is 1, the second item contains the text which will be | |
11319 displayed in place of the concealed text, depending on the | |
11320 current setting of 'conceallevel' and 'listchars'. | |
11321 3. The third and final item in the list is a number | |
11322 representing the specific syntax region matched in the | |
11323 line. When the character is not concealed the value is | |
11324 zero. This allows detection of the beginning of a new | |
11325 concealable region if there are two consecutive regions | |
11326 with the same replacement character. For an example, if | |
11327 the text is "123456" and both "23" and "45" are concealed | |
11328 and replaced by the character "X", then: | |
11329 call returns ~ | |
11330 synconcealed(lnum, 1) [0, '', 0] | |
11331 synconcealed(lnum, 2) [1, 'X', 1] | |
11332 synconcealed(lnum, 3) [1, 'X', 1] | |
11333 synconcealed(lnum, 4) [1, 'X', 2] | |
11334 synconcealed(lnum, 5) [1, 'X', 2] | |
11335 synconcealed(lnum, 6) [0, '', 0] | |
11336 | |
11337 | |
11338 synstack({lnum}, {col}) *synstack()* | |
11339 Return a |List|, which is the stack of syntax items at the | |
11340 position {lnum} and {col} in the current window. {lnum} is | |
11341 used like with |getline()|. Each item in the List is an ID | |
11342 like what |synID()| returns. | |
11343 The first item in the List is the outer region, following are | |
11344 items contained in that one. The last one is what |synID()| | |
11345 returns, unless not the whole item is highlighted or it is a | |
11346 transparent item. | |
11347 This function is useful for debugging a syntax file. | |
11348 Example that shows the syntax stack under the cursor: > | |
11349 for id in synstack(line("."), col(".")) | |
11350 echo synIDattr(id, "name") | |
11351 endfor | |
11352 < When the position specified with {lnum} and {col} is invalid | |
11353 nothing is returned. The position just after the last | |
11354 character in a line and the first column in an empty line are | |
11355 valid positions. | |
11356 | |
11357 system({expr} [, {input}]) *system()* *E677* | |
11358 Get the output of the shell command {expr} as a |String|. See | |
11359 |systemlist()| to get the output as a |List|. | |
11360 | |
11361 When {input} is given and is a |String| this string is written | |
11362 to a file and passed as stdin to the command. The string is | |
11363 written as-is, you need to take care of using the correct line | |
11364 separators yourself. | |
11365 If {input} is given and is a |List| it is written to the file | |
11366 in a way |writefile()| does with {binary} set to "b" (i.e. | |
11367 with a newline between each list item with newlines inside | |
11368 list items converted to NULs). | |
11369 When {input} is given and is a number that is a valid id for | |
11370 an existing buffer then the content of the buffer is written | |
11371 to the file line by line, each line terminated by a NL and | |
11372 NULs characters where the text has a NL. | |
11373 | |
11374 Pipes are not used, the 'shelltemp' option is not used. | |
11375 | |
11376 When prepended by |:silent| the terminal will not be set to | |
11377 cooked mode. This is meant to be used for commands that do | |
11378 not need the user to type. It avoids stray characters showing | |
11379 up on the screen which require |CTRL-L| to remove. > | |
11380 :silent let f = system('ls *.vim') | |
11381 < | |
11382 Note: Use |shellescape()| or |::S| with |expand()| or | |
11383 |fnamemodify()| to escape special characters in a command | |
11384 argument. Newlines in {expr} may cause the command to fail. | |
11385 The characters in 'shellquote' and 'shellxquote' may also | |
11386 cause trouble. | |
11387 This is not to be used for interactive commands. | |
11388 | |
11389 The result is a String. Example: > | |
11390 :let files = system("ls " . shellescape(expand('%:h'))) | |
11391 :let files = system('ls ' . expand('%:h:S')) | |
11392 | |
11393 < To make the result more system-independent, the shell output | |
11394 is filtered to replace <CR> with <NL> for Macintosh, and | |
11395 <CR><NL> with <NL> for DOS-like systems. | |
11396 To avoid the string being truncated at a NUL, all NUL | |
11397 characters are replaced with SOH (0x01). | |
11398 | |
11399 The command executed is constructed using several options: | |
11400 'shell' 'shellcmdflag' 'shellxquote' {expr} 'shellredir' {tmp} 'shellxquote' | |
11401 ({tmp} is an automatically generated file name). | |
11402 For Unix, braces are put around {expr} to allow for | |
11403 concatenated commands. | |
11404 | |
11405 The command will be executed in "cooked" mode, so that a | |
11406 CTRL-C will interrupt the command (on Unix at least). | |
11407 | |
11408 The resulting error code can be found in |v:shell_error|. | |
11409 This function will fail in |restricted-mode|. | |
11410 | |
11411 Note that any wrong value in the options mentioned above may | |
11412 make the function fail. It has also been reported to fail | |
11413 when using a security agent application. | |
11414 Unlike ":!cmd" there is no automatic check for changed files. | |
11415 Use |:checktime| to force a check. | |
11416 | |
11417 Can also be used as a |method|: > | |
11418 :echo GetCmd()->system() | |
11419 | |
11420 | |
11421 systemlist({expr} [, {input}]) *systemlist()* | |
11422 Same as |system()|, but returns a |List| with lines (parts of | |
11423 output separated by NL) with NULs transformed into NLs. Output | |
11424 is the same as |readfile()| will output with {binary} argument | |
11425 set to "b", except that there is no extra empty item when the | |
11426 result ends in a NL. | |
11427 Note that on MS-Windows you may get trailing CR characters. | |
11428 | |
11429 To see the difference between "echo hello" and "echo -n hello" | |
11430 use |system()| and |split()|: > | |
11431 echo system('echo hello')->split('\n', 1) | |
11432 < | |
11433 Returns an empty string on error. | |
11434 | |
11435 Can also be used as a |method|: > | |
11436 :echo GetCmd()->systemlist() | |
11437 | |
11438 | |
11439 tabpagebuflist([{arg}]) *tabpagebuflist()* | |
11440 The result is a |List|, where each item is the number of the | |
11441 buffer associated with each window in the current tab page. | |
11442 {arg} specifies the number of the tab page to be used. When | |
11443 omitted the current tab page is used. | |
11444 When {arg} is invalid the number zero is returned. | |
11445 To get a list of all buffers in all tabs use this: > | |
11446 let buflist = [] | |
11447 for i in range(tabpagenr('$')) | |
11448 call extend(buflist, tabpagebuflist(i + 1)) | |
11449 endfor | |
11450 < Note that a buffer may appear in more than one window. | |
11451 | |
11452 Can also be used as a |method|: > | |
11453 GetTabpage()->tabpagebuflist() | |
11454 | |
11455 tabpagenr([{arg}]) *tabpagenr()* | |
11456 The result is a Number, which is the number of the current | |
11457 tab page. The first tab page has number 1. | |
11458 | |
11459 The optional argument {arg} supports the following values: | |
11460 $ the number of the last tab page (the tab page | |
11461 count). | |
11462 # the number of the last accessed tab page | |
11463 (where |g<Tab>| goes to). if there is no | |
11464 previous tab page 0 is returned. | |
11465 The number can be used with the |:tab| command. | |
11466 | |
11467 | |
11468 tabpagewinnr({tabarg} [, {arg}]) *tabpagewinnr()* | |
11469 Like |winnr()| but for tab page {tabarg}. | |
11470 {tabarg} specifies the number of tab page to be used. | |
11471 {arg} is used like with |winnr()|: | |
11472 - When omitted the current window number is returned. This is | |
11473 the window which will be used when going to this tab page. | |
11474 - When "$" the number of windows is returned. | |
11475 - When "#" the previous window nr is returned. | |
11476 Useful examples: > | |
11477 tabpagewinnr(1) " current window of tab page 1 | |
11478 tabpagewinnr(4, '$') " number of windows in tab page 4 | |
11479 < When {tabarg} is invalid zero is returned. | |
11480 | |
11481 Can also be used as a |method|: > | |
11482 GetTabpage()->tabpagewinnr() | |
11483 < | |
11484 *tagfiles()* | |
11485 tagfiles() Returns a |List| with the file names used to search for tags | |
11486 for the current buffer. This is the 'tags' option expanded. | |
11487 | |
11488 | |
11489 taglist({expr} [, {filename}]) *taglist()* | |
11490 Returns a |List| of tags matching the regular expression {expr}. | |
11491 | |
11492 If {filename} is passed it is used to prioritize the results | |
11493 in the same way that |:tselect| does. See |tag-priority|. | |
11494 {filename} should be the full path of the file. | |
11495 | |
11496 Each list item is a dictionary with at least the following | |
11497 entries: | |
11498 name Name of the tag. | |
11499 filename Name of the file where the tag is | |
11500 defined. It is either relative to the | |
11501 current directory or a full path. | |
11502 cmd Ex command used to locate the tag in | |
11503 the file. | |
11504 kind Type of the tag. The value for this | |
11505 entry depends on the language specific | |
11506 kind values. Only available when | |
11507 using a tags file generated by | |
11508 Exuberant ctags or hdrtag. | |
11509 static A file specific tag. Refer to | |
11510 |static-tag| for more information. | |
11511 More entries may be present, depending on the content of the | |
11512 tags file: access, implementation, inherits and signature. | |
11513 Refer to the ctags documentation for information about these | |
11514 fields. For C code the fields "struct", "class" and "enum" | |
11515 may appear, they give the name of the entity the tag is | |
11516 contained in. | |
11517 | |
11518 The ex-command "cmd" can be either an ex search pattern, a | |
11519 line number or a line number followed by a byte number. | |
11520 | |
11521 If there are no matching tags, then an empty list is returned. | |
11522 | |
11523 To get an exact tag match, the anchors '^' and '$' should be | |
11524 used in {expr}. This also make the function work faster. | |
11525 Refer to |tag-regexp| for more information about the tag | |
11526 search regular expression pattern. | |
11527 | |
11528 Refer to |'tags'| for information about how the tags file is | |
11529 located by Vim. Refer to |tags-file-format| for the format of | |
11530 the tags file generated by the different ctags tools. | |
11531 | |
11532 Can also be used as a |method|: > | |
11533 GetTagpattern()->taglist() | |
11534 | |
11535 tan({expr}) *tan()* | |
11536 Return the tangent of {expr}, measured in radians, as a |Float| | |
11537 in the range [-inf, inf]. | |
11538 {expr} must evaluate to a |Float| or a |Number|. | |
11539 Examples: > | |
11540 :echo tan(10) | |
11541 < 0.648361 > | |
11542 :echo tan(-4.01) | |
11543 < -1.181502 | |
11544 | |
11545 Can also be used as a |method|: > | |
11546 Compute()->tan() | |
11547 < | |
11548 {only available when compiled with the |+float| feature} | |
11549 | |
11550 | |
11551 tanh({expr}) *tanh()* | |
11552 Return the hyperbolic tangent of {expr} as a |Float| in the | |
11553 range [-1, 1]. | |
11554 {expr} must evaluate to a |Float| or a |Number|. | |
11555 Examples: > | |
11556 :echo tanh(0.5) | |
11557 < 0.462117 > | |
11558 :echo tanh(-1) | |
11559 < -0.761594 | |
11560 | |
11561 Can also be used as a |method|: > | |
11562 Compute()->tanh() | |
11563 < | |
11564 {only available when compiled with the |+float| feature} | |
11565 | |
11566 | |
11567 tempname() *tempname()* *temp-file-name* | |
11568 The result is a String, which is the name of a file that | |
11569 doesn't exist. It can be used for a temporary file. The name | |
11570 is different for at least 26 consecutive calls. Example: > | |
11571 :let tmpfile = tempname() | |
11572 :exe "redir > " . tmpfile | |
11573 < For Unix, the file will be in a private directory |tempfile|. | |
11574 For MS-Windows forward slashes are used when the 'shellslash' | |
11575 option is set, or when 'shellcmdflag' starts with '-' and | |
11576 'shell' does not contain powershell or pwsh. | |
11577 | |
11578 | |
11579 term_ functions are documented here: |terminal-function-details| | |
11580 | |
11581 | |
11582 terminalprops() *terminalprops()* | |
11583 Returns a |Dictionary| with properties of the terminal that Vim | |
11584 detected from the response to |t_RV| request. See | |
11585 |v:termresponse| for the response itself. If |v:termresponse| | |
11586 is empty most values here will be 'u' for unknown. | |
11587 cursor_style whether sending |t_RS| works ** | |
11588 cursor_blink_mode whether sending |t_RC| works ** | |
11589 underline_rgb whether |t_8u| works ** | |
11590 mouse mouse type supported | |
11591 | |
11592 ** value 'u' for unknown, 'y' for yes, 'n' for no | |
11593 | |
11594 If the |+termresponse| feature is missing then the result is | |
11595 an empty dictionary. | |
11596 | |
11597 If "cursor_style" is 'y' then |t_RS| will be sent to request the | |
11598 current cursor style. | |
11599 If "cursor_blink_mode" is 'y' then |t_RC| will be sent to | |
11600 request the cursor blink status. | |
11601 "cursor_style" and "cursor_blink_mode" are also set if |t_u7| | |
11602 is not empty, Vim will detect the working of sending |t_RS| | |
11603 and |t_RC| on startup. | |
11604 | |
11605 When "underline_rgb" is not 'y', then |t_8u| will be made empty. | |
11606 This avoids sending it to xterm, which would clear the colors. | |
11607 | |
11608 For "mouse" the value 'u' is unknown | |
11609 | |
11610 Also see: | |
11611 - 'ambiwidth' - detected by using |t_u7|. | |
11612 - |v:termstyleresp| and |v:termblinkresp| for the response to | |
11613 |t_RS| and |t_RC|. | |
11614 | |
11615 | |
11616 test_ functions are documented here: |test-functions-details| | |
11617 | |
11618 | |
11619 *timer_info()* | |
11620 timer_info([{id}]) | |
11621 Return a list with information about timers. | |
11622 When {id} is given only information about this timer is | |
11623 returned. When timer {id} does not exist an empty list is | |
11624 returned. | |
11625 When {id} is omitted information about all timers is returned. | |
11626 | |
11627 For each timer the information is stored in a |Dictionary| with | |
11628 these items: | |
11629 "id" the timer ID | |
11630 "time" time the timer was started with | |
11631 "remaining" time until the timer fires | |
11632 "repeat" number of times the timer will still fire; | |
11633 -1 means forever | |
11634 "callback" the callback | |
11635 "paused" 1 if the timer is paused, 0 otherwise | |
11636 | |
11637 Can also be used as a |method|: > | |
11638 GetTimer()->timer_info() | |
11639 | |
11640 < {only available when compiled with the |+timers| feature} | |
11641 | |
11642 timer_pause({timer}, {paused}) *timer_pause()* | |
11643 Pause or unpause a timer. A paused timer does not invoke its | |
11644 callback when its time expires. Unpausing a timer may cause | |
11645 the callback to be invoked almost immediately if enough time | |
11646 has passed. | |
11647 | |
11648 Pausing a timer is useful to avoid the callback to be called | |
11649 for a short time. | |
11650 | |
11651 If {paused} evaluates to a non-zero Number or a non-empty | |
11652 String, then the timer is paused, otherwise it is unpaused. | |
11653 See |non-zero-arg|. | |
11654 | |
11655 Can also be used as a |method|: > | |
11656 GetTimer()->timer_pause(1) | |
11657 | |
11658 < {only available when compiled with the |+timers| feature} | |
11659 | |
11660 *timer_start()* *timer* *timers* | |
11661 timer_start({time}, {callback} [, {options}]) | |
11662 Create a timer and return the timer ID. | |
11663 | |
11664 {time} is the waiting time in milliseconds. This is the | |
11665 minimum time before invoking the callback. When the system is | |
11666 busy or Vim is not waiting for input the time will be longer. | |
11667 | |
11668 {callback} is the function to call. It can be the name of a | |
11669 function or a |Funcref|. It is called with one argument, which | |
11670 is the timer ID. The callback is only invoked when Vim is | |
11671 waiting for input. | |
11672 If you want to show a message look at |popup_notification()| | |
11673 to avoid interfering with what the user is doing. | |
11674 | |
11675 {options} is a dictionary. Supported entries: | |
11676 "repeat" Number of times to repeat calling the | |
11677 callback. -1 means forever. When not present | |
11678 the callback will be called once. | |
11679 If the timer causes an error three times in a | |
11680 row the repeat is cancelled. This avoids that | |
11681 Vim becomes unusable because of all the error | |
11682 messages. | |
11683 | |
11684 Example: > | |
11685 func MyHandler(timer) | |
11686 echo 'Handler called' | |
11687 endfunc | |
11688 let timer = timer_start(500, 'MyHandler', | |
11689 \ {'repeat': 3}) | |
11690 < This will invoke MyHandler() three times at 500 msec | |
11691 intervals. | |
11692 | |
11693 Can also be used as a |method|: > | |
11694 GetMsec()->timer_start(callback) | |
11695 | |
11696 < Not available in the |sandbox|. | |
11697 {only available when compiled with the |+timers| feature} | |
11698 | |
11699 timer_stop({timer}) *timer_stop()* | |
11700 Stop a timer. The timer callback will no longer be invoked. | |
11701 {timer} is an ID returned by timer_start(), thus it must be a | |
11702 Number. If {timer} does not exist there is no error. | |
11703 | |
11704 Can also be used as a |method|: > | |
11705 GetTimer()->timer_stop() | |
11706 | |
11707 < {only available when compiled with the |+timers| feature} | |
11708 | |
11709 timer_stopall() *timer_stopall()* | |
11710 Stop all timers. The timer callbacks will no longer be | |
11711 invoked. Useful if a timer is misbehaving. If there are no | |
11712 timers there is no error. | |
11713 | |
11714 {only available when compiled with the |+timers| feature} | |
11715 | |
11716 tolower({expr}) *tolower()* | |
11717 The result is a copy of the String given, with all uppercase | |
11718 characters turned into lowercase (just like applying |gu| to | |
11719 the string). | |
11720 | |
11721 Can also be used as a |method|: > | |
11722 GetText()->tolower() | |
11723 | |
11724 toupper({expr}) *toupper()* | |
11725 The result is a copy of the String given, with all lowercase | |
11726 characters turned into uppercase (just like applying |gU| to | |
11727 the string). | |
11728 | |
11729 Can also be used as a |method|: > | |
11730 GetText()->toupper() | |
11731 | |
11732 tr({src}, {fromstr}, {tostr}) *tr()* | |
11733 The result is a copy of the {src} string with all characters | |
11734 which appear in {fromstr} replaced by the character in that | |
11735 position in the {tostr} string. Thus the first character in | |
11736 {fromstr} is translated into the first character in {tostr} | |
11737 and so on. Exactly like the unix "tr" command. | |
11738 This code also deals with multibyte characters properly. | |
11739 | |
11740 Examples: > | |
11741 echo tr("hello there", "ht", "HT") | |
11742 < returns "Hello THere" > | |
11743 echo tr("<blob>", "<>", "{}") | |
11744 < returns "{blob}" | |
11745 | |
11746 Can also be used as a |method|: > | |
11747 GetText()->tr(from, to) | |
11748 | |
11749 trim({text} [, {mask} [, {dir}]]) *trim()* | |
11750 Return {text} as a String where any character in {mask} is | |
11751 removed from the beginning and/or end of {text}. | |
11752 | |
11753 If {mask} is not given, {mask} is all characters up to 0x20, | |
11754 which includes Tab, space, NL and CR, plus the non-breaking | |
11755 space character 0xa0. | |
11756 | |
11757 The optional {dir} argument specifies where to remove the | |
11758 characters: | |
11759 0 remove from the beginning and end of {text} | |
11760 1 remove only at the beginning of {text} | |
11761 2 remove only at the end of {text} | |
11762 When omitted both ends are trimmed. | |
11763 | |
11764 This function deals with multibyte characters properly. | |
11765 | |
11766 Examples: > | |
11767 echo trim(" some text ") | |
11768 < returns "some text" > | |
11769 echo trim(" \r\t\t\r RESERVE \t\n\x0B\xA0") . "_TAIL" | |
11770 < returns "RESERVE_TAIL" > | |
11771 echo trim("rm<Xrm<>X>rrm", "rm<>") | |
11772 < returns "Xrm<>X" (characters in the middle are not removed) > | |
11773 echo trim(" vim ", " ", 2) | |
11774 < returns " vim" | |
11775 | |
11776 Can also be used as a |method|: > | |
11777 GetText()->trim() | |
11778 | |
11779 trunc({expr}) *trunc()* | |
11780 Return the largest integral value with magnitude less than or | |
11781 equal to {expr} as a |Float| (truncate towards zero). | |
11782 {expr} must evaluate to a |Float| or a |Number|. | |
11783 Examples: > | |
11784 echo trunc(1.456) | |
11785 < 1.0 > | |
11786 echo trunc(-5.456) | |
11787 < -5.0 > | |
11788 echo trunc(4.0) | |
11789 < 4.0 | |
11790 | |
11791 Can also be used as a |method|: > | |
11792 Compute()->trunc() | |
11793 < | |
11794 {only available when compiled with the |+float| feature} | |
11795 | |
11796 *type()* | |
11797 type({expr}) The result is a Number representing the type of {expr}. | |
11798 Instead of using the number directly, it is better to use the | |
11799 v:t_ variable that has the value: | |
11800 Number: 0 |v:t_number| | |
11801 String: 1 |v:t_string| | |
11802 Funcref: 2 |v:t_func| | |
11803 List: 3 |v:t_list| | |
11804 Dictionary: 4 |v:t_dict| | |
11805 Float: 5 |v:t_float| | |
11806 Boolean: 6 |v:t_bool| (v:false and v:true) | |
11807 None: 7 |v:t_none| (v:null and v:none) | |
11808 Job: 8 |v:t_job| | |
11809 Channel: 9 |v:t_channel| | |
11810 Blob: 10 |v:t_blob| | |
11811 For backward compatibility, this method can be used: > | |
11812 :if type(myvar) == type(0) | |
11813 :if type(myvar) == type("") | |
11814 :if type(myvar) == type(function("tr")) | |
11815 :if type(myvar) == type([]) | |
11816 :if type(myvar) == type({}) | |
11817 :if type(myvar) == type(0.0) | |
11818 :if type(myvar) == type(v:false) | |
11819 :if type(myvar) == type(v:none) | |
11820 < To check if the v:t_ variables exist use this: > | |
11821 :if exists('v:t_number') | |
11822 | |
11823 < Can also be used as a |method|: > | |
11824 mylist->type() | |
11825 | |
11826 | |
11827 typename({expr}) *typename()* | |
11828 Return a string representation of the type of {expr}. | |
11829 Example: > | |
11830 echo typename([1, 2, 3]) | |
11831 list<number> | |
11832 | |
11833 | |
11834 undofile({name}) *undofile()* | |
11835 Return the name of the undo file that would be used for a file | |
11836 with name {name} when writing. This uses the 'undodir' | |
11837 option, finding directories that exist. It does not check if | |
11838 the undo file exists. | |
11839 {name} is always expanded to the full path, since that is what | |
11840 is used internally. | |
11841 If {name} is empty undofile() returns an empty string, since a | |
11842 buffer without a file name will not write an undo file. | |
11843 Useful in combination with |:wundo| and |:rundo|. | |
11844 When compiled without the |+persistent_undo| option this always | |
11845 returns an empty string. | |
11846 | |
11847 Can also be used as a |method|: > | |
11848 GetFilename()->undofile() | |
11849 | |
11850 undotree() *undotree()* | |
11851 Return the current state of the undo tree in a dictionary with | |
11852 the following items: | |
11853 "seq_last" The highest undo sequence number used. | |
11854 "seq_cur" The sequence number of the current position in | |
11855 the undo tree. This differs from "seq_last" | |
11856 when some changes were undone. | |
11857 "time_cur" Time last used for |:earlier| and related | |
11858 commands. Use |strftime()| to convert to | |
11859 something readable. | |
11860 "save_last" Number of the last file write. Zero when no | |
11861 write yet. | |
11862 "save_cur" Number of the current position in the undo | |
11863 tree. | |
11864 "synced" Non-zero when the last undo block was synced. | |
11865 This happens when waiting from input from the | |
11866 user. See |undo-blocks|. | |
11867 "entries" A list of dictionaries with information about | |
11868 undo blocks. | |
11869 | |
11870 The first item in the "entries" list is the oldest undo item. | |
11871 Each List item is a |Dictionary| with these items: | |
11872 "seq" Undo sequence number. Same as what appears in | |
11873 |:undolist|. | |
11874 "time" Timestamp when the change happened. Use | |
11875 |strftime()| to convert to something readable. | |
11876 "newhead" Only appears in the item that is the last one | |
11877 that was added. This marks the last change | |
11878 and where further changes will be added. | |
11879 "curhead" Only appears in the item that is the last one | |
11880 that was undone. This marks the current | |
11881 position in the undo tree, the block that will | |
11882 be used by a redo command. When nothing was | |
11883 undone after the last change this item will | |
11884 not appear anywhere. | |
11885 "save" Only appears on the last block before a file | |
11886 write. The number is the write count. The | |
11887 first write has number 1, the last one the | |
11888 "save_last" mentioned above. | |
11889 "alt" Alternate entry. This is again a List of undo | |
11890 blocks. Each item may again have an "alt" | |
11891 item. | |
11892 | |
11893 uniq({list} [, {func} [, {dict}]]) *uniq()* *E882* | |
11894 Remove second and succeeding copies of repeated adjacent | |
11895 {list} items in-place. Returns {list}. If you want a list | |
11896 to remain unmodified make a copy first: > | |
11897 :let newlist = uniq(copy(mylist)) | |
11898 < The default compare function uses the string representation of | |
11899 each item. For the use of {func} and {dict} see |sort()|. | |
11900 | |
11901 Can also be used as a |method|: > | |
11902 mylist->uniq() | |
11903 | |
11904 values({dict}) *values()* | |
11905 Return a |List| with all the values of {dict}. The |List| is | |
11906 in arbitrary order. Also see |items()| and |keys()|. | |
11907 | |
11908 Can also be used as a |method|: > | |
11909 mydict->values() | |
11910 | |
11911 virtcol({expr}) *virtcol()* | |
11912 The result is a Number, which is the screen column of the file | |
11913 position given with {expr}. That is, the last screen position | |
11914 occupied by the character at that position, when the screen | |
11915 would be of unlimited width. When there is a <Tab> at the | |
11916 position, the returned Number will be the column at the end of | |
11917 the <Tab>. For example, for a <Tab> in column 1, with 'ts' | |
11918 set to 8, it returns 8. |conceal| is ignored. | |
11919 For the byte position use |col()|. | |
11920 For the use of {expr} see |col()|. | |
11921 When 'virtualedit' is used {expr} can be [lnum, col, off], where | |
11922 "off" is the offset in screen columns from the start of the | |
11923 character. E.g., a position within a <Tab> or after the last | |
11924 character. When "off" is omitted zero is used. | |
11925 When Virtual editing is active in the current mode, a position | |
11926 beyond the end of the line can be returned. |'virtualedit'| | |
11927 The accepted positions are: | |
11928 . the cursor position | |
11929 $ the end of the cursor line (the result is the | |
11930 number of displayed characters in the cursor line | |
11931 plus one) | |
11932 'x position of mark x (if the mark is not set, 0 is | |
11933 returned) | |
11934 v In Visual mode: the start of the Visual area (the | |
11935 cursor is the end). When not in Visual mode | |
11936 returns the cursor position. Differs from |'<| in | |
11937 that it's updated right away. | |
11938 Note that only marks in the current file can be used. | |
11939 Examples: > | |
11940 virtcol(".") with text "foo^Lbar", with cursor on the "^L", returns 5 | |
11941 virtcol("$") with text "foo^Lbar", returns 9 | |
11942 virtcol("'t") with text " there", with 't at 'h', returns 6 | |
11943 < The first column is 1. 0 is returned for an error. | |
11944 A more advanced example that echoes the maximum length of | |
11945 all lines: > | |
11946 echo max(map(range(1, line('$')), "virtcol([v:val, '$'])")) | |
11947 | |
11948 < Can also be used as a |method|: > | |
11949 GetPos()->virtcol() | |
11950 | |
11951 | |
11952 visualmode([{expr}]) *visualmode()* | |
11953 The result is a String, which describes the last Visual mode | |
11954 used in the current buffer. Initially it returns an empty | |
11955 string, but once Visual mode has been used, it returns "v", | |
11956 "V", or "<CTRL-V>" (a single CTRL-V character) for | |
11957 character-wise, line-wise, or block-wise Visual mode | |
11958 respectively. | |
11959 Example: > | |
11960 :exe "normal " . visualmode() | |
11961 < This enters the same Visual mode as before. It is also useful | |
11962 in scripts if you wish to act differently depending on the | |
11963 Visual mode that was used. | |
11964 If Visual mode is active, use |mode()| to get the Visual mode | |
11965 (e.g., in a |:vmap|). | |
11966 If {expr} is supplied and it evaluates to a non-zero Number or | |
11967 a non-empty String, then the Visual mode will be cleared and | |
11968 the old value is returned. See |non-zero-arg|. | |
11969 | |
11970 wildmenumode() *wildmenumode()* | |
11971 Returns |TRUE| when the wildmenu is active and |FALSE| | |
11972 otherwise. See 'wildmenu' and 'wildmode'. | |
11973 This can be used in mappings to handle the 'wildcharm' option | |
11974 gracefully. (Makes only sense with |mapmode-c| mappings). | |
11975 | |
11976 For example to make <c-j> work like <down> in wildmode, use: > | |
11977 :cnoremap <expr> <C-j> wildmenumode() ? "\<Down>\<Tab>" : "\<c-j>" | |
11978 < | |
11979 (Note, this needs the 'wildcharm' option set appropriately). | |
11980 | |
11981 win_execute({id}, {command} [, {silent}]) *win_execute()* | |
11982 Like `execute()` but in the context of window {id}. | |
11983 The window will temporarily be made the current window, | |
11984 without triggering autocommands or changing directory. When | |
11985 executing {command} autocommands will be triggered, this may | |
11986 have unexpected side effects. Use |:noautocmd| if needed. | |
11987 Example: > | |
11988 call win_execute(winid, 'set syntax=python') | |
11989 < Doing the same with `setwinvar()` would not trigger | |
11990 autocommands and not actually show syntax highlighting. | |
11991 | |
11992 *E994* | |
11993 Not all commands are allowed in popup windows. | |
11994 When window {id} does not exist then no error is given and | |
11995 an empty string is returned. | |
11996 | |
11997 Can also be used as a |method|, the base is passed as the | |
11998 second argument: > | |
11999 GetCommand()->win_execute(winid) | |
12000 | |
12001 win_findbuf({bufnr}) *win_findbuf()* | |
12002 Returns a |List| with |window-ID|s for windows that contain | |
12003 buffer {bufnr}. When there is none the list is empty. | |
12004 | |
12005 Can also be used as a |method|: > | |
12006 GetBufnr()->win_findbuf() | |
12007 | |
12008 win_getid([{win} [, {tab}]]) *win_getid()* | |
12009 Get the |window-ID| for the specified window. | |
12010 When {win} is missing use the current window. | |
12011 With {win} this is the window number. The top window has | |
12012 number 1. | |
12013 Without {tab} use the current tab, otherwise the tab with | |
12014 number {tab}. The first tab has number one. | |
12015 Return zero if the window cannot be found. | |
12016 | |
12017 Can also be used as a |method|: > | |
12018 GetWinnr()->win_getid() | |
12019 | |
12020 | |
12021 win_gettype([{nr}]) *win_gettype()* | |
12022 Return the type of the window: | |
12023 "autocmd" autocommand window. Temporary window | |
12024 used to execute autocommands. | |
12025 "command" command-line window |cmdwin| | |
12026 (empty) normal window | |
12027 "loclist" |location-list-window| | |
12028 "popup" popup window |popup| | |
12029 "preview" preview window |preview-window| | |
12030 "quickfix" |quickfix-window| | |
12031 "unknown" window {nr} not found | |
12032 | |
12033 When {nr} is omitted return the type of the current window. | |
12034 When {nr} is given return the type of this window by number or | |
12035 |window-ID|. | |
12036 | |
12037 Also see the 'buftype' option. When running a terminal in a | |
12038 popup window then 'buftype' is "terminal" and win_gettype() | |
12039 returns "popup". | |
12040 | |
12041 Can also be used as a |method|: > | |
12042 GetWinid()->win_gettype() | |
12043 < | |
12044 win_gotoid({expr}) *win_gotoid()* | |
12045 Go to window with ID {expr}. This may also change the current | |
12046 tabpage. | |
12047 Return TRUE if successful, FALSE if the window cannot be found. | |
12048 | |
12049 Can also be used as a |method|: > | |
12050 GetWinid()->win_gotoid() | |
12051 | |
12052 win_id2tabwin({expr}) *win_id2tabwin()* | |
12053 Return a list with the tab number and window number of window | |
12054 with ID {expr}: [tabnr, winnr]. | |
12055 Return [0, 0] if the window cannot be found. | |
12056 | |
12057 Can also be used as a |method|: > | |
12058 GetWinid()->win_id2tabwin() | |
12059 | |
12060 win_id2win({expr}) *win_id2win()* | |
12061 Return the window number of window with ID {expr}. | |
12062 Return 0 if the window cannot be found in the current tabpage. | |
12063 | |
12064 Can also be used as a |method|: > | |
12065 GetWinid()->win_id2win() | |
12066 | |
12067 win_screenpos({nr}) *win_screenpos()* | |
12068 Return the screen position of window {nr} as a list with two | |
12069 numbers: [row, col]. The first window always has position | |
12070 [1, 1], unless there is a tabline, then it is [2, 1]. | |
12071 {nr} can be the window number or the |window-ID|. Use zero | |
12072 for the current window. | |
12073 Returns [0, 0] if the window cannot be found in the current | |
12074 tabpage. | |
12075 | |
12076 Can also be used as a |method|: > | |
12077 GetWinid()->win_screenpos() | |
12078 < | |
12079 win_splitmove({nr}, {target} [, {options}]) *win_splitmove()* | |
12080 Move the window {nr} to a new split of the window {target}. | |
12081 This is similar to moving to {target}, creating a new window | |
12082 using |:split| but having the same contents as window {nr}, and | |
12083 then closing {nr}. | |
12084 | |
12085 Both {nr} and {target} can be window numbers or |window-ID|s. | |
12086 Both must be in the current tab page. | |
12087 | |
12088 Returns zero for success, non-zero for failure. | |
12089 | |
12090 {options} is a |Dictionary| with the following optional entries: | |
12091 "vertical" When TRUE, the split is created vertically, | |
12092 like with |:vsplit|. | |
12093 "rightbelow" When TRUE, the split is made below or to the | |
12094 right (if vertical). When FALSE, it is done | |
12095 above or to the left (if vertical). When not | |
12096 present, the values of 'splitbelow' and | |
12097 'splitright' are used. | |
12098 | |
12099 Can also be used as a |method|: > | |
12100 GetWinid()->win_splitmove(target) | |
12101 < | |
12102 | |
12103 *winbufnr()* | |
12104 winbufnr({nr}) The result is a Number, which is the number of the buffer | |
12105 associated with window {nr}. {nr} can be the window number or | |
12106 the |window-ID|. | |
12107 When {nr} is zero, the number of the buffer in the current | |
12108 window is returned. | |
12109 When window {nr} doesn't exist, -1 is returned. | |
12110 Example: > | |
12111 :echo "The file in the current window is " . bufname(winbufnr(0)) | |
12112 < | |
12113 Can also be used as a |method|: > | |
12114 FindWindow()->winbufnr()->bufname() | |
12115 < | |
12116 *wincol()* | |
12117 wincol() The result is a Number, which is the virtual column of the | |
12118 cursor in the window. This is counting screen cells from the | |
12119 left side of the window. The leftmost column is one. | |
12120 | |
12121 *windowsversion()* | |
12122 windowsversion() | |
12123 The result is a String. For MS-Windows it indicates the OS | |
12124 version. E.g, Windows 10 is "10.0", Windows 8 is "6.2", | |
12125 Windows XP is "5.1". For non-MS-Windows systems the result is | |
12126 an empty string. | |
12127 | |
12128 winheight({nr}) *winheight()* | |
12129 The result is a Number, which is the height of window {nr}. | |
12130 {nr} can be the window number or the |window-ID|. | |
12131 When {nr} is zero, the height of the current window is | |
12132 returned. When window {nr} doesn't exist, -1 is returned. | |
12133 An existing window always has a height of zero or more. | |
12134 This excludes any window toolbar line. | |
12135 Examples: > | |
12136 :echo "The current window has " . winheight(0) . " lines." | |
12137 | |
12138 < Can also be used as a |method|: > | |
12139 GetWinid()->winheight() | |
12140 < | |
12141 winlayout([{tabnr}]) *winlayout()* | |
12142 The result is a nested List containing the layout of windows | |
12143 in a tabpage. | |
12144 | |
12145 Without {tabnr} use the current tabpage, otherwise the tabpage | |
12146 with number {tabnr}. If the tabpage {tabnr} is not found, | |
12147 returns an empty list. | |
12148 | |
12149 For a leaf window, it returns: | |
12150 ['leaf', {winid}] | |
12151 For horizontally split windows, which form a column, it | |
12152 returns: | |
12153 ['col', [{nested list of windows}]] | |
12154 For vertically split windows, which form a row, it returns: | |
12155 ['row', [{nested list of windows}]] | |
12156 | |
12157 Example: > | |
12158 " Only one window in the tab page | |
12159 :echo winlayout() | |
12160 ['leaf', 1000] | |
12161 " Two horizontally split windows | |
12162 :echo winlayout() | |
12163 ['col', [['leaf', 1000], ['leaf', 1001]]] | |
12164 " The second tab page, with three horizontally split | |
12165 " windows, with two vertically split windows in the | |
12166 " middle window | |
12167 :echo winlayout(2) | |
12168 ['col', [['leaf', 1002], ['row', [['leaf', 1003], | |
12169 ['leaf', 1001]]], ['leaf', 1000]]] | |
12170 < | |
12171 Can also be used as a |method|: > | |
12172 GetTabnr()->winlayout() | |
12173 < | |
12174 *winline()* | |
12175 winline() The result is a Number, which is the screen line of the cursor | |
12176 in the window. This is counting screen lines from the top of | |
12177 the window. The first line is one. | |
12178 If the cursor was moved the view on the file will be updated | |
12179 first, this may cause a scroll. | |
12180 | |
12181 *winnr()* | |
12182 winnr([{arg}]) The result is a Number, which is the number of the current | |
12183 window. The top window has number 1. | |
12184 Returns zero for a popup window. | |
12185 | |
12186 The optional argument {arg} supports the following values: | |
12187 $ the number of the last window (the window | |
12188 count). | |
12189 # the number of the last accessed window (where | |
12190 |CTRL-W_p| goes to). If there is no previous | |
12191 window or it is in another tab page 0 is | |
12192 returned. | |
12193 {N}j the number of the Nth window below the | |
12194 current window (where |CTRL-W_j| goes to). | |
12195 {N}k the number of the Nth window above the current | |
12196 window (where |CTRL-W_k| goes to). | |
12197 {N}h the number of the Nth window left of the | |
12198 current window (where |CTRL-W_h| goes to). | |
12199 {N}l the number of the Nth window right of the | |
12200 current window (where |CTRL-W_l| goes to). | |
12201 The number can be used with |CTRL-W_w| and ":wincmd w" | |
12202 |:wincmd|. | |
12203 Also see |tabpagewinnr()| and |win_getid()|. | |
12204 Examples: > | |
12205 let window_count = winnr('$') | |
12206 let prev_window = winnr('#') | |
12207 let wnum = winnr('3k') | |
12208 | |
12209 < Can also be used as a |method|: > | |
12210 GetWinval()->winnr() | |
12211 < | |
12212 *winrestcmd()* | |
12213 winrestcmd() Returns a sequence of |:resize| commands that should restore | |
12214 the current window sizes. Only works properly when no windows | |
12215 are opened or closed and the current window and tab page is | |
12216 unchanged. | |
12217 Example: > | |
12218 :let cmd = winrestcmd() | |
12219 :call MessWithWindowSizes() | |
12220 :exe cmd | |
12221 < | |
12222 *winrestview()* | |
12223 winrestview({dict}) | |
12224 Uses the |Dictionary| returned by |winsaveview()| to restore | |
12225 the view of the current window. | |
12226 Note: The {dict} does not have to contain all values, that are | |
12227 returned by |winsaveview()|. If values are missing, those | |
12228 settings won't be restored. So you can use: > | |
12229 :call winrestview({'curswant': 4}) | |
12230 < | |
12231 This will only set the curswant value (the column the cursor | |
12232 wants to move on vertical movements) of the cursor to column 5 | |
12233 (yes, that is 5), while all other settings will remain the | |
12234 same. This is useful, if you set the cursor position manually. | |
12235 | |
12236 If you have changed the values the result is unpredictable. | |
12237 If the window size changed the result won't be the same. | |
12238 | |
12239 Can also be used as a |method|: > | |
12240 GetView()->winrestview() | |
12241 < | |
12242 *winsaveview()* | |
12243 winsaveview() Returns a |Dictionary| that contains information to restore | |
12244 the view of the current window. Use |winrestview()| to | |
12245 restore the view. | |
12246 This is useful if you have a mapping that jumps around in the | |
12247 buffer and you want to go back to the original view. | |
12248 This does not save fold information. Use the 'foldenable' | |
12249 option to temporarily switch off folding, so that folds are | |
12250 not opened when moving around. This may have side effects. | |
12251 The return value includes: | |
12252 lnum cursor line number | |
12253 col cursor column (Note: the first column | |
12254 zero, as opposed to what getpos() | |
12255 returns) | |
12256 coladd cursor column offset for 'virtualedit' | |
12257 curswant column for vertical movement | |
12258 topline first line in the window | |
12259 topfill filler lines, only in diff mode | |
12260 leftcol first column displayed; only used when | |
12261 'wrap' is off | |
12262 skipcol columns skipped | |
12263 Note that no option values are saved. | |
12264 | |
12265 | |
12266 winwidth({nr}) *winwidth()* | |
12267 The result is a Number, which is the width of window {nr}. | |
12268 {nr} can be the window number or the |window-ID|. | |
12269 When {nr} is zero, the width of the current window is | |
12270 returned. When window {nr} doesn't exist, -1 is returned. | |
12271 An existing window always has a width of zero or more. | |
12272 Examples: > | |
12273 :echo "The current window has " . winwidth(0) . " columns." | |
12274 :if winwidth(0) <= 50 | |
12275 : 50 wincmd | | |
12276 :endif | |
12277 < For getting the terminal or screen size, see the 'columns' | |
12278 option. | |
12279 | |
12280 Can also be used as a |method|: > | |
12281 GetWinid()->winwidth() | |
12282 | |
12283 | |
12284 wordcount() *wordcount()* | |
12285 The result is a dictionary of byte/chars/word statistics for | |
12286 the current buffer. This is the same info as provided by | |
12287 |g_CTRL-G| | |
12288 The return value includes: | |
12289 bytes Number of bytes in the buffer | |
12290 chars Number of chars in the buffer | |
12291 words Number of words in the buffer | |
12292 cursor_bytes Number of bytes before cursor position | |
12293 (not in Visual mode) | |
12294 cursor_chars Number of chars before cursor position | |
12295 (not in Visual mode) | |
12296 cursor_words Number of words before cursor position | |
12297 (not in Visual mode) | |
12298 visual_bytes Number of bytes visually selected | |
12299 (only in Visual mode) | |
12300 visual_chars Number of chars visually selected | |
12301 (only in Visual mode) | |
12302 visual_words Number of words visually selected | |
12303 (only in Visual mode) | |
12304 | |
12305 | |
12306 *writefile()* | |
12307 writefile({object}, {fname} [, {flags}]) | |
12308 When {object} is a |List| write it to file {fname}. Each list | |
12309 item is separated with a NL. Each list item must be a String | |
12310 or Number. | |
12311 When {flags} contains "b" then binary mode is used: There will | |
12312 not be a NL after the last list item. An empty item at the | |
12313 end does cause the last line in the file to end in a NL. | |
12314 | |
12315 When {object} is a |Blob| write the bytes to file {fname} | |
12316 unmodified. | |
12317 | |
12318 When {flags} contains "a" then append mode is used, lines are | |
12319 appended to the file: > | |
12320 :call writefile(["foo"], "event.log", "a") | |
12321 :call writefile(["bar"], "event.log", "a") | |
12322 < | |
12323 When {flags} contains "s" then fsync() is called after writing | |
12324 the file. This flushes the file to disk, if possible. This | |
12325 takes more time but avoids losing the file if the system | |
12326 crashes. | |
12327 When {flags} does not contain "S" or "s" then fsync() is | |
12328 called if the 'fsync' option is set. | |
12329 When {flags} contains "S" then fsync() is not called, even | |
12330 when 'fsync' is set. | |
12331 | |
12332 All NL characters are replaced with a NUL character. | |
12333 Inserting CR characters needs to be done before passing {list} | |
12334 to writefile(). | |
12335 An existing file is overwritten, if possible. | |
12336 When the write fails -1 is returned, otherwise 0. There is an | |
12337 error message if the file can't be created or when writing | |
12338 fails. | |
12339 Also see |readfile()|. | |
12340 To copy a file byte for byte: > | |
12341 :let fl = readfile("foo", "b") | |
12342 :call writefile(fl, "foocopy", "b") | |
12343 | |
12344 < Can also be used as a |method|: > | |
12345 GetText()->writefile("thefile") | |
12346 | |
12347 | |
12348 xor({expr}, {expr}) *xor()* | |
12349 Bitwise XOR on the two arguments. The arguments are converted | |
12350 to a number. A List, Dict or Float argument causes an error. | |
12351 Example: > | |
12352 :let bits = xor(bits, 0x80) | |
12353 < | |
12354 Can also be used as a |method|: > | |
12355 :let bits = bits->xor(0x80) | |
12356 < | |
12357 | |
12358 *feature-list* | |
12359 There are three types of features: | |
12360 1. Features that are only supported when they have been enabled when Vim | |
12361 was compiled |+feature-list|. Example: > | |
12362 :if has("cindent") | |
12363 < *gui_running* | |
12364 2. Features that are only supported when certain conditions have been met. | |
12365 Example: > | |
12366 :if has("gui_running") | |
12367 < *has-patch* | |
12368 3. Beyond a certain version or at a certain version and including a specific | |
12369 patch. The "patch-7.4.248" feature means that the Vim version is 7.5 or | |
12370 later, or it is version 7.4 and patch 248 was included. Example: > | |
12371 :if has("patch-7.4.248") | |
12372 < Note that it's possible for patch 248 to be omitted even though 249 is | |
12373 included. Only happens when cherry-picking patches. | |
12374 Note that this form only works for patch 7.4.237 and later, before that | |
12375 you need to check for the patch and the v:version. Example (checking | |
12376 version 6.2.148 or later): > | |
12377 :if v:version > 602 || (v:version == 602 && has("patch148")) | |
12378 | |
12379 Hint: To find out if Vim supports backslashes in a file name (MS-Windows), | |
12380 use: `if exists('+shellslash')` | |
12381 | |
12382 | |
12383 acl Compiled with |ACL| support. | |
12384 all_builtin_terms Compiled with all builtin terminals enabled. | |
12385 amiga Amiga version of Vim. | |
12386 arabic Compiled with Arabic support |Arabic|. | |
12387 arp Compiled with ARP support (Amiga). | |
12388 autocmd Compiled with autocommand support. (always true) | |
12389 autochdir Compiled with support for 'autochdir' | |
12390 autoservername Automatically enable |clientserver| | |
12391 balloon_eval Compiled with |balloon-eval| support. | |
12392 balloon_multiline GUI supports multiline balloons. | |
12393 beos BeOS version of Vim. | |
12394 browse Compiled with |:browse| support, and browse() will | |
12395 work. | |
12396 browsefilter Compiled with support for |browsefilter|. | |
12397 bsd Compiled on an OS in the BSD family (excluding macOS). | |
12398 builtin_terms Compiled with some builtin terminals. | |
12399 byte_offset Compiled with support for 'o' in 'statusline' | |
12400 channel Compiled with support for |channel| and |job| | |
12401 cindent Compiled with 'cindent' support. | |
12402 clientserver Compiled with remote invocation support |clientserver|. | |
12403 clipboard Compiled with 'clipboard' support. | |
12404 clipboard_working Compiled with 'clipboard' support and it can be used. | |
12405 cmdline_compl Compiled with |cmdline-completion| support. | |
12406 cmdline_hist Compiled with |cmdline-history| support. | |
12407 cmdline_info Compiled with 'showcmd' and 'ruler' support. | |
12408 comments Compiled with |'comments'| support. | |
12409 compatible Compiled to be very Vi compatible. | |
12410 conpty Platform where |ConPTY| can be used. | |
12411 cryptv Compiled with encryption support |encryption|. | |
12412 cscope Compiled with |cscope| support. | |
12413 cursorbind Compiled with |'cursorbind'| (always true) | |
12414 debug Compiled with "DEBUG" defined. | |
12415 dialog_con Compiled with console dialog support. | |
12416 dialog_gui Compiled with GUI dialog support. | |
12417 diff Compiled with |vimdiff| and 'diff' support. | |
12418 digraphs Compiled with support for digraphs. | |
12419 directx Compiled with support for DirectX and 'renderoptions'. | |
12420 dnd Compiled with support for the "~ register |quote_~|. | |
12421 drop_file Compiled with |drop_file| support. | |
12422 ebcdic Compiled on a machine with ebcdic character set. | |
12423 emacs_tags Compiled with support for Emacs tags. | |
12424 eval Compiled with expression evaluation support. Always | |
12425 true, of course! | |
12426 ex_extra |+ex_extra| (always true) | |
12427 extra_search Compiled with support for |'incsearch'| and | |
12428 |'hlsearch'| | |
12429 farsi Support for Farsi was removed |farsi|. | |
12430 file_in_path Compiled with support for |gf| and |<cfile>| | |
12431 filterpipe When 'shelltemp' is off pipes are used for shell | |
12432 read/write/filter commands | |
12433 find_in_path Compiled with support for include file searches | |
12434 |+find_in_path|. | |
12435 float Compiled with support for |Float|. | |
12436 fname_case Case in file names matters (for Amiga and MS-Windows | |
12437 this is not present). | |
12438 folding Compiled with |folding| support. | |
12439 footer Compiled with GUI footer support. |gui-footer| | |
12440 fork Compiled to use fork()/exec() instead of system(). | |
12441 gettext Compiled with message translation |multi-lang| | |
12442 gui Compiled with GUI enabled. | |
12443 gui_athena Compiled with Athena GUI. | |
12444 gui_gnome Compiled with Gnome support (gui_gtk is also defined). | |
12445 gui_gtk Compiled with GTK+ GUI (any version). | |
12446 gui_gtk2 Compiled with GTK+ 2 GUI (gui_gtk is also defined). | |
12447 gui_gtk3 Compiled with GTK+ 3 GUI (gui_gtk is also defined). | |
12448 gui_haiku Compiled with Haiku GUI. | |
12449 gui_mac Compiled with Macintosh GUI. | |
12450 gui_motif Compiled with Motif GUI. | |
12451 gui_photon Compiled with Photon GUI. | |
12452 gui_running Vim is running in the GUI, or it will start soon. | |
12453 gui_win32 Compiled with MS-Windows Win32 GUI. | |
12454 gui_win32s idem, and Win32s system being used (Windows 3.1) | |
12455 haiku Haiku version of Vim. | |
12456 hangul_input Compiled with Hangul input support. |hangul| | |
12457 hpux HP-UX version of Vim. | |
12458 iconv Can use iconv() for conversion. | |
12459 insert_expand Compiled with support for CTRL-X expansion commands in | |
12460 Insert mode. (always true) | |
12461 job Compiled with support for |channel| and |job| | |
12462 ipv6 Compiled with support for IPv6 networking in |channel|. | |
12463 jumplist Compiled with |jumplist| support. | |
12464 keymap Compiled with 'keymap' support. | |
12465 lambda Compiled with |lambda| support. | |
12466 langmap Compiled with 'langmap' support. | |
12467 libcall Compiled with |libcall()| support. | |
12468 linebreak Compiled with 'linebreak', 'breakat', 'showbreak' and | |
12469 'breakindent' support. | |
12470 linux Linux version of Vim. | |
12471 lispindent Compiled with support for lisp indenting. | |
12472 listcmds Compiled with commands for the buffer list |:files| | |
12473 and the argument list |arglist|. | |
12474 localmap Compiled with local mappings and abbr. |:map-local| | |
12475 lua Compiled with Lua interface |Lua|. | |
12476 mac Any Macintosh version of Vim cf. osx | |
12477 macunix Synonym for osxdarwin | |
12478 menu Compiled with support for |:menu|. | |
12479 mksession Compiled with support for |:mksession|. | |
12480 modify_fname Compiled with file name modifiers. |filename-modifiers| | |
12481 (always true) | |
12482 mouse Compiled with support for mouse. | |
12483 mouse_dec Compiled with support for Dec terminal mouse. | |
12484 mouse_gpm Compiled with support for gpm (Linux console mouse) | |
12485 mouse_gpm_enabled GPM mouse is working | |
12486 mouse_netterm Compiled with support for netterm mouse. | |
12487 mouse_pterm Compiled with support for qnx pterm mouse. | |
12488 mouse_sysmouse Compiled with support for sysmouse (*BSD console mouse) | |
12489 mouse_sgr Compiled with support for sgr mouse. | |
12490 mouse_urxvt Compiled with support for urxvt mouse. | |
12491 mouse_xterm Compiled with support for xterm mouse. | |
12492 mouseshape Compiled with support for 'mouseshape'. | |
12493 multi_byte Compiled with support for 'encoding' (always true) | |
12494 multi_byte_encoding 'encoding' is set to a multibyte encoding. | |
12495 multi_byte_ime Compiled with support for IME input method. | |
12496 multi_lang Compiled with support for multiple languages. | |
12497 mzscheme Compiled with MzScheme interface |mzscheme|. | |
12498 nanotime Compiled with sub-second time stamp checks. | |
12499 netbeans_enabled Compiled with support for |netbeans| and connected. | |
12500 netbeans_intg Compiled with support for |netbeans|. | |
12501 num64 Compiled with 64-bit |Number| support. | |
12502 ole Compiled with OLE automation support for Win32. | |
12503 osx Compiled for macOS cf. mac | |
12504 osxdarwin Compiled for macOS, with |mac-darwin-feature| | |
12505 packages Compiled with |packages| support. | |
12506 path_extra Compiled with up/downwards search in 'path' and 'tags' | |
12507 perl Compiled with Perl interface. | |
12508 persistent_undo Compiled with support for persistent undo history. | |
12509 postscript Compiled with PostScript file printing. | |
12510 printer Compiled with |:hardcopy| support. | |
12511 profile Compiled with |:profile| support. | |
12512 python Python 2.x interface available. |has-python| | |
12513 python_compiled Compiled with Python 2.x interface. |has-python| | |
12514 python_dynamic Python 2.x interface is dynamically loaded. |has-python| | |
12515 python3 Python 3.x interface available. |has-python| | |
12516 python3_compiled Compiled with Python 3.x interface. |has-python| | |
12517 python3_dynamic Python 3.x interface is dynamically loaded. |has-python| | |
12518 pythonx Python 2.x and/or 3.x interface available. |python_x| | |
12519 qnx QNX version of Vim. | |
12520 quickfix Compiled with |quickfix| support. | |
12521 reltime Compiled with |reltime()| support. | |
12522 rightleft Compiled with 'rightleft' support. | |
12523 ruby Compiled with Ruby interface |ruby|. | |
12524 scrollbind Compiled with 'scrollbind' support. (always true) | |
12525 showcmd Compiled with 'showcmd' support. | |
12526 signs Compiled with |:sign| support. | |
12527 smartindent Compiled with 'smartindent' support. | |
12528 sodium Compiled with libsodium for better crypt support | |
12529 sound Compiled with sound support, e.g. `sound_playevent()` | |
12530 spell Compiled with spell checking support |spell|. | |
12531 startuptime Compiled with |--startuptime| support. | |
12532 statusline Compiled with support for 'statusline', 'rulerformat' | |
12533 and special formats of 'titlestring' and 'iconstring'. | |
12534 sun SunOS version of Vim. | |
12535 sun_workshop Support for Sun |workshop| has been removed. | |
12536 syntax Compiled with syntax highlighting support |syntax|. | |
12537 syntax_items There are active syntax highlighting items for the | |
12538 current buffer. | |
12539 system Compiled to use system() instead of fork()/exec(). | |
12540 tag_binary Compiled with binary searching in tags files | |
12541 |tag-binary-search|. | |
12542 tag_old_static Support for old static tags was removed, see | |
12543 |tag-old-static|. | |
12544 tcl Compiled with Tcl interface. | |
12545 termguicolors Compiled with true color in terminal support. | |
12546 terminal Compiled with |terminal| support. | |
12547 terminfo Compiled with terminfo instead of termcap. | |
12548 termresponse Compiled with support for |t_RV| and |v:termresponse|. | |
12549 textobjects Compiled with support for |text-objects|. | |
12550 textprop Compiled with support for |text-properties|. | |
12551 tgetent Compiled with tgetent support, able to use a termcap | |
12552 or terminfo file. | |
12553 timers Compiled with |timer_start()| support. | |
12554 title Compiled with window title support |'title'|. | |
12555 toolbar Compiled with support for |gui-toolbar|. | |
12556 ttyin input is a terminal (tty) | |
12557 ttyout output is a terminal (tty) | |
12558 unix Unix version of Vim. *+unix* | |
12559 unnamedplus Compiled with support for "unnamedplus" in 'clipboard' | |
12560 user_commands User-defined commands. (always true) | |
12561 vartabs Compiled with variable tabstop support |'vartabstop'|. | |
12562 vcon Win32: Virtual console support is working, can use | |
12563 'termguicolors'. Also see |+vtp|. | |
12564 vertsplit Compiled with vertically split windows |:vsplit|. | |
12565 (always true) | |
12566 vim_starting True while initial source'ing takes place. |startup| | |
12567 *vim_starting* | |
12568 viminfo Compiled with viminfo support. | |
12569 vimscript-1 Compiled Vim script version 1 support | |
12570 vimscript-2 Compiled Vim script version 2 support | |
12571 vimscript-3 Compiled Vim script version 3 support | |
12572 virtualedit Compiled with 'virtualedit' option. (always true) | |
12573 visual Compiled with Visual mode. (always true) | |
12574 visualextra Compiled with extra Visual mode commands. (always | |
12575 true) |blockwise-operators|. | |
12576 vms VMS version of Vim. | |
12577 vreplace Compiled with |gR| and |gr| commands. (always true) | |
12578 vtp Compiled for vcon support |+vtp| (check vcon to find | |
12579 out if it works in the current console). | |
12580 wildignore Compiled with 'wildignore' option. | |
12581 wildmenu Compiled with 'wildmenu' option. | |
12582 win16 old version for MS-Windows 3.1 (always false) | |
12583 win32 Win32 version of Vim (MS-Windows 95 and later, 32 or | |
12584 64 bits) | |
12585 win32unix Win32 version of Vim, using Unix files (Cygwin) | |
12586 win64 Win64 version of Vim (MS-Windows 64 bit). | |
12587 win95 Win32 version for MS-Windows 95/98/ME (always false) | |
12588 winaltkeys Compiled with 'winaltkeys' option. | |
12589 windows Compiled with support for more than one window. | |
12590 (always true) | |
12591 writebackup Compiled with 'writebackup' default on. | |
12592 xfontset Compiled with X fontset support |xfontset|. | |
12593 xim Compiled with X input method support |xim|. | |
12594 xpm Compiled with pixmap support. | |
12595 xpm_w32 Compiled with pixmap support for Win32. (Only for | |
12596 backward compatibility. Use "xpm" instead.) | |
12597 xsmp Compiled with X session management support. | |
12598 xsmp_interact Compiled with interactive X session management support. | |
12599 xterm_clipboard Compiled with support for xterm clipboard. | |
12600 xterm_save Compiled with support for saving and restoring the | |
12601 xterm screen. | |
12602 x11 Compiled with X11 support. | |
12603 | |
12604 *string-match* | |
12605 Matching a pattern in a String | |
12606 | |
12607 A regexp pattern as explained at |pattern| is normally used to find a match in | |
12608 the buffer lines. When a pattern is used to find a match in a String, almost | |
12609 everything works in the same way. The difference is that a String is handled | |
12610 like it is one line. When it contains a "\n" character, this is not seen as a | |
12611 line break for the pattern. It can be matched with a "\n" in the pattern, or | |
12612 with ".". Example: > | |
12613 :let a = "aaaa\nxxxx" | |
12614 :echo matchstr(a, "..\n..") | |
12615 aa | |
12616 xx | |
12617 :echo matchstr(a, "a.x") | |
12618 a | |
12619 x | |
12620 | |
12621 Don't forget that "^" will only match at the first character of the String and | |
12622 "$" at the last character of the string. They don't match after or before a | |
12623 "\n". | |
12624 | 2539 |
12625 ============================================================================== | 2540 ============================================================================== |
12626 5. Defining functions *user-functions* | 2541 5. Defining functions *user-functions* |
12627 | 2542 |
12628 New functions can be defined. These can be called just like builtin | 2543 New functions can be defined. These can be called just like builtin |