1 *specky.txt* Last change: $Id$ |
|
2 |
|
3 VIM REFERENCE MANUAL by Mahlon E. Smith |
|
4 |
|
5 |
|
6 specky! |
|
7 |
|
8 A Plugin for testing Ruby code with RSpec -- and more *specky* |
|
9 ============================================================================== |
|
10 CONTENTS *SpeckyContents* |
|
11 |
|
12 1) Intro........................................|SpeckyIntro| |
|
13 2) Functionality................................|SpeckyFunctionality| |
|
14 3) Enabling Specky..............................|SpeckyInstallation| |
|
15 4) Configuration................................|SpeckyOptions| |
|
16 4.1) Create text banners....................|g:speckyBannerKey| |
|
17 4.2) Cycling quote styles...................|g:speckyQuoteSwitcherKey| |
|
18 4.3) Display ruby documentation.............|g:speckyRunRdocKey| |
|
19 4.4) Toggle editing between spec and code...|g:speckySpecSwitcherKey| |
|
20 4.5) Run specs for the current buffer.......|g:speckyRunSpecKey| |
|
21 4.6) Modify the default spec command........|g:speckyRunSpecCmd| |
|
22 4.7) Modify the default rdoc command........|g:speckyRunRdocCmd| |
|
23 4.8) Alter new window behavior..............|g:speckyWindowType| |
|
24 4.9) Running older rspec (1.x) .............|g:speckySpecVersion| |
|
25 5) Author.......................................|SpeckyAuthor| |
|
26 6) License......................................|SpeckyLicense| |
|
27 |
|
28 |
|
29 |
|
30 ============================================================================== |
|
31 1. INTRO *SpeckyIntro* |
|
32 |
|
33 Specky is primarily a small collection of functions to help make behavioral |
|
34 testing streamlined and easy when working with ruby and rspec. Specky |
|
35 supports rspec 2.x by default, and is backwards compatible with rspec 1.x. |
|
36 |
|
37 Specky secondarily includes a couple of conveniences to make your everyday |
|
38 programming tasks smooooth and pleasurable. |
|
39 |
|
40 |
|
41 ============================================================================== |
|
42 2. FUNCTIONALITY *SpeckyFunctionality* |
|
43 |
|
44 Okay then, what does it do? |
|
45 |
|
46 By default? Nothing but syntax highlighting unless you are comfortable using |
|
47 the menus. I decided the easiest way to cherry pick the functionality that |
|
48 you'd like was to enable them via key bindings. By doing this, Specky won't |
|
49 make assumptions about your current environment, and won't stomp on anything |
|
50 you don't want it to. |
|
51 |
|
52 Specky won't do -anything- with your environment until you enable ~ |
|
53 the key bindings!! ~ |
|
54 |
|
55 After you've configured your bindings, here are some of the things you can |
|
56 now do with a single key stroke: |
|
57 > |
|
58 - Switch back and forth from code to testing spec |
|
59 |
|
60 - Run the spec, with results going to a new, syntax highlighted buffer |
|
61 |
|
62 - Jump quickly to spec failures and failure detail |
|
63 - 'e' and 'r' to move back and forth on each failed assertion, |
|
64 - 'E' to jump details for it. |
|
65 - '<C-e>' to "forget" the currently selected failed assertion |
|
66 - 'q' to close the spec output buffer. |
|
67 |
|
68 - View rdoc of the word under the cursor |
|
69 |
|
70 - Dynamically switch string types for the word under the cursor |
|
71 (double quoted, quoted, symbol) |
|
72 |
|
73 - Make lovely and quick comment banners for ruby code. |
|
74 |
|
75 Specky also includes a "snippets" file that can be used with the Snipmate |
|
76 plugin by Michael Sanders <msanders42+vim@gmail.com>. (Minimum version 0.74.) |
|
77 |
|
78 http://www.vim.org/scripts/script.php?script_id=2540 |
|
79 |
|
80 ============================================================================== |
|
81 3. ENABLING-SPECKY *SpeckyInstallation* |
|
82 |
|
83 Getting Specky to work should be a fairly trivial process. Specky now |
|
84 uses a custom rspec formatter to function reliably, and it needs to know |
|
85 where that lives on your system. |
|
86 |
|
87 If you installed Specky from Vimball, it is likely found at: |
|
88 |
|
89 ~/.vim/ruby/specky_formatter.rb ~ |
|
90 |
|
91 Otherwise, you'll need to locate it, and tell rspec to use it in one of two |
|
92 ways. |
|
93 |
|
94 1) Set the 'g:speckyRunSpecCmd' variable explicitly: |
|
95 |
|
96 let g:speckyRunSpecCmd = "rspec -r ~/.vim/ruby/specky_formatter.rb -f SpeckyFormatter" ~ |
|
97 |
|
98 2) or, leave 'g:speckyRunSpecCmd' at its default value, and instead use |
|
99 an '.rspec' settings file in the root directory of the the project |
|
100 you're working in. I find this method much more flexible -- the |
|
101 '.rspec' file can be carried with your project, and customized to |
|
102 include additional bits like custom $LOAD_PATH injections, etc. |
|
103 Here's what mine usually looks like: > |
|
104 |
|
105 -r loadpath |
|
106 -r ~/.vim/bundle/specky/ruby/specky_formatter |
|
107 -f SpeckyFormatter |
|
108 |
|
109 You can also use both of these methods, and use the |
|
110 'SpeckyConsoleFormatter' class from your .rspec file, if it suits |
|
111 your fancy. |
|
112 |
|
113 |
|
114 After that is taken care of, then just set up your keybindings in your |
|
115 .vimrc. Here's what my config looks like. > |
|
116 |
|
117 let g:speckyBannerKey = "<C-S>b" |
|
118 let g:speckyQuoteSwitcherKey = "<C-S>'" |
|
119 let g:speckyRunRdocKey = "<C-S>r" |
|
120 let g:speckySpecSwitcherKey = "<C-S>x" |
|
121 let g:speckyRunSpecKey = "<C-S>s" |
|
122 let g:speckyRunRdocCmd = "fri -L -f plain" |
|
123 let g:speckyWindowType = 2 |
|
124 |
|
125 With these bindings, all Specky commands start with <ctrl-s> ("s" for |
|
126 Specky!), followed by a mnemonic function to run: |
|
127 |
|
128 b ----> Banner creation ~ |
|
129 ' ----> Quote cycling ~ |
|
130 r ----> run Rdoc ~ |
|
131 x ----> code and spec eXchange ~ |
|
132 s ----> run rSpec ~ |
|
133 |
|
134 Of course, <ctrl-s> is a "suspend" signal for most terminals, so these |
|
135 bindings are meant for a |gui| environment, such as gvim. Your mileage (and |
|
136 tastes) will doubtlessly vary. Do what you will. I won't judge you. |
|
137 |
|
138 |
|
139 ============================================================================== |
|
140 4. CONFIGURATION-OPTIONS *SpeckyOptions* |
|
141 |
|
142 Here are all of the available configuration options. |
|
143 |
|
144 Please note that you must set binding variables: |
|
145 |
|
146 |g:speckyBannerKey| |
|
147 |g:speckyQuoteSwitcherKey| |
|
148 |g:speckyRunRdocKey| |
|
149 |g:speckySpecSwitcherKey| |
|
150 |g:speckyRunSpecKey| |
|
151 |
|
152 ...in order to enable the respective Specky functionality. See |
|
153 |SpeckyInstallation| for details. Any other options are entirely optional. |
|
154 Put these into your |vimrc|, or wherever else you enjoy storing this kind of |
|
155 stuff. |
|
156 |
|
157 |
|
158 ------------------------------------------------------------------------------ |
|
159 4.1 *g:speckyBannerKey* |
|
160 |
|
161 Setting this binding enables comment banner creation. |
|
162 |
|
163 This is purely a convenience routine, and a stylistic one at that. I prefer |
|
164 large advertising of what "area" of code you are in, along with other |
|
165 miscellaneous labels for humans to read. If this isn't how you roll, then by |
|
166 all means, don't enable this binding! :) |
|
167 |
|
168 As an example -- you can just type: |
|
169 |
|
170 instance methods ~ |
|
171 |
|
172 Then hit the keystroke. It will magically turn into: > |
|
173 |
|
174 ######################################################################## |
|
175 ### I N S T A N C E M E T H O D S |
|
176 ######################################################################## |
|
177 |
|
178 With all those saved extra keystrokes this might provide you per banner over |
|
179 the years, your RSI-free hands will thank you. And the total time savings!! |
|
180 Oh man, what are you going to DO with all of that extra free time? |
|
181 The possibilities are staggering. |
|
182 |
|
183 |
|
184 ------------------------------------------------------------------------------ |
|
185 4.2 *g:speckyQuoteSwitcherKey* |
|
186 |
|
187 Setting this binding enables quote "style switching". |
|
188 |
|
189 If you aren't in ruby mode, this just changes the word under the cursor |
|
190 back and forth from double quoting to single quoting. |
|
191 |
|
192 string -> "string" -> 'string' -> "string" ... ~ |
|
193 |
|
194 In ruby mode, symbols are also put into the rotation. |
|
195 |
|
196 "string" -> 'string' -> :string -> "string" ... ~ |
|
197 |
|
198 Note that quote cycling only works with a |word|. |
|
199 |
|
200 |
|
201 ------------------------------------------------------------------------------ |
|
202 4.3 *g:speckyRunRdocKey* |
|
203 |
|
204 Setting this enables the display of rdoc documentation for the current |
|
205 word under the cursor. For lookups with multiple matches, you can continue |
|
206 using this binding to "drill down" to the desired documentation. |
|
207 |
|
208 |
|
209 ------------------------------------------------------------------------------ |
|
210 4.4 *g:speckySpecSwitcherKey* |
|
211 |
|
212 Setting this enables spec to code switching, and visa versa. |
|
213 |
|
214 Switching uses path searching instead of reliance on directory structure in |
|
215 your project. The idea here is that you'd |:chdir| into your project |
|
216 directory. Spec files just need to end in '_spec.rb', which is a common |
|
217 convention. |
|
218 |
|
219 aRubyClass.rb ---> aRubyClass_spec.rb~ |
|
220 |
|
221 Because it leaves respective buffers open, you can essentially think of this |
|
222 as a quick toggle between code and tests. |
|
223 |
|
224 |
|
225 ------------------------------------------------------------------------------ |
|
226 4.5 *g:speckyRunSpecKey* |
|
227 |
|
228 Setting this variable runs "rspec" on the current buffer. |
|
229 |
|
230 All output is sent to a syntax highlighted scratch buffer. This new window is |
|
231 re-used for each spec run. You can quickly "jump" to assertion failures and |
|
232 their associated details with the following keys: |
|
233 |
|
234 e and r ~ |
|
235 Move forward and backward through the failed assertions. |
|
236 |
|
237 E~ |
|
238 While on a failure line, jump to the details of the failure. |
|
239 |
|
240 <C-e> ~ |
|
241 "Forget" the last found failed assertion, and start over at the |
|
242 beginning of the list. (ie, the next 'e' keystroke will select |
|
243 error #1.) |
|
244 |
|
245 q ~ |
|
246 Closes the spec output buffer. |
|
247 |
|
248 |
|
249 Normally, you'd only want to perform this keystroke while in a spec file |
|
250 buffer. If Specky thinks you are in code, rather than a buffer (as indicated |
|
251 by the lack of a "_spec.rb" file naming convention) then it will attempt to |
|
252 switch to the spec before running the command. |
|
253 |
|
254 |
|
255 ------------------------------------------------------------------------------ |
|
256 4.6 *g:speckyRunSpecCmd* |
|
257 |
|
258 This is the program, with flags, that the current file is sent to when |
|
259 executing the |g:speckyRunSpecKey| keybinding. |
|
260 |
|
261 A common addition is to include an "-r" flag for sucking in local libraries |
|
262 necessary for testing your project. In fact, this is required to use the |
|
263 rspec formatter supplied by Specky. See |SpeckyInstallation| for more info. |
|
264 |
|
265 Default: ~ |
|
266 rspec |
|
267 |
|
268 |
|
269 ------------------------------------------------------------------------------ |
|
270 4.7 *g:speckyRunRdocCmd* |
|
271 |
|
272 If you prefer an rdoc display program other than "ri", you can set it |
|
273 with this variable. "fri -L -f plain" is always a nice choice, for example. |
|
274 |
|
275 Default: ~ |
|
276 ri |
|
277 |
|
278 |
|
279 ------------------------------------------------------------------------------ |
|
280 4.8 *g:speckyWindowType* |
|
281 |
|
282 For both spec and rdoc commands, this variable controls the behavior of the |
|
283 newly generated window. |
|
284 |
|
285 Default: ~ |
|
286 0 |
|
287 |
|
288 0 ~ |
|
289 Create a new tabbed window |
|
290 1 ~ |
|
291 Split the current window horizontally |
|
292 2 ~ |
|
293 Split the current window vertically |
|
294 |
|
295 |
|
296 ------------------------------------------------------------------------------ |
|
297 4.9 *g:speckySpecVersion* |
|
298 |
|
299 Specky should work out of the box with rspec 2.x. If you'd like to use rspec |
|
300 1.x instead, you can do so with the following Vim settings: > |
|
301 |
|
302 let g:speckySpecVersion = 1 |
|
303 let g:speckyRunRdocCmd = "spec -fs" |
|
304 |
|
305 If you have both rspec 1.x and 2.x installed at the same time, you need to |
|
306 be explicit with what version you are executing: > |
|
307 |
|
308 let g:speckyRunRdocCmd = "spec _1.3.0_ -fs" |
|
309 |
|
310 |
|
311 ============================================================================== |
|
312 5. AUTHOR *SpeckyAuthor* |
|
313 |
|
314 |
|
315 Specky was written by Mahlon E. Smith. |
|
316 |
|
317 mahlon@martini.nu ~ |
|
318 http://www.martini.nu/ |
|
319 |
|
320 |
|
321 |
|
322 ============================================================================== |
|
323 6. LICENSE *SpeckyLicense* |
|
324 |
|
325 |
|
326 Specky is distributed under the BSD license. |
|
327 http://www.opensource.org/licenses/bsd-license.php |
|
328 > |
|
329 Copyright (c) 2008-2010, Mahlon E. Smith <mahlon@martini.nu> |
|
330 All rights reserved. |
|
331 |
|
332 Redistribution and use in source and binary forms, with or without |
|
333 modification, are permitted provided that the following conditions are |
|
334 met: |
|
335 |
|
336 * Redistributions of source code must retain the above copyright |
|
337 notice, this list of conditions and the following disclaimer. |
|
338 |
|
339 * Redistributions in binary form must reproduce the above copyright |
|
340 notice, this list of conditions and the following disclaimer in the |
|
341 documentation and/or other materials provided with the distribution. |
|
342 |
|
343 THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS |
|
344 "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT |
|
345 LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR |
|
346 A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT |
|
347 OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, |
|
348 SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED |
|
349 TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR |
|
350 PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF |
|
351 LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING |
|
352 NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS |
|
353 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. |
|
354 |
|
355 |
|
356 |
|
357 vim: set noet nosta sw=4 ts=4 ft=help : |
|
358 |
|