Merge pull request #3763 from HiPhish/vimscript

[vimscript/en] Vimscript tutorial

1 files changed, 651 insertions, 0 deletions

diff --git a/vimscript.html.markdown b/vimscript.html.markdown
new file mode 100644
index 00000000..8e023713
--- /dev/null
+++ b/vimscript.html.markdown
@@ -0,0 +1,651 @@
+---
+language: Vimscript
+filename: learnvimscript.vim
+contributors:
+    - ["HiPhish", "http://hiphish.github.io/"]
+---
+
+```vim
+" ##############
+"  Introduction
+" ##############
+"
+" Vim script (also called VimL) is the subset of Vim's ex-commands which
+" supplies a number of features one one would expect from a scripting language,
+" such as values, variables, functions or loops. Always keep in the back of
+" your mind that a Vim script file is just a sequence of ex-commands. It is
+" very common for a script to mix programming-language features and raw
+" ex-commands.
+"
+" You can run Vim script directly by entering the commands in command-mode
+" (press `:` to enter command-mode), or you can write them to a file (without
+" the leading `:`) and source it in a running Vim instance (`:source
+" path/to/file`). Some files are sourced automatically as part of your
+" configuration (see |startup|). This guide assumes that you are familiar
+" with ex-commands and will only cover the scripting. Help topics to the
+" relevant manual sections are included.
+"
+" See |usr_41.txt| for the official introduction to Vim script. A comment is
+" anything following an unmatched `"` until the end of the line, and `|`
+" separates instructions (what `;` does in most other languages). References to
+" the manual as surrounded with `|`, such as |help.txt|.
+
+" This is a comment
+
+" The vertical line '|' (pipe) separates commands
+echo 'Hello' | echo 'world!'
+
+" Putting a comment after a command usually works
+pwd                   " Displays the current working directory
+
+" Except for some commands it does not; use the command delemiter before the
+" comment (echo assumes that the quotation mark begins a string)
+echo 'Hello world!'  | " Displays a message
+
+" Line breaks can be escaped by pacing a backslash as the first non-whitespace
+" character on the *following* line. Only works in script files, not on the
+" command line
+echo " Hello
+    \ world "
+
+echo [1, 
+    \ 2]
+
+echo {
+    \ 'a': 1,
+    \ 'b': 2
+\}
+
+
+" #######
+"  Types
+" #######
+"
+" For an overview of types see |E712|. For an overview of operators see
+" |expression-syntax|
+
+" Numbers (|expr-number|)
+" #######
+
+echo  123         | " Decimal
+echo  0b1111011   | " Binary
+echo  0173        | " Octal
+echo  0x7B        | " Hexadecimal
+echo  123.0       | " Floating-point
+echo  1.23e2      | " Floating-point (scientific notation)
+
+" Note that an *integer* number with a leading `0` is in octal notation. The
+" usual arithmetic operations are supported.
+
+echo  1 + 2       | " Addition
+echo  1 - 2       | " Subtraction
+echo  - 1         | " Negation (unary minus)
+echo  + 1         | " Unary plus (does nothing really, but still legal)
+echo  1 * 2       | " Multiplication
+echo  1 / 2       | " Division
+echo  1 % 2       | " Modulo (remainder)
+
+" Booleans (|Boolean|)
+" ########
+"
+" The number 0 is false, every other number is true. Strings are implicitly
+" converted to numbers (see below). There are two pre-defined semantic
+" constants.
+
+echo  v:true      | " Evaluates to 1 or the string 'v:true'
+echo  v:false     | " Evaluates to 0 or the string 'v:false'
+
+" Boolean values can result from comparison of two objects.
+
+echo  x == y             | " Equality by value
+echo  x != y             | " Unequality
+echo  x >  y             | " Greater than
+echo  x >= y             | " Greater than or equal
+echo  x <  y             | " Smaller than
+echo  x <= y             | " Smaller than or equal
+echo  x is y             | " Instance identity (lists and dictionaries)
+echo  x isnot y          | " Instance non-identity (lists and dictionaries)
+
+" Strings are compared based on their alphanumerical ordering
+" echo 'a' < 'b'. Case sensitivity depends on the setting of 'ignorecase'
+"
+" Explicit case-sensitivity is specified by appending '#' (match case) or '?'
+" (ignore case) to the operator. Prefer explicity case sensitivity when writing
+" portable scripts.
+
+echo  'a' <  'B'         | " True or false depending on 'ignorecase'
+echo  'a' <? 'B'         | " True
+echo  'a' <# 'B'         | " False
+
+" Regular expression matching
+echo  "hi" =~  "hello"    | " Regular expression match, uses 'ignorecase'
+echo  "hi" =~# "hello"    | " Regular expression match, case sensitive
+echo  "hi" =~? "hello"    | " Regular expression match, case insensitive
+echo  "hi" !~  "hello"    | " Regular expression unmatch, use 'ignorecase'
+echo  "hi" !~# "hello"    | " Regular expression unmatch, case sensitive
+echo  "hi" !~? "hello"    | " Regular expression unmatch, case insensitive
+
+" Boolean operations are possible.
+
+echo  v:true && v:false       | " Logical AND
+echo  v:true || v:false       | " Logical OR
+echo  ! v:true                | " Logical NOT
+echo  v:true ? 'yes' : 'no'   | " Ternary operator
+
+
+" Strings (|String|)
+" #######
+"
+" An ordered zero-indexed sequence of bytes. The encoding of text into bytes
+" depends on the option |'encoding'|.
+
+" Literal constructors
+echo  "Hello world\n"   | " The last two characters stand for newline
+echo  'Hello world\n'   | " The last two characters are literal
+echo  'Let''s go!'      | " Two single quotes become one quote character
+
+" Single-quote strings take all characters are literal, except two single
+" quotes, which are taken to be a single quote in the string itself. See 
+" |expr-quote| for all possible escape sequences.
+
+" String concatenation
+" The .. operator is preferred, but only supported in since Vim 8.1.1114
+echo  'Hello ' .  'world'  | " String concatenation
+echo  'Hello ' .. 'world'  | " String concatenation (new variant)
+
+" String indexing
+echo  'Hello'[0]           | " First byte
+echo  'Hello'[1]           | " Second byte
+echo  'Hellö'[4]           | " Returns a byte, not the character 'ö'
+
+" Substrings (second index is inclusive)
+echo  'Hello'[:]           | " Copy of entire string
+echo  'Hello'[1:3]         | " Substring, second to fourth byte
+echo  'Hello'[1:-2]        | " Substring until second to last byte
+echo  'Hello'[1:]          | " Substring with starting index
+echo  'Hello'[:2]          | " Substring with ending index
+echo  'Hello'[-2:]         | " Substring relative to end of string
+
+" A negative index is relative to the end of the string. See
+" |string-functions| for all string-related functions.
+
+" Lists (|List|)
+" #####
+"
+" An ordered zero-indexed heterogeneous sequence of arbitrary Vim script
+" objects.
+
+" Literal constructor
+echo  []                   | " Empty list
+echo  [1, 2, 'Hello']      | " List with elements
+echo  [1, 2, 'Hello', ]    | " Trailing comma permitted
+echo  [[1, 2], 'Hello']    | " Lists can be nested arbitrarily
+
+" List concatenation
+echo  [1, 2] + [3, 4]      | " Creates a new list
+
+" List indexing, negative is relative to end of list (|list-index|)
+echo  [1, 2, 3, 4][2]      | " Third element
+echo  [1, 2, 3, 4][-1]     | " Last element
+
+" List slicing (|sublist|)
+echo  [1, 2, 3, 4][:]      | " Shallow copy of entire list
+echo  [1, 2, 3, 4][:2]     | " Sublist until third item (inclusive)
+echo  [1, 2, 3, 4][2:]     | " Sublist from third item (inclusive)
+echo  [1, 2, 3, 4][:-2]    | " Sublist until second-to-last item (inclusive)
+
+" All slicing operations create new lists. To modify a list in-place use list
+" functions (|list-functions|) or assign directly to an item (see below about
+" variables).
+
+
+" Dictionaries (|Dictionary|)
+" ############
+"
+" An unordered sequence of key-value pairs, keys are always strings (numbers
+" are implicitly converted to strings).
+
+" Dictionary literal
+echo  {}                       | " Empty dictionary
+echo  {'a': 1, 'b': 2}         | " Dictionary literal
+echo  {'a': 1, 'b': 2, }       | " Trailing comma permitted
+echo  {'x': {'a': 1, 'b': 2}}  | " Nested dictionary
+
+" Indexing a dictionary
+echo  {'a': 1, 'b': 2}['a']    | " Literal index
+echo  {'a': 1, 'b': 2}.a       | " Syntactic sugar for simple keys
+
+" See |dict-functions| for dictionary manipulation functions.
+
+
+" Funcref (|Funcref|)
+" #######
+"
+" Reference to a function, uses the function name as a string for construction.
+" When stored in a variable the name of the variable has the same restrictions
+" as a function name (see below).
+
+echo  function('type')                   | " Reference to function type()
+" Note that `funcref('type')` will throw an error because the argument must be
+" a user-defined function; see further below for defining your own functions.
+echo  funcref('type')                    | " Reference by identity, not name
+" A lambda (|lambda|) is an anonymous function; it can only contain one
+" expression in its body, which is also its implicit return value.
+echo  {x -> x * x}                       | " Anonymous function
+echo  function('substitute', ['hello'])  | " Partial function
+
+
+" Regular expression (|regular-expression|)
+" ##################
+"
+" A regular expression pattern is generally a string, but in some cases you can
+" also use a regular expression between a pair of delimiters (usually `/`, but
+" you can choose anything).
+
+" Substitute 'hello' for 'Hello'
+substitute/hello/Hello/
+
+
+" ###########################
+"  Implicit type conversions
+" ###########################
+"
+" Strings are converted to numbers, and numbers to strings when necessary. A
+" number becomes its decimal notation as a string. A string becomes its
+" numerical value if it can be parsed to a number, otherwise it becomes zero.
+
+echo  "1" + 1         | " Number
+echo  "1" .. 1        | " String
+echo  "0xA" + 1       | " Number
+
+" Strings are treated like numbers when used as booleans
+echo "true" ? 1 : 0   | " This string is parsed to 0, which is false
+
+" ###########
+"  Variables
+" ###########
+" 
+" Variables are bound within a scope; if no scope is provided a default is
+" chosen by Vim. Use `:let` and `:const` to bind a value and `:unlet` to unbind
+" it.
+
+let b:my_var = 1        | " Local to current buffer
+let w:my_var = 1        | " Local to current window
+let t:my_var = 1        | " Local to current tab page
+let g:my_var = 1        | " Global variable
+let l:my_var = 1        | " Local to current function (see functions below)
+let s:my_var = 1        | " Local to current script file
+let a:my_arg = 1        | " Function argument (see functions below)
+
+" The Vim scope is read-only
+echo  v:true            | " Special built-in Vim variables (|v:var|)
+
+" Access special Vim memory like variables
+let @a = 'Hello'        | " Register
+let $PATH=''            | " Environment variable
+let &textwidth = 79     | " Option
+let &l:textwidth = 79   | " Local option
+let &g:textwidth = 79   | " Global option
+
+" Access scopes as dictionaries (can be modified like all dictionaries)
+" See the |dict-functions|, especially |get()|, for access and manipulation
+echo  b:                | " All buffer variables
+echo  w:                | " All window variables
+echo  t:                | " All tab page variables
+echo  g:                | " All global variables
+echo  l:                | " All local variables
+echo  s:                | " All script variables
+echo  a:                | " All function arguments
+echo  v:                | " All Vim variables
+
+" Constant variables
+const x = 10            | " See |:const|, |:lockvar|
+
+" Function reference variables have the same restrictions as function names
+let IsString = {x -> type(x) == type('')}    | " Global: capital letter
+let s:isNumber = {x -> type(x) == type(0)}   | " Local: any name allowed
+
+" When omitted the scope `g:` is implied, except in functions, there `l:` is
+" implied.
+
+
+" Multiple value binding (list unpacking)
+" #######################################
+"
+" Assign values of list to multiple variables (number of items must match)
+let [x, y] = [1, 2]
+
+" Assign the remainer to a rest variable (note the semicolon)
+let [mother, father; children] = ['Alice', 'Bob', 'Carol', 'Dennis', 'Emily']
+
+
+" ##############
+"  Flow control
+" ##############
+
+" Conditional (|:if|, |:elseif|, |:else|, |:endif|)
+" ###########
+" 
+" Conditions are set between `if` and `endif`. They can be nested.
+
+let condition = v:true
+
+if condition
+    echo 'First condition'
+elseif another_condition
+    echo 'Second condition'
+else
+    echo 'Fail'
+endif
+
+" Loops (|:for|, |:endfor|, |:while|, |:endwhile|, |:break|, |:continue|)
+" #####
+"
+" Two types of loops: `:for` and `:while`. Use `:continue` to skip to the next
+" iteration, `:break` to break out of the loop.
+
+" For-loop (|:for|, |:endfor|)
+" ========
+"
+" For-loops iterate over lists and nothing else. If you want to iterate over
+" another sequence you need to use a function which will create a list.
+
+" Iterate over a list
+for person in ['Alice', 'Bob', 'Carol', 'Dennis', 'Emily']
+    echo 'Hello ' .. person
+endfor
+
+" Iterate over a nested list by unpacking it
+for [x, y] in [[1, 0], [0, 1], [-1, 0], [0, -1]]
+    echo 'Position: x ='  .. x .. ', y = ' .. y
+endfor
+
+" Iterate over a range of numbers
+for i in range(10, 0, -1)  " Count down from 10
+    echo 'T minus'  .. i
+endfor
+
+" Iterate over the keys of a dictionary
+for symbol in keys({'π': 3.14, 'e': 2.71})
+    echo 'The constant ' .. symbol .. ' is a transcendent number'
+endfor
+
+" Iterate over the values of a dictionary
+for value in values({'π': 3.14, 'e': 2.71})
+    echo 'The value ' .. value .. ' approximates a transcendent number'
+endfor
+
+" Iterate over the keys and values of a dictionary
+for [symbol, value] in items({'π': 3.14, 'e': 2.71})
+    echo 'The number ' .. symbol .. ' is approximately ' .. value
+endfor
+
+" While-loops (|:while|, |:endwhile|)
+
+let there_yet = v:true
+while !there_yet
+    echo 'Are we there yet?'
+endwhile
+
+
+" Exception handling (|exception-handling|)
+" ##################
+"
+" Throw new exceptions as strings, catch them by pattern-matching a regular
+" expression against the string
+
+" Throw new exception
+throw "Wrong arguments"
+
+" Guard against an exception (the second catch matches any exception)
+try
+    source path/to/file
+catch /Cannot open/
+    echo 'Looks like that file does not exist'
+catch /.*/
+    echo 'Something went wrong, but I don't know what'
+finally
+    echo 'I'm done trying'
+endtry
+
+
+" ##########
+"  Functions
+" ##########
+
+" Defining functions (|:function|, |:endfunction|)
+" ##################
+
+" Unscoped function names have to start with a capital letter
+function! AddNumbersLoudly(x, y)
+    " Use a: scope to access arguments
+    echo 'Adding'  .. a:x ..  'and'  .. a:y   | " A side effect
+    return a:x + a:y                          | " A return value
+endfunction
+
+" Scoped function names may start with a lower-case letter
+function! s:addNumbersLoudly(x, y)
+    echo 'Adding'  .. a:x ..  'and'  .. a:y
+    return a:x + a:y
+endfunction
+
+" Without the exclamation mark it would be an error to re-define a function,
+" with the exclamation mark the new definition can replace the old one. Since
+" Vim script files can be reloaded several times over the course of a session
+" it is best to use the exclamation mark unless you really know what you are
+" doing.
+
+" Function definitions can have special qualifiers following the argument list.
+
+" Range functions define two implicit arguments, which will be set to the range
+" of the ex-command
+function! FirstAndLastLine() range
+    echo [a:firstline, a:lastline]
+endfunction
+
+" Prints the first and last line that match a pattern (|cmdline-ranges|)
+/^#!/,/!#$/call FirstAndLastLine()
+
+" Aborting functions, abort once error occurs (|:func-abort|)
+function! SourceMyFile() abort
+    source my-file.vim        | " Try sourcing non-existing file
+    echo 'This will never be printed'
+endfunction
+
+" Closures, functions carrying values from outer scope (|:func-closure|)
+function! MakeAdder(x)
+    function! Adder(n) closure
+        return a:n + a:x
+    endfunction
+    return funcref('Adder')
+endfunction
+let AddFive = MakeAdder(5)
+echo AddFive(3)               | " Prints 8
+
+" Dictionary functions, poor man's OOP methods (|Dictionary-function|)
+function! Mylen() dict
+    return len(self.data)     | " Implicit variable self
+endfunction
+let mydict = {'data': [0, 1, 2, 3], 'len': function("Mylen")}
+echo mydict.len()
+
+" Alternatively, more concise
+let mydict = {'data': [0, 1, 2, 3]}
+function! mydict.len()
+    return len(self.data)
+endfunction
+
+" Calling functions (|:call|)
+" #################
+
+" Call a function for its return value, and possibly for its side effects
+let animals = keys({'cow': 'moo', 'dog': 'woof', 'cat': 'meow'})
+
+" Call a function for its side effects only, ignore potential result
+call sign_undefine()
+
+" The call() function calls a function reference and passes parameters as a
+" list, and returns the function's result.
+echo  call(function('get'), [{'a': 1, 'b': 2}, 'c', 3])   | " Prints 3
+
+" Recall that Vim script is embedded within the ex-commands, that is why we
+" cannot just call a function directly, we have to use the `:call` ex-command.
+
+" Function namespaces (|write-library-script|, |autoload|)
+" ###################
+
+" Must be defined in autoload/foo/bar.vim
+" Namspaced function names do not have to start with a capital letter
+function! foo#bar#log(value)
+    echomsg value
+endfunction
+
+call foo#bar#log('Hello')
+
+
+" #############################
+"  Frequently used ex-commands
+" #############################
+
+
+" Sourcing runtime files (|'runtimepath'|)
+" ######################
+
+" Source first match among runtime paths
+runtime plugin/my-plugin.vim
+
+
+" Defining new ex-commands (|40.2|, |:command|)
+" ########################
+
+" First argument here is the name of the command, rest is the command body
+command! SwapAdjacentLines normal! ddp
+
+" The exclamation mark works the same as with `:function`. User-defined
+" commands must start with a capital letter. The `:command` command can take a
+" number of attributes (some of which have their own parameters with `=`), such
+" as `-nargs`, all of them start with a dash to set them apart from the command
+" name.
+
+:command -nargs=1 Error echoerr <args>
+
+
+" Defining auto-commands (|40.3|, |autocmd|, |autocommand-events|)
+" ######################
+
+" The arguments are "events", "patterns", rest is "commands"
+autocmd BufWritePost $MYVIMRC source $MYVIMRC
+
+" Events and patterns are separated by commas with no space between. See
+" |autocmd-events| for standard events, |User| for custom events. Everything
+" else are the ex-commands which will be executed.
+
+" Auto groups
+" ===========
+"
+" When a file is sourced multiple times the auto-commands are defined anew,
+" without deleting the old ones, causing auto-commands to pile up over time.
+" Use auto-groups and the following ritual to guard against this.
+
+augroup auto-source   | " The name of the group is arbitrary
+    autocmd!          | " Deletes all auto-commands in the current group
+    autocmd BufWritePost $MYVIMRC source $MYVIMRC
+augroup END           | " Switch back to default auto-group
+
+" It is also possible to assign a group directly. This is useful if the
+" definition of the group is in one script and the definition of the
+" auto-command is in another script.
+
+" In one file
+augroup auto-source
+    autocmd!
+augroup END
+
+" In another file
+autocmd auto-source BufWritePost $MYVIMRC source $MYVIMRC
+
+" Executing (run-time macros of sorts)
+" ####################################
+
+" Sometimes we need to construct an ex-command where part of the command is not
+" known until runtime.
+
+let line = 3                | " Line number determined at runtime
+execute line .. 'delete'    | " Delete a line
+
+" Executing normal-mode commands
+" ##############################
+"
+" Use `:normal` to play back a sequence of normal mode commands from the
+" command-line. Add an exclamation mark to ignore user mappings.
+
+normal! ggddGp             | " Transplant first line to end of buffer
+
+" Window commands can be used with :normal, or with :wincmd if :normal would
+" not work
+wincmd L                   | " Move current window all the way to the right
+
+
+" ###########################
+"  Frequently used functions
+" ###########################
+
+" Feature check
+echo  has('nvim')                  | " Running Neovim
+echo  has('python3')               | " Support for Python 3 plugins
+echo  has('unix')                  | " Running on a Unix system
+echo  has('win32')                 | " Running on a Windows system
+
+
+" Test if something exists
+echo  exists('&mouse')             | " Option (exists only)
+echo  exists('+mouse')             | " Option (exists and works)
+echo  exists('$HOSTNAME')          | " Environment variable
+echo  exists('*strftime')          | " Built-in function
+echo  exists('**s:MyFunc')         | " User-defined function
+echo  exists('bufcount')           | " Variable (scope optional)
+echo  exists('my_dict["foo"]')     | " Variable (dictionary entry)
+echo  exists('my_dict["foo"]')     | " Variable (dictionary entry)
+echo  exists(':Make')              | " Command
+echo  exists("#CursorHold")        | " Auto-command defined for event
+echo  exists("#BufReadPre#*.gz")   | " Event and pattern
+echo  exists("#filetypeindent")    | " Auto-command group
+echo  exists("##ColorScheme")      | " Auto-commnand supported for event
+
+" Various dynamic values (see |expand()|)
+echo  expand('%')                  | " Current file name
+echo  expand('<cword>')            | " Current word under cursor
+echo  expand('%:p')                | " Modifier are possible
+
+" Type tests
+echo  type(my_var) == type(0)                  | " Number
+echo  type(my_var) == type('')                 | " String
+echo  type(my_var) == type([])                 | " List
+echo  type(my_var) == type({})                 | " Dictionary
+echo  type(my_var) == type(function('type'))   | " Funcref
+
+" Format strings
+echo  printf('%d in hexadecimal is %X', 123, 123)
+
+
+" #####################
+"  Tricks of the trade
+" #####################
+
+" Source guard
+" ############
+
+" Prevent a file from being source multiple times; users can set the variable
+" in their configuration to prevent the plugin from loading at all.
+if exists('g:loaded_my_plugin')
+    finish
+endif
+let g:loaded_my_plugin = v:true
+
+" Default values
+" ##############
+
+" Get a default value: if the user defines a variable use it, otherwise use a
+" hard-coded default. Uses the fact that a scope is also a dictionary.
+let s:greeting = get(g:, 'my_plugin_greeting', 'Hello')
+```