diff -r 2b198f0a86fe -r a0e6ddfadf82 doc/specky.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/specky.txt Sat Jan 16 11:31:53 2016 -0800 @@ -0,0 +1,358 @@ +*specky.txt* Last change: $Id$ + + 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. + - '' 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 . (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:speckyRunSpecCmd = "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 + + You can also use both of these methods, and use the + 'SpeckyConsoleFormatter' class from your .rspec file, if it suits + your fancy. + + +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 = "b" + let g:speckyQuoteSwitcherKey = "'" + let g:speckyRunRdocKey = "r" + let g:speckySpecSwitcherKey = "x" + let g:speckyRunSpecKey = "s" + let g:speckyRunRdocCmd = "fri -L -f plain" + let g:speckyWindowType = 2 + +With these bindings, all Specky commands start with ("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, 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. + + ~ + "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 + 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 : +