diff -r fd505fd00e63 -r 6b33188f1694 specky/doc/specky.txt --- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/specky/doc/specky.txt Sun Mar 22 00:39:19 2009 +0000 @@ -0,0 +1,290 @@ +*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..............................|SpeckyVimrcExample| + 4) Configuration................................|SpeckyOptions| + 4.1) Cycling quote styles...................|g:speckyQuoteSwitcherKey| + 4.2) Display ruby documentation.............|g:speckyRunRdocKey| + 4.3) Toggle editing between spec and code...|g:speckySpecSwitcherKey| + 4.4) Run specs for the current buffer.......|g:speckyRunSpecKey| + 4.5) Modify the default spec command........|g:speckyRunSpecCmd| + 4.6) Modify the default rdoc command........|g:speckyRunRdocCmd| + 4.7) Split windows vertically...............|g:speckyVertSplit| + 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 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, 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) + + + +============================================================================== +3. ENABLING-SPECKY *SpeckyVimrcExample* + + +Here's what my config looks like. > + + let g:speckyQuoteSwitcherKey = "'" + let g:speckyRunRdocKey = "r" + let g:speckySpecSwitcherKey = "x" + let g:speckyRunSpecKey = "s" + let g:speckyRunSpecCmd = "spec -fs -r loadpath.rb" + let g:speckyRunRdocCmd = "fri -L -f plain" + let g:speckyVertSplit = 1 + + +With these bindings, all specky commands start with ("s" for +specky!), followed by a mnemonic function to run: + + ' ----> Quote cycling ~ + r ----> run Rdoc ~ + x ----> code and spec eXchange ~ + s ----> run Spec ~ + +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. + + + +============================================================================== +4. CONFIGURATION-OPTIONS *SpeckyOptions* + + +Here are all of the available configuration options. + +Please note that you must (at an optional minimum) set the respective binding +variables: + + |g:speckyQuoteSwitcherKey| + |g:speckyRunRdocKey| + |g:speckySpecSwitcherKey| + |g:speckyRunSpecKey| + +...in order to enable specky functionality. See |SpeckyVimrcExample| 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: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|. Sentences are not currently +supported. (But hopefully will be soon.) + + + +------------------------------------------------------------------------------ +4.2 *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.3 *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 for code and tests. + + + +------------------------------------------------------------------------------ +4.4 *g:speckyRunSpecKey* + + +Setting this variable allows you to run "spec" 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.5 *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. The spec "plain" output format is +supported too, though less useful. + + Default: ~ + spec -fs + + + +------------------------------------------------------------------------------ +4.6 *g:speckyRunRdocCmd* + + +If you prefer an rdoc display program other than "ri", you can set it +with this variable. + + Default: ~ + ri + + + +------------------------------------------------------------------------------ +4.7 *g:speckyVertSplit* + + +For both spec and rdoc commands, split the new window vertically instead of +horizontally. + + + +============================================================================== +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, 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 : +