-
Notifications
You must be signed in to change notification settings - Fork 0
/
README
265 lines (211 loc) · 11 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
*TagmaTips.txt* Plugin to display Tool Tips.
For Vim version 7.x.
Last Changed: Fri Nov 22 05:33 AM 2013 EST
https://github.com/JessicaKMcIntosh/TagmaTips
http://www.vim.org/scripts/script.php?script_id=3738
By Jessica K McIntosh AT gmail DOT com
Contents: *TagmaTips*
Description |TagmaTips-description|
Installation |TagmaTips-installation|
Supported Types |TagmaTips-types|
Commands |TagmaTips-commands|
Settings |TagmaTips-settings|
Adding File Types |TagmaTips-adding-types|
Plugin API |TagmaTips-api|
==============================================================================
DESCRIPTION *TagmaTips-description*
This plugin uses the Tool Tip / Balloon functionality of Vim to display Tool
Tips for code. Currently only Awl, Tcl and Vim are supported.
Tool Tips are displayed for commands, variables and user defined procedures /
functions. The current buffer is checked for user defined procedures /
functions when it is written to disk.
See the GitHub URL above for more information and screenshots (in the wiki)
Note: TagmaTips can consume a large quantity of memory. To limit the memory
used either disable auto enable or limit the file types that are enabled.
==============================================================================
INSTALLATION *TagmaTips-installation*
Copy the files to your ~/.vim or ~/vimfiles directory.
If using a package manager like pathogen place the whole directory in the
bundle directory.
==============================================================================
SUPPORTED TYPES *TagmaTips-types*
AwK Locates user defined functions.
Supports Awk variables and most primitives.
Perl Locates user defined functions.
Supports most Perl primitives.
Tcl Locates user defined functions.
Supports most Tcl variables and primitives.
Vim Locates user defined functions.
Loads builtin functions, internal variables and features from the
eval.txt help file. Loads options from the options.txt help file.
Loads AutoCmd Events from the autocmd.txt help file.
If enabled the data loaded from the help files is cached.
==============================================================================
COMMANDS *TagmaTips-commands*
:EnableTips *EnableTips*
Enables tool tips for the current buffer if the file type is
supported. Reports an error if the file type is not supported or if
tool tips are already enabled for the current buffer.
==============================================================================
SETTINGS *TagmaTips-settings*
*g:TagmaTipsAutoEnable*
Automatically enables tool tips for supported file types.
If disabled tool tips must be manually enabled for each buffer using
the command |EnableTips|.
Defaults to true. Set to 0 to disable. >
let g:TagmaTipsAutoEnable = 1
<
*g:TagmaTipsDebugMode*
Enables debugging output.
This is only useful if developing changes or experiencing issues.
Currently this only enables errors when attempting to load a file type
specific autoload file. This will have more uses in the future.
Disabled by default. Set to 1 to enable. >
let g:TagmaTipsDebugMode = 0
<
*g:TagmaTipsCachePath*
The path to save Cache files.
Defaults to the directory 'cache/' where the plugin is installed.
If the directory does not exist an attempt is made to create it. >
let g:TagmaTipsCachePath = '~/.vim/tips_cache/'
<
*g:TagmaTipsEnableCache*
Enables caching of Tool Tips data if the file type supports it.
If disabled also disables creathing the cache path.
Enabled by default. Set to 0 to disable. >
let g:TagmaTipsEnableCache = 1
<
*g:TagmaTipsLineLimit*
Limits the number of lines in the Tool Tips body.
If a tool tip body exceeds this number of lines it is truncated and
the last line is "...". Does not affect existinc cache files.
Defaults to 30 lines. >
let g:TagmaTipsLineLimit = 30
<
*g:TagmaTipsTypes*
Set the file types that will be enabled. This must be a list.
If not specified all supported file types are enabled. >
let g:TagmaTipsTypes = ['awk']
<
*g:TagmaTipsVimDisable*
Disables the extended Vim support.
Reading the data from the help files can take a while.
This will stop the related slow-down.
If caching is enabled this slow-down will only be experienced once.
Enabled by default. Set to 0 to disable. >
let g:TagmaTipsVimDisable = 1
<
==============================================================================
ADDING FILE TYPES *TagmaTips-adding-types*
To add new file types the file "plugin/TagmaTips.vim" needs to be modified.
The file type needs to be added to the Dictionary "g:TagmaTips#Settings. See
the the |TagmaTips-api| section for details.
In order for primitives and variables to exist for tool tips they must be
defined in an file type specific autoload file. The name of the file is
"autoload/TagmaTips#.vim" where "#" is the file type identifier. For example
the Tcl specific file is "autoload/TagmaTipstcl.vim". When a file type is
setup the function "LoadSettings" is called from the file type specific
autoload file. The function must include the autoload file in the name. The
Tcl example would be "TagmaTipstcl#LoadSettings()". See |autolaod| for more
information.
File types can have a custom function to lookup tool tips. If the setting
"expr" exists for a file type then that function is called if the tool tip can
not be found in the normal lists. See the |TagmaTips-api| section for details.
It is suggested to copy the settings and autoload files for an exist file type
and modify them to match the new file type. For a simple example see the Tcl
settings and file, for a complex example see the Vim settings and file.
==============================================================================
PLUGIN API *TagmaTips-api*
User Procedures ~
User procedures are searched in the current buffer using the function
TagmaTips#ProcScan(). This function is invoked when the buffer is written via
an |autocmd|. The procedures are stored in the dictionary
b:TagmaToolTipsProcs.
Cache Files ~
Cache files are stored in the directory cache/ in the directory the plugin
files are located. This can be changed via the |g:TagmaTipsCachePath| setting.
If the directory does not exist an attempt is made to create it. Cache files
are named after the file type with the extension .txt appended, eg vim.txt.
Cache data is saved and loaded using the functions TagmaTips#CacheSave() and
TagmaTips#CacheLoad()
Cache files contain four lines. The first two are comments, the plugin version
and the cache data. The comments identify the purpose of the file and warn
against changing the contents. The version is saved to prevent compatability
issues in future versions. The version is incremented when any change would
impact existing cache files, eliminating user intervention in such cases.
Functions ~
TagmaTips#CacheLoad({type}) *TagmaTips#CacheLoad()*
Source File: autoload/TagmaTips.vim
Load cache data for a file {type}. The cache data is added to the
g:TagmaTipsSettings dictionary for the specified file type.
TagmaTips#CacheSave({type}, {keys}) *TagmaTips#CacheSave()*
Source File: autoload/TagmaTips.vim
Saves the specified {keys} from the g:TagmaTipsSettings dictionary for
the specified file {type} to a cache file.
*TagmaTips#StoreTip()*
TagmaTips#StoreTip({type}, {key}, {name}, {body})
Source File: autoload/TagmaTips.vim
Stores a tool tip in the g:TagmaTipsSettings dictionary. The tool tip
is stored by {name} for the file {type} under the specific {key}. The
{body} should be a list and will be converted if it is not. If the
{body} has more than |g:TagmaTipsLineLimit| elements it is truncated
and "..." is used for the last item. If {name} is empty no action is
performed. This is intended behavior to allow calling as data is
parsed without adding extra checks. If {type} is empty the tool tip is
stored instead in b:TagmaToolTipsProcs.
TagmaTips#ProcScan() *TagmaTips#ProcScan()*
Source File: autoload/TagmaTips.vim
This is the function that scans a file for user defined procedures. It
is run via an autocmd when the file is written to disk. This function
should not be changed as it will affect all file types. The settings
_blank and _proc define what is considered a user procedure and which
lines are included in the tool tip body.
TagmaTips#SetupBuffer() *TagmaTips#SetupBuffer()*
Source File: autoload/TagmaTips.vim
Creates settings in the current buffer for tool tips. All settings are
based on the file type. An autocmd is created to scan for user
procedures when the buffer is written. If the file type specific
settings, see _loaded, have not been loaded they are loaded at this
point. Some settings are cached in buffer variables for cleaner code
and faster access.
File Type Settings ~
Each file type has an entry in the g:TagmaTipsSettings dictionary. The
dictionary is keyed by file type. These settings determin how the plugin
behaves for each file type. At a minimum the settings "_blank" and "_proc"
must be set. All other settings are optional, with the exception of "_loaded".
File type specific settings can be freely added. Settings that start with an
underscore, "_", are reserved for internal use only.
_loaded Boolean to indicate if file type specific settings are loaded.
Only present when the file type settings have been loaded. To disable
checking for file type specific settings set this to 1. Normally this
should only be set internally.
_blank Regexp that matches a blank line.
This is used to locate the start of the description for a user
procedure.
_proc Regexp that matches a procedure definition.
Each line of the current file is checked for this regexp when the file
is written. Combined with the setting blank defines how the function
TagmaTips#ProcScan() locates user defined procedures.
The regexp must contain two groupings:
#1 The procedure definition for the tooltip body.
#2 The name of the procedure for the dictionary of user procedures.
This is used as they key in the dictionary and is what would be
passed from Vim to indicate the cursor is over a word.
_prim Dictionary of language primitives.
_vars Dictionary of language variables.
_expr If present this function is called if no matches are found for the
word under the cursor. Normally tool tips are checked for in the user
procedure dictionary then the settings _prim, _vars, _palias and
_valias. If no entries are found the function name stored in this
setting is called. This function MUST return a list, even if it is
empty. See the file autoload/TagmaTipsvim.vim for an example.
_palias Dictionary of primitive aliases.
_valias Dictionary of variable aliases.
The alias settings are used when a primitive or variable can have
several names. If an alias matches then that word is looked up in the
respective setting. For example the Perl documentation for the "-X"
operator is would have aliases keys for "-r", "-w" and so on.
The settings "_vars", "_prim", "_palias" and "_valias" are populated from an
autoload plugin for the file type. See autoload/TagmaTipstcl.vim for a simple
example.
vim:ts=8 sw=8 noexpandtab tw=78 ft=help: