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 

    13     1) Intro........................................|SpeckyIntro|

    14     2) Functionality................................|SpeckyFunctionality|

    15     3) Enabling Specky..............................|SpeckyVimrcExample|

    16     4) Configuration................................|SpeckyOptions|

    17         4.1) Cycling quote styles...................|g:speckyQuoteSwitcherKey|

    18         4.2) Display ruby documentation.............|g:speckyRunRdocKey|

    19         4.3) Toggle editing between spec and code...|g:speckySpecSwitcherKey|

    20         4.4) Run specs for the current buffer.......|g:speckyRunSpecKey|

    21         4.5) Modify the default spec command........|g:speckyRunSpecCmd|

    22         4.6) Modify the default rdoc command........|g:speckyRunRdocCmd|

    23         4.7) Split windows vertically...............|g:speckyVertSplit|

    24     5) Author.......................................|SpeckyAuthor|

    25     6) License......................................|SpeckyLicense|

    26 

    27 

    28 

    29 ==============================================================================

    30 1. INTRO                                                         *SpeckyIntro*

    31 

    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.

    35 

    36 Specky secondarily includes a couple of conveniences to make your everyday

    37 programming tasks smooooth and pleasurable.

    38 

    39 

    40 

    41 ==============================================================================

    42 2. FUNCTIONALITY                                         *SpeckyFunctionality*

    43 

    44 

    45 Okay then, what does it do?

    46 

    47 By default?  Nothing, unless you are comfortable using the menus.  I decided

    48 the easiest way to cherry pick the functionality that you'd like was to enable

    49 them via key bindings.  By doing this, Specky won't make assumptions about

    50 your current environment, and won't stomp on anything 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 

    74 

    75 ==============================================================================

    76 3. ENABLING-SPECKY                                        *SpeckyVimrcExample*

    77 

    78 

    79 Here's what my config looks like. >

    80 

    81     let g:speckyQuoteSwitcherKey = "<C-S>'"

    82     let g:speckyRunRdocKey = "<C-S>r"

    83     let g:speckySpecSwitcherKey = "<C-S>x"

    84     let g:speckyRunSpecKey = "<C-S>s"

    85     let g:speckyRunSpecCmd = "spec -fs -r loadpath.rb"

    86     let g:speckyRunRdocCmd = "fri -L -f plain"

    87     let g:speckyVertSplit = 1

    88 

    89 

    90 With these bindings, all specky commands start with <ctrl-s> ("s" for

    91 specky!), followed by a mnemonic function to run:

    92 

    93     ' ----> Quote cycling ~

    94     r ----> run Rdoc ~

    95     x ----> code and spec eXchange ~

    96     s ----> run Spec ~

    97 

    98 Of course, <ctrl-s> is a "suspend" signal for most terminals, so these

    99 bindings are meant for a |gui| environment, such as gvim.  Your mileage (and

   100 tastes) will doubtlessly vary.

   101 

   102 

   103 

   104 ==============================================================================

   105 4. CONFIGURATION-OPTIONS                                       *SpeckyOptions*

   106 

   107 

   108 Here are all of the available configuration options.

   109 

   110 Please note that you must (at an optional minimum) set the respective binding

   111 variables:

   112 

   113     |g:speckyQuoteSwitcherKey|

   114     |g:speckyRunRdocKey|

   115     |g:speckySpecSwitcherKey|

   116     |g:speckyRunSpecKey|

   117 

   118 ...in order to enable specky functionality.  See |SpeckyVimrcExample| for

   119 details. Any other options are entirely optional.  Put these into your

   120 |vimrc|, or wherever else you enjoy storing this kind of stuff.

   121 

   122 

   123 

   124 ------------------------------------------------------------------------------

   125 4.1                                                 *g:speckyQuoteSwitcherKey*

   126 

   127 

   128 Setting this binding enables quote "style switching".

   129 

   130 If you aren't in ruby mode, this just changes the word under the cursor

   131 back and forth from double quoting to single quoting.

   132 

   133     string -> "string" -> 'string' -> "string" ... ~

   134 

   135 In ruby mode, symbols are also put into the rotation.

   136 

   137     "string" -> 'string' -> :string -> "string" ... ~

   138 

   139 Note that quote cycling only works with a |word|.  Sentences are not currently

   140 supported.  (But hopefully will be soon.)

   141 

   142 

   143 

   144 ------------------------------------------------------------------------------

   145 4.2                                                       *g:speckyRunRdocKey*

   146 

   147 

   148 Setting this enables the display of rdoc documentation for the current

   149 word under the cursor.  For lookups with multiple matches, you can continue

   150 using this binding to "drill down" to the desired documentation.

   151          

   152 

   153 

   154 ------------------------------------------------------------------------------

   155 4.3                                                  *g:speckySpecSwitcherKey*

   156 

   157 

   158 Setting this enables spec to code switching, and visa versa.

   159 

   160 Switching uses path searching instead of reliance on directory structure in

   161 your project.  The idea here is that you'd |:chdir| into your project

   162 directory.  Spec files just need to end in '_spec.rb', which is a common

   163 convention.

   164 

   165     aRubyClass.rb ---> aRubyClass_spec.rb~

   166  

   167  Because it leaves respective buffers open, you can essentially think of this

   168  as a quick toggle for code and tests.

   169 

   170 

   171 

   172 ------------------------------------------------------------------------------

   173 4.4                                                       *g:speckyRunSpecKey*

   174 

   175 

   176 Setting this variable allows you to run "spec" on the current buffer.

   177 

   178 All output is sent to a syntax highlighted scratch buffer. This new window is

   179 re-used for each spec run.  You can quickly "jump" to assertion failures and

   180 their associated details with the following keys:

   181 

   182         e and r ~

   183             Move forward and backward through the failed assertions.

   184 

   185         E~

   186             While on a failure line, jump to the details of the failure.

   187 

   188         <C-e> ~

   189             "Forget" the last found failed assertion, and start over at the

   190             beginning of the list. (ie, the next 'e' keystroke will select

   191             error #1.)

   192 

   193         q ~

   194             Closes the spec output buffer. 

   195 

   196 

   197 Normally, you'd only want to perform this keystroke while in a spec file

   198 buffer.  If specky thinks you are in code, rather than a buffer (as indicated

   199 by the lack of a "_spec.rb" file naming convention) then it will attempt to

   200 switch to the spec before running the command.

   201 

   202 

   203 

   204 ------------------------------------------------------------------------------

   205 4.5                                                       *g:speckyRunSpecCmd*

   206 

   207 

   208 This is the program, with flags, that the current file is sent to when

   209 executing the |g:speckyRunSpecKey| keybinding.

   210 

   211 A common addition is to include an "-r" flag for sucking in local libraries

   212 necessary for testing your project.  The spec "plain" output format is

   213 supported too, though less useful.

   214 

   215     Default: ~

   216         spec -fs

   217 

   218 

   219 

   220 ------------------------------------------------------------------------------

   221 4.6                                                       *g:speckyRunRdocCmd*

   222 

   223 

   224 If you prefer an rdoc display program other than "ri", you can set it

   225 with this variable.

   226 

   227     Default: ~

   228         ri

   229 

   230 

   231 

   232 ------------------------------------------------------------------------------

   233 4.7                                                        *g:speckyVertSplit*

   234 

   235 

   236 For both spec and rdoc commands, split the new window vertically instead of

   237 horizontally.

   238 

   239 

   240 

   241 ==============================================================================

   242 5. AUTHOR                                                       *SpeckyAuthor*

   243 

   244 

   245 Specky was written by Mahlon E. Smith.

   246 

   247     mahlon@martini.nu ~

   248     http://www.martini.nu/ 

   249 

   250 

   251 

   252 ==============================================================================

   253 6. LICENSE                                                     *SpeckyLicense*

   254 

   255 

   256 Specky is distributed under the BSD license.

   257     http://www.opensource.org/licenses/bsd-license.php

   258 

   259 >

   260     Copyright (c) 2008, Mahlon E. Smith <mahlon@martini.nu>

   261     All rights reserved.

   262 

   263     Redistribution and use in source and binary forms, with or without

   264     modification, are permitted provided that the following conditions are

   265     met:

   266 

   267         * Redistributions of source code must retain the above copyright

   268           notice, this list of conditions and the following disclaimer.

   269 

   270         * Redistributions in binary form must reproduce the above copyright

   271           notice, this list of conditions and the following disclaimer in the

   272           documentation and/or other materials provided with the distribution.

   273 

   274     THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS

   275     "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT

   276     LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR

   277     A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT

   278     OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,

   279     SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED

   280     TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR

   281     PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF

   282     LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING

   283     NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS

   284     SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

   285 

   286 

   287 

   288 

   289 vim: set noet nosta sw=4 ts=4 ft=help :

   290