vim: runtime/doc/eval.txt annotate

annotate runtime/doc/eval.txt @ 35069:abc67b413453 default tip

Added tag v9.1.0378 for changeset 60a7fae995600da671d5aaed70644cbea45b3043

author	Christian Brabandt <cb@256bit.org>
date	Sun, 28 Apr 2024 10:00:08 +0200
parents	5b25ec43f208
children

rev	line source
34676 5b25ec43f208 patch 9.1.0219: Vim9: No enum support Christian Brabandt <cb@256bit.org> parents: 34602 diff changeset	1 eval.txt For Vim version 9.1. Last change: 2024 Mar 28
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4 VIM REFERENCE MANUAL by Bram Moolenaar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	6
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	7 Expression evaluation expression expr E15 eval
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	8 E1002
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	9 Using expressions is introduced in chapter 41 of the user manual \|usr_41.txt\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	11 Note: Expression evaluation can be disabled at compile time. If this has been
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	12 done, the features in this document are not available. See \|+eval\| and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	13 \|no-eval-feature\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	14
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	15 This file is mainly about the backwards compatible (legacy) Vim script. For
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	16 specifics of Vim9 script, which can execute much faster, supports type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	17 checking and much more, see \|vim9.txt\|. Where the syntax or semantics differ
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	18 a remark is given.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	19
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	20 1. Variables \|variables\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	21 1.1 Variable types
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	22 1.2 Function references \|Funcref\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	23 1.3 Lists \|Lists\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	24 1.4 Dictionaries \|Dictionaries\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	25 1.5 Blobs \|Blobs\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	26 1.6 More about variables \|more-variables\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	27 2. Expression syntax \|expression-syntax\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	28 3. Internal variable \|internal-variables\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	29 4. Builtin Functions \|functions\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	30 5. Defining functions \|user-functions\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	31 6. Curly braces names \|curly-braces-names\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	32 7. Commands \|expression-commands\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	33 8. Exception handling \|exception-handling\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	34 9. Examples \|eval-examples\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	35 10. Vim script version \|vimscript-version\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	36 11. No +eval feature \|no-eval-feature\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	37 12. The sandbox \|eval-sandbox\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	38 13. Textlock \|textlock\|
33721 d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	39 14. Vim script library \|vim-script-library\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	40
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	41 Testing support is documented in \|testing.txt\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	42 Profiling is documented at \|profiling\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	43
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	44 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	45 1. Variables variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	46
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	47 1.1 Variable types ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	48 E712 E896 E897 E899 E1098
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	49 E1107 E1135 E1138
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	50 There are ten types of variables:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	51
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	52 Number Integer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	53 Number A 32 or 64 bit signed number. \|expr-number\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	54 The number of bits is available in \|v:numbersize\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	55 Examples: -123 0x10 0177 0o177 0b1011
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	56
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	57 Float A floating point number. \|floating-point-format\| Float
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	58 Examples: 123.456 1.15e-6 -1.1e3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	59
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	60 String A NUL terminated string of 8-bit unsigned characters (bytes).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	61 \|expr-string\| Examples: "ab\txx\"--" 'x-z''a,c'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	62
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	63 List An ordered sequence of items, see \|List\| for details.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	64 Example: [1, 2, ['a', 'b']]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	65
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	66 Dictionary An associative, unordered array: Each entry has a key and a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	67 value. \|Dictionary\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	68 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	69 {'blue': "#0000ff", 'red': "#ff0000"}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	70 #{blue: "#0000ff", red: "#ff0000"}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	71
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	72 Funcref A reference to a function \|Funcref\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	73 Example: function("strlen")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	74 It can be bound to a dictionary and arguments, it then works
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	75 like a Partial.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	76 Example: function("Callback", [arg], myDict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	77
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	78 Special \|v:false\|, \|v:true\|, \|v:none\| and \|v:null\|. Special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	79
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	80 Job Used for a job, see \|job_start()\|. Job Jobs
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	81
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	82 Channel Used for a channel, see \|ch_open()\|. Channel Channels
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	83
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	84 Blob Binary Large Object. Stores any sequence of bytes. See \|Blob\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	85 for details
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	86 Example: 0zFF00ED015DAF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	87 0z is an empty Blob.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	88
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	89 The Number and String types are converted automatically, depending on how they
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	90 are used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	91
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	92 Conversion from a Number to a String is by making the ASCII representation of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	93 the Number. Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	94 Number 123 --> String "123" ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	95 Number 0 --> String "0" ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	96 Number -1 --> String "-1" ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	97 octal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	98 Conversion from a String to a Number only happens in legacy Vim script, not in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	99 Vim9 script. It is done by converting the first digits to a number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	100 Hexadecimal "0xf9", Octal "017" or "0o17", and Binary "0b10"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	101 numbers are recognized
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	102 NOTE: when using \|Vim9\| script or \|scriptversion-4\| octal with a leading "0"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	103 is not recognized. The 0o notation requires patch 8.2.0886.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	104 If the String doesn't start with digits, the result is zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	105 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	106 String "456" --> Number 456 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	107 String "6bar" --> Number 6 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	108 String "foo" --> Number 0 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	109 String "0xf1" --> Number 241 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	110 String "0100" --> Number 64 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	111 String "0o100" --> Number 64 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	112 String "0b101" --> Number 5 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	113 String "-8" --> Number -8 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	114 String "+8" --> Number 0 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	115
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	116 To force conversion from String to Number, add zero to it: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	117 :echo "0100" + 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	118 < 64 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	119
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	120 To avoid a leading zero to cause octal conversion, or for using a different
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	121 base, use \|str2nr()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	122
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	123 TRUE FALSE Boolean
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	124 For boolean operators Numbers are used. Zero is FALSE, non-zero is TRUE.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	125 You can also use \|v:false\| and \|v:true\|, in Vim9 script \|false\| and \|true\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	126 When TRUE is returned from a function it is the Number one, FALSE is the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	127 number zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	128
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	129 Note that in the command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	130 :if "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	131 :" NOT executed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	132 "foo" is converted to 0, which means FALSE. If the string starts with a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	133 non-zero number it means TRUE: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	134 :if "8foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	135 :" executed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	136 To test for a non-empty string, use empty(): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	137 :if !empty("foo")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	138
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	139 < falsy truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	140 An expression can be used as a condition, ignoring the type and only using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	141 whether the value is "sort of true" or "sort of false". Falsy is:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	142 the number zero
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	143 empty string, blob, list or dictionary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	144 Other values are truthy. Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	145 0 falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	146 1 truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	147 -1 truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	148 0.0 falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	149 0.1 truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	150 '' falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	151 'x' truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	152 [] falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	153 [0] truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	154 {} falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	155 #{x: 1} truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	156 0z falsy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	157 0z00 truthy
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	158
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	159 non-zero-arg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	160 Function arguments often behave slightly different from \|TRUE\|: If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	161 argument is present and it evaluates to a non-zero Number, \|v:true\| or a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	162 non-empty String, then the value is considered to be TRUE.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	163 Note that " " and "0" are also non-empty strings, thus considered to be TRUE.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	164 A List, Dictionary or Float is not a Number or String, thus evaluate to FALSE.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	165
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	166 E611 E745 E728 E703 E729 E730 E731 E908 E910
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	167 E913 E974 E975 E976 E1319 E1320 E1321 E1322
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	168 E1323 E1324
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	169 \|List\|, \|Dictionary\|, \|Funcref\|, \|Job\|, \|Channel\|, \|Blob\|, \|Class\| and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	170 \|object\| types are not automatically converted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	171
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	172 E805 E806 E808
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	173 When mixing Number and Float the Number is converted to Float. Otherwise
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	174 there is no automatic conversion of Float. You can use str2float() for String
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	175 to Float, printf() for Float to String and float2nr() for Float to Number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	176
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	177 E362 E891 E892 E893 E894 E907 E911 E914
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	178 When expecting a Float a Number can also be used, but nothing else.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	179
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	180 no-type-checking
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	181 You will not get an error if you try to change the type of a variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	182
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	183
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	184 1.2 Function references ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	185 Funcref E695 E718 E1192
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	186 A Funcref variable is obtained with the \|function()\| function, the \|funcref()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	187 function, (in \|Vim9\| script) the name of a function, or created with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	188 lambda expression \|expr-lambda\|. It can be used in an expression in the place
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	189 of a function name, before the parenthesis around the arguments, to invoke the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	190 function it refers to. Example in \|Vim9\| script: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	191
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	192 :var Fn = MyFunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	193 :echo Fn()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	194
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	195 Legacy script: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	196 :let Fn = function("MyFunc")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	197 :echo Fn()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	198 < E704 E705 E707
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	199 A Funcref variable must start with a capital, "s:", "w:", "t:" or "b:". You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	200 can use "g:" but the following name must still start with a capital. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	201 cannot have both a Funcref variable and a function with the same name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	202
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	203 A special case is defining a function and directly assigning its Funcref to a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	204 Dictionary entry. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	205 :function dict.init() dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	206 : let self.val = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	207 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	208
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	209 The key of the Dictionary can start with a lower case letter. The actual
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	210 function name is not used here. Also see \|numbered-function\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	211
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	212 A Funcref can also be used with the \|:call\| command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	213 :call Fn()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	214 :call dict.init()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	215
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	216 The name of the referenced function can be obtained with \|string()\|. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	217 :let func = string(Fn)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	218
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	219 You can use \|call()\| to invoke a Funcref and use a list variable for the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	220 arguments: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	221 :let r = call(Fn, mylist)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	222 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	223 Partial
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	224 A Funcref optionally binds a Dictionary and/or arguments. This is also called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	225 a Partial. This is created by passing the Dictionary and/or arguments to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	226 function() or funcref(). When calling the function the Dictionary and/or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	227 arguments will be passed to the function. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	228
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	229 let Cb = function('Callback', ['foo'], myDict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	230 call Cb('bar')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	231
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	232 This will invoke the function as if using: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	233 call myDict.Callback('foo', 'bar')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	234
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	235 This is very useful when passing a function around, e.g. in the arguments of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	236 \|ch_open()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	237
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	238 Note that binding a function to a Dictionary also happens when the function is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	239 a member of the Dictionary: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	240
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	241 let myDict.myFunction = MyFunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	242 call myDict.myFunction()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	243
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	244 Here MyFunction() will get myDict passed as "self". This happens when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	245 "myFunction" member is accessed. When making assigning "myFunction" to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	246 otherDict and calling it, it will be bound to otherDict: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	247
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	248 let otherDict.myFunction = myDict.myFunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	249 call otherDict.myFunction()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	250
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	251 Now "self" will be "otherDict". But when the dictionary was bound explicitly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	252 this won't happen: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	253
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	254 let myDict.myFunction = function(MyFunction, myDict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	255 let otherDict.myFunction = myDict.myFunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	256 call otherDict.myFunction()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	257
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	258 Here "self" will be "myDict", because it was bound explicitly.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	259
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	260
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	261 1.3 Lists ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	262 list List Lists E686
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	263 A List is an ordered sequence of items. An item can be of any type. Items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	264 can be accessed by their index number. Items can be added and removed at any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	265 position in the sequence.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	266
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	267
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	268 List creation ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	269 E696 E697
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	270 A List is created with a comma-separated list of items in square brackets.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	271 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	272 :let mylist = [1, two, 3, "four"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	273 :let emptylist = []
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	274
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	275 An item can be any expression. Using a List for an item creates a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	276 List of Lists: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	277 :let nestlist = [[11, 12], [21, 22], [31, 32]]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	278
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	279 An extra comma after the last item is ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	280
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	281
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	282 List index ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	283 list-index E684
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	284 An item in the List can be accessed by putting the index in square brackets
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	285 after the List. Indexes are zero-based, thus the first item has index zero. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	286 :let item = mylist[0] " get the first item: 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	287 :let item = mylist[2] " get the third item: 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	288
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	289 When the resulting item is a list this can be repeated: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	290 :let item = nestlist[0][1] " get the first list, second item: 12
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	291 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	292 A negative index is counted from the end. Index -1 refers to the last item in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	293 the List, -2 to the last but one item, etc. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	294 :let last = mylist[-1] " get the last item: "four"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	295
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	296 To avoid an error for an invalid index use the \|get()\| function. When an item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	297 is not available it returns zero or the default value you specify: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	298 :echo get(mylist, idx)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	299 :echo get(mylist, idx, "NONE")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	300
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	301
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	302 List concatenation ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	303 list-concatenation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	304 Two lists can be concatenated with the "+" operator: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	305 :let longlist = mylist + [5, 6]
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	306 :let longlist = [5, 6] + mylist
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	307 To prepend or append an item, turn it into a list by putting [] around it.
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	308
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	309 A list can be concatenated with another one in-place using \|:let+=\| or
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	310 \|extend()\|: >
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	311 :let mylist += [7, 8]
34290 167d80fce1b1 runtime(doc): Clarify list-concatenation a bit more Christian Brabandt <cb@256bit.org> parents: 34288 diff changeset	312 :call extend(mylist, [7, 8])
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	313 <
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	314 See \|list-modification\| below for more about changing a list in-place.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	315
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	316
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	317 Sublist ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	318 sublist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	319 A part of the List can be obtained by specifying the first and last index,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	320 separated by a colon in square brackets: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	321 :let shortlist = mylist[2:-1] " get List [3, "four"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	322
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	323 Omitting the first index is similar to zero. Omitting the last index is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	324 similar to -1. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	325 :let endlist = mylist[2:] " from item 2 to the end: [3, "four"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	326 :let shortlist = mylist[2:2] " List with one item: [3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	327 :let otherlist = mylist[:] " make a copy of the List
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	328
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	329 Notice that the last index is inclusive. If you prefer using an exclusive
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	330 index use the \|slice()\| method.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	331
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	332 If the first index is beyond the last item of the List or the second item is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	333 before the first item, the result is an empty list. There is no error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	334 message.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	335
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	336 If the second index is equal to or greater than the length of the list the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	337 length minus one is used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	338 :let mylist = [0, 1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	339 :echo mylist[2:8] " result: [2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	340
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	341 NOTE: mylist[s:e] means using the variable "s:e" as index. Watch out for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	342 using a single letter variable before the ":". Insert a space when needed:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	343 mylist[s : e].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	344
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	345
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	346 List identity ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	347 list-identity
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	348 When variable "aa" is a list and you assign it to another variable "bb", both
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	349 variables refer to the same list. Thus changing the list "aa" will also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	350 change "bb": >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	351 :let aa = [1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	352 :let bb = aa
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	353 :call add(aa, 4)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	354 :echo bb
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	355 < [1, 2, 3, 4]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	356
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	357 Making a copy of a list is done with the \|copy()\| function. Using [:] also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	358 works, as explained above. This creates a shallow copy of the list: Changing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	359 a list item in the list will also change the item in the copied list: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	360 :let aa = [[1, 'a'], 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	361 :let bb = copy(aa)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	362 :call add(aa, 4)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	363 :let aa[0][1] = 'aaa'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	364 :echo aa
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	365 < [[1, aaa], 2, 3, 4] >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	366 :echo bb
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	367 < [[1, aaa], 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	368
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	369 To make a completely independent list use \|deepcopy()\|. This also makes a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	370 copy of the values in the list, recursively. Up to a hundred levels deep.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	371
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	372 The operator "is" can be used to check if two variables refer to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	373 List. "isnot" does the opposite. In contrast "==" compares if two lists have
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	374 the same value. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	375 :let alist = [1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	376 :let blist = [1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	377 :echo alist is blist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	378 < 0 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	379 :echo alist == blist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	380 < 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	381
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	382 Note about comparing lists: Two lists are considered equal if they have the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	383 same length and all items compare equal, as with using "==". There is one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	384 exception: When comparing a number with a string they are considered
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	385 different. There is no automatic type conversion, as with using "==" on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	386 variables. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	387 echo 4 == "4"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	388 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	389 echo [4] == ["4"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	390 < 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	391
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	392 Thus comparing Lists is more strict than comparing numbers and strings. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	393 can compare simple values this way too by putting them in a list: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	394
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	395 :let a = 5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	396 :let b = "5"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	397 :echo a == b
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	398 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	399 :echo [a] == [b]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	400 < 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	401
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	402
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	403 List unpack ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	404
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	405 To unpack the items in a list to individual variables, put the variables in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	406 square brackets, like list items: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	407 :let [var1, var2] = mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	408
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	409 When the number of variables does not match the number of items in the list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	410 this produces an error. To handle any extra items from the list append ";"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	411 and a variable name: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	412 :let [var1, var2; rest] = mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	413
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	414 This works like: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	415 :let var1 = mylist[0]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	416 :let var2 = mylist[1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	417 :let rest = mylist[2:]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	418
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	419 Except that there is no error if there are only two items. "rest" will be an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	420 empty list then.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	421
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	422
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	423 List modification ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	424 list-modification
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	425 To change a specific item of a list use \|:let\| this way: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	426 :let list[4] = "four"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	427 :let listlist[0][3] = item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	428
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	429 To change part of a list you can specify the first and last item to be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	430 modified. The value must at least have the number of items in the range: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	431 :let list[3:5] = [3, 4, 5]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	432
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	433 To add items to a List in-place, you can use \|:let+=\| (\|list-concatenation\|): >
34288 6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	434 :let listA = [1, 2]
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	435 :let listA += [3, 4]
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	436 <
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	437 When two variables refer to the same List, changing one List in-place will
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	438 cause the referenced List to be changed in-place: >
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	439 :let listA = [1, 2]
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	440 :let listB = listA
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	441 :let listB += [3, 4]
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	442 :echo listA
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	443 [1, 2, 3, 4]
6df143135376 patch 9.1.0080: unexpected error for modifying final list using += Christian Brabandt <cb@256bit.org> parents: 34278 diff changeset	444 <
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	445 Adding and removing items from a list is done with functions. Here are a few
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	446 examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	447 :call insert(list, 'a') " prepend item 'a'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	448 :call insert(list, 'a', 3) " insert item 'a' before list[3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	449 :call add(list, "new") " append String item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	450 :call add(list, [1, 2]) " append a List as one new item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	451 :call extend(list, [1, 2]) " extend the list with two more items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	452 :let i = remove(list, 3) " remove item 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	453 :unlet list[3] " idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	454 :let l = remove(list, 3, -1) " remove items 3 to last item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	455 :unlet list[3 : ] " idem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	456 :call filter(list, 'v:val !~ "x"') " remove items with an 'x'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	457
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	458 Changing the order of items in a list: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	459 :call sort(list) " sort a list alphabetically
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	460 :call reverse(list) " reverse the order of items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	461 :call uniq(sort(list)) " sort and remove duplicates
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	462
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	463
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	464 For loop ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	465
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	466 The \|:for\| loop executes commands for each item in a List, String or Blob.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	467 A variable is set to each item in sequence. Example with a List: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	468 :for item in mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	469 : call Doit(item)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	470 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	471
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	472 This works like: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	473 :let index = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	474 :while index < len(mylist)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	475 : let item = mylist[index]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	476 : :call Doit(item)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	477 : let index = index + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	478 :endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	479
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	480 If all you want to do is modify each item in the list then the \|map()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	481 function will be a simpler method than a for loop.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	482
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	483 Just like the \|:let\| command, \|:for\| also accepts a list of variables. This
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	484 requires the argument to be a List of Lists. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	485 :for [lnum, col] in [[1, 3], [2, 8], [3, 0]]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	486 : call Doit(lnum, col)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	487 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	488
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	489 This works like a \|:let\| command is done for each list item. Again, the types
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	490 must remain the same to avoid an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	491
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	492 It is also possible to put remaining items in a List variable: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	493 :for [i, j; rest] in listlist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	494 : call Doit(i, j)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	495 : if !empty(rest)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	496 : echo "remainder: " .. string(rest)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	497 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	498 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	499
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	500 For a Blob one byte at a time is used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	501
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	502 For a String one character, including any composing characters, is used as a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	503 String. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	504 for c in text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	505 echo 'This character is ' .. c
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	506 endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	507
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	508
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	509 List functions ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	510 E714
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	511 Functions that are useful with a List: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	512 :let r = call(funcname, list) " call a function with an argument list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	513 :if empty(list) " check if list is empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	514 :let l = len(list) " number of items in list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	515 :let big = max(list) " maximum value in list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	516 :let small = min(list) " minimum value in list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	517 :let xs = count(list, 'x') " count nr of times 'x' appears in list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	518 :let i = index(list, 'x') " index of first 'x' in list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	519 :let lines = getline(1, 10) " get ten text lines from buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	520 :call append('$', lines) " append text lines in buffer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	521 :let list = split("a b c") " create list from items in a string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	522 :let string = join(list, ', ') " create string from list items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	523 :let s = string(list) " String representation of list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	524 :call map(list, '">> " .. v:val') " prepend ">> " to each item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	525
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	526 Don't forget that a combination of features can make things simple. For
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	527 example, to add up all the numbers in a list: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	528 :exe 'let sum = ' .. join(nrlist, '+')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	529
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	530
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	531 1.4 Dictionaries ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	532 dict Dict Dictionaries Dictionary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	533 A Dictionary is an associative array: Each entry has a key and a value. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	534 entry can be located with the key. The entries are stored without a specific
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	535 ordering.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	536
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	537
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	538 Dictionary creation ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	539 E720 E721 E722 E723
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	540 A Dictionary is created with a comma-separated list of entries in curly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	541 braces. Each entry has a key and a value, separated by a colon. Each key can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	542 only appear once. Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	543 :let mydict = {1: 'one', 2: 'two', 3: 'three'}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	544 :let emptydict = {}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	545 < E713 E716 E717
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	546 A key is always a String. You can use a Number, it will be converted to a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	547 String automatically. Thus the String '4' and the number 4 will find the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	548 entry. Note that the String '04' and the Number 04 are different, since the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	549 Number will be converted to the String '4', leading zeros are dropped. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	550 empty string can also be used as a key.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	551
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	552 In \|Vim9\| script a literal key can be used if it consists only of alphanumeric
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	553 characters, underscore and dash, see \|vim9-literal-dict\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	554 literal-Dict #{}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	555 To avoid having to put quotes around every key the #{} form can be used in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	556 legacy script. This does require the key to consist only of ASCII letters,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	557 digits, '-' and '_'. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	558 :let mydict = #{zero: 0, one_key: 1, two-key: 2, 333: 3}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	559 Note that 333 here is the string "333". Empty keys are not possible with #{}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	560 In \|Vim9\| script the #{} form cannot be used because it can be confused with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	561 the start of a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	562
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	563 A value can be any expression. Using a Dictionary for a value creates a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	564 nested Dictionary: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	565 :let nestdict = {1: {11: 'a', 12: 'b'}, 2: {21: 'c'}}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	566
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	567 An extra comma after the last entry is ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	568
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	569
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	570 Accessing entries ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	571
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	572 The normal way to access an entry is by putting the key in square brackets: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	573 :let val = mydict["one"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	574 :let mydict["four"] = 4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	575
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	576 You can add new entries to an existing Dictionary this way, unlike Lists.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	577
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	578 For keys that consist entirely of letters, digits and underscore the following
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	579 form can be used \|expr-entry\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	580 :let val = mydict.one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	581 :let mydict.four = 4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	582
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	583 Since an entry can be any type, also a List and a Dictionary, the indexing and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	584 key lookup can be repeated: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	585 :echo dict.key[idx].key
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	586
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	587
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	588 Dictionary to List conversion ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	589
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	590 You may want to loop over the entries in a dictionary. For this you need to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	591 turn the Dictionary into a List and pass it to \|:for\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	592
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	593 Most often you want to loop over the keys, using the \|keys()\| function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	594 :for key in keys(mydict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	595 : echo key .. ': ' .. mydict[key]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	596 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	597
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	598 The List of keys is unsorted. You may want to sort them first: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	599 :for key in sort(keys(mydict))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	600
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	601 To loop over the values use the \|values()\| function: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	602 :for v in values(mydict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	603 : echo "value: " .. v
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	604 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	605
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	606 If you want both the key and the value use the \|items()\| function. It returns
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	607 a List in which each item is a List with two items, the key and the value: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	608 :for [key, value] in items(mydict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	609 : echo key .. ': ' .. value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	610 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	611
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	612
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	613 Dictionary identity ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	614 dict-identity
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	615 Just like Lists you need to use \|copy()\| and \|deepcopy()\| to make a copy of a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	616 Dictionary. Otherwise, assignment results in referring to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	617 Dictionary: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	618 :let onedict = {'a': 1, 'b': 2}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	619 :let adict = onedict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	620 :let adict['a'] = 11
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	621 :echo onedict['a']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	622 11
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	623
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	624 Two Dictionaries compare equal if all the key-value pairs compare equal. For
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	625 more info see \|list-identity\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	626
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	627
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	628 Dictionary modification ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	629 dict-modification
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	630 To change an already existing entry of a Dictionary, or to add a new entry,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	631 use \|:let\| this way: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	632 :let dict[4] = "four"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	633 :let dict['one'] = item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	634
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	635 Removing an entry from a Dictionary is done with \|remove()\| or \|:unlet\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	636 Three ways to remove the entry with key "aaa" from dict: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	637 :let i = remove(dict, 'aaa')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	638 :unlet dict.aaa
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	639 :unlet dict['aaa']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	640
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	641 Merging a Dictionary with another is done with \|extend()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	642 :call extend(adict, bdict)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	643 This extends adict with all entries from bdict. Duplicate keys cause entries
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	644 in adict to be overwritten. An optional third argument can change this.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	645 Note that the order of entries in a Dictionary is irrelevant, thus don't
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	646 expect ":echo adict" to show the items from bdict after the older entries in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	647 adict.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	648
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	649 Weeding out entries from a Dictionary can be done with \|filter()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	650 :call filter(dict, 'v:val =~ "x"')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	651 This removes all entries from "dict" with a value not matching 'x'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	652 This can also be used to remove all entries: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	653 call filter(dict, 0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	654
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	655 In some situations it is not allowed to remove or add entries to a Dictionary.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	656 Especially when iterating over all the entries. You will get E1313 or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	657 another error in that case.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	658
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	659
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	660 Dictionary function ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	661 Dictionary-function self E725 E862
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	662 When a function is defined with the "dict" attribute it can be used in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	663 special way with a dictionary. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	664 :function Mylen() dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	665 : return len(self.data)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	666 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	667 :let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	668 :echo mydict.len()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	669
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	670 This is like a method in object oriented programming. The entry in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	671 Dictionary is a \|Funcref\|. The local variable "self" refers to the dictionary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	672 the function was invoked from. When using \|Vim9\| script you can use classes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	673 and objects, see `:class`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	674
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	675 It is also possible to add a function without the "dict" attribute as a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	676 Funcref to a Dictionary, but the "self" variable is not available then.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	677
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	678 numbered-function anonymous-function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	679 To avoid the extra name for the function it can be defined and directly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	680 assigned to a Dictionary in this way: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	681 :let mydict = {'data': [0, 1, 2, 3]}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	682 :function mydict.len()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	683 : return len(self.data)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	684 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	685 :echo mydict.len()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	686
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	687 The function will then get a number and the value of dict.len is a \|Funcref\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	688 that references this function. The function can only be used through a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	689 \|Funcref\|. It will automatically be deleted when there is no \|Funcref\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	690 remaining that refers to it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	691
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	692 It is not necessary to use the "dict" attribute for a numbered function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	693
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	694 If you get an error for a numbered function, you can find out what it is with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	695 a trick. Assuming the function is 42, the command is: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	696 :function g:42
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	697
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	698
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	699 Functions for Dictionaries ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	700 E715
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	701 Functions that can be used with a Dictionary: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	702 :if has_key(dict, 'foo') " TRUE if dict has entry with key "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	703 :if empty(dict) " TRUE if dict is empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	704 :let l = len(dict) " number of items in dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	705 :let big = max(dict) " maximum value in dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	706 :let small = min(dict) " minimum value in dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	707 :let xs = count(dict, 'x') " count nr of times 'x' appears in dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	708 :let s = string(dict) " String representation of dict
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	709 :call map(dict, '">> " .. v:val') " prepend ">> " to each item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	710
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	712 1.5 Blobs ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	713 blob Blob Blobs E978
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	714 A Blob is a binary object. It can be used to read an image from a file and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	715 send it over a channel, for example.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	716
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	717 A Blob mostly behaves like a \|List\| of numbers, where each number has the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	718 value of an 8-bit byte, from 0 to 255.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	719
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	720
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	721 Blob creation ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	722
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	723 A Blob can be created with a \|blob-literal\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	724 :let b = 0zFF00ED015DAF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	725 Dots can be inserted between bytes (pair of hex characters) for readability,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	726 they don't change the value: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	727 :let b = 0zFF00.ED01.5DAF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	728
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	729 A blob can be read from a file with \|readfile()\| passing the {type} argument
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	730 set to "B", for example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	731 :let b = readfile('image.png', 'B')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	732
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	733 A blob can be read from a channel with the \|ch_readblob()\| function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	734
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	735
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	736 Blob index ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	737 blob-index E979
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	738 A byte in the Blob can be accessed by putting the index in square brackets
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	739 after the Blob. Indexes are zero-based, thus the first byte has index zero. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	740 :let myblob = 0z00112233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	741 :let byte = myblob[0] " get the first byte: 0x00
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	742 :let byte = myblob[2] " get the third byte: 0x22
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	743
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	744 A negative index is counted from the end. Index -1 refers to the last byte in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	745 the Blob, -2 to the last but one byte, etc. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	746 :let last = myblob[-1] " get the last byte: 0x33
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	747
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	748 To avoid an error for an invalid index use the \|get()\| function. When an item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	749 is not available it returns -1 or the default value you specify: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	750 :echo get(myblob, idx)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	751 :echo get(myblob, idx, 999)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	752
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	753
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	754 Blob iteration ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	755
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	756 The \|:for\| loop executes commands for each byte of a Blob. The loop variable is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	757 set to each byte in the Blob. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	758 :for byte in 0z112233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	759 : call Doit(byte)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	760 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	761 This calls Doit() with 0x11, 0x22 and 0x33.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	762
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	763
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	764 Blob concatenation ~
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	765 blob-concatenation
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	766 Two blobs can be concatenated with the "+" operator: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	767 :let longblob = myblob + 0z4455
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	768 :let longblob = 0z4455 + myblob
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	769 <
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	770 A blob can be concatenated with another one in-place using \|:let+=\|: >
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	771 :let myblob += 0z6677
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	772 <
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	773 See \|blob-modification\| below for more about changing a blob in-place.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	774
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	775
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	776 Part of a blob ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	777
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	778 A part of the Blob can be obtained by specifying the first and last index,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	779 separated by a colon in square brackets: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	780 :let myblob = 0z00112233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	781 :let shortblob = myblob[1:2] " get 0z1122
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	782 :let shortblob = myblob[2:-1] " get 0z2233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	783
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	784 Omitting the first index is similar to zero. Omitting the last index is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	785 similar to -1. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	786 :let endblob = myblob[2:] " from item 2 to the end: 0z2233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	787 :let shortblob = myblob[2:2] " Blob with one byte: 0z22
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	788 :let otherblob = myblob[:] " make a copy of the Blob
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	789
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	790 If the first index is beyond the last byte of the Blob or the second index is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	791 before the first index, the result is an empty Blob. There is no error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	792 message.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	793
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	794 If the second index is equal to or greater than the length of the list the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	795 length minus one is used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	796 :echo myblob[2:8] " result: 0z2233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	797
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	798
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	799 Blob modification ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	800 blob-modification E1182 E1184
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	801 To change a specific byte of a blob use \|:let\| this way: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	802 :let blob[4] = 0x44
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	803
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	804 When the index is just one beyond the end of the Blob, it is appended. Any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	805 higher index is an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	806
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	807 To change a sequence of bytes the [:] notation can be used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	808 let blob[1:3] = 0z445566
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	809 The length of the replaced bytes must be exactly the same as the value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	810 provided. E972
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	811
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	812 To change part of a blob you can specify the first and last byte to be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	813 modified. The value must have the same number of bytes in the range: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	814 :let blob[3:5] = 0z334455
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	815
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	816 To add items to a Blob in-place, you can use \|:let+=\| (\|blob-concatenation\|): >
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	817 :let blobA = 0z1122
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	818 :let blobA += 0z3344
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	819 <
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	820 When two variables refer to the same Blob, changing one Blob in-place will
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	821 cause the referenced Blob to be changed in-place: >
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	822 :let blobA = 0z1122
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	823 :let blobB = blobA
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	824 :let blobB += 0z3344
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	825 :echo blobA
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	826 0z11223344
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	827 <
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	828 You can also use the functions \|add()\|, \|remove()\| and \|insert()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	829
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	830
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	831 Blob identity ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	832
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	833 Blobs can be compared for equality: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	834 if blob == 0z001122
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	835 And for equal identity: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	836 if blob is otherblob
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	837 < blob-identity E977
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	838 When variable "aa" is a Blob and you assign it to another variable "bb", both
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	839 variables refer to the same Blob. Then the "is" operator returns true.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	840
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	841 When making a copy using [:] or \|copy()\| the values are the same, but the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	842 identity is different: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	843 :let blob = 0z112233
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	844 :let blob2 = blob
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	845 :echo blob == blob2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	846 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	847 :echo blob is blob2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	848 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	849 :let blob3 = blob[:]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	850 :echo blob == blob3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	851 < 1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	852 :echo blob is blob3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	853 < 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	854
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	855 Making a copy of a Blob is done with the \|copy()\| function. Using [:] also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	856 works, as explained above.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	857
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	858
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	859 1.6 More about variables ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	860 more-variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	861 If you need to know the type of a variable or expression, use the \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	862 function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	863
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	864 When the '!' flag is included in the 'viminfo' option, global variables that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	865 start with an uppercase letter, and don't contain a lowercase letter, are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	866 stored in the viminfo file \|viminfo-file\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	867
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	868 When the 'sessionoptions' option contains "global", global variables that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	869 start with an uppercase letter and contain at least one lowercase letter are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	870 stored in the session file \|session-file\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	871
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	872 variable name can be stored where ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	873 my_var_6 not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	874 My_Var_6 session file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	875 MY_VAR_6 viminfo file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	876
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	877
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	878 In legacy script it is possible to form a variable name with curly braces, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	879 \|curly-braces-names\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	880
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	881 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	882 2. Expression syntax expression-syntax
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	883 E1143
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	884 Expression syntax summary, from least to most significant:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	885
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	886 \|expr1\| expr2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	887 expr2 ? expr1 : expr1 if-then-else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	888
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	889 \|expr2\| expr3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	890 expr3 \|\| expr3 ... logical OR
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	891
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	892 \|expr3\| expr4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	893 expr4 && expr4 ... logical AND
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	894
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	895 \|expr4\| expr5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	896 expr5 == expr5 equal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	897 expr5 != expr5 not equal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	898 expr5 > expr5 greater than
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	899 expr5 >= expr5 greater than or equal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	900 expr5 < expr5 smaller than
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	901 expr5 <= expr5 smaller than or equal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	902 expr5 =~ expr5 regexp matches
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	903 expr5 !~ expr5 regexp doesn't match
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	904
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	905 expr5 ==? expr5 equal, ignoring case
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	906 expr5 ==# expr5 equal, match case
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	907 etc. As above, append ? for ignoring case, # for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	908 matching case
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	909
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	910 expr5 is expr5 same \|List\|, \|Dictionary\| or \|Blob\| instance
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	911 expr5 isnot expr5 different \|List\|, \|Dictionary\| or \|Blob\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	912 instance
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	913
33901 6732325893cc runtime(doc): Update eval.txt (#13645) Christian Brabandt <cb@256bit.org> parents: 33798 diff changeset	914 \|expr5\| expr6
6732325893cc runtime(doc): Update eval.txt (#13645) Christian Brabandt <cb@256bit.org> parents: 33798 diff changeset	915 expr6 << expr6 bitwise left shift
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	916 expr6 >> expr6 bitwise right shift
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	917
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	918 \|expr6\| expr7
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	919 expr7 + expr7 ... number addition, list or blob concatenation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	920 expr7 - expr7 ... number subtraction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	921 expr7 . expr7 ... string concatenation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	922 expr7 .. expr7 ... string concatenation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	923
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	924 \|expr7\| expr8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	925 expr8 * expr8 ... number multiplication
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	926 expr8 / expr8 ... number division
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	927 expr8 % expr8 ... number modulo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	928
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	929 \|expr8\| expr9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	930 <type>expr9 type check and conversion (\|Vim9\| only)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	931
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	932 \|expr9\| expr10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	933 ! expr9 logical NOT
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	934 - expr9 unary minus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	935 + expr9 unary plus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	936
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	937 \|expr10\| expr11
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	938 expr10[expr1] byte of a String or item of a \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	939 expr10[expr1 : expr1] substring of a String or sublist of a \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	940 expr10.name entry in a \|Dictionary\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	941 expr10(expr1, ...) function call with \|Funcref\| variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	942 expr10->name(expr1, ...) \|method\| call
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	943
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	944 \|expr11\| number number constant
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	945 "string" string constant, backslash is special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	946 'string' string constant, ' is doubled
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	947 [expr1, ...] \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	948 {expr1: expr1, ...} \|Dictionary\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	949 #{key: expr1, ...} legacy \|Dictionary\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	950 &option option value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	951 (expr1) nested expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	952 variable internal variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	953 va{ria}ble internal variable with curly braces
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	954 $VAR environment variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	955 @r contents of register 'r'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	956 function(expr1, ...) function call
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	957 func{ti}on(expr1, ...) function call with curly braces
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	958 {args -> expr1} legacy lambda expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	959 (args) => expr1 Vim9 lambda expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	960
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	961
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	962 "..." indicates that the operations in this level can be concatenated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	963 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	964 &nu \|\| &list && &shell == "csh"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	965
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	966 All expressions within one level are parsed from left to right.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	967
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	968 Expression nesting is limited to 1000 levels deep (300 when build with MSVC)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	969 to avoid running out of stack and crashing. E1169
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	970
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	971
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	972 expr1 expr1 ternary falsy-operator ?? E109
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	973 -----
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	974
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	975 The ternary operator: expr2 ? expr1 : expr1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	976 The falsy operator: expr2 ?? expr1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	977
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	978 Ternary operator ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	979
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	980 In legacy script the expression before the '?' is evaluated to a number. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	981 it evaluates to \|TRUE\|, the result is the value of the expression between the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	982 '?' and ':', otherwise the result is the value of the expression after the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	983 ':'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	984
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	985 In \|Vim9\| script the first expression must evaluate to a boolean, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	986 \|vim9-boolean\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	987
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	988 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	989 :echo lnum == 1 ? "top" : lnum
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	990
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	991 Since the first expression is an "expr2", it cannot contain another ?:. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	992 other two expressions can, thus allow for recursive use of ?:.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	993 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	994 :echo lnum == 1 ? "top" : lnum == 1000 ? "last" : lnum
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	995
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	996 To keep this readable, using \|line-continuation\| is suggested: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	997 :echo lnum == 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	998 :\ ? "top"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	999 :\ : lnum == 1000
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1000 :\ ? "last"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1001 :\ : lnum
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1002
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1003 You should always put a space before the ':', otherwise it can be mistaken for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1004 use in a variable such as "a:1".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1005
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1006 Falsy operator ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1007
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1008 This is also known as the "null coalescing operator", but that's too
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1009 complicated, thus we just call it the falsy operator.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1010
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1011 The expression before the '??' is evaluated. If it evaluates to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1012 \|truthy\|, this is used as the result. Otherwise the expression after the '??'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1013 is evaluated and used as the result. This is most useful to have a default
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1014 value for an expression that may result in zero or empty: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1015 echo theList ?? 'list is empty'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1016 echo GetName() ?? 'unknown'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1017
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1018 These are similar, but not equal: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1019 expr2 ?? expr1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1020 expr2 ? expr2 : expr1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1021 In the second line "expr2" is evaluated twice. And in \|Vim9\| script the type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1022 of expr2 before "?" must be a boolean.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1023
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1024
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1025 expr2 and expr3 expr2 expr3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1026 ---------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1027
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1028 expr3 \|\| expr3 .. logical OR expr-barbar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1029 expr4 && expr4 .. logical AND expr-&&
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1030
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1031 The "\|\|" and "&&" operators take one argument on each side.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1032
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1033 In legacy script the arguments are (converted to) Numbers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1034
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1035 In \|Vim9\| script the values must be boolean, see \|vim9-boolean\|. Use "!!" to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1036 convert any type to a boolean.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1037
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1038 The result is:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1039 input output ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1040 n1 n2 n1 \|\| n2 n1 && n2 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1041 \|FALSE\| \|FALSE\| \|FALSE\| \|FALSE\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1042 \|FALSE\| \|TRUE\| \|TRUE\| \|FALSE\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1043 \|TRUE\| \|FALSE\| \|TRUE\| \|FALSE\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1044 \|TRUE\| \|TRUE\| \|TRUE\| \|TRUE\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1045
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1046 The operators can be concatenated, for example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1047
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1048 &nu \|\| &list && &shell == "csh"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1049
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1050 Note that "&&" takes precedence over "\|\|", so this has the meaning of: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1051
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1052 &nu \|\| (&list && &shell == "csh")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1053
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1054 Once the result is known, the expression "short-circuits", that is, further
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1055 arguments are not evaluated. This is like what happens in C. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1056
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1057 let a = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1058 echo a \|\| b
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1059
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1060 This is valid even if there is no variable called "b" because "a" is \|TRUE\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1061 so the result must be \|TRUE\|. Similarly below: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1062
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1063 echo exists("b") && b == "yes"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1064
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1065 This is valid whether "b" has been defined or not. The second clause will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1066 only be evaluated if "b" has been defined.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1067
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1068
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1069 expr4 expr4 E1153
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1070 -----
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1071
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1072 expr5 {cmp} expr5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1073
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1074 Compare two expr5 expressions. In legacy script the result is a 0 if it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1075 evaluates to false, or 1 if it evaluates to true. In \|Vim9\| script the result
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1076 is \|true\| or \|false\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1077
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1078 expr-== expr-!= expr-> expr->=
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1079 expr-< expr-<= expr-=~ expr-!~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1080 expr-==# expr-!=# expr-># expr->=#
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1081 expr-<# expr-<=# expr-=~# expr-!~#
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1082 expr-==? expr-!=? expr->? expr->=?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1083 expr-<? expr-<=? expr-=~? expr-!~?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1084 expr-is expr-isnot expr-is# expr-isnot#
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1085 expr-is? expr-isnot? E1072
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1086 use 'ignorecase' match case ignore case ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1087 equal == ==# ==?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1088 not equal != !=# !=?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1089 greater than > ># >?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1090 greater than or equal >= >=# >=?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1091 smaller than < <# <?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1092 smaller than or equal <= <=# <=?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1093 regexp matches =~ =~# =~?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1094 regexp doesn't match !~ !~# !~?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1095 same instance is is# is?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1096 different instance isnot isnot# isnot?
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1097
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1098 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1099 "abc" ==# "Abc" evaluates to 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1100 "abc" ==? "Abc" evaluates to 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1101 "abc" == "Abc" evaluates to 1 if 'ignorecase' is set, 0 otherwise
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1102 NOTE: In \|Vim9\| script 'ignorecase' is not used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1103
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1104 E691 E692
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1105 A \|List\| can only be compared with a \|List\| and only "equal", "not equal",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1106 "is" and "isnot" can be used. This compares the values of the list,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1107 recursively. Ignoring case means case is ignored when comparing item values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1108
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1109 E735 E736
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1110 A \|Dictionary\| can only be compared with a \|Dictionary\| and only "equal", "not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1111 equal", "is" and "isnot" can be used. This compares the key/values of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1112 \|Dictionary\| recursively. Ignoring case means case is ignored when comparing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1113 item values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1114
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1115 E694
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1116 A \|Funcref\| can only be compared with a \|Funcref\| and only "equal", "not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1117 equal", "is" and "isnot" can be used. Case is never ignored. Whether
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1118 arguments or a Dictionary are bound (with a partial) matters. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1119 Dictionaries must also be equal (or the same, in case of "is") and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1120 arguments must be equal (or the same).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1121
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1122 To compare Funcrefs to see if they refer to the same function, ignoring bound
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1123 Dictionary and arguments, use \|get()\| to get the function name: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1124 if get(Part1, 'name') == get(Part2, 'name')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1125 " Part1 and Part2 refer to the same function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1126 < E1037
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1127 Using "is" or "isnot" with a \|List\|, \|Dictionary\| or \|Blob\| checks whether
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1128 the expressions are referring to the same \|List\|, \|Dictionary\| or \|Blob\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1129 instance. A copy of a \|List\| is different from the original \|List\|. When
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1130 using "is" without a \|List\|, \|Dictionary\| or \|Blob\|, it is equivalent to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1131 using "equal", using "isnot" equivalent to using "not equal". Except that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1132 a different type means the values are different: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1133 echo 4 == '4'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1134 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1135 echo 4 is '4'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1136 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1137 echo 0 is []
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1138 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1139 "is#"/"isnot#" and "is?"/"isnot?" can be used to match and ignore case.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1140 In \|Vim9\| script this doesn't work, two strings are never identical.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1141
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1142 In legacy script, when comparing a String with a Number, the String is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1143 converted to a Number, and the comparison is done on Numbers. This means
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1144 that: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1145 echo 0 == 'x'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1146 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1147 because 'x' converted to a Number is zero. However: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1148 echo [0] == ['x']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1149 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1150 Inside a List or Dictionary this conversion is not used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1151
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1152 In \|Vim9\| script the types must match.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1153
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1154 When comparing two Strings, this is done with strcmp() or stricmp(). This
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1155 results in the mathematical difference (comparing byte values), not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1156 necessarily the alphabetical difference in the local language.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1157
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1158 When using the operators with a trailing '#', or the short version and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1159 'ignorecase' is off, the comparing is done with strcmp(): case matters.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1160
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1161 When using the operators with a trailing '?', or the short version and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1162 'ignorecase' is set, the comparing is done with stricmp(): case is ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1163
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1164 'smartcase' is not used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1165
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1166 The "=~" and "!~" operators match the lefthand argument with the righthand
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1167 argument, which is used as a pattern. See \|pattern\| for what a pattern is.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1168 This matching is always done like 'magic' was set and 'cpoptions' is empty, no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1169 matter what the actual value of 'magic' or 'cpoptions' is. This makes scripts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1170 portable. To avoid backslashes in the regexp pattern to be doubled, use a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1171 single-quote string, see \|literal-string\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1172 Since a string is considered to be a single line, a multi-line pattern
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1173 (containing \n, backslash-n) will not match. However, a literal NL character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1174 can be matched like an ordinary character. Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1175 "foo\nbar" =~ "\n" evaluates to 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1176 "foo\nbar" =~ "\\n" evaluates to 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1177
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1178
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1179 expr5 expr5 bitwise-shift
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1180 -----
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1181 expr6 << expr6 bitwise left shift expr-<<
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1182 expr6 >> expr6 bitwise right shift expr->>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1183 E1282 E1283
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1184 The "<<" and ">>" operators can be used to perform bitwise left or right shift
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1185 of the left operand by the number of bits specified by the right operand. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1186 operands are used as positive numbers. When shifting right with ">>" the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1187 topmost bit (sometimes called the sign bit) is cleared. If the right operand
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1188 (shift amount) is more than the maximum number of bits in a number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1189 (\|v:numbersize\|) the result is zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1190
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1191
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1192 expr6 and expr7 expr6 expr7 E1036 E1051
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1193 ---------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1194 expr7 + expr7 Number addition, \|List\| or \|Blob\| concatenation expr-+
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1195 expr7 - expr7 Number subtraction expr--
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1196 expr7 . expr7 String concatenation expr-.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1197 expr7 .. expr7 String concatenation expr-..
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1198
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1199 For \|Lists\| only "+" is possible and then both expr7 must be a list. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1200 result is a new list with the two lists Concatenated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1201
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1202 For String concatenation ".." is preferred, since "." is ambiguous, it is also
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1203 used for \|Dict\| member access and floating point numbers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1204 In \|Vim9\| script and when \|vimscript-version\| is 2 or higher, using "." is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1205 allowed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1206
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1207 In \|Vim9\| script the arguments of ".." are converted to String for simple
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1208 types: Number, Float, Special and Bool. For other types \|string()\| should be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1209 used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1210
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1211 expr8 * expr8 Number multiplication expr-star
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1212 expr8 / expr8 Number division expr-/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1213 expr8 % expr8 Number modulo expr-%
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1214
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1215 In legacy script, for all operators except "." and "..", Strings are converted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1216 to Numbers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1217
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1218 For bitwise operators see \|and()\|, \|or()\| and \|xor()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1219
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1220 Note the difference between "+" and ".." in legacy script:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1221 "123" + "456" = 579
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1222 "123" .. "456" = "123456"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1223
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1224 Since '..' has the same precedence as '+' and '-', you need to read: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1225 1 .. 90 + 90.0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1226 As: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1227 (1 .. 90) + 90.0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1228 That works in legacy script, since the String "190" is automatically converted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1229 to the Number 190, which can be added to the Float 90.0. However: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1230 1 .. 90 * 90.0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1231 Should be read as: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1232 1 .. (90 * 90.0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1233 Since '..' has lower precedence than '*'. This does NOT work, since this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1234 attempts to concatenate a Float and a String.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1235
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1236 When dividing a Number by zero the result depends on the value:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1237 0 / 0 = -0x80000000 (like NaN for Float)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1238 >0 / 0 = 0x7fffffff (like positive infinity)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1239 <0 / 0 = -0x7fffffff (like negative infinity)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1240 (before Vim 7.2 it was always 0x7fffffff)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1241 In \|Vim9\| script dividing a number by zero is an error. E1154
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1242
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1243 When 64-bit Number support is enabled:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1244 0 / 0 = -0x8000000000000000 (like NaN for Float)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1245 >0 / 0 = 0x7fffffffffffffff (like positive infinity)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1246 <0 / 0 = -0x7fffffffffffffff (like negative infinity)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1247
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1248 When the righthand side of '%' is zero, the result is 0.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1249
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1250 None of these work for \|Funcref\|s.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1251
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1252 ".", ".." and "%" do not work for Float. E804 E1035
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1253
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1254
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1255 expr8 expr8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1256 -----
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1257 <type>expr9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1258
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1259 This is only available in \|Vim9\| script, see \|type-casting\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1260
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1261
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1262 expr9 expr9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1263 -----
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1264 ! expr9 logical NOT expr-!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1265 - expr9 unary minus expr-unary--
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1266 + expr9 unary plus expr-unary-+
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1267
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1268 For '!' \|TRUE\| becomes \|FALSE\|, \|FALSE\| becomes \|TRUE\| (one).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1269 For '-' the sign of the number is changed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1270 For '+' the number is unchanged. Note: "++" has no effect.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1271
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1272 In legacy script a String will be converted to a Number first. Note that if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1273 the string does not start with a digit you likely don't get what you expect.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1274
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1275 In \|Vim9\| script an error is given when "-" or "+" is used and the type is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1276 a number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1277
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1278 In \|Vim9\| script "!" can be used for any type and the result is always a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1279 boolean. Use "!!" to convert any type to a boolean, according to whether the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1280 value is \|falsy\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1281
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1282 These three can be repeated and mixed. Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1283 !-1 == 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1284 !!8 == 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1285 --9 == 9
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1286
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1287
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1288 expr10 expr10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1289 ------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1290 This expression is either \|expr11\| or a sequence of the alternatives below,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1291 in any order. E.g., these are all possible:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1292 expr10[expr1].name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1293 expr10.name[expr1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1294 expr10(expr1, ...)[expr1].name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1295 expr10->(expr1, ...)[expr1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1296 Evaluation is always from left to right.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1297
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1298 expr10[expr1] item of String or \|List\| expr-[] E111
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1299 E909 subscript E1062
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1300 In legacy Vim script:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1301 If expr10 is a Number or String this results in a String that contains the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1302 expr1'th single byte from expr10. expr10 is used as a String (a number is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1303 automatically converted to a String), expr1 as a Number. This doesn't
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1304 recognize multibyte encodings, see `byteidx()` for an alternative, or use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1305 `split()` to turn the string into a list of characters. Example, to get the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1306 byte under the cursor: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1307 :let c = getline(".")[col(".") - 1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1308
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1309 In \|Vim9\| script: E1147 E1148
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1310 If expr10 is a String this results in a String that contains the expr1'th
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1311 single character (including any composing characters) from expr10. To use byte
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1312 indexes use \|strpart()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1313
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1314 Index zero gives the first byte or character. Careful: text column numbers
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1315 start with one!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1316
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1317 If the length of the String is less than the index, the result is an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1318 String. A negative index always results in an empty string (reason: backward
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1319 compatibility). Use [-1:] to get the last byte or character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1320 In Vim9 script a negative index is used like with a list: count from the end.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1321
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1322 If expr10 is a \|List\| then it results the item at index expr1. See \|list-index\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1323 for possible index values. If the index is out of range this results in an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1324 error. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1325 :let item = mylist[-1] " get last item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1326
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1327 Generally, if a \|List\| index is equal to or higher than the length of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1328 \|List\|, or more negative than the length of the \|List\|, this results in an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1329 error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1330
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1331
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1332 expr10[expr1a : expr1b] substring or \|sublist\| expr-[:] substring
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1333
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1334 If expr10 is a String this results in the substring with the bytes or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1335 characters from expr1a to and including expr1b. expr10 is used as a String,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1336 expr1a and expr1b are used as a Number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1337
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1338 In legacy Vim script the indexes are byte indexes. This doesn't recognize
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1339 multibyte encodings, see \|byteidx()\| for computing the indexes. If expr10 is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1340 a Number it is first converted to a String.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1341
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1342 In Vim9 script the indexes are character indexes and include composing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1343 characters. To use byte indexes use \|strpart()\|. To use character indexes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1344 without including composing characters use \|strcharpart()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1345
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1346 The item at index expr1b is included, it is inclusive. For an exclusive index
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1347 use the \|slice()\| function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1348
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1349 If expr1a is omitted zero is used. If expr1b is omitted the length of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1350 string minus one is used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1351
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1352 A negative number can be used to measure from the end of the string. -1 is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1353 the last character, -2 the last but one, etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1354
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1355 If an index goes out of range for the string characters are omitted. If
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1356 expr1b is smaller than expr1a the result is an empty string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1357
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1358 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1359 :let c = name[-1:] " last byte of a string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1360 :let c = name[0:-1] " the whole string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1361 :let c = name[-2:-2] " last but one byte of a string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1362 :let s = line(".")[4:] " from the fifth byte to the end
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1363 :let s = s[:-3] " remove last two bytes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1364 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1365 slice
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1366 If expr10 is a \|List\| this results in a new \|List\| with the items indicated by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1367 the indexes expr1a and expr1b. This works like with a String, as explained
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1368 just above. Also see \|sublist\| below. Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1369 :let l = mylist[:3] " first four items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1370 :let l = mylist[4:4] " List with one item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1371 :let l = mylist[:] " shallow copy of a List
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1372
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1373 If expr10 is a \|Blob\| this results in a new \|Blob\| with the bytes in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1374 indexes expr1a and expr1b, inclusive. Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1375 :let b = 0zDEADBEEF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1376 :let bs = b[1:2] " 0zADBE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1377 :let bs = b[:] " copy of 0zDEADBEEF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1378
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1379 Using expr10[expr1] or expr10[expr1a : expr1b] on a \|Funcref\| results in an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1380 error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1381
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1382 Watch out for confusion between a namespace and a variable followed by a colon
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1383 for a sublist: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1384 mylist[n:] " uses variable n
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1385 mylist[s:] " uses namespace s:, error!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1386
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1387
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1388 expr10.name entry in a \|Dictionary\| expr-entry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1389 E1203 E1229
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1390 If expr10 is a \|Dictionary\| and it is followed by a dot, then the following
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1391 name will be used as a key in the \|Dictionary\|. This is just like:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1392 expr10[name].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1393
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1394 The name must consist of alphanumeric characters, just like a variable name,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1395 but it may start with a number. Curly braces cannot be used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1396
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1397 There must not be white space before or after the dot.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1398
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1399 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1400 :let dict = {"one": 1, 2: "two"}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1401 :echo dict.one " shows "1"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1402 :echo dict.2 " shows "two"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1403 :echo dict .2 " error because of space before the dot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1404
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1405 Note that the dot is also used for String concatenation. To avoid confusion
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1406 always put spaces around the dot for String concatenation.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1407
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1408
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1409 expr10(expr1, ...) \|Funcref\| function call E1085
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1410
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1411 When expr10 is a \|Funcref\| type variable, invoke the function it refers to.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1412
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1413
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1414 expr10->name([args]) method call method ->
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1415 expr10->{lambda}([args])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1416 E260 E276 E1265
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1417 For methods that are also available as global functions this is the same as: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1418 name(expr10 [, args])
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1419 There can also be methods specifically for the type of "expr10".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1420
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1421 This allows for chaining, passing the value that one method returns to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1422 next method: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1423 mylist->filter(filterexpr)->map(mapexpr)->sort()->join()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1424 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1425 Example of using a lambda: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1426 GetPercentage()->{x -> x * 100}()->printf('%d%%')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1427 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1428 When using -> the \|expr9\| operators will be applied first, thus: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1429 -1.234->string()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1430 Is equivalent to: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1431 (-1.234)->string()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1432 And NOT: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1433 -(1.234->string())
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1434
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1435 What comes after "->" can be a name, a simple expression (not containing any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1436 parenthesis), or any expression in parentheses: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1437 base->name(args)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1438 base->some.name(args)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1439 base->alist[idx](args)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1440 base->(getFuncRef())(args)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1441 Note that in the last call the base is passed to the function resulting from
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1442 "(getFuncRef())", inserted before "args". E1275
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1443
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1444 E274
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1445 "->name(" must not contain white space. There can be white space before the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1446 "->" and after the "(", thus you can split the lines like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1447 mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1448 \ ->filter(filterexpr)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1449 \ ->map(mapexpr)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1450 \ ->sort()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1451 \ ->join()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1452
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1453 When using the lambda form there must be no white space between the } and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1454 (.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1455
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1456
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1457 expr11
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1458 number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1459 ------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1460 number number constant expr-number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1461
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1462 0x hex-number 0o octal-number binary-number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1463 Decimal, Hexadecimal (starting with 0x or 0X), Binary (starting with 0b or 0B)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1464 and Octal (starting with 0, 0o or 0O).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1465
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1466 Assuming 64 bit numbers are used (see \|v:numbersize\|) an unsigned number is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1467 truncated to 0x7fffffffffffffff or 9223372036854775807. You can use -1 to get
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1468 0xffffffffffffffff.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1469
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1470 floating-point-format
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1471 Floating point numbers can be written in two forms:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1472
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1473 [-+]{N}.{M}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1474 [-+]{N}.{M}[eE][-+]{exp}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1475
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1476 {N} and {M} are numbers. Both {N} and {M} must be present and can only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1477 contain digits, except that in \|Vim9\| script in {N} single quotes between
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1478 digits are ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1479 [-+] means there is an optional plus or minus sign.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1480 {exp} is the exponent, power of 10.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1481 Only a decimal point is accepted, not a comma. No matter what the current
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1482 locale is.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1483
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1484 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1485 123.456
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1486 +0.0001
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1487 55.0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1488 -0.123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1489 1.234e03
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1490 1.0E-6
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1491 -3.1416e+88
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1492
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1493 These are INVALID:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1494 3. empty {M}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1495 1e40 missing .{M}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1496
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1497 Rationale:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1498 Before floating point was introduced, the text "123.456" was interpreted as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1499 the two numbers "123" and "456", both converted to a string and concatenated,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1500 resulting in the string "123456". Since this was considered pointless, and we
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1501 could not find it intentionally being used in Vim scripts, this backwards
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1502 incompatibility was accepted in favor of being able to use the normal notation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1503 for floating point numbers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1504
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1505 float-pi float-e
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1506 A few useful values to copy&paste: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1507 :let pi = 3.14159265359
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1508 :let e = 2.71828182846
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1509 Or, if you don't want to write them in as floating-point literals, you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1510 also use functions, like the following: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1511 :let pi = acos(-1.0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1512 :let e = exp(1.0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1513 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1514 floating-point-precision
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1515 The precision and range of floating points numbers depends on what "double"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1516 means in the library Vim was compiled with. There is no way to change this at
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1517 runtime.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1518
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1519 The default for displaying a \|Float\| is to use 6 decimal places, like using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1520 printf("%g", f). You can select something else when using the \|printf()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1521 function. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1522 :echo printf('%.15e', atan(1))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1523 < 7.853981633974483e-01
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1524
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1525
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1526
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1527 string string String expr-string E114
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1528 ------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1529 "string" string constant expr-quote
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1530
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1531 Note that double quotes are used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1532
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1533 A string constant accepts these special characters:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1534 \... three-digit octal number (e.g., "\316")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1535 \.. two-digit octal number (must be followed by non-digit)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1536 \. one-digit octal number (must be followed by non-digit)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1537 \x.. byte specified with two hex numbers (e.g., "\x1f")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1538 \x. byte specified with one hex number (must be followed by non-hex char)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1539 \X.. same as \x..
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1540 \X. same as \x.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1541 \u.... character specified with up to 4 hex numbers, stored according to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1542 current value of 'encoding' (e.g., "\u02a4")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1543 \U.... same as \u but allows up to 8 hex numbers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1544 \b backspace <BS>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1545 \e escape <Esc>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1546 \f formfeed 0x0C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1547 \n newline <NL>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1548 \r return <CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1549 \t tab <Tab>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1550 \\ backslash
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1551 \" double quote
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1552 \<xxx> Special key named "xxx". e.g. "\<C-W>" for CTRL-W. This is for use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1553 in mappings, the 0x80 byte is escaped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1554 To use the double quote character it must be escaped: "<M-\">".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1555 Don't use <Char-xxxx> to get a UTF-8 character, use \uxxxx as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1556 mentioned above.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1557 \<*xxx> Like \<xxx> but prepends a modifier instead of including it in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1558 character. E.g. "\<C-w>" is one character 0x17 while "\<*C-w>" is four
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1559 bytes: 3 for the CTRL modifier and then character "W".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1560
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1561 Note that "\xff" is stored as the byte 255, which may be invalid in some
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1562 encodings. Use "\u00ff" to store character 255 according to the current value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1563 of 'encoding'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1564
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1565 Note that "\000" and "\x00" force the end of the string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1566
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1567
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1568 blob-literal blob-literal E973
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1569 ------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1570
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1571 Hexadecimal starting with 0z or 0Z, with an arbitrary number of bytes.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1572 The sequence must be an even number of hex characters. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1573 :let b = 0zFF00ED015DAF
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1574
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1575
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1576 literal-string literal-string E115
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1577 ---------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1578 'string' string constant expr-'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1579
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1580 Note that single quotes are used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1581
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1582 This string is taken as it is. No backslashes are removed or have a special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1583 meaning. The only exception is that two quotes stand for one quote.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1584
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1585 Single quoted strings are useful for patterns, so that backslashes do not need
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1586 to be doubled. These two commands are equivalent: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1587 if a =~ "\\s*"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1588 if a =~ '\s*'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1589
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1590
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1591 interpolated-string $quote interpolated-string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1592 --------------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1593 $"string" interpolated string constant expr-$quote
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1594 $'string' interpolated literal string constant expr-$'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1595
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1596 Interpolated strings are an extension of the \|string\| and \|literal-string\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1597 allowing the inclusion of Vim script expressions (see \|expr1\|). Any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1598 expression returning a value can be enclosed between curly braces. The value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1599 is converted to a string. All the text and results of the expressions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1600 are concatenated to make a new string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1601 E1278 E1279
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1602 To include an opening brace '{' or closing brace '}' in the string content
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1603 double it. For double quoted strings using a backslash also works. A single
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1604 closing brace '}' will result in an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1605
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1606 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1607 let your_name = input("What's your name? ")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1608 < What's your name? Peter ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1609 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1610 echo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1611 echo $"Hello, {your_name}!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1612 < Hello, Peter! ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1613 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1614 echo $"The square root of {{9}} is {sqrt(9)}"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1615 < The square root of {9} is 3.0 ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1616
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1617 string-offset-encoding
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1618 A string consists of multiple characters. How the characters are stored
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1619 depends on 'encoding'. Most common is UTF-8, which uses one byte for ASCII
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1620 characters, two bytes for other latin characters and more bytes for other
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1621 characters.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1622
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1623 A string offset can count characters or bytes. Other programs may use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1624 UTF-16 encoding (16-bit words) and an offset of UTF-16 words. Some functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1625 use byte offsets, usually for UTF-8 encoding. Other functions use character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1626 offsets, in which case the encoding doesn't matter.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1627
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1628 The different offsets for the string "a©😊" are below:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1629
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1630 UTF-8 offsets:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1631 [0]: 61, [1]: C2, [2]: A9, [3]: F0, [4]: 9F, [5]: 98, [6]: 8A
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1632 UTF-16 offsets:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1633 [0]: 0061, [1]: 00A9, [2]: D83D, [3]: DE0A
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1634 UTF-32 (character) offsets:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1635 [0]: 00000061, [1]: 000000A9, [2]: 0001F60A
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1636
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1637 You can use the "g8" and "ga" commands on a character to see the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1638 decimal/hex/octal values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1639
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1640 The functions \|byteidx()\|, \|utf16idx()\| and \|charidx()\| can be used to convert
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1641 between these indices. The functions \|strlen()\|, \|strutf16len()\| and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1642 \|strcharlen()\| return the number of bytes, UTF-16 code units and characters in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1643 a string respectively.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1644
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1645 option expr-option E112 E113
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1646 ------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1647 &option option value, local value if possible
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1648 &g:option global option value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1649 &l:option local option value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1650
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1651 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1652 echo "tabstop is " .. &tabstop
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1653 if &insertmode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1654
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1655 Any option name can be used here. See \|options\|. When using the local value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1656 and there is no buffer-local or window-local value, the global value is used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1657 anyway.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1658
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1659
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1660 register expr-register @r
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1661 --------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1662 @r contents of register 'r'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1663
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1664 The result is the contents of the named register, as a single string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1665 Newlines are inserted where required. To get the contents of the unnamed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1666 register use @" or @@. See \|registers\| for an explanation of the available
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1667 registers.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1668
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1669 When using the '=' register you get the expression itself, not what it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1670 evaluates to. Use \|eval()\| to evaluate it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1671
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1672
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1673 nesting expr-nesting E110
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1674 -------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1675 (expr1) nested expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1676
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1677
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1678 environment variable expr-env
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1679 --------------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1680 $VAR environment variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1681
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1682 The String value of any environment variable. When it is not defined, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1683 result is an empty string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1684
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1685 The functions `getenv()` and `setenv()` can also be used and work for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1686 environment variables with non-alphanumeric names.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1687 The function `environ()` can be used to get a Dict with all environment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1688 variables.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1689
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1690
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1691 expr-env-expand
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1692 Note that there is a difference between using $VAR directly and using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1693 expand("$VAR"). Using it directly will only expand environment variables that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1694 are known inside the current Vim session. Using expand() will first try using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1695 the environment variables known inside the current Vim session. If that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1696 fails, a shell will be used to expand the variable. This can be slow, but it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1697 does expand all variables that the shell knows about. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1698 :echo $shell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1699 :echo expand("$shell")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1700 The first one probably doesn't echo anything, the second echoes the $shell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1701 variable (if your shell supports it).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1702
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1703
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1704 internal variable expr-variable E1015 E1089
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1705 -----------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1706 variable internal variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1707 See below \|internal-variables\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1708
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1709
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1710 function call expr-function E116 E118 E119 E120
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1711 -------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1712 function(expr1, ...) function call
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1713 See below \|functions\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1714
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1715
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1716 lambda expression expr-lambda lambda
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1717 -----------------
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1718 {args -> expr1} legacy lambda expression E451
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1719 (args) => expr1 \|Vim9\| lambda expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1720
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1721 A lambda expression creates a new unnamed function which returns the result of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1722 evaluating \|expr1\|. Lambda expressions differ from \|user-functions\| in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1723 the following ways:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1724
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1725 1. The body of the lambda expression is an \|expr1\| and not a sequence of \|Ex\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1726 commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1727 2. The prefix "a:" should not be used for arguments. E.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1728 :let F = {arg1, arg2 -> arg1 - arg2}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1729 :echo F(5, 2)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1730 < 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1731
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1732 The arguments are optional. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1733 :let F = {-> 'error function'}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1734 :echo F('ignored')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1735 < error function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1736
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1737 The \|Vim9\| lambda does not only use a different syntax, it also adds type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1738 checking and can be split over multiple lines, see \|vim9-lambda\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1739
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1740 closure
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1741 Lambda expressions can access outer scope variables and arguments. This is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1742 often called a closure. Example where "i" and "a:arg" are used in a lambda
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1743 while they already exist in the function scope. They remain valid even after
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1744 the function returns: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1745 :function Foo(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1746 : let i = 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1747 : return {x -> x + i - a:arg}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1748 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1749 :let Bar = Foo(4)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1750 :echo Bar(6)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1751 < 5
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1752
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1753 Note that the variables must exist in the outer scope before the lambda is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1754 defined for this to work. See also \|:func-closure\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1755
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1756 Lambda and closure support can be checked with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1757 if has('lambda')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1758
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1759 Examples for using a lambda expression with \|sort()\|, \|map()\| and \|filter()\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1760 :echo map([1, 2, 3], {idx, val -> val + 1})
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1761 < [2, 3, 4] >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1762 :echo sort([3,7,2,1,4], {a, b -> a - b})
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1763 < [1, 2, 3, 4, 7]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1764
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1765 The lambda expression is also useful for Channel, Job and timer: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1766 :let timer = timer_start(500,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1767 \ {-> execute("echo 'Handler called'", "")},
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1768 \ {'repeat': 3})
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1769 < Handler called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1770 Handler called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1771 Handler called
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1772
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1773 Note that it is possible to cause memory to be used and not freed if the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1774 closure is referenced by the context it depends on: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1775 function Function()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1776 let x = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1777 let F = {-> x}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1778 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1779 The closure uses "x" from the function scope, and "F" in that same scope
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1780 refers to the closure. This cycle results in the memory not being freed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1781 Recommendation: don't do this.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1782
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1783 Notice how execute() is used to execute an Ex command. That's ugly though.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1784 In Vim9 script you can use a command block, see \|inline-function\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1785
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1786 Although you can use the loop variable of a `for` command, it must still exist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1787 when the closure is called, otherwise you get an error. E1302
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1788
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1789 Lambda expressions have internal names like '<lambda>42'. If you get an error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1790 for a lambda expression, you can find what it is with the following command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1791 :function <lambda>42
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1792 See also: \|numbered-function\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1793
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1794 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1795 3. Internal variable internal-variables E461 E1001
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1796
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1797 An internal variable name can be made up of letters, digits and '_'. But it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1798 cannot start with a digit. In legacy script it is also possible to use curly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1799 braces, see \|curly-braces-names\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1800
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1801 In legacy script an internal variable is created with the ":let" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1802 \|:let\|. An internal variable is explicitly destroyed with the ":unlet"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1803 command \|:unlet\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1804 Using a name that is not an internal variable or refers to a variable that has
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1805 been destroyed results in an error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1806
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1807 In \|Vim9\| script `:let` is not used and variables work differently, see \|:var\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1808
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1809 variable-scope
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1810 There are several name spaces for variables. Which one is to be used is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1811 specified by what is prepended:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1812
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1813 (nothing) In a function: local to the function;
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1814 in a legacy script: global;
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1815 in a \|Vim9\| script: local to the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1816 \|buffer-variable\| b: Local to the current buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1817 \|window-variable\| w: Local to the current window.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1818 \|tabpage-variable\| t: Local to the current tab page.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1819 \|global-variable\| g: Global.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1820 \|local-variable\| l: Local to a function (only in a legacy function)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1821 \|script-variable\| s: Local to a \|:source\|'ed Vim script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1822 \|function-argument\| a: Function argument (only in a legacy function).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1823 \|vim-variable\| v: Global, predefined by Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1824
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1825 The scope name by itself can be used as a \|Dictionary\|. For example, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1826 delete all script-local variables: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1827 :for k in keys(s:)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1828 : unlet s:[k]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1829 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1830
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1831 Note: in Vim9 script variables can also be local to a block of commands, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1832 \|vim9-scopes\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1833 buffer-variable b:var b:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1834 A variable name that is preceded with "b:" is local to the current buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1835 Thus you can have several "b:foo" variables, one for each buffer.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1836 This kind of variable is deleted when the buffer is wiped out or deleted with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1837 \|:bdelete\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1838
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1839 One local buffer variable is predefined:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1840 b:changedtick changetick
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1841 b:changedtick The total number of changes to the current buffer. It is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1842 incremented for each change. An undo command is also a change
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1843 in this case. Resetting 'modified' when writing the buffer is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1844 also counted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1845 This can be used to perform an action only when the buffer has
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1846 changed. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1847 :if my_changedtick != b:changedtick
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1848 : let my_changedtick = b:changedtick
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1849 : call My_Update()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1850 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1851 < You cannot change or delete the b:changedtick variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1852 If you need more information about the change see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1853 \|listener_add()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1854
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1855 window-variable w:var w:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1856 A variable name that is preceded with "w:" is local to the current window. It
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1857 is deleted when the window is closed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1858
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1859 tabpage-variable t:var t:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1860 A variable name that is preceded with "t:" is local to the current tab page,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1861 It is deleted when the tab page is closed. {not available when compiled
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1862 without the \|+windows\| feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1863
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1864 global-variable g:var g:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1865 Inside functions and in \|Vim9\| script global variables are accessed with "g:".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1866 Omitting this will access a variable local to a function or script. "g:"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1867 can also be used in any other place if you like.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1868
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1869 local-variable l:var l:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1870 Inside functions local variables are accessed without prepending anything.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1871 But you can also prepend "l:" if you like. However, without prepending "l:"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1872 you may run into reserved variable names. For example "count". By itself it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1873 refers to "v:count". Using "l:count" you can have a local variable with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1874 same name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1875
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1876 script-variable s:var
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1877 In a legacy Vim script variables starting with "s:" can be used. They cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1878 be accessed from outside of the scripts, thus are local to the script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1879 In \|Vim9\| script the "s:" prefix can be omitted, variables are script-local by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1880 default.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1881
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1882 They can be used in:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1883 - commands executed while the script is sourced
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1884 - functions defined in the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1885 - autocommands defined in the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1886 - functions and autocommands defined in functions and autocommands which were
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1887 defined in the script (recursively)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1888 - user defined commands defined in the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1889 Thus not in:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1890 - other scripts sourced from this one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1891 - mappings
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1892 - menus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1893 - etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1894
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1895 Script variables can be used to avoid conflicts with global variable names.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1896 Take this example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1897
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1898 let s:counter = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1899 function MyCounter()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1900 let s:counter = s:counter + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1901 echo s:counter
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1902 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1903 command Tick call MyCounter()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1904
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1905 You can now invoke "Tick" from any script, and the "s:counter" variable in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1906 that script will not be changed, only the "s:counter" in the script where
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1907 "Tick" was defined is used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1908
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1909 Another example that does the same: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1910
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1911 let s:counter = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1912 command Tick let s:counter = s:counter + 1 \| echo s:counter
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1913
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1914 When calling a function and invoking a user-defined command, the context for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1915 script variables is set to the script where the function or command was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1916 defined.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1917
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1918 The script variables are also available when a function is defined inside a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1919 function that is defined in a script. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1920
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1921 let s:counter = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1922 function StartCounting(incr)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1923 if a:incr
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1924 function MyCounter()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1925 let s:counter = s:counter + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1926 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1927 else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1928 function MyCounter()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1929 let s:counter = s:counter - 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1930 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1931 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1932 endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1933
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1934 This defines the MyCounter() function either for counting up or counting down
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1935 when calling StartCounting(). It doesn't matter from where StartCounting() is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1936 called, the s:counter variable will be accessible in MyCounter().
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1937
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1938 When the same script is sourced again it will use the same script variables.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1939 They will remain valid as long as Vim is running. This can be used to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1940 maintain a counter: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1941
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1942 if !exists("s:counter")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1943 let s:counter = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1944 echo "script executed for the first time"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1945 else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1946 let s:counter = s:counter + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1947 echo "script executed " .. s:counter .. " times now"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1948 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1949
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1950 Note that this means that filetype plugins don't get a different set of script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1951 variables for each buffer. Use local buffer variables instead \|b:var\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1952
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1953
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1954 PREDEFINED VIM VARIABLES vim-variable v:var v:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1955 E963 E1063
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1956 Some variables can be set by the user, but the type cannot be changed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1957
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1958 v:argv argv-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1959 v:argv The command line arguments Vim was invoked with. This is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1960 list of strings. The first item is the Vim command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1961 See \|v:progpath\| for the command with full path.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1962
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1963 v:beval_col beval_col-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1964 v:beval_col The number of the column, over which the mouse pointer is.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1965 This is the byte index in the \|v:beval_lnum\| line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1966 Only valid while evaluating the 'balloonexpr' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1967
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1968 v:beval_bufnr beval_bufnr-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1969 v:beval_bufnr The number of the buffer, over which the mouse pointer is. Only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1970 valid while evaluating the 'balloonexpr' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1971
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1972 v:beval_lnum beval_lnum-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1973 v:beval_lnum The number of the line, over which the mouse pointer is. Only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1974 valid while evaluating the 'balloonexpr' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1975
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1976 v:beval_text beval_text-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1977 v:beval_text The text under or after the mouse pointer. Usually a word as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1978 it is useful for debugging a C program. 'iskeyword' applies,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1979 but a dot and "->" before the position is included. When on a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1980 ']' the text before it is used, including the matching '[' and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1981 word before it. When on a Visual area within one line the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1982 highlighted text is used. Also see \|<cexpr>\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1983 Only valid while evaluating the 'balloonexpr' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1984
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1985 v:beval_winnr beval_winnr-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1986 v:beval_winnr The number of the window, over which the mouse pointer is. Only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1987 valid while evaluating the 'balloonexpr' option. The first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1988 window has number zero (unlike most other places where a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1989 window gets a number).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1990
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1991 v:beval_winid beval_winid-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1992 v:beval_winid The \|window-ID\| of the window, over which the mouse pointer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1993 is. Otherwise like v:beval_winnr.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1994
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1995 v:char char-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1996 v:char Argument for evaluating 'formatexpr' and used for the typed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1997 character when using <expr> in an abbreviation \|:map-<expr>\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1998 It is also used by the \|InsertCharPre\| and \|InsertEnter\| events.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	1999
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2000 v:charconvert_from charconvert_from-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2001 v:charconvert_from
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2002 The name of the character encoding of a file to be converted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2003 Only valid while evaluating the 'charconvert' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2004
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2005 v:charconvert_to charconvert_to-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2006 v:charconvert_to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2007 The name of the character encoding of a file after conversion.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2008 Only valid while evaluating the 'charconvert' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2009
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2010 v:cmdarg cmdarg-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2011 v:cmdarg This variable is used for two purposes:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2012 1. The extra arguments given to a file read/write command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2013 Currently these are "++enc=" and "++ff=". This variable is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2014 set before an autocommand event for a file read/write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2015 command is triggered. There is a leading space to make it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2016 possible to append this variable directly after the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2017 read/write command. Note: The "+cmd" argument isn't
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2018 included here, because it will be executed anyway.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2019 2. When printing a PostScript file with ":hardcopy" this is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2020 the argument for the ":hardcopy" command. This can be used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2021 in 'printexpr'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2022
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2023 v:cmdbang cmdbang-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2024 v:cmdbang Set like v:cmdarg for a file read/write command. When a "!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2025 was used the value is 1, otherwise it is 0. Note that this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2026 can only be used in autocommands. For user commands \|<bang>\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2027 can be used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2028 v:collate collate-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2029 v:collate The current locale setting for collation order of the runtime
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2030 environment. This allows Vim scripts to be aware of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2031 current locale encoding. Technical: it's the value of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2032 LC_COLLATE. When not using a locale the value is "C".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2033 This variable can not be set directly, use the \|:language\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2034 command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2035 See \|multi-lang\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2036
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2037 v:colornames
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2038 v:colornames A dictionary that maps color names to hex color strings. These
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2039 color names can be used with the \|highlight-guifg\|,
34278 e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2040 \|highlight-guibg\|, and \|highlight-guisp\| parameters.
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2041
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2042 The key values in the dictionary (the color names) should be
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2043 lower cased, because Vim looks up a color by its lower case
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2044 name.
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2045
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2046 Updating an entry in v:colornames has no immediate effect on
e67eafbceca9 runtime(colors): color names in the v:colornames dict should be lower cased Christian Brabandt <cb@256bit.org> parents: 34132 diff changeset	2047 the syntax highlighting. The highlight commands (probably in a
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2048 colorscheme script) need to be re-evaluated in order to use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2049 the updated color values. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2050
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2051 :let v:colornames['fuscia'] = '#cf3ab4'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2052 :let v:colornames['mauve'] = '#915f6d'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2053 :highlight Normal guifg=fuscia guibg=mauve
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2054 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2055 This cannot be used to override the \|cterm-colors\| but it can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2056 be used to override other colors. For example, the X11 colors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2057 defined in the `colors/lists/default.vim` (previously defined
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2058 in \|rgb.txt\|). When defining new color names in a plugin, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2059 recommended practice is to set a color entry only when it does
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2060 not already exist. For example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2061
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2062 :call extend(v:colornames, {
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2063 \ 'fuscia': '#cf3ab4',
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2064 \ 'mauve': '#915f6d,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2065 \ }, 'keep')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2066 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2067 Using \|extend()\| with the 'keep' option updates each color only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2068 if it did not exist in \|v:colornames\|. Doing so allows the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2069 user to choose the precise color value for a common name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2070 by setting it in their \|.vimrc\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2071
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2072 It is possible to remove entries from this dictionary but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2073 doing so is NOT recommended, because it is disruptive to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2074 other scripts. It is also unlikely to achieve the desired
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2075 result because the \|:colorscheme\| and \|:highlight\| commands will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2076 both automatically load all `colors/lists/default.vim` color
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2077 scripts.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2078
34602 c7680d286e1f runtime(colors): don't unnecessarily reload v:colornames dict Christian Brabandt <cb@256bit.org> parents: 34293 diff changeset	2079 You can make changes to that file, but make sure to add new
c7680d286e1f runtime(colors): don't unnecessarily reload v:colornames dict Christian Brabandt <cb@256bit.org> parents: 34293 diff changeset	2080 keys instead of updating existing ones, otherwise Vim will skip
c7680d286e1f runtime(colors): don't unnecessarily reload v:colornames dict Christian Brabandt <cb@256bit.org> parents: 34293 diff changeset	2081 loading the file (thinking is hasn't been changed).
c7680d286e1f runtime(colors): don't unnecessarily reload v:colornames dict Christian Brabandt <cb@256bit.org> parents: 34293 diff changeset	2082
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2083 v:completed_item completed_item-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2084 v:completed_item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2085 \|Dictionary\| containing the \|complete-items\| for the most
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2086 recently completed word after \|CompleteDone\|. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2087 \|Dictionary\| is empty if the completion failed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2088 Note: Plugins can modify the value to emulate the builtin
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2089 \|CompleteDone\| event behavior.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2090
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2091 v:count count-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2092 v:count The count given for the last Normal mode command. Can be used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2093 to get the count before a mapping. Read-only. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2094 :map _x :<C-U>echo "the count is " .. v:count<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2095 < Note: The <C-U> is required to remove the line range that you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2096 get when typing ':' after a count.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2097 When there are two counts, as in "3d2w", they are multiplied,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2098 just like what happens in the command, "d6w" for the example.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2099 Also used for evaluating the 'formatexpr' option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2100 "count" also works, for backwards compatibility, unless
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2101 \|scriptversion\| is 3 or higher.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2102
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2103 v:count1 count1-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2104 v:count1 Just like "v:count", but defaults to one when no count is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2105 used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2106
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2107 v:ctype ctype-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2108 v:ctype The current locale setting for characters of the runtime
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2109 environment. This allows Vim scripts to be aware of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2110 current locale encoding. Technical: it's the value of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2111 LC_CTYPE. When not using a locale the value is "C".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2112 This variable can not be set directly, use the \|:language\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2113 command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2114 See \|multi-lang\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2115
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2116 v:dying dying-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2117 v:dying Normally zero. When a deadly signal is caught it's set to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2118 one. When multiple signals are caught the number increases.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2119 Can be used in an autocommand to check if Vim didn't
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2120 terminate normally. {only works on Unix}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2121 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2122 :au VimLeave * if v:dying \| echo "\nAAAAaaaarrrggghhhh!!!\n" \| endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2123 < Note: if another deadly signal is caught when v:dying is one,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2124 VimLeave autocommands will not be executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2125
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2126 v:exiting exiting-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2127 v:exiting Vim exit code. Normally zero, non-zero when something went
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2128 wrong. The value is v:null before invoking the \|VimLeavePre\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2129 and \|VimLeave\| autocmds. See \|:q\|, \|:x\| and \|:cquit\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2130 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2131 :au VimLeave * echo "Exit value is " .. v:exiting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2132 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2133 v:echospace echospace-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2134 v:echospace Number of screen cells that can be used for an `:echo` message
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2135 in the last screen line before causing the \|hit-enter-prompt\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2136 Depends on 'showcmd', 'ruler' and 'columns'. You need to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2137 check 'cmdheight' for whether there are full-width lines
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2138 available above the last line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2139
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2140 v:errmsg errmsg-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2141 v:errmsg Last given error message. It's allowed to set this variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2142 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2143 :let v:errmsg = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2144 :silent! next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2145 :if v:errmsg != ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2146 : ... handle error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2147 < "errmsg" also works, for backwards compatibility, unless
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2148 \|scriptversion\| is 3 or higher.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2149
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2150 v:errors errors-variable assert-return
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2151 v:errors Errors found by assert functions, such as \|assert_true()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2152 This is a list of strings.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2153 The assert functions append an item when an assert fails.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2154 The return value indicates this: a one is returned if an item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2155 was added to v:errors, otherwise zero is returned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2156 To remove old results make it empty: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2157 :let v:errors = []
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2158 < If v:errors is set to anything but a list it is made an empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2159 list by the assert function.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2160
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2161 v:event event-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2162 v:event Dictionary containing information about the current
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2163 \|autocommand\|. See the specific event for what it puts in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2164 this dictionary.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2165 The dictionary is emptied when the \|autocommand\| finishes,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2166 please refer to \|dict-identity\| for how to get an independent
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2167 copy of it. Use \|deepcopy()\| if you want to keep the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2168 information after the event triggers. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2169 au TextYankPost * let g:foo = deepcopy(v:event)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2170 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2171 v:exception exception-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2172 v:exception The value of the exception most recently caught and not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2173 finished. See also \|v:throwpoint\| and \|throw-variables\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2174 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2175 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2176 : throw "oops"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2177 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2178 : echo "caught " .. v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2179 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2180 < Output: "caught oops".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2181
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2182 v:false false-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2183 v:false A Number with value zero. Used to put "false" in JSON. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2184 \|json_encode()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2185 When used as a string this evaluates to "v:false". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2186 echo v:false
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2187 < v:false ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2188 That is so that eval() can parse the string back to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2189 value. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2190 In \|Vim9\| script "false" can be used which has a boolean type.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2191
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2192 v:fcs_reason fcs_reason-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2193 v:fcs_reason The reason why the \|FileChangedShell\| event was triggered.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2194 Can be used in an autocommand to decide what to do and/or what
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2195 to set v:fcs_choice to. Possible values:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2196 deleted file no longer exists
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2197 conflict file contents, mode or timestamp was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2198 changed and buffer is modified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2199 changed file contents has changed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2200 mode mode of file changed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2201 time only file timestamp changed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2202
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2203 v:fcs_choice fcs_choice-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2204 v:fcs_choice What should happen after a \|FileChangedShell\| event was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2205 triggered. Can be used in an autocommand to tell Vim what to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2206 do with the affected buffer:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2207 reload Reload the buffer (does not work if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2208 the file was deleted).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2209 edit Reload the buffer and detect the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2210 values for options such as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2211 'fileformat', 'fileencoding', 'binary'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2212 (does not work if the file was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2213 deleted).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2214 ask Ask the user what to do, as if there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2215 was no autocommand. Except that when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2216 only the timestamp changed nothing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2217 will happen.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2218 <empty> Nothing, the autocommand should do
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2219 everything that needs to be done.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2220 The default is empty. If another (invalid) value is used then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2221 Vim behaves like it is empty, there is no warning message.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2222
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2223 v:fname fname-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2224 v:fname When evaluating 'includeexpr': the file name that was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2225 detected. Empty otherwise.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2226
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2227 v:fname_in fname_in-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2228 v:fname_in The name of the input file. Valid while evaluating:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2229 option used for ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2230 'charconvert' file to be converted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2231 'diffexpr' original file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2232 'patchexpr' original file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2233 'printexpr' file to be printed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2234 And set to the swap file name for \|SwapExists\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2235
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2236 v:fname_out fname_out-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2237 v:fname_out The name of the output file. Only valid while
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2238 evaluating:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2239 option used for ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2240 'charconvert' resulting converted file (*)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2241 'diffexpr' output of diff
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2242 'patchexpr' resulting patched file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2243 (*) When doing conversion for a write command (e.g., ":w
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2244 file") it will be equal to v:fname_in. When doing conversion
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2245 for a read command (e.g., ":e file") it will be a temporary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2246 file and different from v:fname_in.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2247
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2248 v:fname_new fname_new-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2249 v:fname_new The name of the new version of the file. Only valid while
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2250 evaluating 'diffexpr'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2251
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2252 v:fname_diff fname_diff-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2253 v:fname_diff The name of the diff (patch) file. Only valid while
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2254 evaluating 'patchexpr'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2255
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2256 v:folddashes folddashes-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2257 v:folddashes Used for 'foldtext': dashes representing foldlevel of a closed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2258 fold.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2259 Read-only in the \|sandbox\|. \|fold-foldtext\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2260
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2261 v:foldlevel foldlevel-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2262 v:foldlevel Used for 'foldtext': foldlevel of closed fold.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2263 Read-only in the \|sandbox\|. \|fold-foldtext\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2264
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2265 v:foldend foldend-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2266 v:foldend Used for 'foldtext': last line of closed fold.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2267 Read-only in the \|sandbox\|. \|fold-foldtext\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2268
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2269 v:foldstart foldstart-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2270 v:foldstart Used for 'foldtext': first line of closed fold.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2271 Read-only in the \|sandbox\|. \|fold-foldtext\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2272
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2273 v:hlsearch hlsearch-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2274 v:hlsearch Variable that indicates whether search highlighting is on.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2275 Setting it makes sense only if 'hlsearch' is enabled which
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2276 requires \|+extra_search\|. Setting this variable to zero acts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2277 like the \|:nohlsearch\| command, setting it to one acts like >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2278 let &hlsearch = &hlsearch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2279 < Note that the value is restored when returning from a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2280 function. \|function-search-undo\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2281
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2282 v:insertmode insertmode-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2283 v:insertmode Used for the \|InsertEnter\| and \|InsertChange\| autocommand
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2284 events. Values:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2285 i Insert mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2286 r Replace mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2287 v Virtual Replace mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2288
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2289 v:key key-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2290 v:key Key of the current item of a \|Dictionary\|. Only valid while
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2291 evaluating the expression used with \|map()\| and \|filter()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2292 Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2293
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2294 v:lang lang-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2295 v:lang The current locale setting for messages of the runtime
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2296 environment. This allows Vim scripts to be aware of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2297 current language. Technical: it's the value of LC_MESSAGES.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2298 The value is system dependent.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2299 This variable can not be set directly, use the \|:language\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2300 command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2301 It can be different from \|v:ctype\| when messages are desired
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2302 in a different language than what is used for character
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2303 encoding. See \|multi-lang\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2304
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2305 v:lc_time lc_time-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2306 v:lc_time The current locale setting for time messages of the runtime
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2307 environment. This allows Vim scripts to be aware of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2308 current language. Technical: it's the value of LC_TIME.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2309 This variable can not be set directly, use the \|:language\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2310 command. See \|multi-lang\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2311
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2312 v:lnum lnum-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2313 v:lnum Line number for the 'foldexpr' \|fold-expr\|, 'formatexpr' and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2314 'indentexpr' expressions, tab page number for 'guitablabel'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2315 and 'guitabtooltip'. Only valid while one of these
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2316 expressions is being evaluated. Read-only when in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2317 \|sandbox\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2318
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2319 v:maxcol maxcol-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2320 v:maxcol Maximum line length. Depending on where it is used it can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2321 screen columns, characters or bytes. The value currently is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2322 2147483647 on all systems.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2323
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2324 v:mouse_win mouse_win-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2325 v:mouse_win Window number for a mouse click obtained with \|getchar()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2326 First window has number 1, like with \|winnr()\|. The value is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2327 zero when there was no mouse button click.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2328
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2329 v:mouse_winid mouse_winid-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2330 v:mouse_winid Window ID for a mouse click obtained with \|getchar()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2331 The value is zero when there was no mouse button click.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2332
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2333 v:mouse_lnum mouse_lnum-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2334 v:mouse_lnum Line number for a mouse click obtained with \|getchar()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2335 This is the text line number, not the screen line number. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2336 value is zero when there was no mouse button click.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2337
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2338 v:mouse_col mouse_col-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2339 v:mouse_col Column number for a mouse click obtained with \|getchar()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2340 This is the screen column number, like with \|virtcol()\|. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2341 value is zero when there was no mouse button click.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2342
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2343 v:none none-variable None
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2344 v:none An empty String. Used to put an empty item in JSON. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2345 \|json_encode()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2346 This can also be used as a function argument to use the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2347 default value, see \|none-function_argument\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2348 When used as a number this evaluates to zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2349 When used as a string this evaluates to "v:none". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2350 echo v:none
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2351 < v:none ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2352 That is so that eval() can parse the string back to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2353 value. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2354 Note that using `== v:none` and `!= v:none` will often give
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2355 an error. Instead, use `is v:none` and `isnot v:none` .
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2356
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2357 v:null null-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2358 v:null An empty String. Used to put "null" in JSON. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2359 \|json_encode()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2360 When used as a number this evaluates to zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2361 When used as a string this evaluates to "v:null". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2362 echo v:null
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2363 < v:null ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2364 That is so that eval() can parse the string back to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2365 value. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2366 In \|Vim9\| script `null` can be used without "v:".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2367 In some places `v:null` and `null` can be used for a List,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2368 Dict, Job, etc. that is not set. That is slightly different
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2369 than an empty List, Dict, etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2370
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2371 v:numbermax numbermax-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2372 v:numbermax Maximum value of a number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2373
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2374 v:numbermin numbermin-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2375 v:numbermin Minimum value of a number (negative).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2376
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2377 v:numbersize numbersize-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2378 v:numbersize Number of bits in a Number. This is normally 64, but on some
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2379 systems it may be 32.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2380
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2381 v:oldfiles oldfiles-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2382 v:oldfiles List of file names that is loaded from the \|viminfo\| file on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2383 startup. These are the files that Vim remembers marks for.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2384 The length of the List is limited by the ' argument of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2385 'viminfo' option (default is 100).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2386 When the \|viminfo\| file is not used the List is empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2387 Also see \|:oldfiles\| and \|c_#<\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2388 The List can be modified, but this has no effect on what is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2389 stored in the \|viminfo\| file later. If you use values other
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2390 than String this will cause trouble.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2391 {only when compiled with the \|+viminfo\| feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2392
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2393 v:option_new
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2394 v:option_new New value of the option. Valid while executing an \|OptionSet\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2395 autocommand.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2396 v:option_old
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2397 v:option_old Old value of the option. Valid while executing an \|OptionSet\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2398 autocommand. Depending on the command used for setting and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2399 kind of option this is either the local old value or the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2400 global old value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2401 v:option_oldlocal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2402 v:option_oldlocal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2403 Old local value of the option. Valid while executing an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2404 \|OptionSet\| autocommand.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2405 v:option_oldglobal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2406 v:option_oldglobal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2407 Old global value of the option. Valid while executing an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2408 \|OptionSet\| autocommand.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2409 v:option_type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2410 v:option_type Scope of the set command. Valid while executing an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2411 \|OptionSet\| autocommand. Can be either "global" or "local"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2412 v:option_command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2413 v:option_command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2414 Command used to set the option. Valid while executing an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2415 \|OptionSet\| autocommand.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2416 value option was set via ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2417 "setlocal" \|:setlocal\| or ":let l:xxx"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2418 "setglobal" \|:setglobal\| or ":let g:xxx"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2419 "set" \|:set\| or \|:let\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2420 "modeline" \|modeline\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2421 v:operator operator-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2422 v:operator The last operator given in Normal mode. This is a single
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2423 character except for commands starting with <g> or <z>,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2424 in which case it is two characters. Best used alongside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2425 \|v:prevcount\| and \|v:register\|. Useful if you want to cancel
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2426 Operator-pending mode and then use the operator, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2427 :omap O <Esc>:call MyMotion(v:operator)<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2428 < The value remains set until another operator is entered, thus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2429 don't expect it to be empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2430 v:operator is not set for \|:delete\|, \|:yank\| or other Ex
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2431 commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2432 Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2433
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2434 v:prevcount prevcount-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2435 v:prevcount The count given for the last but one Normal mode command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2436 This is the v:count value of the previous command. Useful if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2437 you want to cancel Visual or Operator-pending mode and then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2438 use the count, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2439 :vmap % <Esc>:call MyFilter(v:prevcount)<CR>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2440 < Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2441
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2442 v:profiling profiling-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2443 v:profiling Normally zero. Set to one after using ":profile start".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2444 See \|profiling\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2445
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2446 v:progname progname-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2447 v:progname Contains the name (with path removed) with which Vim was
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2448 invoked. Allows you to do special initialisations for \|view\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2449 \|evim\| etc., or any other name you might symlink to Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2450 Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2451
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2452 v:progpath progpath-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2453 v:progpath Contains the command with which Vim was invoked, in a form
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2454 that when passed to the shell will run the same Vim executable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2455 as the current one (if $PATH remains unchanged).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2456 Useful if you want to message a Vim server using a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2457 \|--remote-expr\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2458 To get the full path use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2459 echo exepath(v:progpath)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2460 < If the command has a relative path it will be expanded to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2461 full path, so that it still works after `:cd`. Thus starting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2462 "./vim" results in "/home/user/path/to/vim/src/vim".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2463 On Linux and other systems it will always be the full path.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2464 On Mac it may just be "vim" and using exepath() as mentioned
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2465 above should be used to get the full path.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2466 On MS-Windows the executable may be called "vim.exe", but the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2467 ".exe" is not added to v:progpath.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2468 Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2469
33434 484543479bd7 runtime(doc): fix typos. Christian Brabandt <cb@256bit.org> parents: 32936 diff changeset	2470 v:python3_version python3-version-variable
32936 c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2471 v:python3_version
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2472 Version of Python 3 that Vim was built against. When
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2473 Python is loaded dynamically (\|python-dynamic\|), this version
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2474 should exactly match the Python library up to the minor
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2475 version (e.g. 3.10.2 and 3.10.3 are compatible as the minor
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2476 version is "10", whereas 3.9.4 and 3.10.3 are not compatible).
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2477 When \|python-stable-abi\| is used, this will be the minimum Python
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2478 version that you can use instead. (e.g. if v:python3_version
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2479 indicates 3.9, you can use 3.9, 3.10, or anything above).
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2480
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2481 This number is encoded as a hex number following Python ABI
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2482 versioning conventions. Do the following to have a
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2483 human-readable full version in hex: >
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2484 echo printf("%08X", v:python3_version)
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2485 < You can obtain only the minor version by doing: >
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2486 echo and(v:python3_version>>16,0xff)
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2487 < Read-only.
c517845bd10e patch 9.0.1776: No support for stable Python 3 ABI Christian Brabandt <cb@256bit.org> parents: 32670 diff changeset	2488
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2489 v:register register-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2490 v:register The name of the register in effect for the current normal mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2491 command (regardless of whether that command actually used a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2492 register). Or for the currently executing normal mode mapping
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2493 (use this in custom commands that take a register).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2494 If none is supplied it is the default register '"', unless
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2495 'clipboard' contains "unnamed" or "unnamedplus", then it is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2496 '*' or '+'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2497 Also see \|getreg()\| and \|setreg()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2498
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2499 v:scrollstart scrollstart-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2500 v:scrollstart String describing the script or function that caused the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2501 screen to scroll up. It's only set when it is empty, thus the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2502 first reason is remembered. It is set to "Unknown" for a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2503 typed command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2504 This can be used to find out why your script causes the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2505 hit-enter prompt.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2506
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2507 v:servername servername-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2508 v:servername The resulting registered \|client-server-name\| if any.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2509 Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2510
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2511
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2512 v:searchforward v:searchforward searchforward-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2513 Search direction: 1 after a forward search, 0 after a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2514 backward search. It is reset to forward when directly setting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2515 the last search pattern, see \|quote/\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2516 Note that the value is restored when returning from a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2517 function. \|function-search-undo\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2518 Read-write.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2519
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2520 v:shell_error shell_error-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2521 v:shell_error Result of the last shell command. When non-zero, the last
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2522 shell command had an error. When zero, there was no problem.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2523 This only works when the shell returns the error code to Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2524 The value -1 is often used when the command could not be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2525 executed. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2526 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2527 :!mv foo bar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2528 :if v:shell_error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2529 : echo 'could not rename "foo" to "bar"!'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2530 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2531 < "shell_error" also works, for backwards compatibility, unless
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2532 \|scriptversion\| is 3 or higher.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2533
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2534 v:sizeofint sizeofint-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2535 v:sizeofint Number of bytes in an int. Depends on how Vim was compiled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2536 This is only useful for deciding whether a test will give the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2537 expected result.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2538
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2539 v:sizeoflong sizeoflong-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2540 v:sizeoflong Number of bytes in a long. Depends on how Vim was compiled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2541 This is only useful for deciding whether a test will give the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2542 expected result.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2543
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2544 v:sizeofpointer sizeofpointer-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2545 v:sizeofpointer Number of bytes in a pointer. Depends on how Vim was compiled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2546 This is only useful for deciding whether a test will give the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2547 expected result.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2548
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2549 v:statusmsg statusmsg-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2550 v:statusmsg Last given status message. It's allowed to set this variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2551
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2552 v:swapname swapname-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2553 v:swapname Only valid when executing \|SwapExists\| autocommands: Name of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2554 the swap file found. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2555
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2556 v:swapchoice swapchoice-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2557 v:swapchoice \|SwapExists\| autocommands can set this to the selected choice
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2558 for handling an existing swap file:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2559 'o' Open read-only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2560 'e' Edit anyway
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2561 'r' Recover
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2562 'd' Delete swapfile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2563 'q' Quit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2564 'a' Abort
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2565 The value should be a single-character string. An empty value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2566 results in the user being asked, as would happen when there is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2567 no SwapExists autocommand. The default is empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2568
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2569 v:swapcommand swapcommand-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2570 v:swapcommand Normal mode command to be executed after a file has been
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2571 opened. Can be used for a \|SwapExists\| autocommand to have
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2572 another Vim open the file and jump to the right place. For
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2573 example, when jumping to a tag the value is ":tag tagname\r".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2574 For ":edit +cmd file" the value is ":cmd\r".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2575
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2576 v:t_TYPE v:t_bool t_bool-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2577 v:t_bool Value of \|Boolean\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2578 v:t_channel t_channel-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2579 v:t_channel Value of \|Channel\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2580 v:t_dict t_dict-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2581 v:t_dict Value of \|Dictionary\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2582 v:t_float t_float-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2583 v:t_float Value of \|Float\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2584 v:t_func t_func-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2585 v:t_func Value of \|Funcref\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2586 v:t_job t_job-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2587 v:t_job Value of \|Job\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2588 v:t_list t_list-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2589 v:t_list Value of \|List\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2590 v:t_none t_none-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2591 v:t_none Value of \|None\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2592 v:t_number t_number-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2593 v:t_number Value of \|Number\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2594 v:t_string t_string-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2595 v:t_string Value of \|String\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2596 v:t_blob t_blob-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2597 v:t_blob Value of \|Blob\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2598 v:t_class t_class-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2599 v:t_class Value of \|class\| type. Read-only. See: \|type()\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2600 v:t_object t_object-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2601 v:t_object Value of \|object\| type. Read-only. See: \|type()\|
33931 050160b94f02 patch 9.0.2162: Vim9: type documentation out-dated Christian Brabandt <cb@256bit.org> parents: 33902 diff changeset	2602 v:t_typealias t_typealias-variable
050160b94f02 patch 9.0.2162: Vim9: type documentation out-dated Christian Brabandt <cb@256bit.org> parents: 33902 diff changeset	2603 v:t_typealias Value of \|typealias\| type. Read-only. See: \|type()\|
34676 5b25ec43f208 patch 9.1.0219: Vim9: No enum support Christian Brabandt <cb@256bit.org> parents: 34602 diff changeset	2604 v:t_enum t_enum-variable
5b25ec43f208 patch 9.1.0219: Vim9: No enum support Christian Brabandt <cb@256bit.org> parents: 34602 diff changeset	2605 v:t_enum Value of \|enum\| type. Read-only. See: \|type()\|
5b25ec43f208 patch 9.1.0219: Vim9: No enum support Christian Brabandt <cb@256bit.org> parents: 34602 diff changeset	2606 v:t_enumvalue t_enumvalue-variable
5b25ec43f208 patch 9.1.0219: Vim9: No enum support Christian Brabandt <cb@256bit.org> parents: 34602 diff changeset	2607 v:t_enumvalue Value of \|enumvalue\| type. Read-only. See: \|type()\|
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2608
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2609 v:termresponse termresponse-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2610 v:termresponse The escape sequence returned by the terminal for the \|t_RV\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2611 termcap entry. It is set when Vim receives an escape sequence
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2612 that starts with ESC [ or CSI, then '>' or '?' and ends in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2613 'c', with only digits and ';' in between.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2614 When this option is set, the TermResponse autocommand event is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2615 fired, so that you can react to the response from the
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2616 terminal. The TermResponseAll event is also fired, with
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2617 <amatch> set to "version". You can use \|terminalprops()\| to see
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2618 what Vim figured out about the terminal.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2619 The response from a new xterm is: "<Esc>[> Pp ; Pv ; Pc c". Pp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2620 is the terminal type: 0 for vt100 and 1 for vt220. Pv is the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2621 patch level (since this was introduced in patch 95, it's
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2622 always 95 or higher). Pc is always zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2623 If Pv is 141 or higher then Vim will try to request terminal
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2624 codes. This only works with xterm \|xterm-codes\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2625 {only when compiled with \|+termresponse\| feature}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2626
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2627 v:termblinkresp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2628 v:termblinkresp The escape sequence returned by the terminal for the \|t_RC\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2629 termcap entry. This is used to find out whether the terminal
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2630 cursor is blinking. This is used by \|term_getcursor()\|. When
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2631 this option is set, the TermResponseAll autocommand event is
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2632 fired, with <amatch> set to "cursorblink".
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2633
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2634 v:termstyleresp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2635 v:termstyleresp The escape sequence returned by the terminal for the \|t_RS\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2636 termcap entry. This is used to find out what the shape of the
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2637 cursor is. This is used by \|term_getcursor()\|. When this
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2638 option is set, the TermResponseAll autocommand event is fired,
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2639 with <amatch> set to "cursorshape".
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2640
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2641 v:termrbgresp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2642 v:termrbgresp The escape sequence returned by the terminal for the \|t_RB\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2643 termcap entry. This is used to find out what the terminal
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2644 background color is; see 'background'. When this option is
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2645 set, the TermResponseAll autocommand event is fired, with
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2646 <amatch> set to "background".
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2647
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2648 v:termrfgresp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2649 v:termrfgresp The escape sequence returned by the terminal for the \|t_RF\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2650 termcap entry. This is used to find out what the terminal
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2651 foreground color is. When this option is set, the
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2652 TermResponseAll autocommand event is fired, with <amatch> set
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2653 to "foreground".
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2654
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2655 v:termu7resp
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2656 v:termu7resp The escape sequence returned by the terminal for the \|t_u7\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2657 termcap entry. This is used to find out what the terminal
34132 8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2658 does with ambiguous width characters, see 'ambiwidth'. When
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2659 this option is set, the TermResponseAll autocommand event is
8f94a72dfbed patch 9.1.0029: Cannot act on various terminal response codes Christian Brabandt <cb@256bit.org> parents: 34057 diff changeset	2660 fired, with <amatch> set to "ambiguouswidth".
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2661
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2662 v:testing testing-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2663 v:testing Must be set before using `test_garbagecollect_now()`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2664 Also, when set certain error messages won't be shown for 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2665 seconds. (e.g. "'dictionary' option is empty")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2666
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2667 v:this_session this_session-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2668 v:this_session Full filename of the last loaded or saved session file. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2669 \|:mksession\|. It is allowed to set this variable. When no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2670 session file has been saved, this variable is empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2671 "this_session" also works, for backwards compatibility, unless
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2672 \|scriptversion\| is 3 or higher
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2673
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2674 v:throwpoint throwpoint-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2675 v:throwpoint The point where the exception most recently caught and not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2676 finished was thrown. Not set when commands are typed. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2677 also \|v:exception\| and \|throw-variables\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2678 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2679 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2680 : throw "oops"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2681 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2682 : echo "Exception from" v:throwpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2683 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2684 < Output: "Exception from test.vim, line 2"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2685
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2686 v:true true-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2687 v:true A Number with value one. Used to put "true" in JSON. See
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2688 \|json_encode()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2689 When used as a string this evaluates to "v:true". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2690 echo v:true
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2691 < v:true ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2692 That is so that eval() can parse the string back to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2693 value. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2694 In \|Vim9\| script "true" can be used which has a boolean type.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2695 v:val val-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2696 v:val Value of the current item of a \|List\| or \|Dictionary\|. Only
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2697 valid while evaluating the expression used with \|map()\| and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2698 \|filter()\|. Read-only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2699
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2700 v:version version-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2701 v:version Version number of Vim: Major version number times 100 plus
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2702 minor version number. Version 5.0 is 500. Version 5.1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2703 is 501. Read-only. "version" also works, for backwards
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2704 compatibility, unless \|scriptversion\| is 3 or higher.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2705 Use \|has()\| to check if a certain patch was included, e.g.: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2706 if has("patch-7.4.123")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2707 < Note that patch numbers are specific to the version, thus both
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2708 version 5.0 and 5.1 may have a patch 123, but these are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2709 completely different.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2710
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2711 v:versionlong versionlong-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2712 v:versionlong Like v:version, but also including the patchlevel in the last
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2713 four digits. Version 8.1 with patch 123 has value 8010123.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2714 This can be used like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2715 if v:versionlong >= 8010123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2716 < However, if there are gaps in the list of patches included
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2717 this will not work well. This can happen if a recent patch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2718 was included into an older version, e.g. for a security fix.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2719 Use the has() function to make sure the patch is actually
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2720 included.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2721
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2722 v:vim_did_enter vim_did_enter-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2723 v:vim_did_enter Zero until most of startup is done. It is set to one just
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2724 before \|VimEnter\| autocommands are triggered.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2725
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2726 v:warningmsg warningmsg-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2727 v:warningmsg Last given warning message. It's allowed to set this variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2728
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2729 v:windowid windowid-variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2730 v:windowid When any X11 based GUI is running or when running in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2731 terminal and Vim connects to the X server (\|-X\|) this will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2732 set to the window ID.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2733 When an MS-Windows GUI is running this will be set to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2734 window handle.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2735 Otherwise the value is zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2736 Note: for windows inside Vim use \|winnr()\| or \|win_getid()\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2737 see \|window-ID\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2738
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2739 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2740 4. Builtin Functions functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2741
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2742 See \|function-list\| for a list grouped by what the function is used for.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2743
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2744 The alphabetic list of all builtin functions and details are in a separate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2745 help file: \|builtin-functions\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2746
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2747 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2748 5. Defining functions user-functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2749
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2750 New functions can be defined. These can be called just like builtin
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2751 functions. The function takes arguments, executes a sequence of Ex commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2752 and can return a value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2753
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2754 You can find most information about defining functions in \|userfunc.txt\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2755 For Vim9 functions, which execute much faster, support type checking and more,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2756 see \|vim9.txt\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2757
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2758 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2759 6. Curly braces names curly-braces-names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2760
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2761 In most places where you can use a variable, you can use a "curly braces name"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2762 variable. This is a regular variable name with one or more expressions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2763 wrapped in braces {} like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2764 my_{adjective}_variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2765
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2766 This only works in legacy Vim script, not in \|Vim9\| script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2767
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2768 When Vim encounters this, it evaluates the expression inside the braces, puts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2769 that in place of the expression, and re-interprets the whole as a variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2770 name. So in the above example, if the variable "adjective" was set to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2771 "noisy", then the reference would be to "my_noisy_variable", whereas if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2772 "adjective" was set to "quiet", then it would be to "my_quiet_variable".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2773
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2774 One application for this is to create a set of variables governed by an option
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2775 value. For example, the statement >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2776 echo my_{&background}_message
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2777
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2778 would output the contents of "my_dark_message" or "my_light_message" depending
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2779 on the current value of 'background'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2780
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2781 You can use multiple brace pairs: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2782 echo my_{adverb}_{adjective}_message
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2783 ..or even nest them: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2784 echo my_{ad{end_of_word}}_message
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2785 where "end_of_word" is either "verb" or "jective".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2786
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2787 However, the expression inside the braces must evaluate to a valid single
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2788 variable name, e.g. this is invalid: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2789 :let foo='a + b'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2790 :echo c{foo}d
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2791 .. since the result of expansion is "ca + bd", which is not a variable name.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2792
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2793 curly-braces-function-names
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2794 You can call and define functions by an evaluated name in a similar way.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2795 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2796 :let func_end='whizz'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2797 :call my_func_{func_end}(parameter)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2798
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2799 This would call the function "my_func_whizz(parameter)".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2800
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2801 This does NOT work: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2802 :let i = 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2803 :let @{i} = '' " error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2804 :echo @{i} " error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2805
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2806 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2807 7. Commands expression-commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2808
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2809 Note: in \|Vim9\| script `:let` is not used. `:var` is used for variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2810 declarations and assignments do not use a command. \|vim9-declaration\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2811
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2812 :let {var-name} = {expr1} :let E18
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2813 Set internal variable {var-name} to the result of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2814 expression {expr1}. The variable will get the type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2815 from the {expr}. If {var-name} didn't exist yet, it
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2816 is created.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2817
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2818 :let {var-name}[{idx}] = {expr1} E689 E1141
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2819 Set a list item to the result of the expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2820 {expr1}. {var-name} must refer to a list and {idx}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2821 must be a valid index in that list. For nested list
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2822 the index can be repeated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2823 This cannot be used to add an item to a \|List\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2824 This cannot be used to set a byte in a String. You
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2825 can do that like this: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2826 :let var = var[0:2] .. 'X' .. var[4:]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2827 < When {var-name} is a \|Blob\| then {idx} can be the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2828 length of the blob, in which case one byte is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2829 appended.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2830
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2831 E711 E719 E1165 E1166 E1183
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2832 :let {var-name}[{idx1}:{idx2}] = {expr1} E708 E709 E710
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2833 Set a sequence of items in a \|List\| to the result of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2834 the expression {expr1}, which must be a list with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2835 correct number of items.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2836 {idx1} can be omitted, zero is used instead.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2837 {idx2} can be omitted, meaning the end of the list.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2838 When the selected range of items is partly past the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2839 end of the list, items will be added.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2840
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2841 :let+= :let-= :letstar= :let/= :let%=
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2842 :let.= :let..= E734 E985 E1019
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2843 :let {var} += {expr1} Like ":let {var} = {var} + {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2844 :let {var} -= {expr1} Like ":let {var} = {var} - {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2845 :let {var} = {expr1} Like ":let {var} = {var} {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2846 :let {var} /= {expr1} Like ":let {var} = {var} / {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2847 :let {var} %= {expr1} Like ":let {var} = {var} % {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2848 :let {var} .= {expr1} Like ":let {var} = {var} . {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2849 :let {var} ..= {expr1} Like ":let {var} = {var} .. {expr1}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2850 These fail if {var} was not set yet and when the type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2851 of {var} and {expr1} don't fit the operator.
34293 6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	2852 `+=` modifies a \|List\| or a \|Blob\| in-place instead of
6d00518cb316 runtime(doc): further improve docs about List/Blob += operator Christian Brabandt <cb@256bit.org> parents: 34290 diff changeset	2853 creating a new one.
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2854 `.=` is not supported with Vim script version 2 and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2855 later, see \|vimscript-version\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2856
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2857
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2858 :let ${env-name} = {expr1} :let-environment :let-$
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2859 Set environment variable {env-name} to the result of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2860 the expression {expr1}. The type is always String.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2861
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2862 On some systems making an environment variable empty
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2863 causes it to be deleted. Many systems do not make a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2864 difference between an environment variable that is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2865 set and an environment variable that is empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2866
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2867 :let ${env-name} .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2868 Append {expr1} to the environment variable {env-name}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2869 If the environment variable didn't exist yet this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2870 works like "=".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2871
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2872 :let @{reg-name} = {expr1} :let-register :let-@
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2873 Write the result of the expression {expr1} in register
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2874 {reg-name}. {reg-name} must be a single letter, and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2875 must be the name of a writable register (see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2876 \|registers\|). "@@" can be used for the unnamed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2877 register, "@/" for the search pattern.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2878 If the result of {expr1} ends in a <CR> or <NL>, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2879 register will be linewise, otherwise it will be set to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2880 characterwise.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2881 This can be used to clear the last search pattern: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2882 :let @/ = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2883 < This is different from searching for an empty string,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2884 that would match everywhere.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2885
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2886 :let @{reg-name} .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2887 Append {expr1} to register {reg-name}. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2888 register was empty it's like setting it to {expr1}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2889
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2890 :let &{option-name} = {expr1} :let-option :let-&
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2891 Set option {option-name} to the result of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2892 expression {expr1}. A String or Number value is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2893 always converted to the type of the option.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2894 For an option local to a window or buffer the effect
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2895 is just like using the \|:set\| command: both the local
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2896 value and the global value are changed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2897 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2898 :let &path = &path .. ',/usr/local/include'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2899 < This also works for terminal codes in the form t_xx.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2900 But only for alphanumerical names. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2901 :let &t_k1 = "\<Esc>[234;"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2902 < When the code does not exist yet it will be created as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2903 a terminal key code, there is no error.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2904
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2905 :let &{option-name} .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2906 For a string option: Append {expr1} to the value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2907 Does not insert a comma like \|:set+=\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2908
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2909 :let &{option-name} += {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2910 :let &{option-name} -= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2911 For a number or boolean option: Add or subtract
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2912 {expr1}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2913
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2914 :let &l:{option-name} = {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2915 :let &l:{option-name} .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2916 :let &l:{option-name} += {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2917 :let &l:{option-name} -= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2918 Like above, but only set the local value of an option
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2919 (if there is one). Works like \|:setlocal\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2920
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2921 :let &g:{option-name} = {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2922 :let &g:{option-name} .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2923 :let &g:{option-name} += {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2924 :let &g:{option-name} -= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2925 Like above, but only set the global value of an option
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2926 (if there is one). Works like \|:setglobal\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2927 E1093
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2928 :let [{name1}, {name2}, ...] = {expr1} :let-unpack E687 E688
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2929 {expr1} must evaluate to a \|List\|. The first item in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2930 the list is assigned to {name1}, the second item to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2931 {name2}, etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2932 The number of names must match the number of items in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2933 the \|List\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2934 Each name can be one of the items of the ":let"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2935 command as mentioned above.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2936 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2937 :let [s, item] = GetItem(s)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2938 < Detail: {expr1} is evaluated first, then the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2939 assignments are done in sequence. This matters if
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2940 {name2} depends on {name1}. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2941 :let x = [0, 1]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2942 :let i = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2943 :let [i, x[i]] = [1, 2]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2944 :echo x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2945 < The result is [0, 2].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2946
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2947 :let [{name1}, {name2}, ...] .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2948 :let [{name1}, {name2}, ...] += {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2949 :let [{name1}, {name2}, ...] -= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2950 Like above, but append/add/subtract the value for each
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2951 \|List\| item.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2952
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2953 :let [{name}, ..., ; {lastname}] = {expr1} E452
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2954 Like \|:let-unpack\| above, but the \|List\| may have more
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2955 items than there are names. A list of the remaining
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2956 items is assigned to {lastname}. If there are no
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2957 remaining items {lastname} is set to an empty list.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2958 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2959 :let [a, b; rest] = ["aval", "bval", 3, 4]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2960 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2961 :let [{name}, ..., ; {lastname}] .= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2962 :let [{name}, ..., ; {lastname}] += {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2963 :let [{name}, ..., ; {lastname}] -= {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2964 Like above, but append/add/subtract the value for each
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2965 \|List\| item.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2966
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2967 :let=<< :let-heredoc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2968 E990 E991 E172 E221 E1145
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2969 :let {var-name} =<< [trim] [eval] {endmarker}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2970 text...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2971 text...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2972 {endmarker}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2973 Set internal variable {var-name} to a \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2974 containing the lines of text bounded by the string
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2975 {endmarker}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2976
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2977 If "eval" is not specified, then each line of text is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2978 used as a \|literal-string\|, except that single quotes
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2979 does not need to be doubled.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2980 If "eval" is specified, then any Vim expression in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2981 form {expr} is evaluated and the result replaces the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2982 expression, like with \|interpolated-string\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2983 Example where $HOME is expanded: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2984 let lines =<< trim eval END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2985 some text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2986 See the file {$HOME}/.vimrc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2987 more text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2988 END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2989 < There can be multiple Vim expressions in a single line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2990 but an expression cannot span multiple lines. If any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2991 expression evaluation fails, then the assignment fails.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2992
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2993 {endmarker} must not contain white space.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2994 {endmarker} cannot start with a lower case character.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2995 The last line should end only with the {endmarker}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2996 string without any other character. Watch out for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2997 white space after {endmarker}!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2998
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	2999 Without "trim" any white space characters in the lines
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3000 of text are preserved. If "trim" is specified before
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3001 {endmarker}, then indentation is stripped so you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3002 do: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3003 let text =<< trim END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3004 if ok
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3005 echo 'done'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3006 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3007 END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3008 < Results in: ["if ok", " echo 'done'", "endif"]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3009 The marker must line up with "let" and the indentation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3010 of the first line is removed from all the text lines.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3011 Specifically: all the leading indentation exactly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3012 matching the leading indentation of the first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3013 non-empty text line is stripped from the input lines.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3014 All leading indentation exactly matching the leading
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3015 indentation before `let` is stripped from the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3016 containing {endmarker}. Note that the difference
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3017 between space and tab matters here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3018
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3019 If {var-name} didn't exist yet, it is created.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3020 Cannot be followed by another command, but can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3021 followed by a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3022
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3023 To avoid line continuation to be applied, consider
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3024 adding 'C' to 'cpoptions': >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3025 set cpo+=C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3026 let var =<< END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3027 \ leading backslash
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3028 END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3029 set cpo-=C
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3030 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3031 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3032 let var1 =<< END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3033 Sample text 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3034 Sample text 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3035 Sample text 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3036 END
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3037
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3038 let data =<< trim DATA
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3039 1 2 3 4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3040 5 6 7 8
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3041 DATA
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3042
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3043 let code =<< trim eval CODE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3044 let v = {10 + 20}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3045 let h = "{$HOME}"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3046 let s = "{Str1()} abc {Str2()}"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3047 let n = {MyFunc(3, 4)}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3048 CODE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3049 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3050 E121
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3051 :let {var-name} .. List the value of variable {var-name}. Multiple
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3052 variable names may be given. Special names recognized
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3053 here: E738
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3054 g: global variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3055 b: local buffer variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3056 w: local window variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3057 t: local tab page variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3058 s: script-local variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3059 l: local function variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3060 v: Vim variables.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3061 This does not work in Vim9 script. \|vim9-declaration\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3062
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3063 :let List the values of all variables. The type of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3064 variable is indicated before the value:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3065 <nothing> String
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3066 # Number
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3067 * Funcref
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3068 This does not work in Vim9 script. \|vim9-declaration\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3069
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3070 :unl[et][!] {name} ... :unlet :unl E108 E795 E1081
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3071 Remove the internal variable {name}. Several variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3072 names can be given, they are all removed. The name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3073 may also be a \|List\| or \|Dictionary\| item.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3074 With [!] no error message is given for non-existing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3075 variables.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3076 One or more items from a \|List\| can be removed: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3077 :unlet list[3] " remove fourth item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3078 :unlet list[3:] " remove fourth item to last
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3079 < One item from a \|Dictionary\| can be removed at a time: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3080 :unlet dict['two']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3081 :unlet dict.two
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3082 < This is especially useful to clean up used global
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3083 variables and script-local variables (these are not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3084 deleted when the script ends). Function-local
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3085 variables are automatically deleted when the function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3086 ends.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3087 In \|Vim9\| script variables declared in a function or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3088 script cannot be removed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3089
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3090 :unl[et] ${env-name} ... :unlet-environment :unlet-$
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3091 Remove environment variable {env-name}.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3092 Can mix {name} and ${env-name} in one :unlet command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3093 No error message is given for a non-existing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3094 variable, also without !.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3095 If the system does not support deleting an environment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3096 variable, it is made empty.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3097
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3098 :cons :const E1018
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3099 :cons[t] {var-name} = {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3100 :cons[t] [{name1}, {name2}, ...] = {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3101 :cons[t] [{name}, ..., ; {lastname}] = {expr1}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3102 :cons[t] {var-name} =<< [trim] {marker}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3103 text...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3104 text...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3105 {marker}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3106 Similar to \|:let\|, but additionally lock the variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3107 after setting the value. This is the same as locking
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3108 the variable with \|:lockvar\| just after \|:let\|, thus: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3109 :const x = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3110 < is equivalent to: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3111 :let x = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3112 :lockvar! x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3113 < NOTE: in Vim9 script `:const` works differently, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3114 \|vim9-const\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3115 This is useful if you want to make sure the variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3116 is not modified. If the value is a List or Dictionary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3117 literal then the items also cannot be changed: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3118 const ll = [1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3119 let ll[1] = 5 " Error!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3120 < Nested references are not locked: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3121 let lvar = ['a']
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3122 const lconst = [0, lvar]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3123 let lconst[0] = 2 " Error!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3124 let lconst[1][0] = 'b' " OK
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3125 < E995
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3126 \|:const\| does not allow to for changing a variable: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3127 :let x = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3128 :const x = 2 " Error!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3129 < E996
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3130 Note that environment variables, option values and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3131 register values cannot be used here, since they cannot
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3132 be locked.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3133
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3134 :cons[t]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3135 :cons[t] {var-name}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3136 If no argument is given or only {var-name} is given,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3137 the behavior is the same as \|:let\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3138
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3139 :lockv[ar][!] [depth] {name} ... :lockvar :lockv
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3140 Lock the internal variable {name}. Locking means that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3141 it can no longer be changed (until it is unlocked).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3142 A locked variable can be deleted: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3143 :lockvar v
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3144 :let v = 'asdf' " fails!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3145 :unlet v " works
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3146 < E741 E940 E1118 E1119 E1120 E1121 E1122
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3147 If you try to change a locked variable you get an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3148 error message: "E741: Value is locked: {name}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3149 If you try to lock or unlock a built-in variable you
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3150 get an error message: "E940: Cannot lock or unlock
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3151 variable {name}".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3152
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3153 [depth] is relevant when locking a \|List\| or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3154 \|Dictionary\|. It specifies how deep the locking goes:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3155 0 Lock the variable {name} but not its
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3156 value.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3157 1 Lock the \|List\| or \|Dictionary\| itself,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3158 cannot add or remove items, but can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3159 still change their values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3160 2 Also lock the values, cannot change
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3161 the items. If an item is a \|List\| or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3162 \|Dictionary\|, cannot add or remove
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3163 items, but can still change the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3164 values.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3165 3 Like 2 but for the \|List\| /
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3166 \|Dictionary\| in the \|List\| /
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3167 \|Dictionary\|, one level deeper.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3168 The default [depth] is 2, thus when {name} is a \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3169 or \|Dictionary\| the values cannot be changed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3170
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3171 Example with [depth] 0: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3172 let mylist = [1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3173 lockvar 0 mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3174 let mylist[0] = 77 " OK
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3175 call add(mylist, 4) " OK
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3176 let mylist = [7, 8, 9] " Error!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3177 < E743
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3178 For unlimited depth use [!] and omit [depth].
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3179 However, there is a maximum depth of 100 to catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3180 loops.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3181
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3182 Note that when two variables refer to the same \|List\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3183 and you lock one of them, the \|List\| will also be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3184 locked when used through the other variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3185 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3186 :let l = [0, 1, 2, 3]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3187 :let cl = l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3188 :lockvar l
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3189 :let cl[1] = 99 " won't work!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3190 < You may want to make a copy of a list to avoid this.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3191 See \|deepcopy()\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3192
33436 3f96c75df76d runtime(doc): add missing error numbers in the help. (#13241) Christian Brabandt <cb@256bit.org> parents: 33434 diff changeset	3193 E1391 E1392
3f96c75df76d runtime(doc): add missing error numbers in the help. (#13241) Christian Brabandt <cb@256bit.org> parents: 33434 diff changeset	3194 Locking and unlocking object and class variables is
3f96c75df76d runtime(doc): add missing error numbers in the help. (#13241) Christian Brabandt <cb@256bit.org> parents: 33434 diff changeset	3195 currently NOT supported.
3f96c75df76d runtime(doc): add missing error numbers in the help. (#13241) Christian Brabandt <cb@256bit.org> parents: 33434 diff changeset	3196
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3197
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3198 :unlo[ckvar][!] [depth] {name} ... :unlockvar :unlo E1246
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3199 Unlock the internal variable {name}. Does the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3200 opposite of \|:lockvar\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3201
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3202 If {name} does not exist:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3203 - In \|Vim9\| script an error is given.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3204 - In legacy script this is silently ignored.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3205
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3206 :if {expr1} :if :end :endif :en E171 E579 E580
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3207 :en[dif] Execute the commands until the next matching `:else`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3208 or `:endif` if {expr1} evaluates to non-zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3209 Although the short forms work, it is recommended to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3210 always use `:endif` to avoid confusion and to make
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3211 auto-indenting work properly.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3212
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3213 From Vim version 4.5 until 5.0, every Ex command in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3214 between the `:if` and `:endif` is ignored. These two
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3215 commands were just to allow for future expansions in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3216 backward compatible way. Nesting was allowed. Note
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3217 that any `:else` or `:elseif` was ignored, the `else`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3218 part was not executed either.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3219
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3220 You can use this to remain compatible with older
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3221 versions: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3222 :if version >= 500
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3223 : version-5-specific-commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3224 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3225 < The commands still need to be parsed to find the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3226 `endif`. Sometimes an older Vim has a problem with a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3227 new command. For example, `:silent` is recognized as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3228 a `:substitute` command. In that case `:execute` can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3229 avoid problems: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3230 :if version >= 600
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3231 : execute "silent 1,$delete"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3232 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3233 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3234 In \|Vim9\| script `:endif` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3235 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3236 NOTE: The `:append` and `:insert` commands don't work
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3237 properly in between `:if` and `:endif`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3238
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3239 :else :el E581 E583
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3240 :el[se] Execute the commands until the next matching `:else`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3241 or `:endif` if they previously were not being
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3242 executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3243 In \|Vim9\| script `:else` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3244 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3245
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3246 :elseif :elsei E582 E584
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3247 :elsei[f] {expr1} Short for `:else` `:if`, with the addition that there
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3248 is no extra `:endif`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3249 In \|Vim9\| script `:elseif` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3250 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3251
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3252 :wh[ile] {expr1} :while :endwhile :wh :endw
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3253 E170 E585 E588 E733
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3254 :endw[hile] Repeat the commands between `:while` and `:endwhile`,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3255 as long as {expr1} evaluates to non-zero.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3256 When an error is detected from a command inside the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3257 loop, execution continues after the `endwhile`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3258 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3259 :let lnum = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3260 :while lnum <= line("$")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3261 :call FixLine(lnum)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3262 :let lnum = lnum + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3263 :endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3264 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3265 In \|Vim9\| script `:while` and `:endwhile` cannot be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3266 shortened, to improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3267 NOTE: The `:append` and `:insert` commands don't work
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3268 properly inside a `:while` and `:for` loop.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3269
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3270 :for {var} in {object} :for E690 E732
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3271 :endfo[r] :endfo :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3272 Repeat the commands between `:for` and `:endfor` for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3273 each item in {object}. {object} can be a \|List\|,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3274 a \|Blob\| or a \|String\|. E1177
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3275
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3276 Variable {var} is set to the value of each item.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3277 In \|Vim9\| script the loop variable must not have been
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3278 declared yet, unless when it is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3279 global/window/tab/buffer variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3280
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3281 When an error is detected for a command inside the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3282 loop, execution continues after the `endfor`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3283 Changing {object} inside the loop affects what items
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3284 are used. Make a copy if this is unwanted: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3285 :for item in copy(mylist)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3286 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3287 When {object} is a \|List\| and not making a copy, in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3288 legacy script Vim stores a reference to the next item
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3289 in the \|List\| before executing the commands with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3290 current item. Thus the current item can be removed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3291 without effect. Removing any later item means it will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3292 not be found. Thus the following example works (an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3293 inefficient way to make a \|List\| empty): >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3294 for item in mylist
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3295 call remove(mylist, 0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3296 endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3297 < Note that reordering the \|List\| (e.g., with sort() or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3298 reverse()) may have unexpected effects.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3299 In \|Vim9\| script the index is used. If an item before
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3300 the current one is deleted the next item will be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3301 skipped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3302
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3303 When {object} is a \|Blob\|, Vim always makes a copy to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3304 iterate over. Unlike with \|List\|, modifying the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3305 \|Blob\| does not affect the iteration.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3306
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3307 When {object} is a \|String\| each item is a string with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3308 one character, plus any combining characters.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3309
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3310 In \|Vim9\| script `:endfor` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3311 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3312
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3313 :for [{var1}, {var2}, ...] in {listlist}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3314 :endfo[r] E1140
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3315 Like `:for` above, but each item in {listlist} must be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3316 a list, of which each item is assigned to {var1},
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3317 {var2}, etc. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3318 :for [lnum, col] in [[1, 3], [2, 5], [3, 8]]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3319 :echo getline(lnum)[col]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3320 :endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3321 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3322 :continue :con E586
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3323 :con[tinue] When used inside a `:while` or `:for` loop, jumps back
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3324 to the start of the loop.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3325 If it is used after a `:try` inside the loop but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3326 before the matching `:finally` (if present), the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3327 commands following the `:finally` up to the matching
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3328 `:endtry` are executed first. This process applies to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3329 all nested `:try`s inside the loop. The outermost
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3330 `:endtry` then jumps back to the start of the loop.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3331
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3332 In \|Vim9\| script `:cont` is the shortest form, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3333 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3334 :break :brea E587
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3335 :brea[k] When used inside a `:while` or `:for` loop, skips to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3336 the command after the matching `:endwhile` or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3337 `:endfor`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3338 If it is used after a `:try` inside the loop but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3339 before the matching `:finally` (if present), the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3340 commands following the `:finally` up to the matching
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3341 `:endtry` are executed first. This process applies to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3342 all nested `:try`s inside the loop. The outermost
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3343 `:endtry` then jumps to the command after the loop.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3344
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3345 In \|Vim9\| script `:break` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3346 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3347
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3348 :try :try :endt :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3349 E600 E601 E602 E1032
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3350 :endt[ry] Change the error handling for the commands between
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3351 `:try` and `:endtry` including everything being
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3352 executed across `:source` commands, function calls,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3353 or autocommand invocations.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3354
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3355 When an error or interrupt is detected and there is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3356 a `:finally` command following, execution continues
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3357 after the `:finally`. Otherwise, or when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3358 `:endtry` is reached thereafter, the next
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3359 (dynamically) surrounding `:try` is checked for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3360 a corresponding `:finally` etc. Then the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3361 processing is terminated. Whether a function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3362 definition has an "abort" argument does not matter.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3363 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3364 try \| call Unknown() \| finally \| echomsg "cleanup" \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3365 echomsg "not reached"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3366 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3367 Moreover, an error or interrupt (dynamically) inside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3368 `:try` and `:endtry` is converted to an exception. It
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3369 can be caught as if it were thrown by a `:throw`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3370 command (see `:catch`). In this case, the script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3371 processing is not terminated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3372
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3373 The value "Vim:Interrupt" is used for an interrupt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3374 exception. An error in a Vim command is converted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3375 to a value of the form "Vim({command}):{errmsg}",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3376 other errors are converted to a value of the form
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3377 "Vim:{errmsg}". {command} is the full command name,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3378 and {errmsg} is the message that is displayed if the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3379 error exception is not caught, always beginning with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3380 the error number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3381 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3382 try \| sleep 100 \| catch /^Vim:Interrupt$/ \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3383 try \| edit \| catch /^Vim(edit):E\d\+/ \| echo "error" \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3384 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3385 In \|Vim9\| script `:endtry` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3386 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3387
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3388 :cat :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3389 E603 E604 E605 E654 E1033
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3390 :cat[ch] /{pattern}/ The following commands until the next `:catch`,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3391 `:finally`, or `:endtry` that belongs to the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3392 `:try` as the `:catch` are executed when an exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3393 matching {pattern} is being thrown and has not yet
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3394 been caught by a previous `:catch`. Otherwise, these
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3395 commands are skipped.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3396 When {pattern} is omitted all errors are caught.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3397 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3398 :catch /^Vim:Interrupt$/ " catch interrupts (CTRL-C)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3399 :catch /^Vim\%((\a\+)\)\=:E/ " catch all Vim errors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3400 :catch /^Vim\%((\a\+)\)\=:/ " catch errors and interrupts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3401 :catch /^Vim(write):/ " catch all errors in :write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3402 :catch /^Vim\%((\a\+)\)\=:E123:/ " catch error E123
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3403 :catch /my-exception/ " catch user exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3404 :catch /.*/ " catch everything
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3405 :catch " same as /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3406 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3407 Another character can be used instead of / around the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3408 {pattern}, so long as it does not have a special
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3409 meaning (e.g., '\|' or '"') and doesn't occur inside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3410 {pattern}. E1067
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3411 Information about the exception is available in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3412 \|v:exception\|. Also see \|throw-variables\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3413 NOTE: It is not reliable to ":catch" the TEXT of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3414 an error message because it may vary in different
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3415 locales.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3416 In \|Vim9\| script `:catch` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3417 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3418
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3419 :fina :finally E606 E607
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3420 :fina[lly] The following commands until the matching `:endtry`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3421 are executed whenever the part between the matching
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3422 `:try` and the `:finally` is left: either by falling
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3423 through to the `:finally` or by a `:continue`,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3424 `:break`, `:finish`, or `:return`, or by an error or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3425 interrupt or exception (see `:throw`).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3426
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3427 In \|Vim9\| script `:finally` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3428 improve script readability and avoid confusion with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3429 `:final`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3430
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3431 :th :throw E608 E1129
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3432 :th[row] {expr1} The {expr1} is evaluated and thrown as an exception.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3433 If the ":throw" is used after a `:try` but before the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3434 first corresponding `:catch`, commands are skipped
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3435 until the first `:catch` matching {expr1} is reached.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3436 If there is no such `:catch` or if the ":throw" is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3437 used after a `:catch` but before the `:finally`, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3438 commands following the `:finally` (if present) up to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3439 the matching `:endtry` are executed. If the `:throw`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3440 is after the `:finally`, commands up to the `:endtry`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3441 are skipped. At the ":endtry", this process applies
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3442 again for the next dynamically surrounding `:try`
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3443 (which may be found in a calling function or sourcing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3444 script), until a matching `:catch` has been found.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3445 If the exception is not caught, the command processing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3446 is terminated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3447 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3448 :try \| throw "oops" \| catch /^oo/ \| echo "caught" \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3449 < Note that "catch" may need to be on a separate line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3450 for when an error causes the parsing to skip the whole
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3451 line and not see the "\|" that separates the commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3452
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3453 In \|Vim9\| script `:throw` cannot be shortened, to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3454 improve script readability.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3455
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3456 :ec :echo
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3457 :ec[ho] {expr1} .. Echoes each {expr1}, with a space in between. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3458 first {expr1} starts on a new line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3459 Also see \|:comment\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3460 Use "\n" to start a new line. Use "\r" to move the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3461 cursor to the first column.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3462 Uses the highlighting set by the `:echohl` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3463 Cannot be followed by a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3464 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3465 :echo "the value of 'shell' is" &shell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3466 < :echo-redraw
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3467 A later redraw may make the message disappear again.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3468 And since Vim mostly postpones redrawing until it's
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3469 finished with a sequence of commands this happens
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3470 quite often. To avoid that a command from before the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3471 `:echo` causes a redraw afterwards (redraws are often
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3472 postponed until you type something), force a redraw
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3473 with the `:redraw` command. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3474 :new \| redraw \| echo "there is a new window"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3475 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3476 :echon
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3477 :echon {expr1} .. Echoes each {expr1}, without anything added. Also see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3478 \|:comment\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3479 Uses the highlighting set by the `:echohl` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3480 Cannot be followed by a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3481 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3482 :echon "the value of 'shell' is " &shell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3483 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3484 Note the difference between using `:echo`, which is a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3485 Vim command, and `:!echo`, which is an external shell
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3486 command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3487 :!echo % --> filename
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3488 < The arguments of ":!" are expanded, see \|:_%\|. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3489 :!echo "%" --> filename or "filename"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3490 < Like the previous example. Whether you see the double
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3491 quotes or not depends on your 'shell'. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3492 :echo % --> nothing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3493 < The '%' is an illegal character in an expression. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3494 :echo "%" --> %
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3495 < This just echoes the '%' character. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3496 :echo expand("%") --> filename
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3497 < This calls the expand() function to expand the '%'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3498
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3499 :echoh :echohl
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3500 :echoh[l] {name} Use the highlight group {name} for the following
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3501 `:echo`, `:echon` and `:echomsg` commands. Also used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3502 for the `input()` prompt. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3503 :echohl WarningMsg \| echo "Don't panic!" \| echohl None
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3504 < Don't forget to set the group back to "None",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3505 otherwise all following echo's will be highlighted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3506
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3507 :echom :echomsg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3508 :echom[sg] {expr1} .. Echo the expression(s) as a true message, saving the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3509 message in the \|message-history\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3510 Spaces are placed between the arguments as with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3511 `:echo` command. But unprintable characters are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3512 displayed, not interpreted.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3513 The parsing works slightly different from `:echo`,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3514 more like `:execute`. All the expressions are first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3515 evaluated and concatenated before echoing anything.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3516 If expressions does not evaluate to a Number or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3517 String, string() is used to turn it into a string.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3518 Uses the highlighting set by the `:echohl` command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3519 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3520 :echomsg "It's a Zizzer Zazzer Zuzz, as you can plainly see."
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3521 < See \|:echo-redraw\| to avoid the message disappearing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3522 when the screen is redrawn.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3523
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3524 :echow :echowin :echowindow
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3525 :[N]echow[indow] {expr1} ..
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3526 Like \|:echomsg\| but when the messages popup window is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3527 available the message is displayed there. This means
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3528 it will show for three seconds and avoid a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3529 \|hit-enter\| prompt. If you want to hide it before
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3530 that, press Esc in Normal mode (when it would
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3531 otherwise beep). If it disappears too soon you can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3532 use `:messages` to see the text.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3533 When [N] is given then the window will show up for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3534 this number of seconds. The last `:echowindow` with a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3535 count matters, it is used once only.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3536 The message window is available when Vim was compiled
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3537 with the +timer and the +popupwin features.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3538
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3539 :echoe :echoerr
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3540 :echoe[rr] {expr1} .. Echo the expression(s) as an error message, saving the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3541 message in the \|message-history\|. When used in a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3542 script or function the line number will be added.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3543 Spaces are placed between the arguments as with the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3544 `:echomsg` command. When used inside a try conditional,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3545 the message is raised as an error exception instead
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3546 (see \|try-echoerr\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3547 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3548 :echoerr "This script just failed!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3549 < If you just want a highlighted message use `:echohl`.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3550 And to get a beep: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3551 :exe "normal \<Esc>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3552
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3553 :echoc[onsole] {expr1} .. :echoc :echoconsole
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3554 Intended for testing: works like `:echomsg` but when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3555 running in the GUI and started from a terminal write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3556 the text to stdout.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3557
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3558 :eval
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3559 :eval {expr} Evaluate {expr} and discard the result. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3560 :eval Getlist()->Filter()->append('$')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3561
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3562 < The expression is supposed to have a side effect,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3563 since the resulting value is not used. In the example
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3564 the `append()` call appends the List with text to the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3565 buffer. This is similar to `:call` but works with any
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3566 expression.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3567 In \|Vim9\| script an expression without an effect will
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3568 result in error E1207 . This should help noticing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3569 mistakes.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3570
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3571 The command can be shortened to `:ev` or `:eva`, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3572 these are hard to recognize and therefore not to be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3573 used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3574
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3575 The command cannot be followed by "\|" and another
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3576 command, since "\|" is seen as part of the expression.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3577
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3578
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3579 :exe :execute
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3580 :exe[cute] {expr1} .. Executes the string that results from the evaluation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3581 of {expr1} as an Ex command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3582 Multiple arguments are concatenated, with a space in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3583 between. To avoid the extra space use the ".."
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3584 operator to concatenate strings into one argument.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3585 {expr1} is used as the processed command, command line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3586 editing keys are not recognized.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3587 Cannot be followed by a comment.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3588 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3589 :execute "buffer" nextbuf
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3590 :execute "normal" count .. "w"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3591 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3592 ":execute" can be used to append a command to commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3593 that don't accept a '\|'. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3594 :execute '!ls' \| echo "theend"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3595
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3596 < ":execute" is also a nice way to avoid having to type
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3597 control characters in a Vim script for a ":normal"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3598 command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3599 :execute "normal ixxx\<Esc>"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3600 < This has an <Esc> character, see \|expr-string\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3601
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3602 Be careful to correctly escape special characters in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3603 file names. The \|fnameescape()\| function can be used
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3604 for Vim commands, \|shellescape()\| for \|:!\| commands.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3605 Examples: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3606 :execute "e " .. fnameescape(filename)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3607 :execute "!ls " .. shellescape(filename, 1)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3608 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3609 Note: The executed string may be any command-line, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3610 starting or ending "if", "while" and "for" does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3611 always work, because when commands are skipped the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3612 ":execute" is not evaluated and Vim loses track of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3613 where blocks start and end. Also "break" and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3614 "continue" should not be inside ":execute".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3615 This example does not work, because the ":execute" is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3616 not evaluated and Vim does not see the "while", and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3617 gives an error for finding an ":endwhile": >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3618 :if 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3619 : execute 'while i > 5'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3620 : echo "test"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3621 : endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3622 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3623 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3624 It is allowed to have a "while" or "if" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3625 completely in the executed string: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3626 :execute 'while i < 5 \| echo i \| let i = i + 1 \| endwhile'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3627 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3628
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3629 :exe-comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3630 ":execute", ":echo" and ":echon" cannot be followed by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3631 a comment directly, because they see the '"' as the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3632 start of a string. But, you can use '\|' followed by a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3633 comment. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3634 :echo "foo" \| "this is a comment
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3635
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3636 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3637 8. Exception handling exception-handling
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3638
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3639 The Vim script language comprises an exception handling feature. This section
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3640 explains how it can be used in a Vim script.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3641
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3642 Exceptions may be raised by Vim on an error or on interrupt, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3643 \|catch-errors\| and \|catch-interrupt\|. You can also explicitly throw an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3644 exception by using the ":throw" command, see \|throw-catch\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3645
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3646
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3647 TRY CONDITIONALS try-conditionals
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3648
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3649 Exceptions can be caught or can cause cleanup code to be executed. You can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3650 use a try conditional to specify catch clauses (that catch exceptions) and/or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3651 a finally clause (to be executed for cleanup).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3652 A try conditional begins with a \|:try\| command and ends at the matching
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3653 \|:endtry\| command. In between, you can use a \|:catch\| command to start
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3654 a catch clause, or a \|:finally\| command to start a finally clause. There may
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3655 be none or multiple catch clauses, but there is at most one finally clause,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3656 which must not be followed by any catch clauses. The lines before the catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3657 clauses and the finally clause is called a try block. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3658
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3659 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3660 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3661 : ... TRY BLOCK
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3662 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3663 :catch /{pattern}/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3664 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3665 : ... CATCH CLAUSE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3666 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3667 :catch /{pattern}/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3668 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3669 : ... CATCH CLAUSE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3670 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3671 :finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3672 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3673 : ... FINALLY CLAUSE
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3674 : ...
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3675 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3676
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3677 The try conditional allows to watch code for exceptions and to take the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3678 appropriate actions. Exceptions from the try block may be caught. Exceptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3679 from the try block and also the catch clauses may cause cleanup actions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3680 When no exception is thrown during execution of the try block, the control
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3681 is transferred to the finally clause, if present. After its execution, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3682 script continues with the line following the ":endtry".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3683 When an exception occurs during execution of the try block, the remaining
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3684 lines in the try block are skipped. The exception is matched against the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3685 patterns specified as arguments to the ":catch" commands. The catch clause
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3686 after the first matching ":catch" is taken, other catch clauses are not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3687 executed. The catch clause ends when the next ":catch", ":finally", or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3688 ":endtry" command is reached - whatever is first. Then, the finally clause
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3689 (if present) is executed. When the ":endtry" is reached, the script execution
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3690 continues in the following line as usual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3691 When an exception that does not match any of the patterns specified by the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3692 ":catch" commands is thrown in the try block, the exception is not caught by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3693 that try conditional and none of the catch clauses is executed. Only the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3694 finally clause, if present, is taken. The exception pends during execution of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3695 the finally clause. It is resumed at the ":endtry", so that commands after
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3696 the ":endtry" are not executed and the exception might be caught elsewhere,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3697 see \|try-nesting\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3698 When during execution of a catch clause another exception is thrown, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3699 remaining lines in that catch clause are not executed. The new exception is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3700 not matched against the patterns in any of the ":catch" commands of the same
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3701 try conditional and none of its catch clauses is taken. If there is, however,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3702 a finally clause, it is executed, and the exception pends during its
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3703 execution. The commands following the ":endtry" are not executed. The new
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3704 exception might, however, be caught elsewhere, see \|try-nesting\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3705 When during execution of the finally clause (if present) an exception is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3706 thrown, the remaining lines in the finally clause are skipped. If the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3707 clause has been taken because of an exception from the try block or one of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3708 catch clauses, the original (pending) exception is discarded. The commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3709 following the ":endtry" are not executed, and the exception from the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3710 clause is propagated and can be caught elsewhere, see \|try-nesting\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3712 The finally clause is also executed, when a ":break" or ":continue" for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3713 a ":while" loop enclosing the complete try conditional is executed from the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3714 try block or a catch clause. Or when a ":return" or ":finish" is executed
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3715 from the try block or a catch clause of a try conditional in a function or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3716 sourced script, respectively. The ":break", ":continue", ":return", or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3717 ":finish" pends during execution of the finally clause and is resumed when the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3718 ":endtry" is reached. It is, however, discarded when an exception is thrown
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3719 from the finally clause.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3720 When a ":break" or ":continue" for a ":while" loop enclosing the complete
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3721 try conditional or when a ":return" or ":finish" is encountered in the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3722 clause, the rest of the finally clause is skipped, and the ":break",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3723 ":continue", ":return" or ":finish" is executed as usual. If the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3724 clause has been taken because of an exception or an earlier ":break",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3725 ":continue", ":return", or ":finish" from the try block or a catch clause,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3726 this pending exception or command is discarded.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3727
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3728 For examples see \|throw-catch\| and \|try-finally\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3729
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3730
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3731 NESTING OF TRY CONDITIONALS try-nesting
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3732
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3733 Try conditionals can be nested arbitrarily. That is, a complete try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3734 conditional can be put into the try block, a catch clause, or the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3735 clause of another try conditional. If the inner try conditional does not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3736 catch an exception thrown in its try block or throws a new exception from one
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3737 of its catch clauses or its finally clause, the outer try conditional is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3738 checked according to the rules above. If the inner try conditional is in the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3739 try block of the outer try conditional, its catch clauses are checked, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3740 otherwise only the finally clause is executed. It does not matter for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3741 nesting, whether the inner try conditional is directly contained in the outer
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3742 one, or whether the outer one sources a script or calls a function containing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3743 the inner try conditional.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3744
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3745 When none of the active try conditionals catches an exception, just their
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3746 finally clauses are executed. Thereafter, the script processing terminates.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3747 An error message is displayed in case of an uncaught exception explicitly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3748 thrown by a ":throw" command. For uncaught error and interrupt exceptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3749 implicitly raised by Vim, the error message(s) or interrupt message are shown
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3750 as usual.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3751
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3752 For examples see \|throw-catch\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3753
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3754
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3755 EXAMINING EXCEPTION HANDLING CODE except-examine
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3756
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3757 Exception handling code can get tricky. If you are in doubt what happens, set
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3758 'verbose' to 13 or use the ":13verbose" command modifier when sourcing your
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3759 script file. Then you see when an exception is thrown, discarded, caught, or
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3760 finished. When using a verbosity level of at least 14, things pending in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3761 a finally clause are also shown. This information is also given in debug mode
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3762 (see \|debug-scripts\|).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3763
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3764
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3765 THROWING AND CATCHING EXCEPTIONS throw-catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3766
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3767 You can throw any number or string as an exception. Use the \|:throw\| command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3768 and pass the value to be thrown as argument: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3769 :throw 4711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3770 :throw "string"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3771 < throw-expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3772 You can also specify an expression argument. The expression is then evaluated
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3773 first, and the result is thrown: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3774 :throw 4705 + strlen("string")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3775 :throw strpart("strings", 0, 6)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3776
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3777 An exception might be thrown during evaluation of the argument of the ":throw"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3778 command. Unless it is caught there, the expression evaluation is abandoned.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3779 The ":throw" command then does not throw a new exception.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3780 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3781
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3782 :function! Foo(arg)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3783 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3784 : throw a:arg
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3785 : catch /foo/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3786 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3787 : return 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3788 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3789 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3790 :function! Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3791 : echo "in Bar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3792 : return 4710
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3793 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3794 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3795 :throw Foo("arrgh") + Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3796
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3797 This throws "arrgh", and "in Bar" is not displayed since Bar() is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3798 executed. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3799 :throw Foo("foo") + Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3800 however displays "in Bar" and throws 4711.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3801
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3802 Any other command that takes an expression as argument might also be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3803 abandoned by an (uncaught) exception during the expression evaluation. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3804 exception is then propagated to the caller of the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3805 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3806
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3807 :if Foo("arrgh")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3808 : echo "then"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3809 :else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3810 : echo "else"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3811 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3812
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3813 Here neither of "then" or "else" is displayed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3814
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3815 catch-order
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3816 Exceptions can be caught by a try conditional with one or more \|:catch\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3817 commands, see \|try-conditionals\|. The values to be caught by each ":catch"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3818 command can be specified as a pattern argument. The subsequent catch clause
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3819 gets executed when a matching exception is caught.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3820 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3821
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3822 :function! Foo(value)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3823 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3824 : throw a:value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3825 : catch /^\d\+$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3826 : echo "Number thrown"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3827 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3828 : echo "String thrown"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3829 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3830 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3831 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3832 :call Foo(0x1267)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3833 :call Foo('string')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3834
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3835 The first call to Foo() displays "Number thrown", the second "String thrown".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3836 An exception is matched against the ":catch" commands in the order they are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3837 specified. Only the first match counts. So you should place the more
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3838 specific ":catch" first. The following order does not make sense: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3839
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3840 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3841 : echo "String thrown"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3842 : catch /^\d\+$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3843 : echo "Number thrown"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3844
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3845 The first ":catch" here matches always, so that the second catch clause is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3846 never taken.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3847
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3848 throw-variables
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3849 If you catch an exception by a general pattern, you may access the exact value
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3850 in the variable \|v:exception\|: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3851
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3852 : catch /^\d\+$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3853 : echo "Number thrown. Value is" v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3854
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3855 You may also be interested where an exception was thrown. This is stored in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3856 \|v:throwpoint\|. Note that "v:exception" and "v:throwpoint" are valid for the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3857 exception most recently caught as long it is not finished.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3858 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3859
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3860 :function! Caught()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3861 : if v:exception != ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3862 : echo 'Caught "' . v:exception .. '" in ' .. v:throwpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3863 : else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3864 : echo 'Nothing caught'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3865 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3866 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3867 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3868 :function! Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3869 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3870 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3871 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3872 : throw 4711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3873 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3874 : call Caught()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3875 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3876 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3877 : call Caught()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3878 : throw "oops"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3879 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3880 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3881 : call Caught()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3882 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3883 : call Caught()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3884 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3885 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3886 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3887 :call Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3888
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3889 This displays >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3890
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3891 Nothing caught
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3892 Caught "4711" in function Foo, line 4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3893 Caught "oops" in function Foo, line 10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3894 Nothing caught
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3895
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3896 A practical example: The following command ":LineNumber" displays the line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3897 number in the script or function where it has been used: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3898
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3899 :function! LineNumber()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3900 : return substitute(v:throwpoint, '.\D$\d\+$.', '\1', "")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3901 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3902 :command! LineNumber try \| throw "" \| catch \| echo LineNumber() \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3903 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3904 try-nested
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3905 An exception that is not caught by a try conditional can be caught by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3906 a surrounding try conditional: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3907
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3908 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3909 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3910 : throw "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3911 : catch /foobar/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3912 : echo "foobar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3913 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3914 : echo "inner finally"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3915 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3916 :catch /foo/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3917 : echo "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3918 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3919
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3920 The inner try conditional does not catch the exception, just its finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3921 clause is executed. The exception is then caught by the outer try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3922 conditional. The example displays "inner finally" and then "foo".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3923
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3924 throw-from-catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3925 You can catch an exception and throw a new one to be caught elsewhere from the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3926 catch clause: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3927
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3928 :function! Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3929 : throw "foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3930 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3931 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3932 :function! Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3933 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3934 : call Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3935 : catch /foo/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3936 : echo "Caught foo, throw bar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3937 : throw "bar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3938 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3939 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3940 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3941 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3942 : call Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3943 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3944 : echo "Caught" v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3945 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3946
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3947 This displays "Caught foo, throw bar" and then "Caught bar".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3948
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3949 rethrow
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3950 There is no real rethrow in the Vim script language, but you may throw
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3951 "v:exception" instead: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3952
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3953 :function! Bar()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3954 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3955 : call Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3956 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3957 : echo "Rethrow" v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3958 : throw v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3959 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3960 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3961 < try-echoerr
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3962 Note that this method cannot be used to "rethrow" Vim error or interrupt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3963 exceptions, because it is not possible to fake Vim internal exceptions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3964 Trying so causes an error exception. You should throw your own exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3965 denoting the situation. If you want to cause a Vim error exception containing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3966 the original error exception value, you can use the \|:echoerr\| command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3967
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3968 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3969 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3970 : asdf
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3971 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3972 : echoerr v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3973 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3974 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3975 : echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3976 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3977
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3978 This code displays
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3979
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3980 Vim(echoerr):Vim:E492: Not an editor command: asdf ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3981
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3982
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3983 CLEANUP CODE try-finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3984
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3985 Scripts often change global settings and restore them at their end. If the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3986 user however interrupts the script by pressing CTRL-C, the settings remain in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3987 an inconsistent state. The same may happen to you in the development phase of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3988 a script when an error occurs or you explicitly throw an exception without
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3989 catching it. You can solve these problems by using a try conditional with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3990 a finally clause for restoring the settings. Its execution is guaranteed on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3991 normal control flow, on error, on an explicit ":throw", and on interrupt.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3992 (Note that errors and interrupts from inside the try conditional are converted
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3993 to exceptions. When not caught, they terminate the script after the finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3994 clause has been executed.)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3995 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3996
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3997 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3998 : let s:saved_ts = &ts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	3999 : set ts=17
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4000 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4001 : " Do the hard work here.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4002 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4003 :finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4004 : let &ts = s:saved_ts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4005 : unlet s:saved_ts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4006 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4007
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4008 This method should be used locally whenever a function or part of a script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4009 changes global settings which need to be restored on failure or normal exit of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4010 that function or script part.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4011
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4012 break-finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4013 Cleanup code works also when the try block or a catch clause is left by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4014 a ":continue", ":break", ":return", or ":finish".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4015 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4016
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4017 :let first = 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4018 :while 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4019 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4020 : if first
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4021 : echo "first"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4022 : let first = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4023 : continue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4024 : else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4025 : throw "second"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4026 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4027 : catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4028 : echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4029 : break
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4030 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4031 : echo "cleanup"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4032 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4033 : echo "still in while"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4034 :endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4035 :echo "end"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4036
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4037 This displays "first", "cleanup", "second", "cleanup", and "end". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4038
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4039 :function! Foo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4040 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4041 : return 4711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4042 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4043 : echo "cleanup\n"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4044 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4045 : echo "Foo still active"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4046 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4047 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4048 :echo Foo() "returned by Foo"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4049
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4050 This displays "cleanup" and "4711 returned by Foo". You don't need to add an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4051 extra ":return" in the finally clause. (Above all, this would override the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4052 return value.)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4053
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4054 except-from-finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4055 Using either of ":continue", ":break", ":return", ":finish", or ":throw" in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4056 a finally clause is possible, but not recommended since it abandons the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4057 cleanup actions for the try conditional. But, of course, interrupt and error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4058 exceptions might get raised from a finally clause.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4059 Example where an error in the finally clause stops an interrupt from
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4060 working correctly: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4061
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4062 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4063 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4064 : echo "Press CTRL-C for interrupt"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4065 : while 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4066 : endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4067 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4068 : unlet novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4069 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4070 :catch /novar/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4071 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4072 :echo "Script still running"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4073 :sleep 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4074
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4075 If you need to put commands that could fail into a finally clause, you should
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4076 think about catching or ignoring the errors in these commands, see
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4077 \|catch-errors\| and \|ignore-errors\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4078
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4079
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4080 CATCHING ERRORS catch-errors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4081
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4082 If you want to catch specific errors, you just have to put the code to be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4083 watched in a try block and add a catch clause for the error message. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4084 presence of the try conditional causes all errors to be converted to an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4085 exception. No message is displayed and \|v:errmsg\| is not set then. To find
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4086 the right pattern for the ":catch" command, you have to know how the format of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4087 the error exception is.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4088 Error exceptions have the following format: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4089
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4090 Vim({cmdname}):{errmsg}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4091 or >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4092 Vim:{errmsg}
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4093
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4094 {cmdname} is the name of the command that failed; the second form is used when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4095 the command name is not known. {errmsg} is the error message usually produced
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4096 when the error occurs outside try conditionals. It always begins with
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4097 a capital "E", followed by a two or three-digit error number, a colon, and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4098 a space.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4099
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4100 Examples:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4101
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4102 The command >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4103 :unlet novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4104 normally produces the error message >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4105 E108: No such variable: "novar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4106 which is converted inside try conditionals to an exception >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4107 Vim(unlet):E108: No such variable: "novar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4108
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4109 The command >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4110 :dwim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4111 normally produces the error message >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4112 E492: Not an editor command: dwim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4113 which is converted inside try conditionals to an exception >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4114 Vim:E492: Not an editor command: dwim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4115
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4116 You can catch all ":unlet" errors by a >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4117 :catch /^Vim(unlet):/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4118 or all errors for misspelled command names by a >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4119 :catch /^Vim:E492:/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4120
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4121 Some error messages may be produced by different commands: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4122 :function nofunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4123 and >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4124 :delfunction nofunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4125 both produce the error message >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4126 E128: Function name must start with a capital: nofunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4127 which is converted inside try conditionals to an exception >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4128 Vim(function):E128: Function name must start with a capital: nofunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4129 or >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4130 Vim(delfunction):E128: Function name must start with a capital: nofunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4131 respectively. You can catch the error by its number independently on the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4132 command that caused it if you use the following pattern: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4133 :catch /^Vim(\a\+):E128:/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4134
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4135 Some commands like >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4136 :let x = novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4137 produce multiple error messages, here: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4138 E121: Undefined variable: novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4139 E15: Invalid expression: novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4140 Only the first is used for the exception value, since it is the most specific
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4141 one (see \|except-several-errors\|). So you can catch it by >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4142 :catch /^Vim(\a\+):E121:/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4143
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4144 You can catch all errors related to the name "nofunc" by >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4145 :catch /\<nofunc\>/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4146
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4147 You can catch all Vim errors in the ":write" and ":read" commands by >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4148 :catch /^Vim($write\\|read$):E\d\+:/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4149
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4150 You can catch all Vim errors by the pattern >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4151 :catch /^Vim$(\a\+)$\=:E\d\+:/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4152 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4153 catch-text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4154 NOTE: You should never catch the error message text itself: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4155 :catch /No such variable/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4156 only works in the English locale, but not when the user has selected
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4157 a different language by the \|:language\| command. It is however helpful to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4158 cite the message text in a comment: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4159 :catch /^Vim(\a\+):E108:/ " No such variable
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4160
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4161
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4162 IGNORING ERRORS ignore-errors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4163
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4164 You can ignore errors in a specific Vim command by catching them locally: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4165
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4166 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4167 : write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4168 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4169 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4170
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4171 But you are strongly recommended NOT to use this simple form, since it could
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4172 catch more than you want. With the ":write" command, some autocommands could
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4173 be executed and cause errors not related to writing, for instance: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4174
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4175 :au BufWritePre * unlet novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4176
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4177 There could even be such errors you are not responsible for as a script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4178 writer: a user of your script might have defined such autocommands. You would
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4179 then hide the error from the user.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4180 It is much better to use >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4181
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4182 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4183 : write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4184 :catch /^Vim(write):/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4185 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4186
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4187 which only catches real write errors. So catch only what you'd like to ignore
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4188 intentionally.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4189
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4190 For a single command that does not cause execution of autocommands, you could
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4191 even suppress the conversion of errors to exceptions by the ":silent!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4192 command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4193 :silent! nunmap k
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4194 This works also when a try conditional is active.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4195
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4196
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4197 CATCHING INTERRUPTS catch-interrupt
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4198
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4199 When there are active try conditionals, an interrupt (CTRL-C) is converted to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4200 the exception "Vim:Interrupt". You can catch it like every exception. The
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4201 script is not terminated, then.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4202 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4203
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4204 :function! TASK1()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4205 : sleep 10
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4206 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4207
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4208 :function! TASK2()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4209 : sleep 20
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4210 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4211
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4212 :while 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4213 : let command = input("Type a command: ")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4214 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4215 : if command == ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4216 : continue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4217 : elseif command == "END"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4218 : break
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4219 : elseif command == "TASK1"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4220 : call TASK1()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4221 : elseif command == "TASK2"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4222 : call TASK2()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4223 : else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4224 : echo "\nIllegal command:" command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4225 : continue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4226 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4227 : catch /^Vim:Interrupt$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4228 : echo "\nCommand interrupted"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4229 : " Caught the interrupt. Continue with next prompt.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4230 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4231 :endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4232
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4233 You can interrupt a task here by pressing CTRL-C; the script then asks for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4234 a new command. If you press CTRL-C at the prompt, the script is terminated.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4235
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4236 For testing what happens when CTRL-C would be pressed on a specific line in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4237 your script, use the debug mode and execute the \|>quit\| or \|>interrupt\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4238 command on that line. See \|debug-scripts\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4239
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4240
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4241 CATCHING ALL catch-all
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4242
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4243 The commands >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4244
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4245 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4246 :catch //
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4247 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4248
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4249 catch everything, error exceptions, interrupt exceptions and exceptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4250 explicitly thrown by the \|:throw\| command. This is useful at the top level of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4251 a script in order to catch unexpected things.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4252 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4253
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4254 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4255 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4256 : " do the hard work here
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4257 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4258 :catch /MyException/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4259 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4260 : " handle known problem
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4261 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4262 :catch /^Vim:Interrupt$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4263 : echo "Script interrupted"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4264 :catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4265 : echo "Internal error (" .. v:exception .. ")"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4266 : echo " - occurred at " .. v:throwpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4267 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4268 :" end of script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4269
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4270 Note: Catching all might catch more things than you want. Thus, you are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4271 strongly encouraged to catch only for problems that you can really handle by
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4272 specifying a pattern argument to the ":catch".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4273 Example: Catching all could make it nearly impossible to interrupt a script
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4274 by pressing CTRL-C: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4275
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4276 :while 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4277 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4278 : sleep 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4279 : catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4280 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4281 :endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4282
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4283
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4284 EXCEPTIONS AND AUTOCOMMANDS except-autocmd
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4285
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4286 Exceptions may be used during execution of autocommands. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4287
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4288 :autocmd User x try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4289 :autocmd User x throw "Oops!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4290 :autocmd User x catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4291 :autocmd User x echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4292 :autocmd User x endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4293 :autocmd User x throw "Arrgh!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4294 :autocmd User x echo "Should not be displayed"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4295 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4296 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4297 : doautocmd User x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4298 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4299 : echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4300 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4301
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4302 This displays "Oops!" and "Arrgh!".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4303
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4304 except-autocmd-Pre
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4305 For some commands, autocommands get executed before the main action of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4306 command takes place. If an exception is thrown and not caught in the sequence
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4307 of autocommands, the sequence and the command that caused its execution are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4308 abandoned and the exception is propagated to the caller of the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4309 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4310
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4311 :autocmd BufWritePre * throw "FAIL"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4312 :autocmd BufWritePre * echo "Should not be displayed"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4313 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4314 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4315 : write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4316 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4317 : echo "Caught:" v:exception "from" v:throwpoint
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4318 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4319
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4320 Here, the ":write" command does not write the file currently being edited (as
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4321 you can see by checking 'modified'), since the exception from the BufWritePre
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4322 autocommand abandons the ":write". The exception is then caught and the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4323 script displays: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4324
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4325 Caught: FAIL from BufWrite Auto commands for "*"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4326 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4327 except-autocmd-Post
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4328 For some commands, autocommands get executed after the main action of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4329 command has taken place. If this main action fails and the command is inside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4330 an active try conditional, the autocommands are skipped and an error exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4331 is thrown that can be caught by the caller of the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4332 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4333
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4334 :autocmd BufWritePost * echo "File successfully written!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4335 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4336 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4337 : write /i/m/p/o/s/s/i/b/l/e
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4338 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4339 : echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4340 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4341
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4342 This just displays: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4343
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4344 Vim(write):E212: Can't open file for writing (/i/m/p/o/s/s/i/b/l/e)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4345
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4346 If you really need to execute the autocommands even when the main action
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4347 fails, trigger the event from the catch clause.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4348 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4349
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4350 :autocmd BufWritePre * set noreadonly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4351 :autocmd BufWritePost * set readonly
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4352 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4353 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4354 : write /i/m/p/o/s/s/i/b/l/e
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4355 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4356 : doautocmd BufWritePost /i/m/p/o/s/s/i/b/l/e
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4357 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4358 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4359 You can also use ":silent!": >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4360
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4361 :let x = "ok"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4362 :let v:errmsg = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4363 :autocmd BufWritePost * if v:errmsg != ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4364 :autocmd BufWritePost * let x = "after fail"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4365 :autocmd BufWritePost * endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4366 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4367 : silent! write /i/m/p/o/s/s/i/b/l/e
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4368 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4369 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4370 :echo x
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4371
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4372 This displays "after fail".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4373
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4374 If the main action of the command does not fail, exceptions from the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4375 autocommands will be catchable by the caller of the command: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4376
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4377 :autocmd BufWritePost * throw ":-("
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4378 :autocmd BufWritePost * echo "Should not be displayed"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4379 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4380 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4381 : write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4382 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4383 : echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4384 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4385 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4386 except-autocmd-Cmd
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4387 For some commands, the normal action can be replaced by a sequence of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4388 autocommands. Exceptions from that sequence will be catchable by the caller
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4389 of the command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4390 Example: For the ":write" command, the caller cannot know whether the file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4391 had actually been written when the exception occurred. You need to tell it in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4392 some way. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4393
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4394 :if !exists("cnt")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4395 : let cnt = 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4396 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4397 : autocmd BufWriteCmd * if &modified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4398 : autocmd BufWriteCmd * let cnt = cnt + 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4399 : autocmd BufWriteCmd * if cnt % 3 == 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4400 : autocmd BufWriteCmd * throw "BufWriteCmdError"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4401 : autocmd BufWriteCmd * endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4402 : autocmd BufWriteCmd * write \| set nomodified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4403 : autocmd BufWriteCmd * if cnt % 3 == 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4404 : autocmd BufWriteCmd * throw "BufWriteCmdError"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4405 : autocmd BufWriteCmd * endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4406 : autocmd BufWriteCmd * echo "File successfully written!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4407 : autocmd BufWriteCmd * endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4408 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4409 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4410 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4411 : write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4412 :catch /^BufWriteCmdError$/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4413 : if &modified
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4414 : echo "Error on writing (file contents not changed)"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4415 : else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4416 : echo "Error after writing"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4417 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4418 :catch /^Vim(write):/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4419 : echo "Error on writing"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4420 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4421
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4422 When this script is sourced several times after making changes, it displays
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4423 first >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4424 File successfully written!
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4425 then >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4426 Error on writing (file contents not changed)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4427 then >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4428 Error after writing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4429 etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4430
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4431 except-autocmd-ill
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4432 You cannot spread a try conditional over autocommands for different events.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4433 The following code is ill-formed: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4434
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4435 :autocmd BufWritePre * try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4436 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4437 :autocmd BufWritePost * catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4438 :autocmd BufWritePost * echo v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4439 :autocmd BufWritePost * endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4440 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4441 :write
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4442
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4443
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4444 EXCEPTION HIERARCHIES AND PARAMETERIZED EXCEPTIONS except-hier-param
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4445
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4446 Some programming languages allow to use hierarchies of exception classes or to
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4447 pass additional information with the object of an exception class. You can do
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4448 similar things in Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4449 In order to throw an exception from a hierarchy, just throw the complete
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4450 class name with the components separated by a colon, for instance throw the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4451 string "EXCEPT:MATHERR:OVERFLOW" for an overflow in a mathematical library.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4452 When you want to pass additional information with your exception class, add
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4453 it in parentheses, for instance throw the string "EXCEPT:IO:WRITEERR(myfile)"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4454 for an error when writing "myfile".
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4455 With the appropriate patterns in the ":catch" command, you can catch for
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4456 base classes or derived classes of your hierarchy. Additional information in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4457 parentheses can be cut out from \|v:exception\| with the ":substitute" command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4458 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4459
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4460 :function! CheckRange(a, func)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4461 : if a:a < 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4462 : throw "EXCEPT:MATHERR:RANGE(" .. a:func .. ")"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4463 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4464 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4465 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4466 :function! Add(a, b)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4467 : call CheckRange(a:a, "Add")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4468 : call CheckRange(a:b, "Add")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4469 : let c = a:a + a:b
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4470 : if c < 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4471 : throw "EXCEPT:MATHERR:OVERFLOW"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4472 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4473 : return c
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4474 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4475 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4476 :function! Div(a, b)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4477 : call CheckRange(a:a, "Div")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4478 : call CheckRange(a:b, "Div")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4479 : if (a:b == 0)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4480 : throw "EXCEPT:MATHERR:ZERODIV"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4481 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4482 : return a:a / a:b
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4483 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4484 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4485 :function! Write(file)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4486 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4487 : execute "write" fnameescape(a:file)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4488 : catch /^Vim(write):/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4489 : throw "EXCEPT:IO(" .. getcwd() .. ", " .. a:file .. "):WRITEERR"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4490 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4491 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4492 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4493 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4494 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4495 : " something with arithmetic and I/O
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4496 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4497 :catch /^EXCEPT:MATHERR:RANGE/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4498 : let function = substitute(v:exception, '.($\a\+$).', '\1', "")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4499 : echo "Range error in" function
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4500 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4501 :catch /^EXCEPT:MATHERR/ " catches OVERFLOW and ZERODIV
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4502 : echo "Math error"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4503 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4504 :catch /^EXCEPT:IO/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4505 : let dir = substitute(v:exception, '.($.\+$,\s.\+).*', '\1', "")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4506 : let file = substitute(v:exception, '.(.\+,\s$.\+$).*', '\1', "")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4507 : if file !~ '^/'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4508 : let file = dir .. "/" .. file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4509 : endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4510 : echo 'I/O error for "' .. file .. '"'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4511 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4512 :catch /^EXCEPT/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4513 : echo "Unspecified error"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4514 :
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4515 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4516
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4517 The exceptions raised by Vim itself (on error or when pressing CTRL-C) use
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4518 a flat hierarchy: they are all in the "Vim" class. You cannot throw yourself
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4519 exceptions with the "Vim" prefix; they are reserved for Vim.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4520 Vim error exceptions are parameterized with the name of the command that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4521 failed, if known. See \|catch-errors\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4522
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4523
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4524 PECULIARITIES
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4525 except-compat
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4526 The exception handling concept requires that the command sequence causing the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4527 exception is aborted immediately and control is transferred to finally clauses
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4528 and/or a catch clause.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4529
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4530 In the Vim script language there are cases where scripts and functions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4531 continue after an error: in functions without the "abort" flag or in a command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4532 after ":silent!", control flow goes to the following line, and outside
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4533 functions, control flow goes to the line following the outermost ":endwhile"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4534 or ":endif". On the other hand, errors should be catchable as exceptions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4535 (thus, requiring the immediate abortion).
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4536
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4537 This problem has been solved by converting errors to exceptions and using
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4538 immediate abortion (if not suppressed by ":silent!") only when a try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4539 conditional is active. This is no restriction since an (error) exception can
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4540 be caught only from an active try conditional. If you want an immediate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4541 termination without catching the error, just use a try conditional without
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4542 catch clause. (You can cause cleanup code being executed before termination
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4543 by specifying a finally clause.)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4544
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4545 When no try conditional is active, the usual abortion and continuation
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4546 behavior is used instead of immediate abortion. This ensures compatibility of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4547 scripts written for Vim 6.1 and earlier.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4548
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4549 However, when sourcing an existing script that does not use exception handling
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4550 commands (or when calling one of its functions) from inside an active try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4551 conditional of a new script, you might change the control flow of the existing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4552 script on error. You get the immediate abortion on error and can catch the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4553 error in the new script. If however the sourced script suppresses error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4554 messages by using the ":silent!" command (checking for errors by testing
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4555 \|v:errmsg\| if appropriate), its execution path is not changed. The error is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4556 not converted to an exception. (See \|:silent\|.) So the only remaining cause
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4557 where this happens is for scripts that don't care about errors and produce
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4558 error messages. You probably won't want to use such code from your new
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4559 scripts.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4560
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4561 except-syntax-err
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4562 Syntax errors in the exception handling commands are never caught by any of
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4563 the ":catch" commands of the try conditional they belong to. Its finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4564 clauses, however, is executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4565 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4566
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4567 :try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4568 : try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4569 : throw 4711
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4570 : catch /\(/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4571 : echo "in catch with syntax error"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4572 : catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4573 : echo "inner catch-all"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4574 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4575 : echo "inner finally"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4576 : endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4577 :catch
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4578 : echo 'outer catch-all caught "' .. v:exception .. '"'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4579 : finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4580 : echo "outer finally"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4581 :endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4582
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4583 This displays: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4584 inner finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4585 outer catch-all caught "Vim(catch):E54: Unmatched \("
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4586 outer finally
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4587 The original exception is discarded and an error exception is raised, instead.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4588
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4589 except-single-line
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4590 The ":try", ":catch", ":finally", and ":endtry" commands can be put on
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4591 a single line, but then syntax errors may make it difficult to recognize the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4592 "catch" line, thus you better avoid this.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4593 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4594 :try \| unlet! foo # \| catch \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4595 raises an error exception for the trailing characters after the ":unlet!"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4596 argument, but does not see the ":catch" and ":endtry" commands, so that the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4597 error exception is discarded and the "E488: Trailing characters" message gets
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4598 displayed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4599
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4600 except-several-errors
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4601 When several errors appear in a single command, the first error message is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4602 usually the most specific one and therefore converted to the error exception.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4603 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4604 echo novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4605 causes >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4606 E121: Undefined variable: novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4607 E15: Invalid expression: novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4608 The value of the error exception inside try conditionals is: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4609 Vim(echo):E121: Undefined variable: novar
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4610 < except-syntax-error
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4611 But when a syntax error is detected after a normal error in the same command,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4612 the syntax error is used for the exception being thrown.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4613 Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4614 unlet novar #
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4615 causes >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4616 E108: No such variable: "novar"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4617 E488: Trailing characters
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4618 The value of the error exception inside try conditionals is: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4619 Vim(unlet):E488: Trailing characters
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4620 This is done because the syntax error might change the execution path in a way
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4621 not intended by the user. Example: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4622 try
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4623 try \| unlet novar # \| catch \| echo v:exception \| endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4624 catch /.*/
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4625 echo "outer catch:" v:exception
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4626 endtry
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4627 This displays "outer catch: Vim(unlet):E488: Trailing characters", and then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4628 a "E600: Missing :endtry" error message is given, see \|except-single-line\|.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4629
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4630 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4631 9. Examples eval-examples
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4632
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4633 Printing in Binary ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4634 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4635 :" The function Nr2Bin() returns the binary string representation of a number.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4636 :func Nr2Bin(nr)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4637 : let n = a:nr
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4638 : let r = ""
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4639 : while n
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4640 : let r = '01'[n % 2] .. r
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4641 : let n = n / 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4642 : endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4643 : return r
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4644 :endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4645
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4646 :" The function String2Bin() converts each character in a string to a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4647 :" binary string, separated with dashes.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4648 :func String2Bin(str)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4649 : let out = ''
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4650 : for ix in range(strlen(a:str))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4651 : let out = out .. '-' .. Nr2Bin(char2nr(a:str[ix]))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4652 : endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4653 : return out[1:]
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4654 :endfunc
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4655
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4656 Example of its use: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4657 :echo Nr2Bin(32)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4658 result: "100000" >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4659 :echo String2Bin("32")
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4660 result: "110011-110010"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4661
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4662
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4663 Sorting lines ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4664
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4665 This example sorts lines with a specific compare function. >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4666
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4667 :func SortBuffer()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4668 : let lines = getline(1, '$')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4669 : call sort(lines, function("Strcmp"))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4670 : call setline(1, lines)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4671 :endfunction
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4672
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4673 As a one-liner: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4674 :call setline(1, sort(getline(1, '$'), function("Strcmp")))
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4675
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4676
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4677 scanf() replacement ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4678 sscanf
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4679 There is no sscanf() function in Vim. If you need to extract parts from a
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4680 line, you can use matchstr() and substitute() to do it. This example shows
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4681 how to get the file name, line number and column number out of a line like
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4682 "foobar.txt, 123, 45". >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4683 :" Set up the match bit
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4684 :let mx='$\f\+$,\s$\d\+$,\s$\d\+$'
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4685 :"get the part matching the whole expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4686 :let l = matchstr(line, mx)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4687 :"get each item out of the match
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4688 :let file = substitute(l, mx, '\1', '')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4689 :let lnum = substitute(l, mx, '\2', '')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4690 :let col = substitute(l, mx, '\3', '')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4691
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4692 The input is in the variable "line", the results in the variables "file",
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4693 "lnum" and "col". (idea from Michael Geddes)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4694
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4695
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4696 getting the scriptnames in a Dictionary ~
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4697 scriptnames-dictionary
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4698 The `:scriptnames` command can be used to get a list of all script files that
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4699 have been sourced. There is also the `getscriptinfo()` function, but the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4700 information returned is not exactly the same. In case you need to manipulate
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4701 the list, this code can be used as a base: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4702
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4703 # Create or update scripts dictionary, indexed by SNR, and return it.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4704 def Scripts(scripts: dict<string> = {}): dict<string>
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4705 for info in getscriptinfo()
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4706 if scripts->has_key(info.sid)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4707 continue
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4708 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4709 scripts[info.sid] = info.name
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4710 endfor
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4711 return scripts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4712 enddef
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4713
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4714 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4715 10. Vim script versions vimscript-version vimscript-versions
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4716 scriptversion
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4717 Over time many features have been added to Vim script. This includes Ex
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4718 commands, functions, variable types, etc. Each individual feature can be
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4719 checked with the \|has()\| and \|exists()\| functions.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4720
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4721 Sometimes old syntax of functionality gets in the way of making Vim better.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4722 When support is taken away this will break older Vim scripts. To make this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4723 explicit the \|:scriptversion\| command can be used. When a Vim script is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4724 compatible with older versions of Vim this will give an explicit error,
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4725 instead of failing in mysterious ways.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4726
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4727 When using a legacy function, defined with `:function`, in \|Vim9\| script then
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4728 scriptversion 4 is used.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4729
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4730 scriptversion-1 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4731 :scriptversion 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4732 < This is the original Vim script, same as not using a \|:scriptversion\|
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4733 command. Can be used to go back to old syntax for a range of lines.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4734 Test for support with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4735 has('vimscript-1')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4736
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4737 < scriptversion-2 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4738 :scriptversion 2
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4739 < String concatenation with "." is not supported, use ".." instead.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4740 This avoids the ambiguity using "." for Dict member access and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4741 floating point numbers. Now ".5" means the number 0.5.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4742
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4743 scriptversion-3 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4744 :scriptversion 3
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4745 < All \|vim-variable\|s must be prefixed by "v:". E.g. "version" doesn't
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4746 work as \|v:version\| anymore, it can be used as a normal variable.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4747 Same for some obvious names as "count" and others.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4748
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4749 Test for support with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4750 has('vimscript-3')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4751 <
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4752 scriptversion-4 >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4753 :scriptversion 4
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4754 < Numbers with a leading zero are not recognized as octal. "0o" or "0O"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4755 is still recognized as octal. With the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4756 previous version you get: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4757 echo 017 " displays 15 (octal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4758 echo 0o17 " displays 15 (octal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4759 echo 018 " displays 18 (decimal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4760 < with script version 4: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4761 echo 017 " displays 17 (decimal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4762 echo 0o17 " displays 15 (octal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4763 echo 018 " displays 18 (decimal)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4764 < Also, it is possible to use single quotes inside numbers to make them
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4765 easier to read: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4766 echo 1'000'000
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4767 < The quotes must be surrounded by digits.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4768
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4769 Test for support with: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4770 has('vimscript-4')
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4771
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4772 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4773 11. No +eval feature no-eval-feature
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4774
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4775 When the \|+eval\| feature was disabled at compile time, none of the expression
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4776 evaluation commands are available. To prevent this from causing Vim scripts
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4777 to generate all kinds of errors, the ":if" and ":endif" commands are still
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4778 recognized, though the argument of the ":if" and everything between the ":if"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4779 and the matching ":endif" is ignored. Nesting of ":if" blocks is allowed, but
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4780 only if the commands are at the start of the line. The ":else" command is not
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4781 recognized.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4782
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4783 Example of how to avoid executing commands when the \|+eval\| feature is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4784 missing: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4785
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4786 :if 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4787 : echo "Expression evaluation is compiled in"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4788 :else
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4789 : echo "You will _never_ see this message"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4790 :endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4791
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4792 To execute a command only when the \|+eval\| feature is disabled can be done in
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4793 two ways. The simplest is to exit the script (or Vim) prematurely: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4794 if 1
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4795 echo "commands executed with +eval"
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4796 finish
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4797 endif
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4798 args " command executed without +eval
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4799
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4800 If you do not want to abort loading the script you can use a trick, as this
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4801 example shows: >
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4802
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4803 silent! while 0
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4804 set history=111
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4805 silent! endwhile
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4806
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4807 When the \|+eval\| feature is available the command is skipped because of the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4808 "while 0". Without the \|+eval\| feature the "while 0" is an error, which is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4809 silently ignored, and the command is executed.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4810
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4811 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4812 12. The sandbox eval-sandbox sandbox
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4813
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4814 The 'foldexpr', 'formatexpr', 'includeexpr', 'indentexpr', 'statusline' and
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4815 'foldtext' options may be evaluated in a sandbox. This means that you are
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4816 protected from these expressions having nasty side effects. This gives some
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4817 safety for when these options are set from a modeline. It is also used when
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4818 the command from a tags file is executed and for CTRL-R = in the command line.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4819 The sandbox is also used for the \|:sandbox\| command.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4820 E48
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4821 These items are not allowed in the sandbox:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4822 - changing the buffer text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4823 - defining or changing mapping, autocommands, user commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4824 - setting certain options (see \|option-summary\|)
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4825 - setting certain v: variables (see \|v:var\|) E794
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4826 - executing a shell command
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4827 - reading or writing a file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4828 - jumping to another buffer or editing a file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4829 - executing Python, Perl, etc. commands
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4830 This is not guaranteed 100% secure, but it should block most attacks.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4831
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4832 :san :sandbox
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4833 :san[dbox] {cmd} Execute {cmd} in the sandbox. Useful to evaluate an
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4834 option that may have been set from a modeline, e.g.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4835 'foldexpr'.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4836
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4837 sandbox-option
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4838 A few options contain an expression. When this expression is evaluated it may
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4839 have to be done in the sandbox to avoid a security risk. But the sandbox is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4840 restrictive, thus this only happens when the option was set from an insecure
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4841 location. Insecure in this context are:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4842 - sourcing a .vimrc or .exrc in the current directory
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4843 - while executing in the sandbox
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4844 - value coming from a modeline
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4845 - executing a function that was defined in the sandbox
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4846
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4847 Note that when in the sandbox and saving an option value and restoring it, the
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4848 option will still be marked as it was set in the sandbox.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4849
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4850 ==============================================================================
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4851 13. Textlock textlock
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4852
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4853 In a few situations it is not allowed to change the text in the buffer, jump
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4854 to another window and some other things that might confuse or break what Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4855 is currently doing. This mostly applies to things that happen when Vim is
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4856 actually doing something else. For example, evaluating the 'balloonexpr' may
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4857 happen any moment the mouse cursor is resting at some position.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4858
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4859 This is not allowed when the textlock is active:
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4860 - changing the buffer text
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4861 - jumping to another buffer or window
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4862 - editing another file
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4863 - closing a window or quitting Vim
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4864 - etc.
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4865
33721 d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4866 ==============================================================================
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4867 14. Vim script library vim-script-library
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4868
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4869 Vim comes bundled with a Vim script library, that can be used by runtime,
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4870 script authors. Currently, it only includes very few functions, but it may
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4871 grow over time.
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4872
33798 af1b18018eeb runtime(doc): Fix whitespace and formatting of some help files (#13549) Christian Brabandt <cb@256bit.org> parents: 33721 diff changeset	4873 The functions are available as \|Vim9-script\| as well as using legacy Vim
33721 d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4874 script (to be used for non Vim 9.0 versions and Neovim).
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4875
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4876 dist#vim dist#vim9
33798 af1b18018eeb runtime(doc): Fix whitespace and formatting of some help files (#13549) Christian Brabandt <cb@256bit.org> parents: 33721 diff changeset	4877 The functions make use of the autoloaded prefix "dist#vim" (for legacy Vim
af1b18018eeb runtime(doc): Fix whitespace and formatting of some help files (#13549) Christian Brabandt <cb@256bit.org> parents: 33721 diff changeset	4878 script and Neovim) and "dist#vim9" for Vim9 script.
33721 d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4879
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4880 The following functions are available:
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4881
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4882 dist#vim#IsSafeExecutable(filetype, executable) ~
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4883 dist#vim9#IsSafeExecutable(filetype:string, executable:string): bool ~
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4884
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4885 This function takes a filetype and an executable and checks whether it is safe
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4886 to execute the given executable. For security reasons users may not want to
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4887 have Vim execute random executables or may have forbidden to do so for
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4888 specific filetypes by setting the "<filetype>_exec" variable (\|plugin_exec\|).
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4889
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4890 It returns \|true\| or \|false\| to indicate whether the plugin should run the given
33902 8c4c6369239b runtime(doc): link cmdline completion to to \|wildcards\| and fix typos (#13636) Christian Brabandt <cb@256bit.org> parents: 33901 diff changeset	4891 executable. It takes the following arguments:
33721 d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4892
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4893 argument type ~
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4894
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4895 filetype string
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4896 executable string
d7ac49e53d62 runtime(doc): document vim-script library function Christian Brabandt <cb@256bit.org> parents: 33436 diff changeset	4897
32670 695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4898
695b50472e85 Fix line endings issue Christian Brabandt <cb@256bit.org> parents: 32669 diff changeset	4899 vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/eval.txt @ 35069:abc67b413453 default tip