Skip to content

Commit b36e90d

Browse files
Mike Sharpevim-scripts
Mike Sharpe
authored and
vim-scripts
committedNov 6, 2010
Version 2.14 doc
Documentation for a.vim v2.14. Drop it in your doc directory and run helptags.
1 parent d809a1c commit b36e90d

File tree

2 files changed

+161
-619
lines changed

2 files changed

+161
-619
lines changed
 

‎doc/alternate.txt

+161
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,161 @@
1+
2+
*alternate.txt* Alternate Plugin Sat May 13 15:35:38 CDT 2006
3+
4+
Author: Michael Sharpe <feline@irendi.com>
5+
Copyright: (c) 2000-2006 Michael Sharpe
6+
We grant permission to use, copy modify, distribute, and sell this
7+
software for any purpose without fee, provided that the above
8+
copyright notice and this text are not removed. We make no guarantee
9+
about the suitability of this software for any purpose and we are
10+
not liable for any damages resulting from its use. Further, we are
11+
under no obligation to maintain or extend this software. It is
12+
provided on an "as is" basis without any expressed or implied
13+
warranty.
14+
15+
==============================================================================
16+
1. Contents *AS* *AV* *AT* *alternate*
17+
18+
1. Contents...........................: |alternate|
19+
2. Purpose............................: |alternate-purpose|
20+
3. Commands...........................: |alternate-commands|
21+
4. Configuration......................: |alternate-config|
22+
5. Installation.......................: |alternate-installation|
23+
6. Bugs/Enhancements..................: |alternate-support|
24+
7. Acknowledgments....................: |alternate-acknowledgments|
25+
26+
==============================================================================
27+
2. Purpose *alternate-purpose*
28+
29+
The purpose of a.vim is to allow quick and easy switching between source files
30+
and corresponding header files. Many languages (C, C++, ada, ocaml, lex/yacc)
31+
have the concept of source/header files or the like. It is quite common during
32+
development or review to need to edit both files together. This plugin attempts
33+
to simplify that process. There are four commands which while editing a source
34+
file allow for the quick switching to the corresponding header and vice versa.
35+
The only difference between the commands is how the switch occurs. In the
36+
following sections the commands, configuration and installation procedures are
37+
described.
38+
39+
==============================================================================
40+
3. Commands *alternate-commands*
41+
42+
There are 4 commands provided by this plugin. They are
43+
44+
:A switches to the header file corresponding to the source file in the current
45+
buffer (or vice versa).
46+
47+
:AS similar to :A except the current buffer is split horizontally such that the
48+
source file is on one split and the header is in the other.
49+
50+
:AV similar to :AS except that the split is vertical
51+
52+
:AT similar to :AS and :AV except a new tab is opened instead of a split
53+
54+
:AN will cycle through all alternate files found (e.g. ./a.h and
55+
../include/a.h exist when switching from a.c)
56+
57+
In all cases if the corresponding alternate file is already loaded that buffer
58+
is preferred. That is this plugin will never load the same file twice.
59+
60+
==============================================================================
61+
4. Configuration *alternate-config*
62+
63+
It is possible to configure three separate pieces of behaviour of this plugin.
64+
65+
a) Extensions: Each language has different extensions for identifying the
66+
source and header files. Many languages support multiple different but related
67+
extensions. As such this plugin allow for the complete specification of how
68+
source and header files correspond to each other via extension maps. There are
69+
a number of maps built in. For example, the following variable setting
70+
71+
g:alternateExtensions_CPP = "inc,h,H,HPP,hpp"
72+
73+
indicates that any file with a .CPP exetension can have a corresponding file
74+
with any of the .inc, .h, .H, .HPP, .hpp extension. The inverse is not
75+
specified by this map though. Typically each extension will have a mapping. So
76+
there would exist maps for .h, .inc, .H, .HPP, .hpp too. Extension maps should
77+
be specified before loading this plugin. Some of the builtin extension maps are
78+
as follows,
79+
80+
C and C++
81+
g:alternateExtensions_h = "c,cpp,cxx,cc,CC"
82+
g:alternateExtensions_H' = "C,CPP,CXX,CC"
83+
g:alternateExtensions_cpp' = "h,hpp"
84+
g:alternateExtensions_CPP' = "H,HPP"
85+
g:alternateExtensions_c' = "h"
86+
g:alternateExtensions_C' = "H"
87+
g:alternateExtensions_cxx' = "h"
88+
89+
Ada
90+
g:alternateExtensions_adb' = "ads"
91+
g:alternateExtensions_ads' = "adb"
92+
93+
Lex/Yacc
94+
g:alternateExtensions_l' = "y,yacc,ypp"
95+
g:alternateExtensions_lex' = "yacc,y,ypp"
96+
g:alternateExtensions_lpp' = "ypp,y,yacc"
97+
g:alternateExtensions_y' = "l,lex,lpp"
98+
g:alternateExtensions_yacc' = "lex,l,lpp"
99+
g:alternateExtensions_ypp' = "lpp,l,lex"
100+
101+
b) Search Paths: In many projects the location of the source files and the
102+
corresponding header files is not always the same directory. This plugin allows
103+
the search path it uses to locate source and header files to be configured.
104+
The search path is specified by setting the g:alternateSearchPath variable. The
105+
default setting is as follows,
106+
107+
g:alternateSearchPath = 'sfr:../source,sfr:../src,sfr:../include,sfr:../inc'
108+
109+
This indicates that the corresponding file will be searched for in ../source,
110+
../src. ../include and ../inc all relative to the current file being switched
111+
from. The value of the g:alternateSearchPath variable is simply a comma
112+
separated list of prefixes and directories. The "sfr:" prefix indicates that
113+
the path is relative to the file. Other prefixes are "wdr:" which indicates
114+
that the directory is relative to the current working directory and "abs:"
115+
which indicates the path is absolute. If no prefix is specified "sfr:" is
116+
assumed.
117+
118+
c) Regex Paths: Another type of prefix which can appear in the
119+
g:alternateSearchPath variable is that of "reg:". It is used to apply a regex
120+
to the path of the file in the buffer being switched from to locate the
121+
alternate file. E.g. 'reg:/inc/src/g/' will replace every instance of 'inc'
122+
with 'src' in the source file path. It is possible to use match variables so
123+
you could do something like: 'reg:|src/\([^/]*\)|inc/\1||' (see |substitute|,
124+
|help pattern| and |sub-replace-special| for more details. The exact syntax of
125+
a "reg:" specification is
126+
reg:<sep><pattern><sep><subst><sep><flag><sep>
127+
128+
<sep> seperator character, we often use one of [/|%#]
129+
<pattern> is what you are looking for
130+
<subst> is the output pattern
131+
<flag> can be g for global replace or empty
132+
133+
d) No Alternate Behaviour: When attempting to alternate/switch from a
134+
source/header to its corresponding file it is possible that the corresponding
135+
file does not exist. In this case this plugin will create the missing alternate
136+
file in the same directory as the current file. Some users find this behaviour
137+
irritating. This behaviour can be disabled by setting
138+
g:alternateNoDefaultAlternate to 1. When this variable is not 0 a message will
139+
be displayed indicating that no alternate file exists.
140+
141+
==============================================================================
142+
5. Installation *alternate-installation*
143+
144+
To install this plugin simply drop the a.vim file in to $VIMRUNTIME/plugin
145+
(global or local) or simply source the file from the vimrc file. Ensure that
146+
any configuration occurs before the plugin is loaded/sourced.
147+
148+
==============================================================================
149+
6. Bugs/Enhancements *alternate-support*
150+
151+
Whilst no formal support is provided for this plugin the author is always happy
152+
to receive bug reports and enhancement requests. Please email all such
153+
reports/requests to feline@irendi.com.
154+
155+
==============================================================================
156+
7. Acknowledgments *alternate-acknowledgments*
157+
158+
The author would like to thank everyone who has submitted bug reports and
159+
feature enhancement requests in the past. In particular Bindu Wavell provided
160+
much of the original code implementing the search path and regex functionality.
161+
vim:tw=78:ts=8:ft=help

0 commit comments

Comments
 (0)
Failed to load comments.