diff -r 2b198f0a86fe -r a0e6ddfadf82 specky/doc/specky.txt --- a/specky/doc/specky.txt Wed Jan 02 09:14:17 2013 -0800 +++ /dev/null Thu Jan 01 00:00:00 1970 +0000 @@ -1,358 +0,0 @@ -*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 : -