--- /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.
+ - '<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: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 = "<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 :
+