Help Us Help You

I know: you want to be a good #vim citizen; you want to be a good vimmer; you want to learn and grow and solve your problems in a timely manner and do so in a safe and supportive environment filled with smart, caring and funny peers.

I know; we all do. And we all can. Here’s how:

Help Yourself

Vim has an awesome built-in manual filled with more answers than you have questions. Almost every problem you have is addressed somewhere within its many chapters. Unfortunately, newcomers often can’t find what they’re looking for in the manual, or don’t understand the answer because of a lack of jargon or fundamental Vim-specific knowledge. This feeling of inaccessibility passes over time as you level up in Vim, but can be debilitating to the beginner. But despair not! When you don’t understand something in the manual, then that is the time for asking on #vim, but more on that later. First, here are some tips for helping yourself to some Vim love:

I use the loose term manual here to treat the reference-manual and user-guide as a whole, just as the built in tools for navigating them do.

• :help topic will jump to topic within the manual.
  
• :helpgrep pattern will search for all occurrences of pattern throughout the manual. Use :cope to open the quickfix window of search results.
  
• There is a decent FAQ: http://vimhelp.appspot.com/vim_faq.txt.html
  
• The #vim channel has a fact bot called vimgor filled with answers to common problems. These facts are often keyed on weird terms that must be supplied to vimgor precisely to elicit their associated gems of wisdom, which is practically useless to the uninitiated. Thankfully, vimgor supports a listfacts interface that will return all known facts containing the given term, e.g:
  

  /msg vimgor listfacts file

  will list all known keys containing file.
  

You should explore vimgor using either /msg or /query to limit interference on the #vim channel. Feel free to call upon vimgor directly from within #vim if you are using it to answer someone else’s question. Here are some additional tools in that vein: ;help topic ⇐ will provide a URL to Vim’s manual for the given topic. ;man topic ⇐ will provide a URL to the appropriate unix man page.

Ask For Help

So you’ve looked in the manual and can’t find an answer, or don’t understand the answer; you’ve looked at the FAQs and checked in with vimgor to no avail. Now is the time to ask for help on #vim. Alternatively, ask reddit's vim channel. The guidelines for asking on #vim apply equally well for reddit's forum, of course.

Both for reasons of courtesy to others and self-edification, it’s important to try to find the answers to your own questions yourself before asking others on #vim. But just as important is how you ask:

For simple, easy and short examples, asking inline is acceptable and preferred, but if your problem is dense or requires more than a couple lines of data, using a pastebin service is preferred. Github’s gist is popular, but any decent ad-free pastebin will be happily tolerated. The format of your pastebin is also important. Here is an excellent example: https://gist.github.com/2759774

Etiquette

It’s obvious to most people that asking politely will yield better responses; some people need to be told explicitly. The good folk of #vim freely donate their time and energy to helping others discover the joy of being a vimmer. They delight in sharing their arcane knowledge with interested learners and inquisitive minds. In case you’re having trouble reading between the lines here, don’t approach #vim with these attitudes:

• impatience or unwillingness to learn: You don’t care to read the :help topic provided, you just want the solution to your exact problem RIGHT NOW. Nothing upsets a vimmer more. The :help is extremely well written if not a bit obtuse for newcomers, but we’ll help you understand those intricacies — very rarely is someone told to rtfm and then left to drown in their own incomprehension.
  
• rudeness or ungratefulness: diagnosing your problem might take some time and several steps requiring your participation. If you get frustrated at this or interact poorly then your chances of continued support diminish quickly. Be nice, get nice; say please and thank you.
  

One of my greatest teaching mentors gave me this gem once:

Teach as if your mentor is watching from the corner.

The analogy here is: ask as if you weren’t sitting behind a terminal; ask as if your mum or boss or teacher or doctor or someone you respect were listening.

In fairness, I have rarely seen such bad behaviour on #vim; it’s generally one of the most polite chat rooms I’ve ever seen. Let’s keep it that way! :-)

Not Classy, VimLPOO!

Rise, fellow VimLers and cease sobbing onto your consoles about the stink of VimLPOO (VimL Programming Object Orientedly). Vim keeps an open mind and so should you.

tl;dr : VimL OOP can haz class-reopening like Ruby

Okay, maybe not exactly like Ruby, but check it:

VimL’s OOP is more like javascript’s than Ruby’s. It doesn’t have explicit classes. It uses dictionaries to store data and methods that operate on it.

Here is one way in VimL to create an object factory:

function! Kid(name) <1> let k = {} <2> let k.name = a:name <3> func k.say(blah) dict <4> echo self.name . ': ' . a:blah endfunc return k <5> endfunction let boy = Kid('Jack') <6> let girl = Kid('Jill') call boy.say('wassup?') <7> call girl.say('chillin'' at the hill. u?') echo boy <8>

