vim: runtime/doc/usr_51.txt annotate

annotate runtime/doc/usr_51.txt @ 33262:6eac4f616293 v9.0.1899

patch 9.0.1899: potential buffer overflow in PBYTE macro Commit: https://github.com/vim/vim/commit/ffb13674d1af1c90beb229867ec989e4fb232df3 Author: Christian Brabandt <cb@256bit.org> Date: Fri Sep 15 20:22:02 2023 +0200 patch 9.0.1899: potential buffer overflow in PBYTE macro Problem: potential buffer overflow in PBYTE macro Solution: Check returned memline length closes: #13083 the PBYTE macro is used to put byte c at a position lp of the returned memline. However, in case of unexpected errors ml_get_buf() may return either "???" or an empty line in which case it is quite likely that we are causing a buffer overrun. Therefore, switch the macro PBYTE (which is only used in ops.c anyhow) to a function, that verifies that we will only try to access within the given length of the buffer. Also, since the macro is only used in ops.c, move the definition from macros.h to ops.c Signed-off-by: Christian Brabandt <cb@256bit.org>

author	Christian Brabandt <cb@256bit.org>
date	Fri, 15 Sep 2023 20:30:07 +0200
parents	f8116058ca76
children	7544cdfdbf6a

rev	line source
29314 f8116058ca76 release version 9.0 Bram Moolenaar <Bram@vim.org> parents: 29290 diff changeset	1 usr_51.txt For Vim version 9.0. Last change: 2022 Jun 03
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	2
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	3 VIM USER MANUAL - by Bram Moolenaar
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	4
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	5 Write plugins
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	6
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	7
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	8 Plugins can be used to define settings for a specific type of file, syntax
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	9 highlighting and many other things. This chapter explains how to write the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	10 most common Vim plugins.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	11
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	12 \|51.1\| Writing a generic plugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	13 \|51.2\| Writing a filetype plugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	14 \|51.3\| Writing a compiler plugin
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	15 \|51.4\| Distributing Vim scripts
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	16
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	17 Next chapter: \|usr_52.txt\| Write large plugins
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	18 Previous chapter: \|usr_50.txt\| Advanced Vim script writing
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	19 Table of contents: \|usr_toc.txt\|
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	20
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	21 ==============================================================================
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	22 51.1 Writing a generic plugin write-plugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	23
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	24 You can write a Vim script in such a way that many people can use it. This is
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	25 called a plugin. Vim users can drop your script in their plugin directory and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	26 use its features right away \|add-plugin\|.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	27
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	28 There are actually two types of plugins:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	29
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	30 global plugins: For all types of files.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	31 filetype plugins: Only for files of a specific type.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	32
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	33 In this section the first type is explained. Most items are also relevant for
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	34 writing filetype plugins. The specifics for filetype plugins are in the next
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	35 section \|write-filetype-plugin\|.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	36
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	37 We will use \|Vim9\| syntax here, the recommended way to write new plugins.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	38 Make sure the file starts with the `vim9script` command.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	39
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	40
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	41 NAME
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	42
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	43 First of all you must choose a name for your plugin. The features provided
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	44 by the plugin should be clear from its name. And it should be unlikely that
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	45 someone else writes a plugin with the same name but which does something
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	46 different.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	47
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	48 A script that corrects typing mistakes could be called "typecorrect.vim". We
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	49 will use it here as an example.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	50
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	51 For the plugin to work for everybody, it should follow a few guidelines. This
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	52 will be explained step-by-step. The complete example plugin is at the end.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	53
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	54
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	55 BODY
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	56
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	57 Let's start with the body of the plugin, the lines that do the actual work: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	58
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	59 12 iabbrev teh the
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	60 13 iabbrev otehr other
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	61 14 iabbrev wnat want
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	62 15 iabbrev synchronisation
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	63 16 \ synchronization
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	64
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	65 The actual list should be much longer, of course.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	66
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	67 The line numbers have only been added to explain a few things, don't put them
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	68 in your plugin file!
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	69
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	70
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	71 FIRST LINE
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	72 >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	73 1 vim9script noclear
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	74
29290 dc4de65a7fb7 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 29066 diff changeset	75 You need to use `vim9script` as the very first command. Best is to put it in
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	76 the very first line.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	77
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	78 The script we are writing will have a `finish` command to bail out when it is
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	79 loaded a second time. To avoid that the items defined in the script are lost
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	80 the "noclear" argument is used. More info about this at \|vim9-reload\|.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	81
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	82
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	83 HEADER
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	84
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	85 You will probably add new corrections to the plugin and soon have several
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	86 versions lying around. And when distributing this file, people will want to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	87 know who wrote this wonderful plugin and where they can send remarks.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	88 Therefore, put a header at the top of your plugin: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	89
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	90 2 # Vim global plugin for correcting typing mistakes
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	91 3 # Last Change: 2021 Dec 30
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	92 4 # Maintainer: Bram Moolenaar <Bram@vim.org>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	93
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	94 About copyright and licensing: Since plugins are very useful and it's hardly
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	95 worth restricting their distribution, please consider making your plugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	96 either public domain or use the Vim \|license\|. A short note about this near
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	97 the top of the plugin should be sufficient. Example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	98
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	99 5 # License: This file is placed in the public domain.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	100
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	101
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	102 NOT LOADING
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	103
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	104 It is possible that a user doesn't always want to load this plugin. Or the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	105 system administrator has dropped it in the system-wide plugin directory, but a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	106 user has his own plugin he wants to use. Then the user must have a chance to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	107 disable loading this specific plugin. These lines will make it possible: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	108
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	109 7 if exists("g:loaded_typecorrect")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	110 8 finish
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	111 9 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	112 10 g:loaded_typecorrect = 1
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	113
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	114 This also avoids that when the script is loaded twice it would pointlessly
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	115 redefine functions and cause trouble for autocommands that are added twice.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	116
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	117 The name is recommended to start with "g:loaded_" and then the file name of
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	118 the plugin, literally. The "g:" is prepended to make the variable global, so
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	119 that other places can check whether its functionality is available. Without
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	120 "g:" it would be local to the script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	121
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	122 Using `finish` stops Vim from reading the rest of the file, it's much quicker
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	123 than using if-endif around the whole file, since Vim would still need to parse
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	124 the commands to find the `endif`.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	125
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	126
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	127 MAPPING
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	128
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	129 Now let's make the plugin more interesting: We will add a mapping that adds a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	130 correction for the word under the cursor. We could just pick a key sequence
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	131 for this mapping, but the user might already use it for something else. To
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	132 allow the user to define which keys a mapping in a plugin uses, the <Leader>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	133 item can be used: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	134
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	135 20 map <unique> <Leader>a <Plug>TypecorrAdd;
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	136
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	137 The "<Plug>TypecorrAdd;" thing will do the work, more about that further on.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	138
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	139 The user can set the "g:mapleader" variable to the key sequence that he wants
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	140 plugin mappings to start with. Thus if the user has done: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	141
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	142 g:mapleader = "_"
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	143
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	144 the mapping will define "_a". If the user didn't do this, the default value
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	145 will be used, which is a backslash. Then a map for "\a" will be defined.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	146
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	147 Note that <unique> is used, this will cause an error message if the mapping
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	148 already happened to exist. \|:map-<unique>\|
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	149
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	150 But what if the user wants to define his own key sequence? We can allow that
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	151 with this mechanism: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	152
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	153 19 if !hasmapto('<Plug>TypecorrAdd;')
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	154 20 map <unique> <Leader>a <Plug>TypecorrAdd;
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	155 21 endif
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	156
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	157 This checks if a mapping to "<Plug>TypecorrAdd;" already exists, and only
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	158 defines the mapping from "<Leader>a" if it doesn't. The user then has a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	159 chance of putting this in his vimrc file: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	160
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	161 map ,c <Plug>TypecorrAdd;
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	162
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	163 Then the mapped key sequence will be ",c" instead of "_a" or "\a".
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	164
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	165
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	166 PIECES
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	167
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	168 If a script gets longer, you often want to break up the work in pieces. You
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	169 can use functions or mappings for this. But you don't want these functions
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	170 and mappings to interfere with the ones from other scripts. For example, you
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	171 could define a function Add(), but another script could try to define the same
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	172 function. To avoid this, we define the function local to the script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	173 Fortunately, in \|Vim9\| script this is the default. In a legacy script you
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	174 would need to prefix the name with "s:".
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	175
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	176 We will define a function that adds a new typing correction: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	177
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	178 28 def Add(from: string, correct: bool)
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	179 29 var to = input($"type the correction for {from}: ")
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	180 30 exe $":iabbrev {from} {to}"
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	181 ...
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	182 34 enddef
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	183
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	184 Now we can call the function Add() from within this script. If another
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	185 script also defines Add(), it will be local to that script and can only
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	186 be called from that script. There can also be a global g:Add() function,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	187 which is again another function.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	188
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	189 <SID> can be used with mappings. It generates a script ID, which identifies
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	190 the current script. In our typing correction plugin we use it like this: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	191
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	192 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	193 ...
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	194 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	195
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	196 Thus when a user types "\a", this sequence is invoked: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	197
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	198 \a -> <Plug>TypecorrAdd; -> <SID>Add -> :call <SID>Add(...)
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	199
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	200 If another script also maps <SID>Add, it will get another script ID and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	201 thus define another mapping.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	202
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	203 Note that instead of Add() we use <SID>Add() here. That is because the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	204 mapping is typed by the user, thus outside of the script context. The <SID>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	205 is translated to the script ID, so that Vim knows in which script to look for
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	206 the Add() function.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	207
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	208 This is a bit complicated, but it's required for the plugin to work together
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	209 with other plugins. The basic rule is that you use <SID>Add() in mappings and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	210 Add() in other places (the script itself, autocommands, user commands).
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	211
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	212 We can also add a menu entry to do the same as the mapping: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	213
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	214 24 noremenu <script> Plugin.Add\ Correction <SID>Add
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	215
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	216 The "Plugin" menu is recommended for adding menu items for plugins. In this
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	217 case only one item is used. When adding more items, creating a submenu is
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	218 recommended. For example, "Plugin.CVS" could be used for a plugin that offers
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	219 CVS operations "Plugin.CVS.checkin", "Plugin.CVS.checkout", etc.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	220
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	221 Note that in line 28 ":noremap" is used to avoid that any other mappings cause
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	222 trouble. Someone may have remapped ":call", for example. In line 24 we also
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	223 use ":noremap", but we do want "<SID>Add" to be remapped. This is why
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	224 "<script>" is used here. This only allows mappings which are local to the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	225 script. \|:map-<script>\| The same is done in line 26 for ":noremenu".
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	226 \|:menu-<script>\|
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	227
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	228
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	229 <SID> AND <Plug> using-<Plug>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	230
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	231 Both <SID> and <Plug> are used to avoid that mappings of typed keys interfere
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	232 with mappings that are only to be used from other mappings. Note the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	233 difference between using <SID> and <Plug>:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	234
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	235 <Plug> is visible outside of the script. It is used for mappings which the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	236 user might want to map a key sequence to. <Plug> is a special code
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	237 that a typed key will never produce.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	238 To make it very unlikely that other plugins use the same sequence of
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	239 characters, use this structure: <Plug> scriptname mapname
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	240 In our example the scriptname is "Typecorr" and the mapname is "Add".
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	241 We add a semicolon as the terminator. This results in
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	242 "<Plug>TypecorrAdd;". Only the first character of scriptname and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	243 mapname is uppercase, so that we can see where mapname starts.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	244
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	245 <SID> is the script ID, a unique identifier for a script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	246 Internally Vim translates <SID> to "<SNR>123_", where "123" can be any
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	247 number. Thus a function "<SID>Add()" will have a name "<SNR>11_Add()"
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	248 in one script, and "<SNR>22_Add()" in another. You can see this if
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	249 you use the ":function" command to get a list of functions. The
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	250 translation of <SID> in mappings is exactly the same, that's how you
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	251 can call a script-local function from a mapping.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	252
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	253
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	254 USER COMMAND
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	255
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	256 Now let's add a user command to add a correction: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	257
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	258 36 if !exists(":Correct")
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	259 37 command -nargs=1 Correct :call Add(<q-args>, false)
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	260 38 endif
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	261
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	262 The user command is defined only if no command with the same name already
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	263 exists. Otherwise we would get an error here. Overriding the existing user
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	264 command with ":command!" is not a good idea, this would probably make the user
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	265 wonder why the command he defined himself doesn't work. \|:command\|
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	266 If it did happen you can find out who to blame with: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	267
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	268 verbose command Correct
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	269
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	270
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	271 SCRIPT VARIABLES
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	272
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	273 When a variable starts with "s:" it is a script variable. It can only be used
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	274 inside a script. Outside the script it's not visible. This avoids trouble
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	275 with using the same variable name in different scripts. The variables will be
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	276 kept as long as Vim is running. And the same variables are used when sourcing
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	277 the same script again. \|s:var\|
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	278
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	279 The nice thing about \|Vim9\| script is that variables are local to the script
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	280 by default. You can prepend "s:" if you like, but you do not need to. And
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	281 functions in the script can also use the script variables without a prefix
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	282 (they must be declared before the function for this to work).
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	283
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	284 Script-local variables can also be used in functions, autocommands and user
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	285 commands that are defined in the script. Thus they are the perfect way to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	286 share information between parts of your plugin, without it leaking out. In
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	287 our example we can add a few lines to count the number of corrections: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	288
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	289 17 var count = 4
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	290 ...
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	291 28 def Add(from: string, correct: bool)
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	292 ...
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	293 32 count += 1
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	294 33 echo "you now have " .. count .. " corrections"
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	295 34 enddef
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	296
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	297 "count" is declared and initialized to 4 in the script itself. When later
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	298 the Add() function is called, it increments "count". It doesn't matter from
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	299 where the function was called, since it has been defined in the script, it
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	300 will use the local variables from this script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	301
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	302
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	303 THE RESULT
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	304
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	305 Here is the resulting complete example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	306
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	307 1 vim9script noclear
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	308 2 # Vim global plugin for correcting typing mistakes
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	309 3 # Last Change: 2021 Dec 30
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	310 4 # Maintainer: Bram Moolenaar <Bram@vim.org>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	311 5 # License: This file is placed in the public domain.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	312 6
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	313 7 if exists("g:loaded_typecorrect")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	314 8 finish
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	315 9 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	316 10 g:loaded_typecorrect = 1
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	317 11
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	318 12 iabbrev teh the
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	319 13 iabbrev otehr other
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	320 14 iabbrev wnat want
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	321 15 iabbrev synchronisation
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	322 16 \ synchronization
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	323 17 var count = 4
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	324 18
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	325 19 if !hasmapto('<Plug>TypecorrAdd;')
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	326 20 map <unique> <Leader>a <Plug>TypecorrAdd;
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	327 21 endif
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	328 22 noremap <unique> <script> <Plug>TypecorrAdd; <SID>Add
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	329 23
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	330 24 noremenu <script> Plugin.Add\ Correction <SID>Add
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	331 25
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	332 26 noremap <SID>Add :call <SID>Add(expand("<cword>"), true)<CR>
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	333 27
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	334 28 def Add(from: string, correct: bool)
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	335 29 var to = input("type the correction for " .. from .. ": ")
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	336 30 exe ":iabbrev " .. from .. " " .. to
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	337 31 if correct \| exe "normal viws\<C-R>\" \b\e" \| endif
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	338 32 count += 1
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	339 33 echo "you now have " .. count .. " corrections"
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	340 34 enddef
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	341 35
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	342 36 if !exists(":Correct")
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	343 37 command -nargs=1 Correct call Add(<q-args>, false)
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	344 38 endif
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	345
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	346 Line 31 wasn't explained yet. It applies the new correction to the word under
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	347 the cursor. The \|:normal\| command is used to use the new abbreviation. Note
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	348 that mappings and abbreviations are expanded here, even though the function
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	349 was called from a mapping defined with ":noremap".
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	350
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	351
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	352 DOCUMENTATION write-local-help
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	353
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	354 It's a good idea to also write some documentation for your plugin. Especially
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	355 when its behavior can be changed by the user. See \|add-local-help\| for how
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	356 they are installed.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	357
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	358 Here is a simple example for a plugin help file, called "typecorrect.txt": >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	359
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	360 1 typecorrect.txt Plugin for correcting typing mistakes
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	361 2
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	362 3 If you make typing mistakes, this plugin will have them corrected
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	363 4 automatically.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	364 5
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	365 6 There are currently only a few corrections. Add your own if you like.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	366 7
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	367 8 Mappings:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	368 9 <Leader>a or <Plug>TypecorrAdd;
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	369 10 Add a correction for the word under the cursor.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	370 11
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	371 12 Commands:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	372 13 :Correct {word}
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	373 14 Add a correction for {word}.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	374 15
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	375 16 typecorrect-settings
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	376 17 This plugin doesn't have any settings.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	377
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	378 The first line is actually the only one for which the format matters. It will
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	379 be extracted from the help file to be put in the "LOCAL ADDITIONS:" section of
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	380 help.txt \|local-additions\|. The first "*" must be in the first column of the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	381 first line. After adding your help file do ":help" and check that the entries
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	382 line up nicely.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	383
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	384 You can add more tags inside ** in your help file. But be careful not to use
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	385 existing help tags. You would probably use the name of your plugin in most of
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	386 them, like "typecorrect-settings" in the example.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	387
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	388 Using references to other parts of the help in \|\| is recommended. This makes
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	389 it easy for the user to find associated help.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	390
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	391
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	392 SUMMARY plugin-special
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	393
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	394 Summary of special things to use in a plugin:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	395
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	396 var name Variable local to the script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	397
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	398 <SID> Script-ID, used for mappings and functions local to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	399 the script.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	400
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	401 hasmapto() Function to test if the user already defined a mapping
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	402 for functionality the script offers.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	403
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	404 <Leader> Value of "mapleader", which the user defines as the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	405 keys that plugin mappings start with.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	406
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	407 map <unique> Give a warning if a mapping already exists.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	408
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	409 noremap <script> Use only mappings local to the script, not global
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	410 mappings.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	411
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	412 exists(":Cmd") Check if a user command already exists.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	413
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	414 ==============================================================================
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	415 51.2 Writing a filetype plugin write-filetype-plugin ftplugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	416
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	417 A filetype plugin is like a global plugin, except that it sets options and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	418 defines mappings for the current buffer only. See \|add-filetype-plugin\| for
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	419 how this type of plugin is used.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	420
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	421 First read the section on global plugins above \|51.1\|. All that is said there
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	422 also applies to filetype plugins. There are a few extras, which are explained
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	423 here. The essential thing is that a filetype plugin should only have an
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	424 effect on the current buffer.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	425
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	426
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	427 DISABLING
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	428
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	429 If you are writing a filetype plugin to be used by many people, they need a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	430 chance to disable loading it. Put this at the top of the plugin: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	431
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	432 # Only do this when not done yet for this buffer
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	433 if exists("b:did_ftplugin")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	434 finish
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	435 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	436 b:did_ftplugin = 1
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	437
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	438 This also needs to be used to avoid that the same plugin is executed twice for
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	439 the same buffer (happens when using an ":edit" command without arguments).
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	440
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	441 Now users can disable loading the default plugin completely by making a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	442 filetype plugin with only these lines: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	443
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	444 vim9script
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	445 b:did_ftplugin = 1
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	446
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	447 This does require that the filetype plugin directory comes before $VIMRUNTIME
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	448 in 'runtimepath'!
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	449
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	450 If you do want to use the default plugin, but overrule one of the settings,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	451 you can write the different setting in a script: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	452
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	453 setlocal textwidth=70
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	454
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	455 Now write this in the "after" directory, so that it gets sourced after the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	456 distributed "vim.vim" ftplugin \|after-directory\|. For Unix this would be
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	457 "~/.vim/after/ftplugin/vim.vim". Note that the default plugin will have set
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	458 "b:did_ftplugin", it is ignored here.
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	459
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	460
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	461 OPTIONS
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	462
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	463 To make sure the filetype plugin only affects the current buffer use the >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	464
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	465 setlocal
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	466
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	467 command to set options. And only set options which are local to a buffer (see
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	468 the help for the option to check that). When using `:setlocal` for global
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	469 options or options local to a window, the value will change for many buffers,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	470 and that is not what a filetype plugin should do.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	471
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	472 When an option has a value that is a list of flags or items, consider using
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	473 "+=" and "-=" to keep the existing value. Be aware that the user may have
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	474 changed an option value already. First resetting to the default value and
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	475 then changing it is often a good idea. Example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	476
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	477 setlocal formatoptions& formatoptions+=ro
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	478
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	479
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	480 MAPPINGS
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	481
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	482 To make sure mappings will only work in the current buffer use the >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	483
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	484 map <buffer>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	485
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	486 command. This needs to be combined with the two-step mapping explained above.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	487 An example of how to define functionality in a filetype plugin: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	488
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	489 if !hasmapto('<Plug>JavaImport;')
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	490 map <buffer> <unique> <LocalLeader>i <Plug>JavaImport;
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	491 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	492 noremap <buffer> <unique> <Plug>JavaImport; oimport ""<Left><Esc>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	493
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	494 \|hasmapto()\| is used to check if the user has already defined a map to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	495 <Plug>JavaImport;. If not, then the filetype plugin defines the default
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	496 mapping. This starts with \|<LocalLeader>\|, which allows the user to select
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	497 the key(s) he wants filetype plugin mappings to start with. The default is a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	498 backslash.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	499 "<unique>" is used to give an error message if the mapping already exists or
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	500 overlaps with an existing mapping.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	501 \|:noremap\| is used to avoid that any other mappings that the user has defined
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	502 interferes. You might want to use ":noremap <script>" to allow remapping
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	503 mappings defined in this script that start with <SID>.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	504
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	505 The user must have a chance to disable the mappings in a filetype plugin,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	506 without disabling everything. Here is an example of how this is done for a
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	507 plugin for the mail filetype: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	508
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	509 # Add mappings, unless the user didn't want this.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	510 if !exists("g:no_plugin_maps") && !exists("g:no_mail_maps")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	511 # Quote text by inserting "> "
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	512 if !hasmapto('<Plug>MailQuote;')
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	513 vmap <buffer> <LocalLeader>q <Plug>MailQuote;
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	514 nmap <buffer> <LocalLeader>q <Plug>MailQuote;
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	515 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	516 vnoremap <buffer> <Plug>MailQuote; :s/^/> /<CR>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	517 nnoremap <buffer> <Plug>MailQuote; :.,$s/^/> /<CR>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	518 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	519
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	520 Two global variables are used:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	521 \|g:no_plugin_maps\| disables mappings for all filetype plugins
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	522 \|g:no_mail_maps\| disables mappings for the "mail" filetype
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	523
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	524
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	525 USER COMMANDS
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	526
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	527 To add a user command for a specific file type, so that it can only be used in
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	528 one buffer, use the "-buffer" argument to \|:command\|. Example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	529
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	530 command -buffer Make make %:r.s
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	531
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	532
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	533 VARIABLES
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	534
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	535 A filetype plugin will be sourced for each buffer of the type it's for. Local
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	536 script variables will be shared between all invocations. Use local buffer
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	537 variables \|b:var\| if you want a variable specifically for one buffer.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	538
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	539
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	540 FUNCTIONS
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	541
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	542 When defining a function, this only needs to be done once. But the filetype
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	543 plugin will be sourced every time a file with this filetype will be opened.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	544 This construct makes sure the function is only defined once: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	545
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	546 if !exists("*Func")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	547 def Func(arg)
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	548 ...
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	549 enddef
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	550 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	551 <
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	552 Don't forget to use "noclear" with the `vim9script` command to avoid that the
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	553 function is deleted when the script is sourced a second time.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	554
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	555
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	556 UNDO undo_indent undo_ftplugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	557
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	558 When the user does ":setfiletype xyz" the effect of the previous filetype
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	559 should be undone. Set the b:undo_ftplugin variable to the commands that will
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	560 undo the settings in your filetype plugin. Example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	561
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	562 b:undo_ftplugin = "setlocal fo< com< tw< commentstring<"
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	563 \ .. "\| unlet b:match_ignorecase b:match_words b:match_skip"
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	564
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	565 Using ":setlocal" with "<" after the option name resets the option to its
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	566 global value. That is mostly the best way to reset the option value.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	567
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	568 For undoing the effect of an indent script, the b:undo_indent variable should
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	569 be set accordingly.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	570
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	571 Both these variables use legacy script syntax, not \|Vim9\| syntax.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	572
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	573
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	574 FILE NAME
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	575
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	576 The filetype must be included in the file name \|ftplugin-name\|. Use one of
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	577 these three forms:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	578
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	579 .../ftplugin/stuff.vim
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	580 .../ftplugin/stuff_foo.vim
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	581 .../ftplugin/stuff/bar.vim
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	582
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	583 "stuff" is the filetype, "foo" and "bar" are arbitrary names.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	584
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	585
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	586 FILETYPE DETECTION plugin-filetype
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	587
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	588 If your filetype is not already detected by Vim, you should create a filetype
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	589 detection snippet in a separate file. It is usually in the form of an
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	590 autocommand that sets the filetype when the file name matches a pattern.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	591 Example: >
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	592
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	593 au BufNewFile,BufRead *.foo setlocal filetype=foofoo
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	594
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	595 Write this single-line file as "ftdetect/foofoo.vim" in the first directory
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	596 that appears in 'runtimepath'. For Unix that would be
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	597 "~/.vim/ftdetect/foofoo.vim". The convention is to use the name of the
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	598 filetype for the script name.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	599
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	600 You can make more complicated checks if you like, for example to inspect the
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	601 contents of the file to recognize the language. Also see \|new-filetype\|.
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	602
f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	603
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	604 SUMMARY ftplugin-special
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	605
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	606 Summary of special things to use in a filetype plugin:
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	607
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	608 <LocalLeader> Value of "maplocalleader", which the user defines as
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	609 the keys that filetype plugin mappings start with.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	610
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	611 map <buffer> Define a mapping local to the buffer.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	612
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	613 noremap <script> Only remap mappings defined in this script that start
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	614 with <SID>.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	615
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	616 setlocal Set an option for the current buffer only.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	617
29290 dc4de65a7fb7 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 29066 diff changeset	618 command -buffer Define a user command local to the buffer.
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	619
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	620 exists("*s:Func") Check if a function was already defined.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	621
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	622 Also see \|plugin-special\|, the special things used for all plugins.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	623
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	624 ==============================================================================
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	625 51.3 Writing a compiler plugin write-compiler-plugin
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	626
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	627 A compiler plugin sets options for use with a specific compiler. The user can
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	628 load it with the \|:compiler\| command. The main use is to set the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	629 'errorformat' and 'makeprg' options.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	630
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	631 Easiest is to have a look at examples. This command will edit all the default
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	632 compiler plugins: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	633
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	634 next $VIMRUNTIME/compiler/*.vim
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	635
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	636 Type `:next` to go to the next plugin file.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	637
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	638 There are two special items about these files. First is a mechanism to allow
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	639 a user to overrule or add to the default file. The default files start with: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	640
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	641 vim9script
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	642 if exists("g:current_compiler")
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	643 finish
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	644 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	645 g:current_compiler = "mine"
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	646
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	647 When you write a compiler file and put it in your personal runtime directory
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	648 (e.g., ~/.vim/compiler for Unix), you set the "current_compiler" variable to
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	649 make the default file skip the settings.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	650 :CompilerSet
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	651 The second mechanism is to use ":set" for ":compiler!" and ":setlocal" for
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	652 ":compiler". Vim defines the ":CompilerSet" user command for this. However,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	653 older Vim versions don't, thus your plugin should define it then. This is an
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	654 example: >
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	655
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	656 if exists(":CompilerSet") != 2
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	657 command -nargs=* CompilerSet setlocal <args>
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	658 endif
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	659 CompilerSet errorformat& " use the default 'errorformat'
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	660 CompilerSet makeprg=nmake
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	661
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	662 When you write a compiler plugin for the Vim distribution or for a system-wide
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	663 runtime directory, use the mechanism mentioned above. When
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	664 "current_compiler" was already set by a user plugin nothing will be done.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	665
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	666 When you write a compiler plugin to overrule settings from a default plugin,
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	667 don't check "current_compiler". This plugin is supposed to be loaded
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	668 last, thus it should be in a directory at the end of 'runtimepath'. For Unix
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	669 that could be ~/.vim/after/compiler.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	670
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	671 ==============================================================================
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	672 51.4 Distributing Vim scripts distribute-script
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	673
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	674 Vim users will look for scripts on the Vim website: http://www.vim.org.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	675 If you made something that is useful for others, share it!
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	676
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	677 Another place is github. But there you need to know where to find it! The
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	678 advantage is that most plugin managers fetch plugins from github. You'll have
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	679 to use your favorite search engine to find them.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	680
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	681 Vim scripts can be used on any system. However, there might not be a tar or
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	682 gzip command. If you want to pack files together and/or compress them the
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	683 "zip" utility is recommended.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	684
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	685 For utmost portability use Vim itself to pack scripts together. This can be
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	686 done with the Vimball utility. See \|vimball\|.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	687
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	688 It's good if you add a line to allow automatic updating. See \|glvs-plugins\|.
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	689
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	690 ==============================================================================
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	691
29066 f8e9d5023bf6 Update runtime files Bram Moolenaar <Bram@vim.org> parents: 28933 diff changeset	692 Next chapter: \|usr_52.txt\| Write large plugins
28862 82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	693
82244cfc4694 Update runtime files, new color schemes Bram Moolenaar <Bram@vim.org> parents: diff changeset	694 Copyright: see \|manual-copyright\| vim:tw=78:ts=8:noet:ft=help:norl:

Mercurial > vim

annotate runtime/doc/usr_51.txt @ 33262:6eac4f616293 v9.0.1899