specky/doc/specky.txt
branchvim-stuff
changeset 29 a0e6ddfadf82
parent 28 2b198f0a86fe
equal deleted inserted replaced
28:2b198f0a86fe 29:a0e6ddfadf82
     1 *specky.txt* Last change: $Id$
       
     2 
       
     3                 VIM REFERENCE MANUAL    by Mahlon E. Smith
       
     4 
       
     5 
       
     6                                   specky!
       
     7 
       
     8 A Plugin for testing Ruby code with RSpec -- and more                 *specky*
       
     9 ==============================================================================
       
    10 CONTENTS                                                      *SpeckyContents*
       
    11 
       
    12     1) Intro........................................|SpeckyIntro|
       
    13     2) Functionality................................|SpeckyFunctionality|
       
    14     3) Enabling Specky..............................|SpeckyInstallation|
       
    15     4) Configuration................................|SpeckyOptions|
       
    16         4.1) Create text banners....................|g:speckyBannerKey|
       
    17         4.2) Cycling quote styles...................|g:speckyQuoteSwitcherKey|
       
    18         4.3) Display ruby documentation.............|g:speckyRunRdocKey|
       
    19         4.4) Toggle editing between spec and code...|g:speckySpecSwitcherKey|
       
    20         4.5) Run specs for the current buffer.......|g:speckyRunSpecKey|
       
    21         4.6) Modify the default spec command........|g:speckyRunSpecCmd|
       
    22         4.7) Modify the default rdoc command........|g:speckyRunRdocCmd|
       
    23         4.8) Alter new window behavior..............|g:speckyWindowType|
       
    24         4.9) Running older rspec (1.x) .............|g:speckySpecVersion|
       
    25     5) Author.......................................|SpeckyAuthor|
       
    26     6) License......................................|SpeckyLicense|
       
    27 
       
    28 
       
    29 
       
    30 ==============================================================================
       
    31 1. INTRO                                                         *SpeckyIntro*
       
    32 
       
    33 Specky is primarily a small collection of functions to help make behavioral
       
    34 testing streamlined and easy when working with ruby and rspec.  Specky
       
    35 supports rspec 2.x by default, and is backwards compatible with rspec 1.x.
       
    36 
       
    37 Specky secondarily includes a couple of conveniences to make your everyday
       
    38 programming tasks smooooth and pleasurable.
       
    39 
       
    40 
       
    41 ==============================================================================
       
    42 2. FUNCTIONALITY                                         *SpeckyFunctionality*
       
    43 
       
    44 Okay then, what does it do?
       
    45 
       
    46 By default?  Nothing but syntax highlighting unless you are comfortable using
       
    47 the menus.  I decided the easiest way to cherry pick the functionality that
       
    48 you'd like was to enable them via key bindings.  By doing this, Specky won't
       
    49 make assumptions about your current environment, and won't stomp on anything
       
    50 you don't want it to.
       
    51 
       
    52     Specky won't do -anything- with your environment until you enable ~
       
    53     the key bindings!! ~
       
    54 
       
    55 After you've configured your bindings, here are some of the things you can
       
    56 now do with a single key stroke:
       
    57 >
       
    58     - Switch back and forth from code to testing spec 
       
    59 
       
    60     - Run the spec, with results going to a new, syntax highlighted buffer 
       
    61 
       
    62     - Jump quickly to spec failures and failure detail 
       
    63         - 'e' and 'r' to move back and forth on each failed assertion, 
       
    64         - 'E' to jump details for it. 
       
    65         - '<C-e>' to "forget" the currently selected failed assertion
       
    66         - 'q' to close the spec output buffer. 
       
    67 
       
    68     - View rdoc of the word under the cursor
       
    69 
       
    70     - Dynamically switch string types for the word under the cursor
       
    71       (double quoted, quoted, symbol)
       
    72 
       
    73     - Make lovely and quick comment banners for ruby code.
       
    74 
       
    75 Specky also includes a "snippets" file that can be used with the Snipmate
       
    76 plugin by Michael Sanders <msanders42+vim@gmail.com>. (Minimum version 0.74.)
       
    77 
       
    78 	http://www.vim.org/scripts/script.php?script_id=2540
       
    79 
       
    80 ==============================================================================
       
    81 3. ENABLING-SPECKY                                        *SpeckyInstallation*
       
    82 
       
    83 Getting Specky to work should be a fairly trivial process.  Specky now
       
    84 uses a custom rspec formatter to function reliably, and it needs to know
       
    85 where that lives on your system.
       
    86 
       
    87 If you installed Specky from Vimball, it is likely found at:
       
    88 
       
    89 	~/.vim/ruby/specky_formatter.rb ~
       
    90 
       
    91 Otherwise, you'll need to locate it, and tell rspec to use it in one of two
       
    92 ways.
       
    93 
       
    94 	1) Set the 'g:speckyRunSpecCmd' variable explicitly:
       
    95 
       
    96 		let g:speckyRunSpecCmd = "rspec -r ~/.vim/ruby/specky_formatter.rb -f SpeckyFormatter" ~
       
    97 
       
    98 	2) or, leave 'g:speckyRunSpecCmd' at its default value, and instead use
       
    99 	   an '.rspec' settings file in the root directory of the the project
       
   100 	   you're working in.  I find this method much more flexible -- the
       
   101 	   '.rspec' file can be carried with your project, and customized to
       
   102 	   include additional bits like custom $LOAD_PATH injections, etc.
       
   103 	   Here's what mine usually looks like: >
       
   104 
       
   105 		-r loadpath
       
   106 		-r ~/.vim/bundle/specky/ruby/specky_formatter
       
   107 		-f SpeckyFormatter
       
   108 
       
   109 	You can also use both of these methods, and use the
       
   110 	'SpeckyConsoleFormatter' class from your .rspec file, if it suits
       
   111 	your fancy.
       
   112 
       
   113 
       
   114 After that is taken care of, then just set up your keybindings in your
       
   115 .vimrc.  Here's what my config looks like. >
       
   116 
       
   117     let g:speckyBannerKey        = "<C-S>b"
       
   118     let g:speckyQuoteSwitcherKey = "<C-S>'"
       
   119     let g:speckyRunRdocKey       = "<C-S>r"
       
   120     let g:speckySpecSwitcherKey  = "<C-S>x"
       
   121     let g:speckyRunSpecKey       = "<C-S>s"
       
   122     let g:speckyRunRdocCmd       = "fri -L -f plain"
       
   123     let g:speckyWindowType       = 2
       
   124 
       
   125 With these bindings, all Specky commands start with <ctrl-s> ("s" for
       
   126 Specky!), followed by a mnemonic function to run:
       
   127 
       
   128     b ----> Banner creation ~
       
   129     ' ----> Quote cycling ~
       
   130     r ----> run Rdoc ~
       
   131     x ----> code and spec eXchange ~
       
   132     s ----> run rSpec ~
       
   133 
       
   134 Of course, <ctrl-s> is a "suspend" signal for most terminals, so these
       
   135 bindings are meant for a |gui| environment, such as gvim.  Your mileage (and
       
   136 tastes) will doubtlessly vary.  Do what you will.  I won't judge you.
       
   137 
       
   138 
       
   139 ==============================================================================
       
   140 4. CONFIGURATION-OPTIONS                                       *SpeckyOptions*
       
   141 
       
   142 Here are all of the available configuration options.
       
   143 
       
   144 Please note that you must set binding variables:
       
   145 
       
   146     |g:speckyBannerKey|
       
   147     |g:speckyQuoteSwitcherKey|
       
   148     |g:speckyRunRdocKey|
       
   149     |g:speckySpecSwitcherKey|
       
   150     |g:speckyRunSpecKey|
       
   151 
       
   152 ...in order to enable the respective Specky functionality.  See
       
   153 |SpeckyInstallation| for details. Any other options are entirely optional.
       
   154 Put these into your |vimrc|, or wherever else you enjoy storing this kind of
       
   155 stuff.
       
   156 
       
   157 
       
   158 ------------------------------------------------------------------------------
       
   159 4.1                                                        *g:speckyBannerKey*
       
   160 
       
   161 Setting this binding enables comment banner creation.
       
   162 
       
   163 This is purely a convenience routine, and a stylistic one at that.  I prefer
       
   164 large advertising of what "area" of code you are in, along with other
       
   165 miscellaneous labels for humans to read.  If this isn't how you roll, then by
       
   166 all means, don't enable this binding!  :)
       
   167 
       
   168 As an example -- you can just type:
       
   169 
       
   170 	instance methods ~
       
   171 
       
   172 Then hit the keystroke.  It will magically turn into: >
       
   173 
       
   174   ########################################################################
       
   175   ### I N S T A N C E   M E T H O D S
       
   176   ########################################################################
       
   177 
       
   178 With all those saved extra keystrokes this might provide you per banner over
       
   179 the years, your RSI-free hands will thank you.  And the total time savings!!
       
   180 Oh man, what are you going to DO with all of that extra free time?
       
   181 The possibilities are staggering.
       
   182 
       
   183 
       
   184 ------------------------------------------------------------------------------
       
   185 4.2                                                 *g:speckyQuoteSwitcherKey*
       
   186 
       
   187 Setting this binding enables quote "style switching".
       
   188 
       
   189 If you aren't in ruby mode, this just changes the word under the cursor
       
   190 back and forth from double quoting to single quoting.
       
   191 
       
   192     string -> "string" -> 'string' -> "string" ... ~
       
   193 
       
   194 In ruby mode, symbols are also put into the rotation.
       
   195 
       
   196     "string" -> 'string' -> :string -> "string" ... ~
       
   197 
       
   198 Note that quote cycling only works with a |word|.
       
   199 
       
   200 
       
   201 ------------------------------------------------------------------------------
       
   202 4.3                                                       *g:speckyRunRdocKey*
       
   203 
       
   204 Setting this enables the display of rdoc documentation for the current
       
   205 word under the cursor.  For lookups with multiple matches, you can continue
       
   206 using this binding to "drill down" to the desired documentation.
       
   207          
       
   208 
       
   209 ------------------------------------------------------------------------------
       
   210 4.4                                                  *g:speckySpecSwitcherKey*
       
   211 
       
   212 Setting this enables spec to code switching, and visa versa.
       
   213 
       
   214 Switching uses path searching instead of reliance on directory structure in
       
   215 your project.  The idea here is that you'd |:chdir| into your project
       
   216 directory.  Spec files just need to end in '_spec.rb', which is a common
       
   217 convention.
       
   218 
       
   219     aRubyClass.rb ---> aRubyClass_spec.rb~
       
   220  
       
   221 Because it leaves respective buffers open, you can essentially think of this
       
   222 as a quick toggle between code and tests.
       
   223 
       
   224 
       
   225 ------------------------------------------------------------------------------
       
   226 4.5                                                       *g:speckyRunSpecKey*
       
   227 
       
   228 Setting this variable runs "rspec" on the current buffer.
       
   229 
       
   230 All output is sent to a syntax highlighted scratch buffer. This new window is
       
   231 re-used for each spec run.  You can quickly "jump" to assertion failures and
       
   232 their associated details with the following keys:
       
   233 
       
   234         e and r ~
       
   235             Move forward and backward through the failed assertions.
       
   236 
       
   237         E~
       
   238             While on a failure line, jump to the details of the failure.
       
   239 
       
   240         <C-e> ~
       
   241             "Forget" the last found failed assertion, and start over at the
       
   242             beginning of the list. (ie, the next 'e' keystroke will select
       
   243             error #1.)
       
   244 
       
   245         q ~
       
   246             Closes the spec output buffer. 
       
   247 
       
   248 
       
   249 Normally, you'd only want to perform this keystroke while in a spec file
       
   250 buffer.  If Specky thinks you are in code, rather than a buffer (as indicated
       
   251 by the lack of a "_spec.rb" file naming convention) then it will attempt to
       
   252 switch to the spec before running the command.
       
   253 
       
   254 
       
   255 ------------------------------------------------------------------------------
       
   256 4.6                                                       *g:speckyRunSpecCmd*
       
   257 
       
   258 This is the program, with flags, that the current file is sent to when
       
   259 executing the |g:speckyRunSpecKey| keybinding.
       
   260 
       
   261 A common addition is to include an "-r" flag for sucking in local libraries
       
   262 necessary for testing your project.  In fact, this is required to use the 
       
   263 rspec formatter supplied by Specky.  See |SpeckyInstallation| for more info.
       
   264 
       
   265     Default: ~
       
   266         rspec
       
   267 
       
   268 
       
   269 ------------------------------------------------------------------------------
       
   270 4.7                                                       *g:speckyRunRdocCmd*
       
   271 
       
   272 If you prefer an rdoc display program other than "ri", you can set it
       
   273 with this variable.  "fri -L -f plain" is always a nice choice, for example.
       
   274 
       
   275     Default: ~
       
   276         ri
       
   277 
       
   278 
       
   279 ------------------------------------------------------------------------------
       
   280 4.8                                                       *g:speckyWindowType*
       
   281 
       
   282 For both spec and rdoc commands, this variable controls the behavior of the
       
   283 newly generated window.
       
   284 
       
   285 	Default: ~
       
   286 		0
       
   287 		
       
   288 	0 ~
       
   289 		Create a new tabbed window
       
   290 	1 ~
       
   291 		Split the current window horizontally
       
   292 	2 ~
       
   293 		Split the current window vertically
       
   294 
       
   295 
       
   296 ------------------------------------------------------------------------------
       
   297 4.9                                                      *g:speckySpecVersion*
       
   298 
       
   299 Specky should work out of the box with rspec 2.x.  If you'd like to use rspec
       
   300 1.x instead, you can do so with the following Vim settings: >
       
   301 
       
   302     let g:speckySpecVersion = 1
       
   303 	let g:speckyRunRdocCmd  = "spec -fs" 
       
   304 
       
   305 If you have both rspec 1.x and 2.x installed at the same time, you need to 
       
   306 be explicit with what version you are executing: >
       
   307 
       
   308 	let g:speckyRunRdocCmd  = "spec _1.3.0_ -fs" 
       
   309 
       
   310 
       
   311 ==============================================================================
       
   312 5. AUTHOR                                                       *SpeckyAuthor*
       
   313 
       
   314 
       
   315 Specky was written by Mahlon E. Smith.
       
   316 
       
   317     mahlon@martini.nu ~
       
   318     http://www.martini.nu/ 
       
   319 
       
   320 
       
   321 
       
   322 ==============================================================================
       
   323 6. LICENSE                                                     *SpeckyLicense*
       
   324 
       
   325 
       
   326 Specky is distributed under the BSD license.
       
   327     http://www.opensource.org/licenses/bsd-license.php
       
   328 >
       
   329     Copyright (c) 2008-2010, Mahlon E. Smith <mahlon@martini.nu>
       
   330     All rights reserved.
       
   331 
       
   332     Redistribution and use in source and binary forms, with or without
       
   333     modification, are permitted provided that the following conditions are
       
   334     met:
       
   335 
       
   336         * Redistributions of source code must retain the above copyright
       
   337           notice, this list of conditions and the following disclaimer.
       
   338 
       
   339         * Redistributions in binary form must reproduce the above copyright
       
   340           notice, this list of conditions and the following disclaimer in the
       
   341           documentation and/or other materials provided with the distribution.
       
   342 
       
   343     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
       
   344     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
       
   345     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
       
   346     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
       
   347     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
       
   348     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED
       
   349     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
       
   350     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF
       
   351     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
       
   352     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
       
   353     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
       
   354 
       
   355 
       
   356 
       
   357 vim: set noet nosta sw=4 ts=4 ft=help :
       
   358