Jack: wassup?
Jill: chillin' at the hill. u?
{'name': 'Jack', 'say': function('69')}

1. I like to use the full command form function when creating object factories (classes?).
   
2. The object container is a dictionary (hash).
   
3. You can explicitly set attributes outside of methods if desired.
   
4. I like to use the short command form func for methods. The dict argument tells Vim that this is an instance method, providing us the self. accessor.
   

   You don’t need the ! on method declarations as you do for the outer-level.

5. The factory must return the newly created object.
   
6. Create an instance using the factory.
   
7. Call methods using dot notation.
   
8. The object in its native format is just a dictionary (hash).
   

Typically, after creating the object factory, the VimLPOO developer can’t re-open it to augment its behaviour although you can derive a new factory type from an existing one (inheritance without paternity):

function! RudeKid(name) let rk = Kid(a:name) <1> func! rk.say(blah) dict <2> echo self.name . ': Yo, biatch! ' . a:blah endfunc return rk endfunction let boy = RudeKid('Jack') let girl = Kid('Jill') call boy.say('wassup?') call girl.say('wtf?') echo boy

Jack: Yo, biatch! wassup?
Jill: wtf?
{'name': 'Jack', 'say': function('72')}

1. Base this object on the parent factory.
   
2. Override methods as desired.
   

   The use of ! is now required because the method already exists in the base object.

But I’m not here today to talk about weak inheritance. I wanna play with class re-opening, Vim style.

As a quick recap, a Vim object is a dictionary with data and methods that can use the self. modifier internally to refer to its data and other methods. It turns out that Vim is not too particular about who gets to claim dict access on your objects. You’re free to create external functions, adorned with the dict modifier, and have them manipulate your objects as if they were created with the class originally:

function! s:slapped() dict echo self.name . " just got slapped!" endfunction

This happens to be a script-local (s:) function; global scope would work too, but why pollute unnecessarily? Now, if you tried to do a naive direct call of this, you’d be sorely disappointed:

call boy.slapped()

Error detected while processing jack_and_jill.vim:
Line   42:
E716: Key not present in Dictionary: slapped

That makes sense… We created slapped() as a script-local function, not a method on the boy instance.

Adding the method to the Kid() factory after having created the boy instance would be just as useless.

Happiness is just a call away:

call call('s:slapped', [], boy) " Jack just got slapped!

:-D How cool is that?!

I have a little project in the works that uses this to allow clients of the engine to inject their own solutions to various parts of the workflow. It’s almost done, so I should be able to show something a bit more real-worldy soon. For now, what mischief can you concoct with this shiny new toy? I look forward to finding out. :-)

Vim on!

Sort Me A Column

Need to sort a column within your table without messing with the other columns?
Vim has your back with blockwise visual selections and a bit of gymnastics.

Sample table:

1 this 1 apple is 1 2 this 4 durian is 2 3 this 3 carrot is 3 4 this 2 banana is 4 5 this 5 eggplant is 5

Desired result:

1 this 1 apple is 1 2 this 2 banana is 2 3 this 3 carrot is 3 4 this 4 durian is 4 5 this 5 eggplant is 5

[wrong] Result of naive :sort command:

1 this 1 apple is 1 2 this 4 durian is 2 3 this 3 carrot is 3 4 this 2 banana is 4 5 this 5 eggplant is 5

[wrong] Result of :sort /^. / command (to skip leading numbers):

1 this 1 apple is 1 4 this 2 banana is 4 3 this 3 carrot is 3 2 this 4 durian is 2 5 this 5 eggplant is 5

---

A Solution

1. Visually select the column of interest with ctrl-v
   
2. Cut it with x
   
3. Open a temporary scratch buffer with :enew
   
4. Paste with p
   
5. Sort with :sort
   
6. If you need to, ensure your cursor is line 1, col 1 with gg0
   
7. Visually select and yank everything, blockwisely with ctrl-vG$y
   
8. Switch back to where you came from with ctrl-6 (ctrl-^)
   
9. Jump to the start of your original cut with `[
   
10. Paste with P
    

Partial Explosion

Vim has a powerful regex spell, :help /\%[] . While it might look like the emoticon of a lunging crocodile, this little piece of regex lets vimmers match words in either their full form or any partial reduction thereof. That’s a messy explanation. A showing will help:

The pattern:

/r\%[ead]

Will match: r, re, rea, and read

Unicorns, I know!

This actually gets a lot of love in Vim’s syntax highlighting file for its own language, VimL. I wish it didn’t to be honest. I actually deplore the availability of partial keyword forms like fu instead of the full form function. But that’s not why we’re here today, so let’s move on.

Not all regex engines support this awesome atom. In fact… I don’t know of any other that does.

I am in the process of creating a vim.lang file for source-highlighter. As you would expect, it has a regex based DSL for specifying syntax items. One such item is for keywords. Easy!, I thought, I’ll just grab the keywords from Vim’s syntax files and… oh, crap… It’s infested with \%[]…

So… Let’s explode them.

With a quick regex, I got the Vim keywords split out onto separate lines, like this:

a arga[dd] ar[gs] bar bn[ext] breaka[dd]

And then we can explode out the partial variations with this little regex:

:%s/^\(.\{-}\)\[\(.\{-}\)\]/\=join(map(range(len(submatch(2))+1), 'submatch(1).strpart(submatch(2), 0, v:val)'), ' ')/

Producing:

a arga argad argadd ar arg args bar bn bne bnex bnext breaka breakad breakadd

And just in time for dinner, too.

I'd Tap That

The Ruby world and many others have a tap() method on a class way up in the hierarchy near God that lets the bug hunting developer peek inside of objects during execution to see what the gnomes are getting up to under the covers. I needed just such a tool for my latest dabblings in Vim, so I built one and thought I’d share it here:

function! Tap(thing) echom string(a:thing) return a:thing endfunction

It’s not very intimidating, I know, but thats a little gem of a function. I used it to debug the setting of the includeexpr option in Vim, as shown here:

set includeexpr=Tap(substitute(Tap(v:fname),'\\${\\?\\(\\w\\+\\)}\\?','\\=expand(\"$\".submatch(1))','g'))

I was suspicious that the v:fname variable was not being set properly before includeexpr was being evaluated by Vim. Tap() proved that to be the case which allowed me to focus my debug efforts on the real cause, instead of continuing to waste time fretting over the search and replace patterns in the substitute and whether I’d escaped them correctly or not. I only wish the Tap() inspiration had come to me sooner than it really did. Oh well… with Tap() as a permanent fixture in my ~/.vimrc, hopefully it won’t take me as long to think of it the next time I need its services.

Bisectly

wtf?!

We've all been there before; all too often, in fact. There you are in the middle of a serious edit when all of a sudden some vile little gremlin spits at you from deep within Vim. "Argh!" You instantly seethe with indignant rage, vowing to righteously lance that festering pustule...! when the terrifying realisation strikes you - you don't know where this bug is coming from. "Gack." You say as you think to yourself: "It must be one of the plugins... surely? Ok... it could be in my ~/.vimrc... But no! I watered it only yesterday and there were hardly any weeds there. So, it's a plugin... But... which one? How am I supposed to find the menacing little urchin among all those other well behaving citizens in my plugin pool?" Historically the Vimmer faced with this situation has had very little option but to manually move plugins aside until the faulty one is found. This is a laborious, boring and very frustrating task. Even if you knew well enough to use binary search to speed up the process, it's still not something anyone wants to do. Thankfully now, you don't have to. Now, you can do it with Bisectly.


Bisectly is a plugin-manager agnostic fault localisation tool for finding which plugin is causing you nose-bleeds.

Bisectly uses BSFL (Binary Search Fault Localisation) to quickly whittle down the set of loaded plugins in search of the one causing you pain. It uses a cutesy command interface to identify which sessions the user considers fault-free (:Unicorns) or faulty (:Zombies). This process continues until a single plugin remains, which Bisectly considers to be the guilty party.

Plugin Manager Agnostic

Bisectly interrogates your normal Vim for its final set of &runtime paths before juggling those in the BSFL algorithm. As such, it should be completely independent of any plugin manager. I have tested it with pathogen only, but I don't foresee any issues with Vam or Vundle. Feedback appreciated on this.

Possible Futures

My original idea for the Zombies Vs Unicorns theme was actually in regard to using BSFL on locating faults within a user's ~/.vimrc file. I have a plugin that is all-but-finished for this purpose but it has been delayed until a better vimscript parser can be completed. Work on that is currently in progress.

I have dabbled with various solutions to this problem over the last year or so. Most of the other solutions were tied to pathogen or were broader, more generic endeavours (stretching beyond the realm of Vim). All of those solutions, though, utilised an automated testing framework to very rapidly locate the faulty component - in a matter of seconds. I had the idea for this incarnation of Bisectly today and rushed out the simpler manual code while it was fresh in my mind. However, I do intend to revisit this plugin to add support for an automated test framework.

The Path of a Master VimLer

An apprentice approached a Master and said,
“Show me your best Vim.”
to which the Master responded,
“Everything in my Vim is best.
You cannot find here any piece of Vim that is not the best.”
At these words, the apprentice became enlightened.

What might the path to VimL mastery look like?
Here's what Raimondi & I think at the moment:

Trainee → Novice → Worker → Professional → Expert

1. Trainee
   
   • Read the following parts of :help cmdline.txt
     
     • 3. Ex command-lines :help cmdline-lines
       
     • 4. Ex command-line ranges :help cmdline-ranges
       
     • 6. Ex special characters :help cmdline-special
       
   • Read the following parts of :help options.txt
     
     • 1. Setting options :help set-option
       
     • The following specific options:
       
       • :help 'debug'
         
       • :help 'eventignore'
         
       • :help 'ignorecase'
         
       • :help 'magic'
         
       • :help 'maxfuncdepth'
         
       • :help 'runtimepath'
         
       • :help 'verbose'
         
   • Read all of :help pattern.txt
     
   • Read the following parts of :help eval.txt
     
     • 1. Variables :help variables
       
     • 2. Expression syntax (skim) :help expression-syntax
       
     • 3. Internal variable :help internal-variables
       
     • 5. Defining functions :help user-functions
       
     • 7. Commands :help expression-commands
       
     • 9. Examples :help eval-examples
       
   • Read sections 41.1 - 41.8 in :help usr_41.txt
     
   • Read :help function-list (Vim’s built-in VimL library)
     
   • Read http://www.ibm.com/developerworks/linux/library/l-vim-script-1/index.html
     
   • Read http://learnvimscriptthehardway.stevelosh.com/
     
   • Pass the Trainee assessments
     
2. Novice
   
   • Contribute bug fixes and small enhancements to existing plugins.
     
   • Read :help map.txt
     
     • Read :help 'timeout' option
       
     • Read :help 'maxmapdepth' option
       
   • Read :help usr_40.txt
     
   • Read :help autocmd.txt
     
   • Read :help filetype.txt
     
   • Read :help various.txt
     
     • In regard to :normal, read :help motion.txt
       
   • Pass the Novice assessments
     
3. Worker
   
   • Read :help eval.txt
     
   • Read :help usr_41.txt
     
   • Create three or more plugins under the supervision of a Professional or Expert
     
   • Assist Novices
     
4. Professional
   
   • Actively support five or more peer-reviewed, fully usr_41 compliant plugins
     
   • Thoroughly document all supported plugins
     
   • Supervise Workers
     
   • Assist in the development of reference & resource materials
     
   • Participate in discussions about best practice for VimL development
     
5. Expert
   
   • Create new tools and libraries for VimL development
     
   • Create new/interesting/engaging/fun reference material or tutorials for an aspect of Vim/VimL
     
   • Mentor, guide and train other VimLers
     
   • Maintain a regular presence on Stack Overflow, the vim-dev mailing lists, #vim or #viml as an authority and guide on advanced Vim and VimL topics
     

A Plan for Assessing VimL Skills

A central registry of available assessments:
A master github repo called https://github.com/dahu/VimLAssessments.git that contains a list of VimLAss_<level_name>_<assessment_number> github repos in the various skill levels that act as assessments.
E.g.:

1. Trainee:
   
   • https://github.com/dahu/VimLAss_Trainee_001.git — Establish a working VimL Dev environment
     

…

1. Novice:
   
   • VimLAss_Novice_010 — usr_41 compliance: use <Plug> maps
     

Creating New VimLAss Assessment Repositories

To create a new VimLAss assessment piece, just copy the VimLAss_Skeleton repository which has the following layout:

• README.md — an overview of the assessment and a detailed set of tasks to be completed
  
• test/<task>.vim — one or more test files per task as listed in the README.md
  
• plugin directories with files as necessary. e.g.:
  
  • autoload/
    
  • doc/
    
  • colors/
    
  • compiler/
    
  • ftdetect/
    
  • ftplugin/
    
  • indent/
    
  • plugin/
    
  • syntax/
    

All VimLAss repositories are to use the https://github.com/vim-scripts/runVimTests.git unit testing framework. The repositories should contain tests for expected behaviour that initially fail. Corresponding tasks in the READEME.md file detail the necessary fixes and enhancements that the vimmler is supposed to implement to get the tests to pass. Successful completion of the assessment begins with having all tests pass. The vimmler should then apply to a Professional/Expert vimmler to have his work reviewed, gain feedback and get his assessment signed off. Actual signoff could involve digital signatures, if that path was ever deemed necessary, which is unlikely.

Even though I have provided some links to various pieces mentioned above, all of this is still very much in thought space at the moment.

I am sure we haven’t covered all bases yet. Do you have anything to contribute?