# vimhelp: user manual ch.41 Write a Vim script # Copyright (C) 2006 Bram Moolenaar # This file is distributed under the same license as the vim package. # FIRST AUTHOR , YEAR. # #, fuzzy msgid "" msgstr "" "Project-Id-Version: vim 7.0.122\n" "POT-Creation-Date: 2009-01-05 22:50+0100\n" "PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n" "Last-Translator: FULL NAME \n" "Language-Team: LANGUAGE \n" "MIME-Version: 1.0\n" "Content-Type: text/plain; charset=utf8\n" "Content-Transfer-Encoding: 8bit" # type: Plain text #: usr_41.txt:2 #, no-wrap msgid "*usr_41.txt*\tFor Vim version 7.0. Last change: 2006 Apr 30\n" msgstr "" # type: Plain text #: usr_41.txt:4 #, no-wrap msgid "\t\t VIM USER MANUAL - by Bram Moolenaar\n" msgstr "" # type: Plain text #: usr_41.txt:6 #, no-wrap msgid "\t\t\t Write a Vim script\n" msgstr "" # type: Plain text #: usr_41.txt:11 msgid "" "The Vim script language is used for the startup vimrc file, syntax files, " "and many other things. This chapter explains the items that can be used in " "a Vim script. There are a lot of them, thus this is a long chapter." msgstr "" # type: Plain text #: usr_41.txt:28 msgid "" "|41.1|\tIntroduction |41.2|\tVariables |41.3|\tExpressions " "|41.4|\tConditionals |41.5|\tExecuting an expression |41.6|\tUsing functions " "|41.7|\tDefining a function |41.8|\tLists and Dictionaries " "|41.9|\tExceptions |41.10|\tVarious remarks |41.11|\tWriting a plugin " "|41.12|\tWriting a filetype plugin |41.13|\tWriting a compiler plugin " "|41.14|\tWriting a plugin that loads quickly |41.15|\tWriting library " "scripts |41.16|\tDistributing Vim scripts" msgstr "" # type: Plain text #: usr_41.txt:32 #, no-wrap msgid "" " Next chapter: |usr_42.txt| Add new menus\n" " Previous chapter: |usr_40.txt| Make new commands\n" "Table of contents: |usr_toc.txt|\n" msgstr "" # type: Plain text #: usr_41.txt:33 usr_41.txt:133 usr_41.txt:267 usr_41.txt:345 usr_41.txt:482 usr_41.txt:532 usr_41.txt:842 usr_41.txt:1069 usr_41.txt:1355 usr_41.txt:1412 usr_41.txt:1570 usr_41.txt:1983 usr_41.txt:2169 usr_41.txt:2215 usr_41.txt:2291 usr_41.txt:2355 usr_41.txt:2370 #, no-wrap msgid "==============================================================================\n" msgstr "" # type: Plain text #: usr_41.txt:35 #, no-wrap msgid "*41.1*\tIntroduction\t\t\t\t*vim-script-intro* *script*\n" msgstr "" # type: Plain text #: usr_41.txt:43 #, no-wrap msgid "" "Your first experience with Vim scripts is the vimrc file. Vim reads it " "when\n" "it starts up and executes the commands. You can set options to values you\n" "prefer. And you can use any colon command in it (commands that start with " "a\n" "\":\"; these are sometimes referred to as Ex commands or command-line " "commands).\n" " Syntax files are also Vim scripts. As are files that set options for a\n" "specific file type. A complicated macro can be defined by a separate Vim\n" "script file. You can think of other uses yourself.\n" msgstr "" # type: Plain text #: usr_41.txt:45 msgid "Let's start with a simple example: >" msgstr "" # type: Plain text #: usr_41.txt:60 #, no-wrap msgid "" "\t:let i = 1\n" "\t:while i < 5\n" "\t: echo \"count is\" i\n" "\t: let i += 1\n" "\t:endwhile\n" "<\n" "\tNote:\n" "\tThe \":\" characters are not really needed here. You only need to use\n" "\tthem when you type a command. In a Vim script file they can be left\n" "\tout. We will use them here anyway to make clear these are colon\n" "\tcommands and make them stand out from Normal mode commands.\n" "\tNote:\n" "\tYou can try out the examples by yanking the lines from the text here\n" "\tand executing them with :@\"\n" msgstr "" # type: Plain text #: usr_41.txt:62 msgid "The output of the example code is:" msgstr "" # type: Plain text #: usr_41.txt:67 #, no-wrap msgid "" "\tcount is 1 ~\n" "\tcount is 2 ~\n" "\tcount is 3 ~\n" "\tcount is 4 ~\n" msgstr "" # type: Plain text #: usr_41.txt:70 msgid "" "In the first line the \":let\" command assigns a value to a variable. The " "generic form is: >" msgstr "" # type: Plain text #: usr_41.txt:72 #, no-wrap msgid "\t:let {variable} = {expression}\n" msgstr "" # type: Plain text #: usr_41.txt:76 #, no-wrap msgid "" "In this case the variable name is \"i\" and the expression is a simple " "value,\n" "the number one.\n" " The \":while\" command starts a loop. The generic form is: >\n" msgstr "" # type: Plain text #: usr_41.txt:80 #, no-wrap msgid "" "\t:while {condition}\n" "\t: {statements}\n" "\t:endwhile\n" msgstr "" # type: Plain text #: usr_41.txt:87 #, no-wrap msgid "" "The statements until the matching \":endwhile\" are executed for as long as " "the\n" "condition is true. The condition used here is the expression \"i < 5\". " "This\n" "is true when the variable i is smaller than five.\n" "\tNote:\n" "\tIf you happen to write a while loop that keeps on running, you can\n" "\tinterrupt it by pressing CTRL-C (CTRL-Break on MS-Windows).\n" msgstr "" # type: Plain text #: usr_41.txt:90 msgid "" "The \":echo\" command prints its arguments. In this case the string \"count " "is\" and the value of the variable i. Since i is one, this will print:" msgstr "" # type: Plain text #: usr_41.txt:92 #, no-wrap msgid "\tcount is 1 ~\n" msgstr "" # type: Plain text #: usr_41.txt:96 msgid "" "Then there is the \":let i += 1\" command. This does the same thing as " "\":let i = i + 1\". This adds one to the variable i and assigns the new " "value to the same variable." msgstr "" # type: Plain text #: usr_41.txt:99 msgid "" "The example was given to explain the commands, but would you really want to " "make such a loop it can be written much more compact: >" msgstr "" # type: Plain text #: usr_41.txt:103 #, no-wrap msgid "" "\t:for i in range(1, 4)\n" "\t: echo \"count is\" i\n" "\t:endfor\n" msgstr "" # type: Plain text #: usr_41.txt:106 msgid "" "We won't explain how |:for| and |range()| work until later. Follow the " "links if you are impatient." msgstr "" # type: Plain text #: usr_41.txt:109 msgid "THREE KINDS OF NUMBERS" msgstr "" # type: Plain text #: usr_41.txt:115 #, no-wrap msgid "" "Numbers can be decimal, hexadecimal or octal. A hexadecimal number starts\n" "with \"0x\" or \"0X\". For example \"0x1f\" is decimal 31. An octal number " "starts\n" "with a zero. \"017\" is decimal 15. Careful: don't put a zero before a " "decimal\n" "number, it will be interpreted as an octal number!\n" " The \":echo\" command always prints decimal numbers. Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:118 #, no-wrap msgid "" "\t:echo 0x7f 036\n" "<\t127 30 ~\n" msgstr "" # type: Plain text #: usr_41.txt:122 #, no-wrap msgid "" "A number is made negative with a minus sign. This also works for " "hexadecimal\n" "and octal numbers. A minus sign is also used for subtraction. Compare " "this\n" "with the previous example: >\n" msgstr "" # type: Plain text #: usr_41.txt:125 #, no-wrap msgid "" "\t:echo 0x7f -036\n" "<\t97 ~\n" msgstr "" # type: Plain text #: usr_41.txt:130 msgid "" "White space in an expression is ignored. However, it's recommended to use " "it for separating items, to make the expression easier to read. For " "example, to avoid the confusion with a negative number above, put a space " "between the minus sign and the following number: >" msgstr "" # type: Plain text #: usr_41.txt:132 #, no-wrap msgid "\t:echo 0x7f - 036\n" msgstr "" # type: Plain text #: usr_41.txt:135 #, no-wrap msgid "*41.2*\tVariables\n" msgstr "" # type: Plain text #: usr_41.txt:138 msgid "" "A variable name consists of ASCII letters, digits and the underscore. It " "cannot start with a digit. Valid variable names are:" msgstr "" # type: Plain text #: usr_41.txt:144 #, no-wrap msgid "" "\tcounter\n" "\t_aap3\n" "\tvery_long_variable_name_with_underscores\n" "\tFuncLength\n" "\tLENGTH\n" msgstr "" # type: Plain text #: usr_41.txt:148 #, no-wrap msgid "" "Invalid names are \"foo+bar\" and \"6var\".\n" " These variables are global. To see a list of currently defined " "variables\n" "use this command: >\n" msgstr "" # type: Plain text #: usr_41.txt:150 #, no-wrap msgid "\t:let\n" msgstr "" # type: Plain text #: usr_41.txt:156 msgid "" "You can use global variables everywhere. This also means that when the " "variable \"count\" is used in one script file, it might also be used in " "another file. This leads to confusion at least, and real problems at " "worst. To avoid this, you can use a variable local to a script file by " "prepending \"s:\". For example, one script contains this code: >" msgstr "" # type: Plain text #: usr_41.txt:162 #, no-wrap msgid "" "\t:let s:count = 1\n" "\t:while s:count < 5\n" "\t: source other.vim\n" "\t: let s:count += 1\n" "\t:endwhile\n" msgstr "" # type: Plain text #: usr_41.txt:167 msgid "" "Since \"s:count\" is local to this script, you can be sure that sourcing the " "\"other.vim\" script will not change this variable. If \"other.vim\" also " "uses an \"s:count\" variable, it will be a different copy, local to that " "script. More about script-local variables here: |script-variable|." msgstr "" # type: Plain text #: usr_41.txt:170 msgid "" "There are more kinds of variables, see |internal-variables|. The most often " "used ones are:" msgstr "" # type: Plain text #: usr_41.txt:175 #, no-wrap msgid "" "\tb:name\t\tvariable local to a buffer\n" "\tw:name\t\tvariable local to a window\n" "\tg:name\t\tglobal variable (also in a function)\n" "\tv:name\t\tvariable predefined by Vim\n" msgstr "" # type: Plain text #: usr_41.txt:178 msgid "DELETING VARIABLES" msgstr "" # type: Plain text #: usr_41.txt:181 msgid "" "Variables take up memory and show up in the output of the \":let\" command. " "To delete a variable use the \":unlet\" command. Example: >" msgstr "" # type: Plain text #: usr_41.txt:183 #, no-wrap msgid "\t:unlet s:count\n" msgstr "" # type: Plain text #: usr_41.txt:187 msgid "" "This deletes the script-local variable \"s:count\" to free up the memory it " "uses. If you are not sure if the variable exists, and don't want an error " "message when it doesn't, append !: >" msgstr "" # type: Plain text #: usr_41.txt:189 #, no-wrap msgid "\t:unlet! s:count\n" msgstr "" # type: Plain text #: usr_41.txt:193 msgid "" "When a script finishes, the local variables used there will not be " "automatically freed. The next time the script executes, it can still use " "the old value. Example: >" msgstr "" # type: Plain text #: usr_41.txt:199 #, no-wrap msgid "" "\t:if !exists(\"s:call_count\")\n" "\t: let s:call_count = 0\n" "\t:endif\n" "\t:let s:call_count = s:call_count + 1\n" "\t:echo \"called\" s:call_count \"times\"\n" msgstr "" # type: Plain text #: usr_41.txt:203 msgid "" "The \"exists()\" function checks if a variable has already been defined. " "Its argument is the name of the variable you want to check. Not the " "variable itself! If you would do this: >" msgstr "" # type: Plain text #: usr_41.txt:205 #, no-wrap msgid "\t:if !exists(s:call_count)\n" msgstr "" # type: Plain text #: usr_41.txt:218 #, no-wrap msgid "" "Then the value of s:call_count will be used as the name of the variable " "that\n" "exists() checks. That's not what you want.\n" " The exclamation mark ! negates a value. When the value was true, it\n" "becomes false. When it was false, it becomes true. You can read it as " "\"not\".\n" "Thus \"if !exists()\" can be read as \"if not exists()\".\n" " What Vim calls true is anything that is not zero. Zero is false.\n" "\tNote:\n" "\tVim automatically converts a string to a number when it is looking for\n" "\ta number. When using a string that doesn't start with a digit the\n" "\tresulting number is zero. Thus look out for this: >\n" "\t\t:if \"true\"\n" "<\tThe \"true\" will be interpreted as a zero, thus as false!\n" msgstr "" # type: Plain text #: usr_41.txt:221 msgid "STRING VARIABLES AND CONSTANTS" msgstr "" # type: Plain text #: usr_41.txt:228 #, no-wrap msgid "" "So far only numbers were used for the variable value. Strings can be used " "as\n" "well. Numbers and strings are the basic types of variables that Vim " "supports.\n" "The type is dynamic, it is set each time when assigning a value to the\n" "variable with \":let\". More about types in |41.8|.\n" " To assign a string value to a variable, you need to use a string " "constant.\n" "There are two types of these. First the string in double quotes: >\n" msgstr "" # type: Plain text #: usr_41.txt:232 #, no-wrap msgid "" "\t:let name = \"peter\"\n" "\t:echo name\n" "<\tpeter ~\n" msgstr "" # type: Plain text #: usr_41.txt:235 msgid "" "If you want to include a double quote inside the string, put a backslash in " "front of it: >" msgstr "" # type: Plain text #: usr_41.txt:239 #, no-wrap msgid "" "\t:let name = \"\\\"peter\\\"\"\n" "\t:echo name\n" "<\t\"peter\" ~\n" msgstr "" # type: Plain text #: usr_41.txt:241 msgid "To avoid the need for a backslash, you can use a string in single quotes: >" msgstr "" # type: Plain text #: usr_41.txt:245 #, no-wrap msgid "" "\t:let name = '\"peter\"'\n" "\t:echo name\n" "<\t\"peter\" ~\n" msgstr "" # type: Plain text #: usr_41.txt:252 #, no-wrap msgid "" "Inside a single-quote string all the characters are as they are. Only the\n" "single quote itself is special: you need to use two to get one. A " "backslash\n" "is taken literally, thus you can't use it to change the meaning of the\n" "character after it.\n" " In double-quote strings it is possible to use special characters. Here " "are\n" "a few useful ones:\n" msgstr "" # type: Plain text #: usr_41.txt:262 #, no-wrap msgid "" "\t\\t\t\t\n" "\t\\n\t\t, line break\n" "\t\\r\t\t, \n" "\t\\e\t\t\n" "\t\\b\t\t, backspace\n" "\t\\\"\t\t\"\n" "\t\\\\\t\t\\, backslash\n" "\t\\\t\t\n" "\t\\\t\tCTRL-W\n" msgstr "" # type: Plain text #: usr_41.txt:266 #, no-wrap msgid "" "The last two are just examples. The \"\\\" form can be used to " "include\n" "the special key \"name\".\n" " See |expr-quote| for the full list of special items in a string.\n" msgstr "" # type: Plain text #: usr_41.txt:269 #, no-wrap msgid "*41.3*\tExpressions\n" msgstr "" # type: Plain text #: usr_41.txt:276 #, no-wrap msgid "" "Vim has a rich, yet simple way to handle expressions. You can read the\n" "definition here: |expression-syntax|. Here we will show the most common\n" "items.\n" " The numbers, strings and variables mentioned above are expressions by\n" "themselves. Thus everywhere an expression is expected, you can use a " "number,\n" "string or variable. Other basic items in an expression are:\n" msgstr "" # type: Plain text #: usr_41.txt:280 #, no-wrap msgid "" "\t$NAME\t\tenvironment variable\n" "\t&name\t\toption\n" "\t@r\t\tregister\n" msgstr "" # type: Plain text #: usr_41.txt:282 msgid "Examples: >" msgstr "" # type: Plain text #: usr_41.txt:286 #, no-wrap msgid "" "\t:echo \"The value of 'tabstop' is\" &ts\n" "\t:echo \"Your home directory is\" $HOME\n" "\t:if @a > 5\n" msgstr "" # type: Plain text #: usr_41.txt:289 msgid "" "The &name form can be used to save an option value, set it to a new value, " "do something and restore the old value. Example: >" msgstr "" # type: Plain text #: usr_41.txt:294 #, no-wrap msgid "" "\t:let save_ic = &ic\n" "\t:set noic\n" "\t:/The Start/,$delete\n" "\t:let &ic = save_ic\n" msgstr "" # type: Plain text #: usr_41.txt:298 msgid "" "This makes sure the \"The Start\" pattern is used with the 'ignorecase' " "option off. Still, it keeps the value that the user had set. (Another way " "to do this would be to add \"\\C\" to the pattern, see |/\\C|.)" msgstr "" # type: Plain text #: usr_41.txt:301 msgid "MATHEMATICS" msgstr "" # type: Plain text #: usr_41.txt:304 msgid "" "It becomes more interesting if we combine these basic items. Let's start " "with mathematics on numbers:" msgstr "" # type: Plain text #: usr_41.txt:310 #, no-wrap msgid "" "\ta + b\t\tadd\n" "\ta - b\t\tsubtract\n" "\ta * b\t\tmultiply\n" "\ta / b\t\tdivide\n" "\ta % b\t\tmodulo\n" msgstr "" # type: Plain text #: usr_41.txt:312 msgid "The usual precedence is used. Example: >" msgstr "" # type: Plain text #: usr_41.txt:315 #, no-wrap msgid "" "\t:echo 10 + 5 * 2\n" "<\t20 ~\n" msgstr "" # type: Plain text #: usr_41.txt:317 msgid "Grouping is done with braces. No surprises here. Example: >" msgstr "" # type: Plain text #: usr_41.txt:320 #, no-wrap msgid "" "\t:echo (10 + 5) * 2\n" "<\t30 ~\n" msgstr "" # type: Plain text #: usr_41.txt:322 msgid "Strings can be concatenated with \".\". Example: >" msgstr "" # type: Plain text #: usr_41.txt:325 #, no-wrap msgid "" "\t:echo \"foo\" . \"bar\"\n" "<\tfoobar ~\n" msgstr "" # type: Plain text #: usr_41.txt:329 msgid "" "When the \":echo\" command gets multiple arguments, it separates them with a " "space. In the example the argument is a single expression, thus no space is " "inserted." msgstr "" # type: Plain text #: usr_41.txt:331 msgid "Borrowed from the C language is the conditional expression:" msgstr "" # type: Plain text #: usr_41.txt:333 #, no-wrap msgid "\ta ? b : c\n" msgstr "" # type: Plain text #: usr_41.txt:335 msgid "" "If \"a\" evaluates to true \"b\" is used, otherwise \"c\" is used. Example: " ">" msgstr "" # type: Plain text #: usr_41.txt:339 #, no-wrap msgid "" "\t:let i = 4\n" "\t:echo i > 5 ? \"i is big\" : \"i is small\"\n" "<\ti is small ~\n" msgstr "" # type: Plain text #: usr_41.txt:342 msgid "" "The three parts of the constructs are always evaluated first, thus you could " "see it work as:" msgstr "" # type: Plain text #: usr_41.txt:344 #, no-wrap msgid "\t(a) ? (b) : (c)\n" msgstr "" # type: Plain text #: usr_41.txt:347 #, no-wrap msgid "*41.4*\tConditionals\n" msgstr "" # type: Plain text #: usr_41.txt:350 msgid "" "The \":if\" commands executes the following statements, until the matching " "\":endif\", only when a condition is met. The generic form is:" msgstr "" # type: Plain text #: usr_41.txt:354 #, no-wrap msgid "" "\t:if {condition}\n" "\t {statements}\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:359 #, no-wrap msgid "" "Only when the expression {condition} evaluates to true (non-zero) will the\n" "{statements} be executed. These must still be valid commands. If they\n" "contain garbage, Vim won't be able to find the \":endif\".\n" " You can also use \":else\". The generic form for this is:\n" msgstr "" # type: Plain text #: usr_41.txt:365 #, no-wrap msgid "" "\t:if {condition}\n" "\t {statements}\n" "\t:else\n" "\t {statements}\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:368 #, no-wrap msgid "" "The second {statements} is only executed if the first one isn't.\n" " Finally, there is \":elseif\":\n" msgstr "" # type: Plain text #: usr_41.txt:374 #, no-wrap msgid "" "\t:if {condition}\n" "\t {statements}\n" "\t:elseif {condition}\n" "\t {statements}\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:379 #, no-wrap msgid "" "This works just like using \":else\" and then \"if\", but without the need " "for an\n" "extra \":endif\".\n" " A useful example for your vimrc file is checking the 'term' option and\n" "doing something depending upon its value: >\n" msgstr "" # type: Plain text #: usr_41.txt:387 #, no-wrap msgid "" "\t:if &term == \"xterm\"\n" "\t: \" Do stuff for xterm\n" "\t:elseif &term == \"vt100\"\n" "\t: \" Do stuff for a vt100 terminal\n" "\t:else\n" "\t: \" Do something for other terminals\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:390 msgid "LOGIC OPERATIONS" msgstr "" # type: Plain text #: usr_41.txt:393 msgid "" "We already used some of them in the examples. These are the most often used " "ones:" msgstr "" # type: Plain text #: usr_41.txt:400 #, no-wrap msgid "" "\ta == b\t\tequal to\n" "\ta != b\t\tnot equal to\n" "\ta > b\t\tgreater than\n" "\ta >= b\t\tgreater than or equal to\n" "\ta < b\t\tless than\n" "\ta <= b\t\tless than or equal to\n" msgstr "" # type: Plain text #: usr_41.txt:402 msgid "The result is one if the condition is met and zero otherwise. An example: >" msgstr "" # type: Plain text #: usr_41.txt:408 #, no-wrap msgid "" "\t:if v:version >= 700\n" "\t: echo \"congratulations\"\n" "\t:else\n" "\t: echo \"you are using an old version, upgrade!\"\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:413 msgid "" "Here \"v:version\" is a variable defined by Vim, which has the value of the " "Vim version. 600 is for version 6.0. Version 6.1 has the value 601. This " "is very useful to write a script that works with multiple versions of Vim. " "|v:version|" msgstr "" # type: Plain text #: usr_41.txt:420 #, no-wrap msgid "" "The logic operators work both for numbers and strings. When comparing two\n" "strings, the mathematical difference is used. This compares byte values,\n" "which may not be right for some languages.\n" " When comparing a string with a number, the string is first converted to " "a\n" "number. This is a bit tricky, because when a string doesn't look like a\n" "number, the number zero is used. Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:424 #, no-wrap msgid "" "\t:if 0 == \"one\"\n" "\t: echo \"yes\"\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:427 msgid "" "This will echo \"yes\", because \"one\" doesn't look like a number, thus it " "is converted to the number zero." msgstr "" # type: Plain text #: usr_41.txt:429 msgid "For strings there are two more items:" msgstr "" # type: Plain text #: usr_41.txt:432 #, no-wrap msgid "" "\ta =~ b\t\tmatches with\n" "\ta !~ b\t\tdoes not match with\n" msgstr "" # type: Plain text #: usr_41.txt:435 msgid "" "The left item \"a\" is used as a string. The right item \"b\" is used as a " "pattern, like what's used for searching. Example: >" msgstr "" # type: Plain text #: usr_41.txt:442 #, no-wrap msgid "" "\t:if str =~ \" \"\n" "\t: echo \"str contains a space\"\n" "\t:endif\n" "\t:if str !~ '\\.$'\n" "\t: echo \"str does not end in a full stop\"\n" "\t:endif\n" msgstr "" # type: Plain text #: usr_41.txt:446 msgid "" "Notice the use of a single-quote string for the pattern. This is useful, " "because backslashes would need to be doubled in a double-quote string and " "patterns tend to contain many backslashes." msgstr "" # type: Plain text #: usr_41.txt:452 msgid "" "The 'ignorecase' option is used when comparing strings. When you don't want " "that, append \"#\" to match case and \"?\" to ignore case. Thus \"==?\" " "compares two strings to be equal while ignoring case. And \"!~#\" checks if " "a pattern doesn't match, also checking the case of letters. For the full " "table see |expr-==|." msgstr "" # type: Plain text #: usr_41.txt:455 msgid "MORE LOOPING" msgstr "" # type: Plain text #: usr_41.txt:458 msgid "" "The \":while\" command was already mentioned. Two more statements can be " "used in between the \":while\" and the \":endwhile\":" msgstr "" # type: Plain text #: usr_41.txt:463 #, no-wrap msgid "" "\t:continue\t\tJump back to the start of the while loop; the\n" "\t\t\t\tloop continues.\n" "\t:break\t\t\tJump forward to the \":endwhile\"; the loop is\n" "\t\t\t\tdiscontinued.\n" msgstr "" # type: Plain text #: usr_41.txt:465 msgid "Example: >" msgstr "" # type: Plain text #: usr_41.txt:476 #, no-wrap msgid "" "\t:while counter < 40\n" "\t: call do_something()\n" "\t: if skip_flag\n" "\t: continue\n" "\t: endif\n" "\t: if finished_flag\n" "\t: break\n" "\t: endif\n" "\t: sleep 50m\n" "\t:endwhile\n" msgstr "" # type: Plain text #: usr_41.txt:479 msgid "" "The \":sleep\" command makes Vim take a nap. The \"50m\" specifies fifty " "milliseconds. Another example is \":sleep 4\", which sleeps for four " "seconds." msgstr "" # type: Plain text #: usr_41.txt:481 msgid "" "Even more looping can be done with the \":for\" command, see below in " "|41.8|." msgstr "" # type: Plain text #: usr_41.txt:484 #, no-wrap msgid "*41.5*\tExecuting an expression\n" msgstr "" # type: Plain text #: usr_41.txt:489 #, no-wrap msgid "" "So far the commands in the script were executed by Vim directly. The\n" "\":execute\" command allows executing the result of an expression. This is " "a\n" "very powerful way to build commands and execute them.\n" " An example is to jump to a tag, which is contained in a variable: >\n" msgstr "" # type: Plain text #: usr_41.txt:491 #, no-wrap msgid "\t:execute \"tag \" . tag_name\n" msgstr "" # type: Plain text #: usr_41.txt:495 msgid "" "The \".\" is used to concatenate the string \"tag \" with the value of " "variable \"tag_name\". Suppose \"tag_name\" has the value \"get_cmd\", then " "the command that will be executed is: >" msgstr "" # type: Plain text #: usr_41.txt:497 #, no-wrap msgid "\t:tag get_cmd\n" msgstr "" # type: Plain text #: usr_41.txt:501 msgid "" "The \":execute\" command can only execute colon commands. The \":normal\" " "command executes Normal mode commands. However, its argument is not an " "expression but the literal command characters. Example: >" msgstr "" # type: Plain text #: usr_41.txt:503 #, no-wrap msgid "\t:normal gg=G\n" msgstr "" # type: Plain text #: usr_41.txt:507 #, no-wrap msgid "" "This jumps to the first line and formats all lines with the \"=\" " "operator.\n" " To make \":normal\" work with an expression, combine \":execute\" with " "it.\n" "Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:509 #, no-wrap msgid "\t:execute \"normal \" . normal_commands\n" msgstr "" # type: Plain text #: usr_41.txt:514 #, no-wrap msgid "" "The variable \"normal_commands\" must contain the Normal mode commands.\n" " Make sure that the argument for \":normal\" is a complete command. " "Otherwise\n" "Vim will run into the end of the argument and abort the command. For " "example,\n" "if you start Insert mode, you must leave Insert mode as well. This works: " ">\n" msgstr "" # type: Plain text #: usr_41.txt:516 #, no-wrap msgid "\t:execute \"normal Inew text \\\"\n" msgstr "" # type: Plain text #: usr_41.txt:520 msgid "" "This inserts \"new text \" in the current line. Notice the use of the " "special key \"\\\". This avoids having to enter a real character " "in your script." msgstr "" # type: Plain text #: usr_41.txt:523 msgid "" "If you don't want to execute a string but evaluate it to get its expression " "value, you can use the eval() function: >" msgstr "" # type: Plain text #: usr_41.txt:526 #, no-wrap msgid "" "\t:let optname = \"path\"\n" "\t:let optval = eval('&' . optname)\n" msgstr "" # type: Plain text #: usr_41.txt:531 #, no-wrap msgid "" "A \"&\" character is prepended to \"path\", thus the argument to eval() is\n" "\"&path\". The result will then be the value of the 'path' option.\n" " The same thing can be done with: >\n" "\t:exe 'let optval = &' . optname\n" msgstr "" # type: Plain text #: usr_41.txt:534 #, no-wrap msgid "*41.6*\tUsing functions\n" msgstr "" # type: Plain text #: usr_41.txt:538 msgid "" "Vim defines many functions and provides a large amount of functionality that " "way. A few examples will be given in this section. You can find the whole " "list here: |functions|." msgstr "" # type: Plain text #: usr_41.txt:541 msgid "" "A function is called with the \":call\" command. The parameters are passed " "in between braces, separated by commas. Example: >" msgstr "" # type: Plain text #: usr_41.txt:543 #, no-wrap msgid "\t:call search(\"Date: \", \"W\")\n" msgstr "" # type: Plain text #: usr_41.txt:548 msgid "" "This calls the search() function, with arguments \"Date: \" and \"W\". The " "search() function uses its first argument as a search pattern and the second " "one as flags. The \"W\" flag means the search doesn't wrap around the end " "of the file." msgstr "" # type: Plain text #: usr_41.txt:550 msgid "A function can be called in an expression. Example: >" msgstr "" # type: Plain text #: usr_41.txt:554 #, no-wrap msgid "" "\t:let line = getline(\".\")\n" "\t:let repl = substitute(line, '\\a', \"*\", \"g\")\n" "\t:call setline(\".\", repl)\n" msgstr "" # type: Plain text #: usr_41.txt:566 #, no-wrap msgid "" "The getline() function obtains a line from the current buffer. Its " "argument\n" "is a specification of the line number. In this case \".\" is used, which " "means\n" "the line where the cursor is.\n" " The substitute() function does something similar to the \":substitute\"\n" "command. The first argument is the string on which to perform the\n" "substitution. The second argument is the pattern, the third the " "replacement\n" "string. Finally, the last arguments are the flags.\n" " The setline() function sets the line, specified by the first argument, to " "a\n" "new string, the second argument. In this example the line under the cursor " "is\n" "replaced with the result of the substitute(). Thus the effect of the " "three\n" "statements is equal to: >\n" msgstr "" # type: Plain text #: usr_41.txt:568 #, no-wrap msgid "\t:substitute/\\a/*/g\n" msgstr "" # type: Plain text #: usr_41.txt:571 msgid "" "Using the functions becomes more interesting when you do more work before " "and after the substitute() call." msgstr "" # type: Plain text #: usr_41.txt:574 #, no-wrap msgid "FUNCTIONS\t\t\t\t\t\t*function-list*\n" msgstr "" # type: Plain text #: usr_41.txt:578 msgid "" "There are many functions. We will mention them here, grouped by what they " "are used for. You can find an alphabetical list here: |functions|. Use " "CTRL-] on the function name to jump to detailed help on it." msgstr "" # type: Plain text #: usr_41.txt:604 #, no-wrap msgid "" "String manipulation:\n" "\tnr2char()\t\tget a character by its ASCII value\n" "\tchar2nr()\t\tget ASCII value of a character\n" "\tstr2nr()\t\tconvert a string to a number\n" "\tprintf()\t\tformat a string according to % items\n" "\tescape()\t\tescape characters in a string with a '\\'\n" "\ttr()\t\t\ttranslate characters from one set to another\n" "\tstrtrans()\t\ttranslate a string to make it printable\n" "\ttolower()\t\tturn a string to lowercase\n" "\ttoupper()\t\tturn a string to uppercase\n" "\tmatch()\t\t\tposition where a pattern matches in a string\n" "\tmatchend()\t\tposition where a pattern match ends in a string\n" "\tmatchstr()\t\tmatch of a pattern in a string\n" "\tmatchlist()\t\tlike matchstr() and also return submatches\n" "\tstridx()\t\tfirst index of a short string in a long string\n" "\tstrridx()\t\tlast index of a short string in a long string\n" "\tstrlen()\t\tlength of a string\n" "\tsubstitute()\t\tsubstitute a pattern match with a string\n" "\tsubmatch()\t\tget a specific match in a \":substitute\"\n" "\tstrpart()\t\tget part of a string\n" "\texpand()\t\texpand special keywords\n" "\ticonv()\t\t\tconvert text from one encoding to another\n" "\tbyteidx()\t\tbyte index of a character in a string\n" "\trepeat()\t\trepeat a string multiple times\n" "\teval()\t\t\tevaluate a string expression\n" msgstr "" # type: Plain text #: usr_41.txt:629 #, no-wrap msgid "" "List manipulation:\n" "\tget()\t\t\tget an item without error for wrong index\n" "\tlen()\t\t\tnumber of items in a List\n" "\tempty()\t\t\tcheck if List is empty\n" "\tinsert()\t\tinsert an item somewhere in a List\n" "\tadd()\t\t\tappend an item to a List\n" "\textend()\t\tappend a List to a List\n" "\tremove()\t\tremove one or more items from a List\n" "\tcopy()\t\t\tmake a shallow copy of a List\n" "\tdeepcopy()\t\tmake a full copy of a List\n" "\tfilter()\t\tremove selected items from a List\n" "\tmap()\t\t\tchange each List item\n" "\tsort()\t\t\tsort a List\n" "\treverse()\t\treverse the order of a List\n" "\tsplit()\t\t\tsplit a String into a List\n" "\tjoin()\t\t\tjoin List items into a String\n" "\trange()\t\t\treturn a List with a sequence of numbers\n" "\tstring()\t\tString representation of a List\n" "\tcall()\t\t\tcall a function with List as arguments\n" "\tindex()\t\t\tindex of a value in a List\n" "\tmax()\t\t\tmaximum value in a List\n" "\tmin()\t\t\tminimum value in a List\n" "\tcount()\t\t\tcount number of times a value appears in a List\n" "\trepeat()\t\trepeat a List multiple times\n" msgstr "" # type: Plain text #: usr_41.txt:648 #, no-wrap msgid "" "Dictionary manipulation:\n" "\tget()\t\t\tget an entry without an error for a wrong key\n" "\tlen()\t\t\tnumber of entries in a Dictionary\n" "\thas_key()\t\tcheck whether a key appears in a Dictionary\n" "\tempty()\t\t\tcheck if Dictionary is empty\n" "\tremove()\t\tremove an entry from a Dictionary\n" "\textend()\t\tadd entries from one Dictionary to another\n" "\tfilter()\t\tremove selected entries from a Dictionary\n" "\tmap()\t\t\tchange each Dictionary entry\n" "\tkeys()\t\t\tget List of Dictionary keys\n" "\tvalues()\t\tget List of Dictionary values\n" "\titems()\t\t\tget List of Dictionary key-value pairs\n" "\tcopy()\t\t\tmake a shallow copy of a Dictionary\n" "\tdeepcopy()\t\tmake a full copy of a Dictionary\n" "\tstring()\t\tString representation of a Dictionary\n" "\tmax()\t\t\tmaximum value in a Dictionary\n" "\tmin()\t\t\tminimum value in a Dictionary\n" "\tcount()\t\t\tcount number of times a value appears\n" msgstr "" # type: Plain text #: usr_41.txt:660 #, no-wrap msgid "" "Variables:\n" "\ttype()\t\t\ttype of a variable\n" "\tislocked()\t\tcheck if a variable is locked\n" "\tfunction()\t\tget a Funcref for a function name\n" "\tgetbufvar()\t\tget a variable value from a specific buffer\n" "\tsetbufvar()\t\tset a variable in a specific buffer\n" "\tgetwinvar()\t\tget a variable from specific window\n" "\tgettabwinvar()\t\tget a variable from specific window & tab page\n" "\tsetwinvar()\t\tset a variable in a specific window\n" "\tsettabwinvar()\t\tset a variable in a specific window & tab page\n" "\tgarbagecollect()\tpossibly free memory\n" msgstr "" # type: Plain text #: usr_41.txt:673 #, no-wrap msgid "" "Cursor and mark position:\n" "\tcol()\t\t\tcolumn number of the cursor or a mark\n" "\tvirtcol()\t\tscreen column of the cursor or a mark\n" "\tline()\t\t\tline number of the cursor or mark\n" "\twincol()\t\twindow column number of the cursor\n" "\twinline()\t\twindow line number of the cursor\n" "\tcursor()\t\tposition the cursor at a line/column\n" "\tgetpos()\t\tget position of cursor, mark, etc.\n" "\tsetpos()\t\tset position of cursor, mark, etc.\n" "\tbyte2line()\t\tget line number at a specific byte count\n" "\tline2byte()\t\tbyte count at a specific line\n" "\tdiff_filler()\t\tget the number of filler lines above a line\n" msgstr "" # type: Plain text #: usr_41.txt:688 #, no-wrap msgid "" "Working with text in the current buffer:\n" "\tgetline()\t\tget a line or list of lines from the buffer\n" "\tsetline()\t\treplace a line in the buffer\n" "\tappend()\t\tappend line or list of lines in the buffer\n" "\tindent()\t\tindent of a specific line\n" "\tcindent()\t\tindent according to C indenting\n" "\tlispindent()\t\tindent according to Lisp indenting\n" "\tnextnonblank()\t\tfind next non-blank line\n" "\tprevnonblank()\t\tfind previous non-blank line\n" "\tsearch()\t\tfind a match for a pattern\n" "\tsearchpos()\t\tfind a match for a pattern\n" "\tsearchpair()\t\tfind the other end of a start/skip/end\n" "\tsearchpairpos()\t\tfind the other end of a start/skip/end\n" "\tsearchdecl()\t\tsearch for the declaration of a name\n" msgstr "" # type: Plain text #: usr_41.txt:714 #, no-wrap msgid "" "System functions and manipulation of files:\n" "\tglob()\t\t\texpand wildcards\n" "\tglobpath()\t\texpand wildcards in a number of directories\n" "\tfindfile()\t\tfind a file in a list of directories\n" "\tfinddir()\t\tfind a directory in a list of directories\n" "\tresolve()\t\tfind out where a shortcut points to\n" "\tfnamemodify()\t\tmodify a file name\n" "\tpathshorten()\t\tshorten directory names in a path\n" "\tsimplify()\t\tsimplify a path without changing its meaning\n" "\texecutable()\t\tcheck if an executable program exists\n" "\tfilereadable()\t\tcheck if a file can be read\n" "\tfilewritable()\t\tcheck if a file can be written to\n" "\tgetfperm()\t\tget the permissions of a file\n" "\tgetftype()\t\tget the kind of a file\n" "\tisdirectory()\t\tcheck if a directory exists\n" "\tgetfsize()\t\tget the size of a file\n" "\tgetcwd()\t\tget the current working directory\n" "\ttempname()\t\tget the name of a temporary file\n" "\tmkdir()\t\t\tcreate a new directory\n" "\tdelete()\t\tdelete a file\n" "\trename()\t\trename a file\n" "\tsystem()\t\tget the result of a shell command\n" "\thostname()\t\tname of the system\n" "\treadfile()\t\tread a file into a List of lines\n" "\twritefile()\t\twrite a List of lines into a file\n" msgstr "" # type: Plain text #: usr_41.txt:721 #, no-wrap msgid "" "Date and Time:\n" "\tgetftime()\t\tget last modification time of a file\n" "\tlocaltime()\t\tget current time in seconds\n" "\tstrftime()\t\tconvert time to a string\n" "\treltime()\t\tget the current or elapsed time accurately\n" "\treltimestr()\t\tconvert reltime() result to a string\n" msgstr "" # type: Plain text #: usr_41.txt:738 #, no-wrap msgid "" "Buffers, windows and the argument list:\n" "\targc()\t\t\tnumber of entries in the argument list\n" "\targidx()\t\tcurrent position in the argument list\n" "\targv()\t\t\tget one entry from the argument list\n" "\tbufexists()\t\tcheck if a buffer exists\n" "\tbuflisted()\t\tcheck if a buffer exists and is listed\n" "\tbufloaded()\t\tcheck if a buffer exists and is loaded\n" "\tbufname()\t\tget the name of a specific buffer\n" "\tbufnr()\t\t\tget the buffer number of a specific buffer\n" "\ttabpagebuflist()\treturn List of buffers in a tab page\n" "\ttabpagenr()\t\tget the number of a tab page\n" "\ttabpagewinnr()\t\tlike winnr() for a specified tab page\n" "\twinnr()\t\t\tget the window number for the current window\n" "\tbufwinnr()\t\tget the window number of a specific buffer\n" "\twinbufnr()\t\tget the buffer number of a specific window\n" "\tgetbufline()\t\tget a list of lines from the specified buffer\n" msgstr "" # type: Plain text #: usr_41.txt:744 #, no-wrap msgid "" "Command line:\n" "\tgetcmdline()\t\tget the current command line\n" "\tgetcmdpos()\t\tget position of the cursor in the command line\n" "\tsetcmdpos()\t\tset position of the cursor in the command line\n" "\tgetcmdtype()\t\treturn the current command-line type\n" msgstr "" # type: Plain text #: usr_41.txt:750 #, no-wrap msgid "" "Quickfix and location lists:\n" "\tgetqflist()\t\tlist of quickfix errors\n" "\tsetqflist()\t\tmodify a quickfix list\n" "\tgetloclist()\t\tlist of location list items\n" "\tsetloclist()\t\tmodify a location list\n" msgstr "" # type: Plain text #: usr_41.txt:756 #, no-wrap msgid "" "Insert mode completion:\n" "\tcomplete()\t\tset found matches\n" "\tcomplete_add()\t\tadd to found matches\n" "\tcomplete_check()\tcheck if completion should be aborted\n" "\tpumvisible()\t\tcheck if the popup menu is displayed\n" msgstr "" # type: Plain text #: usr_41.txt:763 #, no-wrap msgid "" "Folding:\n" "\tfoldclosed()\t\tcheck for a closed fold at a specific line\n" "\tfoldclosedend()\t\tlike foldclosed() but return the last line\n" "\tfoldlevel()\t\tcheck for the fold level at a specific line\n" "\tfoldtext()\t\tgenerate the line displayed for a closed fold\n" "\tfoldtextresult()\tget the text displayed for a closed fold\n" msgstr "" # type: Plain text #: usr_41.txt:772 #, no-wrap msgid "" "Syntax and highlighting:\n" "\thlexists()\t\tcheck if a highlight group exists\n" "\thlID()\t\t\tget ID of a highlight group\n" "\tsynID()\t\t\tget syntax ID at a specific position\n" "\tsynIDattr()\t\tget a specific attribute of a syntax ID\n" "\tsynIDtrans()\t\tget translated syntax ID\n" "\tdiff_hlID()\t\tget highlight ID for diff mode at a position\n" "\tmatcharg()\t\tget info about |:match| arguments\n" msgstr "" # type: Plain text #: usr_41.txt:777 #, no-wrap msgid "" "Spelling:\n" "\tspellbadword()\t\tlocate badly spelled word at or after cursor\n" "\tspellsuggest()\t\treturn suggested spelling corrections\n" "\tsoundfold()\t\treturn the sound-a-like equivalent of a word\n" msgstr "" # type: Plain text #: usr_41.txt:783 #, no-wrap msgid "" "History:\n" "\thistadd()\t\tadd an item to a history\n" "\thistdel()\t\tdelete an item from a history\n" "\thistget()\t\tget an item from a history\n" "\thistnr()\t\tget highest index of a history list\n" msgstr "" # type: Plain text #: usr_41.txt:796 #, no-wrap msgid "" "Interactive:\n" "\tbrowse()\t\tput up a file requester\n" "\tbrowsedir()\t\tput up a directory requester\n" "\tconfirm()\t\tlet the user make a choice\n" "\tgetchar()\t\tget a character from the user\n" "\tgetcharmod()\t\tget modifiers for the last typed character\n" "\tinput()\t\t\tget a line from the user\n" "\tinputlist()\t\tlet the user pick an entry from a list\n" "\tinputsecret()\t\tget a line from the user without showing it\n" "\tinputdialog()\t\tget a line from the user in a dialog\n" "\tinputsave()\t\tsave and clear typeahead\n" "\tinputrestore()\t\trestore typeahead\n" msgstr "" # type: Plain text #: usr_41.txt:801 #, no-wrap msgid "" "GUI:\n" "\tgetfontname()\t\tget name of current font being used\n" "\tgetwinposx()\t\tX position of the GUI Vim window\n" "\tgetwinposy()\t\tY position of the GUI Vim window\n" msgstr "" # type: Plain text #: usr_41.txt:811 #, no-wrap msgid "" "Vim server:\n" "\tserverlist()\t\treturn the list of server names\n" "\tremote_send()\t\tsend command characters to a Vim server\n" "\tremote_expr()\t\tevaluate an expression in a Vim server\n" "\tserver2client()\t\tsend a reply to a client of a Vim server\n" "\tremote_peek()\t\tcheck if there is a reply from a Vim server\n" "\tremote_read()\t\tread a reply from a Vim server\n" "\tforeground()\t\tmove the Vim window to the foreground\n" "\tremote_foreground()\tmove the Vim server window to the foreground\n" msgstr "" # type: Plain text #: usr_41.txt:818 #, no-wrap msgid "" "Window size and position:\n" "\twinheight()\t\tget height of a specific window\n" "\twinwidth()\t\tget width of a specific window\n" "\twinrestcmd()\t\treturn command to restore window sizes\n" "\twinsaveview()\t\tget view of current window\n" "\twinrestview()\t\trestore saved view of current window\n" msgstr "" # type: Plain text #: usr_41.txt:831 #, no-wrap msgid "" "Various:\n" "\tmode()\t\t\tget current editing mode\n" "\tvisualmode()\t\tlast visual mode used\n" "\thasmapto()\t\tcheck if a mapping exists\n" "\tmapcheck()\t\tcheck if a matching mapping exists\n" "\tmaparg()\t\tget rhs of a mapping\n" "\texists()\t\tcheck if a variable, function, etc. exists\n" "\thas()\t\t\tcheck if a feature is supported in Vim\n" "\tchangenr()\t\treturn number of most recent change\n" "\tcscope_connection()\tcheck if a cscope connection exists\n" "\tdid_filetype()\t\tcheck if a FileType autocommand was used\n" "\teventhandler()\t\tcheck if invoked by an event handler\n" msgstr "" # type: Plain text #: usr_41.txt:834 #, no-wrap msgid "" "\tlibcall()\t\tcall a function in an external library\n" "\tlibcallnr()\t\tidem, returning a number\n" msgstr "" # type: Plain text #: usr_41.txt:838 #, no-wrap msgid "" "\tgetreg()\t\tget contents of a register\n" "\tgetregtype()\t\tget type of a register\n" "\tsetreg()\t\tset contents and type of a register\n" msgstr "" # type: Plain text #: usr_41.txt:841 #, no-wrap msgid "" "\ttaglist()\t\tget list of matching tags\n" "\ttagfiles()\t\tget a list of tags files\n" msgstr "" # type: Plain text #: usr_41.txt:844 #, no-wrap msgid "*41.7*\tDefining a function\n" msgstr "" # type: Plain text #: usr_41.txt:847 msgid "" "Vim enables you to define your own functions. The basic function " "declaration begins as follows: >" msgstr "" # type: Plain text #: usr_41.txt:854 #, no-wrap msgid "" "\t:function {name}({var1}, {var2}, ...)\n" "\t: {body}\n" "\t:endfunction\n" "<\n" "\tNote:\n" "\tFunction names must begin with a capital letter.\n" msgstr "" # type: Plain text #: usr_41.txt:857 msgid "" "Let's define a short function to return the smaller of two numbers. It " "starts with this line: >" msgstr "" # type: Plain text #: usr_41.txt:859 #, no-wrap msgid "\t:function Min(num1, num2)\n" msgstr "" # type: Plain text #: usr_41.txt:865 #, no-wrap msgid "" "This tells Vim that the function is named \"Min\" and it takes two " "arguments:\n" "\"num1\" and \"num2\".\n" " The first thing you need to do is to check to see which number is " "smaller:\n" " >\n" "\t: if a:num1 < a:num2\n" msgstr "" # type: Plain text #: usr_41.txt:868 msgid "" "The special prefix \"a:\" tells Vim that the variable is a function " "argument. Let's assign the variable \"smaller\" the value of the smallest " "number: >" msgstr "" # type: Plain text #: usr_41.txt:874 #, no-wrap msgid "" "\t: if a:num1 < a:num2\n" "\t: let smaller = a:num1\n" "\t: else\n" "\t: let smaller = a:num2\n" "\t: endif\n" msgstr "" # type: Plain text #: usr_41.txt:877 msgid "" "The variable \"smaller\" is a local variable. Variables used inside a " "function are local unless prefixed by something like \"g:\", \"a:\", or " "\"s:\"." msgstr "" # type: Plain text #: usr_41.txt:883 #, no-wrap msgid "" "\tNote:\n" "\tTo access a global variable from inside a function you must prepend\n" "\t\"g:\" to it. Thus \"g:count\" inside a function is used for the global\n" "\tvariable \"count\", and \"count\" is another variable, local to the\n" "\tfunction.\n" msgstr "" # type: Plain text #: usr_41.txt:886 msgid "" "You now use the \":return\" statement to return the smallest number to the " "user. Finally, you end the function: >" msgstr "" # type: Plain text #: usr_41.txt:889 #, no-wrap msgid "" "\t: return smaller\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:891 msgid "The complete function definition is as follows: >" msgstr "" # type: Plain text #: usr_41.txt:900 #, no-wrap msgid "" "\t:function Min(num1, num2)\n" "\t: if a:num1 < a:num2\n" "\t: let smaller = a:num1\n" "\t: else\n" "\t: let smaller = a:num2\n" "\t: endif\n" "\t: return smaller\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:902 msgid "For people who like short functions, this does the same thing: >" msgstr "" # type: Plain text #: usr_41.txt:909 #, no-wrap msgid "" "\t:function Min(num1, num2)\n" "\t: if a:num1 < a:num2\n" "\t: return a:num1\n" "\t: endif\n" "\t: return a:num2\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:913 msgid "" "A user defined function is called in exactly the same way as a built-in " "function. Only the name is different. The Min function can be used like " "this: >" msgstr "" # type: Plain text #: usr_41.txt:915 #, no-wrap msgid "\t:echo Min(5, 8)\n" msgstr "" # type: Plain text #: usr_41.txt:920 msgid "" "Only now will the function be executed and the lines be interpreted by Vim. " "If there are mistakes, like using an undefined variable or function, you " "will now get an error message. When defining the function these errors are " "not detected." msgstr "" # type: Plain text #: usr_41.txt:923 msgid "" "When a function reaches \":endfunction\" or \":return\" is used without an " "argument, the function returns zero." msgstr "" # type: Plain text #: usr_41.txt:926 msgid "" "To redefine a function that already exists, use the ! for the \":function\" " "command: >" msgstr "" # type: Plain text #: usr_41.txt:928 #, no-wrap msgid "\t:function! Min(num1, num2, num3)\n" msgstr "" # type: Plain text #: usr_41.txt:931 msgid "USING A RANGE" msgstr "" # type: Plain text #: usr_41.txt:938 #, no-wrap msgid "" "The \":call\" command can be given a line range. This can have one of two\n" "meanings. When a function has been defined with the \"range\" keyword, it " "will\n" "take care of the line range itself.\n" " The function will be passed the variables \"a:firstline\" and " "\"a:lastline\".\n" "These will have the line numbers from the range the function was called " "with.\n" "Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:948 #, no-wrap msgid "" "\t:function Count_words() range\n" "\t: let n = a:firstline\n" "\t: let count = 0\n" "\t: while n <= a:lastline\n" "\t: let count = count + Wordcount(getline(n))\n" "\t: let n = n + 1\n" "\t: endwhile\n" "\t: echo \"found \" . count . \" words\"\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:950 msgid "You can call this function with: >" msgstr "" # type: Plain text #: usr_41.txt:952 #, no-wrap msgid "\t:10,30call Count_words()\n" msgstr "" # type: Plain text #: usr_41.txt:957 #, no-wrap msgid "" "It will be executed once and echo the number of words.\n" " The other way to use a line range is by defining a function without the\n" "\"range\" keyword. The function will be called once for every line in the\n" "range, with the cursor in that line. Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:961 #, no-wrap msgid "" "\t:function Number()\n" "\t: echo \"line \" . line(\".\") . \" contains: \" . getline(\".\")\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:963 msgid "If you call this function with: >" msgstr "" # type: Plain text #: usr_41.txt:965 #, no-wrap msgid "\t:10,15call Number()\n" msgstr "" # type: Plain text #: usr_41.txt:967 msgid "The function will be called six times." msgstr "" # type: Plain text #: usr_41.txt:970 msgid "VARIABLE NUMBER OF ARGUMENTS" msgstr "" # type: Plain text #: usr_41.txt:974 msgid "" "Vim enables you to define functions that have a variable number of " "arguments. The following command, for instance, defines a function that " "must have 1 argument (start) and can have up to 20 additional arguments: >" msgstr "" # type: Plain text #: usr_41.txt:976 #, no-wrap msgid "\t:function Show(start, ...)\n" msgstr "" # type: Plain text #: usr_41.txt:980 #, no-wrap msgid "" "The variable \"a:1\" contains the first optional argument, \"a:2\" the " "second, and\n" "so on. The variable \"a:0\" contains the number of extra arguments.\n" " For example: >\n" msgstr "" # type: Plain text #: usr_41.txt:992 #, no-wrap msgid "" "\t:function Show(start, ...)\n" "\t: echohl Title\n" "\t: echo \"Show is \" . a:start\n" "\t: echohl None\n" "\t: let index = 1\n" "\t: while index <= a:0\n" "\t: echo \" Arg \" . index . \" is \" . a:{index}\n" "\t: let index = index + 1\n" "\t: endwhile\n" "\t: echo \"\"\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:996 msgid "" "This uses the \":echohl\" command to specify the highlighting used for the " "following \":echo\" command. \":echohl None\" stops it again. The " "\":echon\" command works like \":echo\", but doesn't output a line break." msgstr "" # type: Plain text #: usr_41.txt:999 msgid "" "You can also use the a:000 variable, it is a List of all the \"...\" " "arguments. See |a:000|." msgstr "" # type: Plain text #: usr_41.txt:1002 msgid "LISTING FUNCTIONS" msgstr "" # type: Plain text #: usr_41.txt:1005 msgid "" "The \":function\" command lists the names and arguments of all user-defined " "functions: >" msgstr "" # type: Plain text #: usr_41.txt:1010 #, no-wrap msgid "" "\t:function\n" "<\tfunction Show(start, ...) ~\n" "\tfunction GetVimIndent() ~\n" "\tfunction SetSyn(name) ~\n" msgstr "" # type: Plain text #: usr_41.txt:1012 msgid "" "To see what a function does, use its name as an argument for \":function\": " ">" msgstr "" # type: Plain text #: usr_41.txt:1018 #, no-wrap msgid "" "\t:function SetSyn\n" "<\t1 if &syntax == '' ~\n" "\t2 let &syntax = a:name ~\n" "\t3 endif ~\n" "\t endfunction ~\n" msgstr "" # type: Plain text #: usr_41.txt:1021 msgid "DEBUGGING" msgstr "" # type: Plain text #: usr_41.txt:1026 #, no-wrap msgid "" "The line number is useful for when you get an error message or when " "debugging.\n" "See |debug-scripts| about debugging mode.\n" " You can also set the 'verbose' option to 12 or higher to see all " "function\n" "calls. Set it to 15 or higher to see every executed line.\n" msgstr "" # type: Plain text #: usr_41.txt:1029 msgid "DELETING A FUNCTION" msgstr "" # type: Plain text #: usr_41.txt:1031 msgid "To delete the Show() function: >" msgstr "" # type: Plain text #: usr_41.txt:1033 #, no-wrap msgid "\t:delfunction Show\n" msgstr "" # type: Plain text #: usr_41.txt:1035 msgid "You get an error when the function doesn't exist." msgstr "" # type: Plain text #: usr_41.txt:1038 msgid "FUNCTION REFERENCES" msgstr "" # type: Plain text #: usr_41.txt:1042 msgid "" "Sometimes it can be useful to have a variable point to one function or " "another. You can do it with the function() function. It turns the name of " "a function into a reference: >" msgstr "" # type: Plain text #: usr_41.txt:1058 #, no-wrap msgid "" "\t:let result = 0\t\t\" or 1\n" "\t:function! Right()\n" "\t: return 'Right!'\n" "\t:endfunc\n" "\t:function! Wrong()\n" "\t: return 'Wrong!'\n" "\t:endfunc\n" "\t:\n" "\t:if result == 1\n" "\t: let Afunc = function('Right')\n" "\t:else\n" "\t: let Afunc = function('Wrong')\n" "\t:endif\n" "\t:echo call(Afunc, [])\n" "<\tWrong! ~\n" msgstr "" # type: Plain text #: usr_41.txt:1065 #, no-wrap msgid "" "Note that the name of a variable that holds a function reference must " "start\n" "with a capital. Otherwise it could be confused with the name of a builtin\n" "function.\n" " The way to invoke a function that a variable refers to is with the " "call()\n" "function. Its first argument is the function reference, the second " "argument\n" "is a List with arguments.\n" msgstr "" # type: Plain text #: usr_41.txt:1068 msgid "" "Function references are most useful in combination with a Dictionary, as is " "explained in the next section." msgstr "" # type: Plain text #: usr_41.txt:1071 #, no-wrap msgid "*41.8*\tLists and Dictionaries\n" msgstr "" # type: Plain text #: usr_41.txt:1074 msgid "" "So far we have used the basic types String and Number. Vim also supports " "two composite types: List and Dictionary." msgstr "" # type: Plain text #: usr_41.txt:1078 msgid "" "A List is an ordered sequence of things. The things can be any kind of " "value, thus you can make a List of numbers, a List of Lists and even a List " "of mixed items. To create a List with three strings: >" msgstr "" # type: Plain text #: usr_41.txt:1080 #, no-wrap msgid "\t:let alist = ['aap', 'mies', 'noot']\n" msgstr "" # type: Plain text #: usr_41.txt:1083 msgid "" "The List items are enclosed in square brackets and separated by commas. To " "create an empty List: >" msgstr "" # type: Plain text #: usr_41.txt:1085 #, no-wrap msgid "\t:let alist = []\n" msgstr "" # type: Plain text #: usr_41.txt:1087 msgid "You can add items to a List with the add() function: >" msgstr "" # type: Plain text #: usr_41.txt:1093 #, no-wrap msgid "" "\t:let alist = []\n" "\t:call add(alist, 'foo')\n" "\t:call add(alist, 'bar')\n" "\t:echo alist\n" "<\t['foo', 'bar'] ~\n" msgstr "" # type: Plain text #: usr_41.txt:1095 msgid "List concatenation is done with +: >" msgstr "" # type: Plain text #: usr_41.txt:1098 #, no-wrap msgid "" "\t:echo alist + ['foo', 'bar']\n" "<\t['foo', 'bar', 'foo', 'bar'] ~\n" msgstr "" # type: Plain text #: usr_41.txt:1100 msgid "Or, if you want to extend a List directly: >" msgstr "" # type: Plain text #: usr_41.txt:1105 #, no-wrap msgid "" "\t:let alist = ['one']\n" "\t:call extend(alist, ['two', 'three'])\n" "\t:echo alist\n" "<\t['one', 'two', 'three'] ~\n" msgstr "" # type: Plain text #: usr_41.txt:1107 msgid "Notice that using add() will have a different effect: >" msgstr "" # type: Plain text #: usr_41.txt:1112 #, no-wrap msgid "" "\t:let alist = ['one']\n" "\t:call add(alist, ['two', 'three'])\n" "\t:echo alist\n" "<\t['one', ['two', 'three']] ~\n" msgstr "" # type: Plain text #: usr_41.txt:1114 msgid "The second argument of add() is added as a single item." msgstr "" # type: Plain text #: usr_41.txt:1117 msgid "FOR LOOP" msgstr "" # type: Plain text #: usr_41.txt:1119 msgid "One of the nice things you can do with a List is iterate over it: >" msgstr "" # type: Plain text #: usr_41.txt:1127 #, no-wrap msgid "" "\t:let alist = ['one', 'two', 'three']\n" "\t:for n in alist\n" "\t: echo n\n" "\t:endfor\n" "<\tone ~\n" "\ttwo ~\n" "\tthree ~\n" msgstr "" # type: Plain text #: usr_41.txt:1130 msgid "" "This will loop over each element in List \"alist\", assigning the value to " "variable \"n\". The generic form of a for loop is: >" msgstr "" # type: Plain text #: usr_41.txt:1134 #, no-wrap msgid "" "\t:for {varname} in {listexpression}\n" "\t: {commands}\n" "\t:endfor\n" msgstr "" # type: Plain text #: usr_41.txt:1137 msgid "" "To loop a certain number of times you need a List of a specific length. The " "range() function creates one for you: >" msgstr "" # type: Plain text #: usr_41.txt:1144 #, no-wrap msgid "" "\t:for a in range(3)\n" "\t: echo a\n" "\t:endfor\n" "<\t0 ~\n" "\t1 ~\n" "\t2 ~\n" msgstr "" # type: Plain text #: usr_41.txt:1148 #, no-wrap msgid "" "Notice that the first item of the List that range() produces is zero, thus " "the\n" "last item is one less than the length of the list.\n" " You can also specify the maximum value, the stride and even go backwards: " ">\n" msgstr "" # type: Plain text #: usr_41.txt:1155 #, no-wrap msgid "" "\t:for a in range(8, 4, -2)\n" "\t: echo a\n" "\t:endfor\n" "<\t8 ~\n" "\t6 ~\n" "\t4 ~\n" msgstr "" # type: Plain text #: usr_41.txt:1157 msgid "A more useful example, looping over lines in the buffer: >" msgstr "" # type: Plain text #: usr_41.txt:1163 #, no-wrap msgid "" "\t:for line in getline(1, 20)\n" "\t: if line =~ \"Date: \"\n" "\t: echo matchstr(line, 'Date: \\zs.*')\n" "\t: endif\n" "\t:endfor\n" msgstr "" # type: Plain text #: usr_41.txt:1165 msgid "" "This looks into lines 1 to 20 (inclusive) and echoes any date found in " "there." msgstr "" # type: Plain text #: usr_41.txt:1168 msgid "DICTIONARIES" msgstr "" # type: Plain text #: usr_41.txt:1171 msgid "" "A Dictionary stores key-value pairs. You can quickly lookup a value if you " "know the key. A Dictionary is created with curly braces: >" msgstr "" # type: Plain text #: usr_41.txt:1173 #, no-wrap msgid "\t:let uk2nl = {'one': 'een', 'two': 'twee', 'three': 'drie'}\n" msgstr "" # type: Plain text #: usr_41.txt:1175 msgid "Now you can lookup words by putting the key in square brackets: >" msgstr "" # type: Plain text #: usr_41.txt:1178 #, no-wrap msgid "" "\t:echo uk2nl['two']\n" "<\ttwee ~\n" msgstr "" # type: Plain text #: usr_41.txt:1180 msgid "The generic form for defining a Dictionary is: >" msgstr "" # type: Plain text #: usr_41.txt:1182 #, no-wrap msgid "\t{ : , ...}\n" msgstr "" # type: Plain text #: usr_41.txt:1184 msgid "An empty Dictionary is one without any keys: >" msgstr "" # type: Plain text #: usr_41.txt:1186 #, no-wrap msgid "\t{}\n" msgstr "" # type: Plain text #: usr_41.txt:1190 msgid "" "The possibilities with Dictionaries are numerous. There are various " "functions for them as well. For example, you can obtain a list of the keys " "and loop over them: >" msgstr "" # type: Plain text #: usr_41.txt:1197 #, no-wrap msgid "" "\t:for key in keys(uk2nl)\n" "\t: echo key\n" "\t:endfor\n" "<\tthree ~\n" "\tone ~\n" "\ttwo ~\n" msgstr "" # type: Plain text #: usr_41.txt:1200 msgid "" "The will notice the keys are not ordered. You can sort the list to get a " "specific order: >" msgstr "" # type: Plain text #: usr_41.txt:1207 #, no-wrap msgid "" "\t:for key in sort(keys(uk2nl))\n" "\t: echo key\n" "\t:endfor\n" "<\tone ~\n" "\tthree ~\n" "\ttwo ~\n" msgstr "" # type: Plain text #: usr_41.txt:1210 msgid "" "But you can never get back the order in which items are defined. For that " "you need to use a List, it stores items in an ordered sequence." msgstr "" # type: Plain text #: usr_41.txt:1213 msgid "DICTIONARY FUNCTIONS" msgstr "" # type: Plain text #: usr_41.txt:1216 msgid "" "The items in a Dictionary can normally be obtained with an index in square " "brackets: >" msgstr "" # type: Plain text #: usr_41.txt:1219 #, no-wrap msgid "" "\t:echo uk2nl['one']\n" "<\teen ~\n" msgstr "" # type: Plain text #: usr_41.txt:1221 msgid "A method that does the same, but without so many punctuation characters: >" msgstr "" # type: Plain text #: usr_41.txt:1224 #, no-wrap msgid "" "\t:echo uk2nl.one\n" "<\teen ~\n" msgstr "" # type: Plain text #: usr_41.txt:1227 msgid "" "This only works for a key that is made of ASCII letters, digits and the " "underscore. You can also assign a new value this way: >" msgstr "" # type: Plain text #: usr_41.txt:1231 #, no-wrap msgid "" "\t:let uk2nl.four = 'vier'\n" "\t:echo uk2nl\n" "<\t{'three': 'drie', 'four': 'vier', 'one': 'een', 'two': 'twee'} ~\n" msgstr "" # type: Plain text #: usr_41.txt:1234 msgid "" "And now for something special: you can directly define a function and store " "a reference to it in the dictionary: >" msgstr "" # type: Plain text #: usr_41.txt:1238 #, no-wrap msgid "" "\t:function uk2nl.translate(line) dict\n" "\t: return join(map(split(a:line), 'get(self, v:val, \"???\")'))\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:1240 msgid "Let's first try it out: >" msgstr "" # type: Plain text #: usr_41.txt:1243 #, no-wrap msgid "" "\t:echo uk2nl.translate('three two five one')\n" "<\tdrie twee ??? een ~\n" msgstr "" # type: Plain text #: usr_41.txt:1248 #, no-wrap msgid "" "The first special thing you notice is the \"dict\" at the end of the " "\":function\"\n" "line. This marks the function as being used from a Dictionary. The " "\"self\"\n" "local variable will then refer to that Dictionary.\n" " Now let's break up the complicated return command: >\n" msgstr "" # type: Plain text #: usr_41.txt:1250 #, no-wrap msgid "\tsplit(a:line)\n" msgstr "" # type: Plain text #: usr_41.txt:1253 msgid "" "The split() function takes a string, chops it into white separated words and " "returns a list with these words. Thus in the example it returns: >" msgstr "" # type: Plain text #: usr_41.txt:1256 #, no-wrap msgid "" "\t:echo split('three two five one')\n" "<\t['three', 'two', 'five', 'one'] ~\n" msgstr "" # type: Plain text #: usr_41.txt:1260 msgid "" "This list is the first argument to the map() function. This will go through " "the list, evaluating its second argument with \"v:val\" set to the value of " "each item. This is a shortcut to using a for loop. This command: >" msgstr "" # type: Plain text #: usr_41.txt:1262 #, no-wrap msgid "\t:let alist = map(split(a:line), 'get(self, v:val, \"???\")')\n" msgstr "" # type: Plain text #: usr_41.txt:1264 msgid "Is equivalent to: >" msgstr "" # type: Plain text #: usr_41.txt:1269 #, no-wrap msgid "" "\t:let alist = split(a:line)\n" "\t:for idx in range(len(alist))\n" "\t: let alist[idx] = get(self, alist[idx], \"???\")\n" "\t:endfor\n" msgstr "" # type: Plain text #: usr_41.txt:1274 msgid "" "The get() function checks if a key is present in a Dictionary. If it is, " "then the value is retrieved. If it isn't, then the default value is " "returned, in the example it's '???'. This is a convenient way to handle " "situations where a key may not be present and you don't want an error " "message." msgstr "" # type: Plain text #: usr_41.txt:1279 #, no-wrap msgid "" "The join() function does the opposite of split(): it joins together a list " "of\n" "words, putting a space in between.\n" " This combination of split(), map() and join() is a nice way to filter a " "line\n" "of words in a very compact way.\n" msgstr "" # type: Plain text #: usr_41.txt:1282 msgid "OBJECT ORIENTED PROGRAMMING" msgstr "" # type: Plain text #: usr_41.txt:1288 #, no-wrap msgid "" "Now that you can put both values and functions in a Dictionary, you can\n" "actually use a Dictionary like an object.\n" " Above we used a Dictionary for translating Dutch to English. We might " "want\n" "to do the same for other languages. Let's first make an object (aka\n" "Dictionary) that has the translate function, but no words to translate: >\n" msgstr "" # type: Plain text #: usr_41.txt:1293 #, no-wrap msgid "" "\t:let transdict = {}\n" "\t:function transdict.translate(line) dict\n" "\t: return join(map(split(a:line), 'get(self.words, v:val, \"???\")'))\n" "\t:endfunction\n" msgstr "" # type: Plain text #: usr_41.txt:1297 msgid "" "It's slightly different from the function above, using 'self.words' to " "lookup word translations. But we don't have a self.words. Thus you could " "call this an abstract class." msgstr "" # type: Plain text #: usr_41.txt:1299 msgid "Now we can instantiate a Dutch translation object: >" msgstr "" # type: Plain text #: usr_41.txt:1304 #, no-wrap msgid "" "\t:let uk2nl = copy(transdict)\n" "\t:let uk2nl.words = {'one': 'een', 'two': 'twee', 'three': 'drie'}\n" "\t:echo uk2nl.translate('three one')\n" "<\tdrie een ~\n" msgstr "" # type: Plain text #: usr_41.txt:1306 msgid "And a German translator: >" msgstr "" # type: Plain text #: usr_41.txt:1311 #, no-wrap msgid "" "\t:let uk2de = copy(transdict)\n" "\t:let uk2de.words = {'one': 'ein', 'two': 'zwei', 'three': 'drei'}\n" "\t:echo uk2de.translate('three one')\n" "<\tdrei ein ~\n" msgstr "" # type: Plain text #: usr_41.txt:1315 msgid "" "You see that the copy() function is used to make a copy of the \"transdict\" " "Dictionary and then the copy is changed to add the words. The original " "remains the same, of course." msgstr "" # type: Plain text #: usr_41.txt:1317 msgid "Now you can go one step further, and use your preferred translator: >" msgstr "" # type: Plain text #: usr_41.txt:1325 #, no-wrap msgid "" "\t:if $LANG =~ \"de\"\n" "\t: let trans = uk2de\n" "\t:else\n" "\t: let trans = uk2nl\n" "\t:endif\n" "\t:echo trans.translate('one two three')\n" "<\teen twee drie ~\n" msgstr "" # type: Plain text #: usr_41.txt:1329 msgid "" "Here \"trans\" refers to one of the two objects (Dictionaries). No copy is " "made. More about List and Dictionary identity can be found at " "|list-identity| and |dict-identity|." msgstr "" # type: Plain text #: usr_41.txt:1332 msgid "" "Now you might use a language that isn't supported. You can overrule the " "translate() function to do nothing: >" msgstr "" # type: Plain text #: usr_41.txt:1339 #, no-wrap msgid "" "\t:let uk2uk = copy(transdict)\n" "\t:function! uk2uk.translate(line)\n" "\t: return a:line\n" "\t:endfunction\n" "\t:echo uk2uk.translate('three one wladiwostok')\n" "<\tthree one wladiwostok ~\n" msgstr "" # type: Plain text #: usr_41.txt:1342 msgid "" "Notice that a ! was used to overwrite the existing function reference. Now " "use \"uk2uk\" when no recognized language is found: >" msgstr "" # type: Plain text #: usr_41.txt:1352 #, no-wrap msgid "" "\t:if $LANG =~ \"de\"\n" "\t: let trans = uk2de\n" "\t:elseif $LANG =~ \"nl\"\n" "\t: let trans = uk2nl\n" "\t:else\n" "\t: let trans = uk2uk\n" "\t:endif\n" "\t:echo trans.translate('one two three')\n" "<\tone two three ~\n" msgstr "" # type: Plain text #: usr_41.txt:1354 msgid "For further reading see |Lists| and |Dictionaries|." msgstr "" # type: Plain text #: usr_41.txt:1357 #, no-wrap msgid "*41.9*\tExceptions\n" msgstr "" # type: Plain text #: usr_41.txt:1359 msgid "Let's start with an example: >" msgstr "" # type: Plain text #: usr_41.txt:1365 #, no-wrap msgid "" "\t:try\n" "\t: read ~/templates/pascal.tmpl\n" "\t:catch /E484:/\n" "\t: echo \"Sorry, the Pascal template file cannot be found.\"\n" "\t:endtry\n" msgstr "" # type: Plain text #: usr_41.txt:1369 msgid "" "The \":read\" command will fail if the file does not exist. Instead of " "generating an error message, this code catches the error and gives the user " "a nice message instead." msgstr "" # type: Plain text #: usr_41.txt:1375 msgid "" "For the commands in between \":try\" and \":endtry\" errors are turned into " "exceptions. An exception is a string. In the case of an error the string " "contains the error message. And every error message has a number. In this " "case, the error we catch contains \"E484:\". This number is guaranteed to " "stay the same (the text may change, e.g., it may be translated)." msgstr "" # type: Plain text #: usr_41.txt:1379 msgid "" "When the \":read\" command causes another error, the pattern \"E484:\" will " "not match in it. Thus this exception will not be caught and result in the " "usual error message." msgstr "" # type: Plain text #: usr_41.txt:1381 msgid "You might be tempted to do this: >" msgstr "" # type: Plain text #: usr_41.txt:1387 #, no-wrap msgid "" "\t:try\n" "\t: read ~/templates/pascal.tmpl\n" "\t:catch\n" "\t: echo \"Sorry, the Pascal template file cannot be found.\"\n" "\t:endtry\n" msgstr "" # type: Plain text #: usr_41.txt:1390 msgid "" "This means all errors are caught. But then you will not see errors that are " "useful, such as \"E21: Cannot make changes, 'modifiable' is off\"." msgstr "" # type: Plain text #: usr_41.txt:1392 msgid "Another useful mechanism is the \":finally\" command: >" msgstr "" # type: Plain text #: usr_41.txt:1402 #, no-wrap msgid "" "\t:let tmp = tempname()\n" "\t:try\n" "\t: exe \".,$write \" . tmp\n" "\t: exe \"!filter \" . tmp\n" "\t: .,$delete\n" "\t: exe \"$read \" . tmp\n" "\t:finally\n" "\t: call delete(tmp)\n" "\t:endtry\n" msgstr "" # type: Plain text #: usr_41.txt:1408 msgid "" "This filters the lines from the cursor until the end of the file through the " "\"filter\" command, which takes a file name argument. No matter if the " "filtering works, something goes wrong in between \":try\" and \":finally\" " "or the user cancels the filtering by pressing CTRL-C, the \"call " "delete(tmp)\" is always executed. This makes sure you don't leave the " "temporary file behind." msgstr "" # type: Plain text #: usr_41.txt:1411 msgid "" "More information about exception handling can be found in the reference " "manual: |exception-handling|." msgstr "" # type: Plain text #: usr_41.txt:1414 #, no-wrap msgid "*41.10*\tVarious remarks\n" msgstr "" # type: Plain text #: usr_41.txt:1417 msgid "" "Here is a summary of items that apply to Vim scripts. They are also " "mentioned elsewhere, but form a nice checklist." msgstr "" # type: Plain text #: usr_41.txt:1421 msgid "" "The end-of-line character depends on the system. For Unix a single " "character is used. For MS-DOS, Windows, OS/2 and the like, is " "used. This is important when using mappings that end in a . See " "|:source_crnl|." msgstr "" # type: Plain text #: usr_41.txt:1424 msgid "WHITE SPACE" msgstr "" # type: Plain text #: usr_41.txt:1426 msgid "Blank lines are allowed and ignored." msgstr "" # type: Plain text #: usr_41.txt:1432 msgid "" "Leading whitespace characters (blanks and TABs) are always ignored. The " "whitespaces between parameters (e.g. between the 'set' and the 'cpoptions' " "in the example below) are reduced to one blank character and plays the role " "of a separator, the whitespaces after the last (visible) character may or " "may not be ignored depending on the situation, see below." msgstr "" # type: Plain text #: usr_41.txt:1434 msgid "For a \":set\" command involving the \"=\" (equal) sign, such as in: >" msgstr "" # type: Plain text #: usr_41.txt:1436 #, no-wrap msgid "\t:set cpoptions =aABceFst\n" msgstr "" # type: Plain text #: usr_41.txt:1439 msgid "" "the whitespace immediately before the \"=\" sign is ignored. But there can " "be no whitespace after the \"=\" sign!" msgstr "" # type: Plain text #: usr_41.txt:1442 msgid "" "To include a whitespace character in the value of an option, it must be " "escaped by a \"\\\" (backslash) as in the following example: >" msgstr "" # type: Plain text #: usr_41.txt:1444 #, no-wrap msgid "\t:set tags=my\\ nice\\ file\n" msgstr "" # type: Plain text #: usr_41.txt:1446 msgid "The same example written as >" msgstr "" # type: Plain text #: usr_41.txt:1448 #, no-wrap msgid "\t:set tags=my nice file\n" msgstr "" # type: Plain text #: usr_41.txt:1450 msgid "will issue an error, because it is interpreted as: >" msgstr "" # type: Plain text #: usr_41.txt:1454 #, no-wrap msgid "" "\t:set tags=my\n" "\t:set nice\n" "\t:set file\n" msgstr "" # type: Plain text #: usr_41.txt:1457 msgid "COMMENTS" msgstr "" # type: Plain text #: usr_41.txt:1462 msgid "" "The character \" (the double quote mark) starts a comment. Everything after " "and including this character until the end-of-line is considered a comment " "and is ignored, except for commands that don't consider comments, as shown " "in examples below. A comment can start on any character position on the " "line." msgstr "" # type: Plain text #: usr_41.txt:1464 msgid "There is a little \"catch\" with comments for some commands. Examples: >" msgstr "" # type: Plain text #: usr_41.txt:1469 #, no-wrap msgid "" "\t:abbrev dev development\t\t\" shorthand\n" "\t:map o#include\t\t\" insert include\n" "\t:execute cmd\t\t\t\" do it\n" "\t:!ls *.c\t\t\t\" list C files\n" msgstr "" # type: Plain text #: usr_41.txt:1478 #, no-wrap msgid "" "The abbreviation 'dev' will be expanded to 'development \" shorthand'. " "The\n" "mapping of will actually be the whole line after the 'o# ....' " "including\n" "the '\" insert include'. The \"execute\" command will give an error. The " "\"!\"\n" "command will send everything after it to the shell, causing an error for " "an\n" "unmatched '\"' character.\n" " There can be no comment after \":map\", \":abbreviate\", \":execute\" and " "\"!\"\n" "commands (there are a few more commands with this restriction). For the\n" "\":map\", \":abbreviate\" and \":execute\" commands there is a trick: >\n" msgstr "" # type: Plain text #: usr_41.txt:1482 #, no-wrap msgid "" "\t:abbrev dev development|\" shorthand\n" "\t:map o#include|\" insert include\n" "\t:execute cmd\t\t\t|\" do it\n" msgstr "" # type: Plain text #: usr_41.txt:1485 msgid "" "With the '|' character the command is separated from the next one. And that " "next command is only a comment." msgstr "" # type: Plain text #: usr_41.txt:1490 msgid "" "Notice that there is no white space before the '|' in the abbreviation and " "mapping. For these commands, any character until the end-of-line or '|' is " "included. As a consequence of this behavior, you don't always see that " "trailing whitespace is included: >" msgstr "" # type: Plain text #: usr_41.txt:1492 #, no-wrap msgid "\t:map o#include \n" msgstr "" # type: Plain text #: usr_41.txt:1495 msgid "" "To avoid these problems, you can set the 'list' option when editing vimrc " "files." msgstr "" # type: Plain text #: usr_41.txt:1498 msgid "PITFALLS" msgstr "" # type: Plain text #: usr_41.txt:1500 msgid "Even bigger problem arises in the following example: >" msgstr "" # type: Plain text #: usr_41.txt:1503 #, no-wrap msgid "" "\t:map ,ab o#include\n" "\t:unmap ,ab \n" msgstr "" # type: Plain text #: usr_41.txt:1508 msgid "" "Here the unmap command will not work, because it tries to unmap \",ab \". " "This does not exist as a mapped sequence. An error will be issued, which is " "very hard to identify, because the ending whitespace character in \":unmap " ",ab \" is not visible." msgstr "" # type: Plain text #: usr_41.txt:1511 msgid "" "And this is the same as what happens when one uses a comment after an " "'unmap' command: >" msgstr "" # type: Plain text #: usr_41.txt:1513 #, no-wrap msgid "\t:unmap ,ab \" comment\n" msgstr "" # type: Plain text #: usr_41.txt:1516 #, no-wrap msgid "" "Here the comment part will be ignored. However, Vim will try to unmap\n" "',ab ', which does not exist. Rewrite it as: >\n" msgstr "" # type: Plain text #: usr_41.txt:1518 #, no-wrap msgid "\t:unmap ,ab| \" comment\n" msgstr "" # type: Plain text #: usr_41.txt:1521 msgid "RESTORING THE VIEW" msgstr "" # type: Plain text #: usr_41.txt:1527 #, no-wrap msgid "" "Sometimes you want to make a change and go back to where cursor was.\n" "Restoring the relative position would also be nice, so that the same line\n" "appears at the top of the window.\n" " This example yanks the current line, puts it above the first line in " "the\n" "file and then restores the view: >\n" msgstr "" # type: Plain text #: usr_41.txt:1529 #, no-wrap msgid "\tmap ,p ma\"aYHmbgg\"aP`bzt`a\n" msgstr "" # type: Plain text #: usr_41.txt:1540 #, no-wrap msgid "" "What this does: >\n" "\tma\"aYHmbgg\"aP`bzt`a\n" "<\tma\t\t\tset mark a at cursor position\n" "\t \"aY\t\t\tyank current line into register a\n" "\t Hmb\t\tgo to top line in window and set mark b there\n" "\t\tgg\t\tgo to first line in file\n" "\t\t \"aP\t\tput the yanked line above it\n" "\t\t `b\t\tgo back to top line in display\n" "\t\t zt\tposition the text in the window as before\n" "\t\t\t `a\tgo back to saved cursor position\n" msgstr "" # type: Plain text #: usr_41.txt:1543 msgid "PACKAGING" msgstr "" # type: Plain text #: usr_41.txt:1552 #, no-wrap msgid "" "To avoid your function names to interfere with functions that you get from\n" "others, use this scheme:\n" "- Prepend a unique string before each function name. I often use an\n" " abbreviation. For example, \"OW_\" is used for the option window " "functions.\n" "- Put the definition of your functions together in a file. Set a global\n" " variable to indicate that the functions have been loaded. When sourcing " "the\n" " file again, first unload the functions.\n" "Example: >\n" msgstr "" # type: Plain text #: usr_41.txt:1554 #, no-wrap msgid "\t\" This is the XXX package\n" msgstr "" # type: Plain text #: usr_41.txt:1559 #, no-wrap msgid "" "\tif exists(\"XXX_loaded\")\n" "\t delfun XXX_one\n" "\t delfun XXX_two\n" "\tendif\n" msgstr "" # type: Plain text #: usr_41.txt:1563 #, no-wrap msgid "" "\tfunction XXX_one(a)\n" "\t\t... body of function ...\n" "\tendfun\n" msgstr "" # type: Plain text #: usr_41.txt:1567 #, no-wrap msgid "" "\tfunction XXX_two(b)\n" "\t\t... body of function ...\n" "\tendfun\n" msgstr "" # type: Plain text #: usr_41.txt:1569 #, no-wrap msgid "\tlet XXX_loaded = 1\n" msgstr "" # type: Plain text #: usr_41.txt:1572 #, no-wrap msgid "*41.11*\tWriting a plugin\t\t\t\t*write-plugin*\n" msgstr "" # type: Plain text #: usr_41.txt:1576 msgid "" "You can write a Vim script in such a way that many people can use it. This " "is called a plugin. Vim users can drop your script in their plugin " "directory and use its features right away |add-plugin|." msgstr "" # type: Plain text #: usr_41.txt:1578 msgid "There are actually two types of plugins:" msgstr "" # type: Plain text #: usr_41.txt:1581 #, no-wrap msgid "" " global plugins: For all types of files.\n" "filetype plugins: Only for files of a specific type.\n" msgstr "" # type: Plain text #: usr_41.txt:1585 msgid "" "In this section the first type is explained. Most items are also relevant " "for writing filetype plugins. The specifics for filetype plugins are in the " "next section |write-filetype-plugin|." msgstr "" # type: Plain text #: usr_41.txt:1588 msgid "NAME" msgstr "" # type: Plain text #: usr_41.txt:1594 msgid "" "First of all you must choose a name for your plugin. The features provided " "by the plugin should be clear from its name. And it should be unlikely that " "someone else writes a plugin with the same name but which does something " "different. And please limit the name to 8 characters, to avoid problems on " "old Windows systems." msgstr "" # type: Plain text #: usr_41.txt:1597 msgid "" "A script that corrects typing mistakes could be called \"typecorr.vim\". We " "will use it here as an example." msgstr "" # type: Plain text #: usr_41.txt:1600 msgid "" "For the plugin to work for everybody, it should follow a few guidelines. " "This will be explained step-by-step. The complete example plugin is at the " "end." msgstr "" # type: Plain text #: usr_41.txt:1603 msgid "BODY" msgstr "" # type: Plain text #: usr_41.txt:1605 msgid "" "Let's start with the body of the plugin, the lines that do the actual work: " ">" msgstr "" # type: Plain text #: usr_41.txt:1612 #, no-wrap msgid "" " 14\tiabbrev teh the\n" " 15\tiabbrev otehr other\n" " 16\tiabbrev wnat want\n" " 17\tiabbrev synchronisation\n" " 18\t\t\\ synchronization\n" " 19\tlet s:count = 4\n" msgstr "" # type: Plain text #: usr_41.txt:1614 msgid "The actual list should be much longer, of course." msgstr "" # type: Plain text #: usr_41.txt:1617 msgid "" "The line numbers have only been added to explain a few things, don't put " "them in your plugin file!" msgstr "" # type: Plain text #: usr_41.txt:1620 msgid "HEADER" msgstr "" # type: Plain text #: usr_41.txt:1625 msgid "" "You will probably add new corrections to the plugin and soon have several " "versions laying around. And when distributing this file, people will want " "to know who wrote this wonderful plugin and where they can send remarks. " "Therefore, put a header at the top of your plugin: >" msgstr "" # type: Plain text #: usr_41.txt:1629 #, no-wrap msgid "" " 1\t\" Vim global plugin for correcting typing mistakes\n" " 2\t\" Last Change:\t2000 Oct 15\n" " 3\t\" Maintainer:\tBram Moolenaar \n" msgstr "" # type: Plain text #: usr_41.txt:1634 msgid "" "About copyright and licensing: Since plugins are very useful and it's hardly " "worth restricting their distribution, please consider making your plugin " "either public domain or use the Vim |license|. A short note about this near " "the top of the plugin should be sufficient. Example: >" msgstr "" # type: Plain text #: usr_41.txt:1636 #, no-wrap msgid " 4\t\" License:\tThis file is placed in the public domain.\n" msgstr "" # type: Plain text #: usr_41.txt:1639 msgid "LINE CONTINUATION, AVOIDING SIDE EFFECTS\t\t*use-cpo-save*" msgstr "" # type: Plain text #: usr_41.txt:1646 msgid "" "In line 18 above, the line-continuation mechanism is used " "|line-continuation|. Users with 'compatible' set will run into trouble " "here, they will get an error message. We can't just reset 'compatible', " "because that has a lot of side effects. To avoid this, we will set the " "'cpoptions' option to its Vim default value and restore it later. That will " "allow the use of line-continuation and make the script work for most " "people. It is done like this: >" msgstr "" # type: Plain text #: usr_41.txt:1651 #, no-wrap msgid "" " 11\tlet s:save_cpo = &cpo\n" " 12\tset cpo&vim\n" " ..\n" " 42\tlet &cpo = s:save_cpo\n" msgstr "" # type: Plain text #: usr_41.txt:1654 msgid "" "We first store the old value of 'cpoptions' in the s:save_cpo variable. At " "the end of the plugin this value is restored." msgstr "" # type: Plain text #: usr_41.txt:1658 msgid "" "Notice that a script-local variable is used |s:var|. A global variable " "could already be in use for something else. Always use script-local " "variables for things that are only used in the script." msgstr "" # type: Plain text #: usr_41.txt:1661 msgid "NOT LOADING" msgstr "" # type: Plain text #: usr_41.txt:1666 msgid "" "It's possible that a user doesn't always want to load this plugin. Or the " "system administrator has dropped it in the system-wide plugin directory, but " "a user has his own plugin he wants to use. Then the user must have a chance " "to disable loading this specific plugin. This will make it possible: >" msgstr "" # type: Plain text #: usr_41.txt:1671 #, no-wrap msgid "" " 6\tif exists(\"loaded_typecorr\")\n" " 7\t finish\n" " 8\tendif\n" " 9\tlet loaded_typecorr = 1\n" msgstr "" # type: Plain text #: usr_41.txt:1675 msgid "" "This also avoids that when the script is loaded twice it would cause error " "messages for redefining functions and cause trouble for autocommands that " "are added twice." msgstr "" # type: Plain text #: usr_41.txt:1678 msgid "MAPPING" msgstr "" # type: Plain text #: usr_41.txt:1684 msgid "" "Now let's make the plugin more interesting: We will add a mapping that adds " "a correction for the word under the cursor. We could just pick a key " "sequence for this mapping, but the user might already use it for something " "else. To allow the user to define which keys a mapping in a plugin uses, " "the item can be used: >" msgstr "" # type: Plain text #: usr_41.txt:1686 #, no-wrap msgid " 22\t map a TypecorrAdd\n" msgstr "" # type: Plain text #: usr_41.txt:1688 msgid "" "The \"TypecorrAdd\" thing will do the work, more about that further " "on." msgstr "" # type: Plain text #: usr_41.txt:1691 msgid "" "The user can set the \"mapleader\" variable to the key sequence that he " "wants this mapping to start with. Thus if the user has done: >" msgstr "" # type: Plain text #: usr_41.txt:1693 #, no-wrap msgid "\tlet mapleader = \"_\"\n" msgstr "" # type: Plain text #: usr_41.txt:1696 msgid "" "the mapping will define \"_a\". If the user didn't do this, the default " "value will be used, which is a backslash. Then a map for \"\\a\" will be " "defined." msgstr "" # type: Plain text #: usr_41.txt:1699 msgid "" "Note that is used, this will cause an error message if the mapping " "already happened to exist. |:map-|" msgstr "" # type: Plain text #: usr_41.txt:1702 msgid "" "But what if the user wants to define his own key sequence? We can allow that " "with this mechanism: >" msgstr "" # type: Plain text #: usr_41.txt:1706 #, no-wrap msgid "" " 21\tif !hasmapto('TypecorrAdd')\n" " 22\t map a TypecorrAdd\n" " 23\tendif\n" msgstr "" # type: Plain text #: usr_41.txt:1710 msgid "" "This checks if a mapping to \"TypecorrAdd\" already exists, and only " "defines the mapping from \"a\" if it doesn't. The user then has a " "chance of putting this in his vimrc file: >" msgstr "" # type: Plain text #: usr_41.txt:1712 #, no-wrap msgid "\tmap ,c TypecorrAdd\n" msgstr "" # type: Plain text #: usr_41.txt:1714 msgid "Then the mapped key sequence will be \",c\" instead of \"_a\" or \"\\a\"." msgstr "" # type: Plain text #: usr_41.txt:1717 msgid "PIECES" msgstr "" # type: Plain text #: usr_41.txt:1724 msgid "" "If a script gets longer, you often want to break up the work in pieces. You " "can use functions or mappings for this. But you don't want these functions " "and mappings to interfere with the ones from other scripts. For example, " "you could define a function Add(), but another script could try to define " "the same function. To avoid this, we define the function local to the " "script by prepending it with \"s:\"." msgstr "" # type: Plain text #: usr_41.txt:1726 msgid "We will define a function that adds a new typing correction: >" msgstr "" # type: Plain text #: usr_41.txt:1732 #, no-wrap msgid "" " 30\tfunction s:Add(from, correct)\n" " 31\t let to = input(\"type the correction for \" . a:from . \": \")\n" " 32\t exe \":iabbrev \" . a:from . \" \" . to\n" " ..\n" " 36\tendfunction\n" msgstr "" # type: Plain text #: usr_41.txt:1737 msgid "" "Now we can call the function s:Add() from within this script. If another " "script also defines s:Add(), it will be local to that script and can only be " "called from the script it was defined in. There can also be a global Add() " "function (without the \"s:\"), which is again another function." msgstr "" # type: Plain text #: usr_41.txt:1740 msgid "" " can be used with mappings. It generates a script ID, which identifies " "the current script. In our typing correction plugin we use it like this: >" msgstr "" # type: Plain text #: usr_41.txt:1744 #, no-wrap msgid "" " 24\tnoremap