/
metarw.txt
367 lines (271 loc) · 12.8 KB
/
metarw.txt
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
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
*metarw.txt* a framework to read/write a fake:path
Version 0.2.0
Script ID: 2335
Copyright (C) 2008-2018 Kana Natsuno <http://whileimautomaton.net/>
License: MIT license {{{
Permission is hereby granted, free of charge, to any person obtaining
a copy of this software and associated documentation files (the
"Software"), to deal in the Software without restriction, including
without limitation the rights to use, copy, modify, merge, publish,
distribute, sublicense, and/or sell copies of the Software, and to
permit persons to whom the Software is furnished to do so, subject to
the following conditions:
The above copyright notice and this permission notice shall be included
in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
}}}
CONTENTS *metarw-contents*
Introduction |metarw-introduction|
Interface |metarw-interface|
Commands |metarw-commands|
Functions |metarw-functions|
Key Mappings |metarw-key-mappings|
Content Browswer |metarw-content-browser|
Schemes |metarw-schemes|
Terms |metarw-terms|
Bugs |metarw-bugs|
Changelog |metarw-changelog|
==============================================================================
INTRODUCTION *metarw-introduction*
*metarw* is a Vim plugin to provide a framework to read/write anything via
a file of which name is written in a special notation. Suppose that you are
editing `src/app.js`, and you want to view the same file in another topic
branch. It is tedius to switch a branch just for viewing a file. It would be
useful if the file was viewed by `:new git:topic:src/app.js`, wouldn't it?
It is possible to implement such behavior by hooking |BufReadCmd| and other
events. But it is a tedious task to do so for each time without mistakings.
With metarw, all you have to do write two functions to describe how to
read/write desired contents.
In addition, metarw also provides content browser like |netrw|. For example,
you can list contents of `src` directory in another topic branch by opening
`git:topic:src/`. Though you have to define a function for how to list
contents of this fakepath, you don't have to implement netrw-like browser for
each time.
Requirements:
- Vim 8.0 or later
Optionals:
- |metarw-scheme-script| such as
- |metarw-git| https://github.com/kana/vim-metarw-git
- |metarw-esa| https://github.com/kana/vim-metarw-esa
Demo:
- http://www.screencast.com/t/fCc8cFaiQj
Latest version:
- https://github.com/kana/vim-metarw
==============================================================================
INTERFACE *metarw-interface*
------------------------------------------------------------------------------
COMMANDS *metarw-commands*
:Edit[!] [++opt] [+cmd] [{file}] *:Edit*
:Read [++opt] [{file}] *:Read*
:Source [{file}] *:Source*
:[range]Write[!] [{file}] *:Write*
Same as |:edit| and other commands, but the completion
of their arguments is extended to also complete
fakepathes.
These wrapper commands are not defined automatically.
If you want them, you have to call
|metarw#define_wrapper_commands()|.
------------------------------------------------------------------------------
FUNCTIONS *metarw-functions*
*metarw#complete()*
metarw#complete({arglead}, {cmdline}, {cursorpos})
Function for |:command-complete| to complete also
fakepathes. Use as follows:
"-complete=customlist,metarw#complete".
*metarw#define_wrapper_commands()*
metarw#define_wrapper_commands({override-p})
Define wrapper commands (see |metarw-commands|.)
Override existent commands if {override-p} is true.
*metarw#is_preparing_to_edit()*
metarw#is_preparing_to_edit()
Return true if the current context is preparing to
|:edit| a fakepath rather than to |:read| it.
Otherwise, return false.
This is useful if you need special configuration for
interactive editing which is not necessary for :read.
------------------------------------------------------------------------------
KEY MAPPINGS *metarw-key-mappings*
The following key mappings are available for |metarw-content-browser|. All of
them are buffer-local and defined in Normal mode:
<Plug>(metarw-open-here) *<Plug>(metarw-open-here)*
<Plug>(metarw-open-split) *<Plug>(metarw-open-split)*
<Plug>(metarw-open-vsplit) *<Plug>(metarw-open-vsplit)*
Open the item under the cursor in the current window
or newly created window. If there is no item under
the cursor, nothing will be happened.
<Plug>(metarw-go-to-parent) *<Plug>(metarw-go-to-parent)*
Open the "parent" item in the current window. The
"parent" item is always the first item listed in
a content browser.
*g:metarw_no_default_key_mappings*
The following key mappings will be also available unless
g:metarw_no_default_key_mappings is defined:
{lhs} {rhs}
-------- -----------------------------
<Return> <Plug>(metarw-open-here)
<C-m> <Plug>(metarw-open-here)
o <Plug>(metarw-open-split)
v <Plug>(metarw-open-vsplit)
- <Plug>(metarw-go-to-parent)
------------------------------------------------------------------------------
CONTENT BROWSER *metarw-content-browser*
Similar to the relation of directories and files, some sorts of fakepaths are
containers of other fakepaths. If such fakepaths are given to |:edit|, |:new|
or other commands, metarw will set up the newly created buffer as a content
browser like |newrw|.
In this content browser, |metarw-key-mappings| are available, and 'filetype'
of a content browser is set to "metarw". Use this information for your own
customization.
*metarw-browser-item*
Each item displayed in the content browser is represented as a |Dictionary|.
The following keys are available:
label (string, required)
The label of the item which is displayed in the content browser.
fakepath (string, required)
The fakepath to open the item by |<Plug>(metarw-open-here)| etc.
The first item should be the "parent" of the current {fakepath}, and it is
used for |<Plug>(metarw-go-to-parent)|.
==============================================================================
SCHEMES *metarw-schemes*
To create your own scheme, write a Vim script file and put the file under
a directory named "autoload/metarw/" in 'runtimepath'. Such script is called
as a scheme script. The name of a scheme script must be "{scheme}.vim", where
{scheme} is the name of the scheme.
Scheme scripts must implement all of the following functions:
*metarw#{scheme}#complete()*
metarw#{scheme}#complete({arglead}, {cmdline}, {cursorpos})
Complete the names of fakepaths. This function is
like the one which is described at
|:command-completion-customlist|, but there are the
following differences:
- {arglead} is split into "head" part and "tail" part.
They must fulfill the following equation:
{arglead} ==# head_part . tail_part
- This function must complete candidates which are
conteind in a stuff represented by the "head" part.
- Return value is a list with 3 items.
The first item is a list of candidates.
The second item is the "head" part.
The third item is the "tail" part.
- Returned candidates will be filtered by callers. So
don't filter in this function.
For example, when completing file names and {arglead}
is "foo/b":
- The "head" part is "foo/".
- The "tail" part is "b".
- This function must complete files in the directory
"foo/".
metarw#{scheme}#read({fakepath}) *metarw#{scheme}#read()*
Read the content of {fakepath}.
This function must return a list with two items. The
first item indicates the type of a return value, and
the second item is an additional information for the
return value. The meanings of return values are as
follows:
First item Second item ~
---------- ---------------------------------- ~
*metarw#{scheme}#read()-error*
"error" A string which represents an error
message.
*metarw#{scheme}#read()-read*
"read" A string which will be given to
|:read| to read the content of
{fakepath}.
Or, a |Funcref| to return a list of
lines from {fakepath}.
*metarw#{scheme}#read()-browse*
"browse" A list of |metarw-brower-item|s to
set up |metarw-content-browser|.
See also |metarw#is_preparing_to_edit()|.
*metarw#{scheme}#write()*
metarw#{scheme}#write({fakepath}, {line1}, {line2}, {append-p})
Write or append the content of the current buffer from
{line1} to {line2} into {fakepath}. If {append-p} is
true, does appending instead of writing.
This function must return a list with one or more
items like |metarw#{scheme}#read()|, but the meanings
of return values are as follows:
First item Rest items ~
---------- ----------------------------------- ~
*metarw#{scheme}#write()-error*
"error" The second item must be a string which
represents an error message.
*metarw#{scheme}#write()-write*
"write" The second item must be a string which
will be given to |:write| to write the
content of {fakepath}, or must be
a |Funcref| to write to {fakepath}.
The third item is optional; if it is
given, it must be a string which is
a Vim script and it will be
|:execute|d after writing.
*metarw#{scheme}#write()-done*
"done" The rest items are just ignored. This
type means that writing is already
done by |metarw#{scheme}#write()|.
Don't reset 'modified' in this function. It will be
automatically treated by metarw.
==============================================================================
TERMS *metarw-terms*
Fakepath *metarw-fakepath*
A file-like argument written in a special notation.
For example, "git:master:src/ui.c" is a fakepath.
Scheme *metarw-scheme*
Scheme is the substring before the first ":" in the name of
a fakepath. For example, the scheme of "git:master:src/ui.c" is
"git".
The name of a scheme must consist of 2 or more characters, and it
should consist of only lowercase, English alphabets.
Scheme script *metarw-scheme-script*
Support script to enable to read/write fakepathes. One scheme script
supports just one scheme.
==============================================================================
BUGS *metarw-bugs*
- {range} for ":read {fakepath}" is ignored and it will always be treated as
the current line. Because there is no way to get {range} in |FileReadCmd|.
- See also https://github.com/kana/vim-metarw/issues
==============================================================================
CHANGELOG *metarw-changelog*
0.2.0 2018-04-11T22:10:10+09:00 *metarw-changelog-0.2.0*
- Add |metarw#is_preparing_to_edit()| for advanced use.
0.1.1 2018-04-09T02:53:34+09:00 *metarw-changelog-0.1.1*
- Fix a bug that 'modified' is not reset on |:write| if a scheme
script renames the buffer name.
0.1.0 2018-04-06T23:53:13+09:00 *metarw-changelog-0.1.0*
- Vim 8.0 or later is required.
- |Funcref| can be used to |metarw#{scheme}#read()| and
|metarw#{scheme}#write()|.
0.0.5 2009-05-23T14:51:43+09:00 *metarw-changelog-0.0.5*
- Fix wrong directory structure.
0.0.4 2009-05-23T14:51:43+09:00 *metarw-changelog-0.0.4*
- Refine the document.
- |metarw#{scheme}#write()|:
- Fix a bug that some kind of errors are not handled properly.
- Add a way to execute a script after writing. See
|metarw#{scheme}#write()-write| for the details.
0.0.3 2008-08-30T03:11:55+09:00 *metarw-changelog-0.0.3*
- |metarw#{scheme}#write()|:
- Fix wrong implementation.
- Add new type of return value "done".
0.0.2 2008-08-10T23:43:48+09:00 *metarw-changelog-0.0.2*
- Separate |ku-metarw| as a independent package.
0.0.1 2008-08-10T12:19:52+09:00 *metarw-changelog-0.0.1*
- Add a special source of ku (see |metarw-schemes-as-ku-sources|).
- Fix autocommands not to hook fakepaths with any schene name which
consists of less than 2 characters. Old definitions incorrectly
recognized paths with a drive letter in Microsoft Windows
environment as a fakepath. (thanks to id:thinca)
- Add 2 rules on the name of a scheme (see |metarw-scheme|).
- Fix plugin/metarw.vim to be properly reloadable.
- Fix requirements - metarw uses |fnameescape()| which is added since
Vim 7.1.299. (thanks to id:thinca)
0.0.0 2008-07-11T16:51:59+09:00 *metarw-changelog-0.0.0*
- Initial version.
==============================================================================
vim:tw=78:ts=8:ft=help:norl:fen:fdl=0:fdm=marker: