forked from vim-scripts/Specky
-
Notifications
You must be signed in to change notification settings - Fork 0
/
specky.txt
354 lines (236 loc) · 13.5 KB
/
specky.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
*specky.txt* Last change: $Id: specky.txt,v 763cef799c74 2010/12/18 08:56:09 mahlon $
VIM REFERENCE MANUAL by Mahlon E. Smith
specky!
A Plugin for testing Ruby code with RSpec -- and more *specky*
==============================================================================
CONTENTS *SpeckyContents*
1) Intro........................................|SpeckyIntro|
2) Functionality................................|SpeckyFunctionality|
3) Enabling Specky..............................|SpeckyInstallation|
4) Configuration................................|SpeckyOptions|
4.1) Create text banners....................|g:speckyBannerKey|
4.2) Cycling quote styles...................|g:speckyQuoteSwitcherKey|
4.3) Display ruby documentation.............|g:speckyRunRdocKey|
4.4) Toggle editing between spec and code...|g:speckySpecSwitcherKey|
4.5) Run specs for the current buffer.......|g:speckyRunSpecKey|
4.6) Modify the default spec command........|g:speckyRunSpecCmd|
4.7) Modify the default rdoc command........|g:speckyRunRdocCmd|
4.8) Alter new window behavior..............|g:speckyWindowType|
4.9) Running older rspec (1.x) .............|g:speckySpecVersion|
5) Author.......................................|SpeckyAuthor|
6) License......................................|SpeckyLicense|
==============================================================================
1. INTRO *SpeckyIntro*
Specky is primarily a small collection of functions to help make behavioral
testing streamlined and easy when working with ruby and rspec. Specky
supports rspec 2.x by default, and is backwards compatible with rspec 1.x.
Specky secondarily includes a couple of conveniences to make your everyday
programming tasks smooooth and pleasurable.
==============================================================================
2. FUNCTIONALITY *SpeckyFunctionality*
Okay then, what does it do?
By default? Nothing but syntax highlighting unless you are comfortable using
the menus. I decided the easiest way to cherry pick the functionality that
you'd like was to enable them via key bindings. By doing this, Specky won't
make assumptions about your current environment, and won't stomp on anything
you don't want it to.
Specky won't do -anything- with your environment until you enable ~
the key bindings!! ~
After you've configured your bindings, here are some of the things you can
now do with a single key stroke:
>
- Switch back and forth from code to testing spec
- Run the spec, with results going to a new, syntax highlighted buffer
- Jump quickly to spec failures and failure detail
- 'e' and 'r' to move back and forth on each failed assertion,
- 'E' to jump details for it.
- '<C-e>' to "forget" the currently selected failed assertion
- 'q' to close the spec output buffer.
- View rdoc of the word under the cursor
- Dynamically switch string types for the word under the cursor
(double quoted, quoted, symbol)
- Make lovely and quick comment banners for ruby code.
Specky also includes a "snippets" file that can be used with the Snipmate
plugin by Michael Sanders <msanders42+vim@gmail.com>. (Minimum version 0.74.)
http://www.vim.org/scripts/script.php?script_id=2540
==============================================================================
3. ENABLING-SPECKY *SpeckyInstallation*
Getting Specky to work should be a fairly trivial process. Specky now
uses a custom rspec formatter to function reliably, and it needs to know
where that lives on your system.
If you installed Specky from Vimball, it is likely found at:
~/.vim/ruby/specky_formatter.rb ~
Otherwise, you'll need to locate it, and tell rspec to use it in one of two
ways.
1) Set the *g:speckyRunSpecCmd* variable explicitly:
let g:speckyRunRdocCmd = "rspec -r ~/.vim/ruby/specky_formatter.rb -f SpeckyFormatter" ~
2) or, leave *g:speckyRunSpecCmd* at its default value, and instead use
an '.rspec' settings file in the root directory of the the project
you're working in. I find this method much more flexible -- the
'.rspec' file can be carried with your project, and customized to
include additional bits like custom $LOAD_PATH injections, etc.
Here's what mine usually looks like: >
-r loadpath
-r ~/.vim/bundle/specky/ruby/specky_formatter
-f SpeckyFormatter
After that is taken care of, then just set up your keybindings in your
.vimrc. Here's what my config looks like. >
let g:speckyBannerKey = "<C-S>b"
let g:speckyQuoteSwitcherKey = "<C-S>'"
let g:speckyRunRdocKey = "<C-S>r"
let g:speckySpecSwitcherKey = "<C-S>x"
let g:speckyRunSpecKey = "<C-S>s"
let g:speckyRunRdocCmd = "fri -L -f plain"
let g:speckyWindowType = 2
With these bindings, all Specky commands start with <ctrl-s> ("s" for
Specky!), followed by a mnemonic function to run:
b ----> Banner creation ~
' ----> Quote cycling ~
r ----> run Rdoc ~
x ----> code and spec eXchange ~
s ----> run rSpec ~
Of course, <ctrl-s> is a "suspend" signal for most terminals, so these
bindings are meant for a |gui| environment, such as gvim. Your mileage (and
tastes) will doubtlessly vary. Do what you will. I won't judge you.
==============================================================================
4. CONFIGURATION-OPTIONS *SpeckyOptions*
Here are all of the available configuration options.
Please note that you must set binding variables:
|g:speckyBannerKey|
|g:speckyQuoteSwitcherKey|
|g:speckyRunRdocKey|
|g:speckySpecSwitcherKey|
|g:speckyRunSpecKey|
...in order to enable the respective Specky functionality. See
|SpeckyInstallation| for details. Any other options are entirely optional.
Put these into your |vimrc|, or wherever else you enjoy storing this kind of
stuff.
------------------------------------------------------------------------------
4.1 *g:speckyBannerKey*
Setting this binding enables comment banner creation.
This is purely a convenience routine, and a stylistic one at that. I prefer
large advertising of what "area" of code you are in, along with other
miscellaneous labels for humans to read. If this isn't how you roll, then by
all means, don't enable this binding! :)
As an example -- you can just type:
instance methods ~
Then hit the keystroke. It will magically turn into: >
########################################################################
### I N S T A N C E M E T H O D S
########################################################################
With all those saved extra keystrokes this might provide you per banner over
the years, your RSI-free hands will thank you. And the total time savings!!
Oh man, what are you going to DO with all of that extra free time?
The possibilities are staggering.
------------------------------------------------------------------------------
4.2 *g:speckyQuoteSwitcherKey*
Setting this binding enables quote "style switching".
If you aren't in ruby mode, this just changes the word under the cursor
back and forth from double quoting to single quoting.
string -> "string" -> 'string' -> "string" ... ~
In ruby mode, symbols are also put into the rotation.
"string" -> 'string' -> :string -> "string" ... ~
Note that quote cycling only works with a |word|.
------------------------------------------------------------------------------
4.3 *g:speckyRunRdocKey*
Setting this enables the display of rdoc documentation for the current
word under the cursor. For lookups with multiple matches, you can continue
using this binding to "drill down" to the desired documentation.
------------------------------------------------------------------------------
4.4 *g:speckySpecSwitcherKey*
Setting this enables spec to code switching, and visa versa.
Switching uses path searching instead of reliance on directory structure in
your project. The idea here is that you'd |:chdir| into your project
directory. Spec files just need to end in '_spec.rb', which is a common
convention.
aRubyClass.rb ---> aRubyClass_spec.rb~
Because it leaves respective buffers open, you can essentially think of this
as a quick toggle between code and tests.
------------------------------------------------------------------------------
4.5 *g:speckyRunSpecKey*
Setting this variable runs "rspec" on the current buffer.
All output is sent to a syntax highlighted scratch buffer. This new window is
re-used for each spec run. You can quickly "jump" to assertion failures and
their associated details with the following keys:
e and r ~
Move forward and backward through the failed assertions.
E~
While on a failure line, jump to the details of the failure.
<C-e> ~
"Forget" the last found failed assertion, and start over at the
beginning of the list. (ie, the next 'e' keystroke will select
error #1.)
q ~
Closes the spec output buffer.
Normally, you'd only want to perform this keystroke while in a spec file
buffer. If Specky thinks you are in code, rather than a buffer (as indicated
by the lack of a "_spec.rb" file naming convention) then it will attempt to
switch to the spec before running the command.
------------------------------------------------------------------------------
4.6 *g:speckyRunSpecCmd*
This is the program, with flags, that the current file is sent to when
executing the |g:speckyRunSpecKey| keybinding.
A common addition is to include an "-r" flag for sucking in local libraries
necessary for testing your project. In fact, this is required to use the
rspec formatter supplied by Specky. See |SpeckyInstallation| for more info.
Default: ~
rspec
------------------------------------------------------------------------------
4.7 *g:speckyRunRdocCmd*
If you prefer an rdoc display program other than "ri", you can set it
with this variable. "fri -L -f plain" is always a nice choice, for example.
Default: ~
ri
------------------------------------------------------------------------------
4.8 *g:speckyWindowType*
For both spec and rdoc commands, this variable controls the behavior of the
newly generated window.
Default: ~
0
0 ~
Create a new tabbed window
1 ~
Split the current window horizontally
2 ~
Split the current window vertically
------------------------------------------------------------------------------
4.9 *g:speckySpecVersion*
Specky should work out of the box with rspec 2.x. If you'd like to use rspec
1.x instead, you can do so with the following Vim settings: >
let g:speckySpecVersion = 1
let g:speckyRunRdocCmd = "spec -fs"
If you have both rspec 1.x and 2.x installed at the same time, you need to
be explicit with what version you are executing: >
let g:speckyRunRdocCmd = "spec _1.3.0_ -fs"
==============================================================================
5. AUTHOR *SpeckyAuthor*
Specky was written by Mahlon E. Smith.
mahlon@martini.nu ~
http://www.martini.nu/
==============================================================================
6. LICENSE *SpeckyLicense*
Specky is distributed under the BSD license.
http://www.opensource.org/licenses/bsd-license.php
>
Copyright (c) 2008-2010, Mahlon E. Smith <mahlon@martini.nu>
All rights reserved.
Redistribution and use in source and binary forms, with or without
modification, are permitted provided that the following conditions are
met:
* Redistributions of source code must retain the above copyright
notice, this list of conditions and the following disclaimer.
* Redistributions in binary form must reproduce the above copyright
notice, this list of conditions and the following disclaimer in the
documentation and/or other materials provided with the distribution.
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
vim: set noet nosta sw=4 ts=4 ft=help :