Version 0.6

Switched to VimBall packaging.  Added real documentation.  Better whitespace cleanup for 'Align'.  Saner config args for overriding defaults.

doc/specky.txt

@@ -0,0 +1,337 @@
+*specky.txt* Last change: $Id: specky.txt 92 2008-08-06 19:49:52Z 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..............................|SpeckyVimrcExample|
+    4) Configuration................................|SpeckyOptions|
+        4.1) Cycling quote styles...................|g:speckyQuoteSwitcherKey|
+        4.2) Beautify assignment lines..............|g:speckyAlignKey|
+        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) 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. 
+        - '<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)
+
+    - Automatically align hash blocks and assignment lines of all shapes
+      and sizes.
+
+
+
+==============================================================================
+3. ENABLING-SPECKY                                        *SpeckyVimrcExample*
+
+
+Here's what my config looks like. >
+
+    let g:speckyQuoteSwitcherKey = "<C-S>'"
+    let g:speckyAlignKey = "<C-S>a"
+    let g:speckyRunRdocKey = "<C-S>r"
+    let g:speckySpecSwitcherKey = "<C-S>x"
+    let g:speckyRunSpecKey = "<C-S>s"
+    let g:speckyRunSpecCmd = "spec -fs -r loadpath.rb"
+    let g:speckyRunRdocCmd = "fri -L -f plain"
+    let g:speckyVertSplit = 1
+
+    map <C-S>} vi}=vi}<C-S>a
+
+
+With these bindings, all specky commands start with <ctrl-s> ("s" for
+specky!), followed by a mnemonic function to run:
+
+    ' ----> Quote cycling ~
+    a ----> Align assignments ~
+    r ----> run Rdoc ~
+    x ----> code and spec eXchange ~
+    s ----> run Spec ~
+    } ----> align contents of curly Braces ~
+
+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.
+
+
+
+==============================================================================
+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:speckyAlignKey|
+    |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:speckyAlignKey*
+
+
+Automatically line up consecutive assignments, or hash definitions.
+As an example:
+>
+    CONSTANT = "something"   |  CONSTANT      = "something"   
+    LONG_CONSTANT = "woooo"  |  LONG_CONSTANT = "woooo"
+
+You can also line up arbitrary key/value pairs, so long as the separator is
+"sane". (Dashes, ascii art arrows, etc)
+>
+    Mahlon E. Smith -----> 5000  |  Mahlon E. Smith -----> 5000
+    Edward Reich -----> 4842     |  Edward Reich    -----> 4842
+    Relvin Sanders -----> 3909   |  Relvin Sanders  -----> 3909
+
+This beautification works on a range of lines.  It's probably easiest to use
+with vim's |visual-mode|.
+
+Here's a useful macro for aligning hashes, assuming you use the
+<ctrl-s>+a binding:
+
+    :map <C-S>} vi}=vi}<C-S>a ~
+
+
+This auto aligns anything inside braces. if your cursor is anywhere within
+the hash.
+>
+    hash = {                  |   hash = {   
+          :blah => 1,         |       :blah     => 1,
+        :woo   => 2,          |       :woo      => 2,
+            :whatever => 3    |       :whatever => 3 
+    }                         |   }
+
+
+
+------------------------------------------------------------------------------
+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 for code and tests.
+
+
+
+------------------------------------------------------------------------------
+4.5                                                       *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.
+
+        <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.  The spec "plain" output format is
+supported too, though less useful.
+
+    Default: ~
+        spec -fs
+
+
+
+------------------------------------------------------------------------------
+4.7                                                       *g:speckyRunRdocCmd*
+
+
+If you prefer an rdoc display program other than "ri", you can set it
+with this variable.
+
+    Default: ~
+        ri
+
+
+
+------------------------------------------------------------------------------
+4.8                                                        *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 <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 :
+