[Update, 2011-02-24] Reader Jason Coombs kindly made the necessary changes to get this working on Windows 7! Now I might be shamed into getting it working for Mac OS X as well His changes are here. I’ve updated my script linked below as well. I’ll add some nicer instructions for Windows users soon .[/Update]

I love checking the National Geographic Photo of the Day page to see what wonderful slice of nature or mankind some intrepid soul has captured and shared. Often a wallpaper-sized image download is provided. I wanted to automate the process of checking the page for a wallpaper link, downloading the file, putting it somewhere appropriate, and setting it as my background. The result is this script, which does all that and even:

• Verifies you have at least 25% free disk space before continuing
• Renames the image to the title shown on the page
• Creates a dir to hold these images if it doesn’t exist

Windows users

Download that script and double click assuming Python is installed.

Linux users

Download it, set it to be executable (chmod u+x nat-geo_background-setter.py), put it somewhere like /opt. You could add an alias to run it whenever you fancy:

If you want it to run every day on Linux you could add a crontab entry:

Enjoy a bit of nature on your desktop!

If you use Vim only to edit text files when you happen to be logged into a CLI: mosey on along, this isn’t the book for you. If you currently use Vim regularly and want to improve your knowledge and effectiveness with it: your time reading this book will be well-spent. If you’ve somehow never heard of Vim but are enraptured by the idea of a text editor that can be an effective IDE in addition to allowing you to play Tetris and Rubik’s Cube: you might like this book too.

At first this book seemed rather short for such a potentially expansive topic. In the end I found this to be mostly a virtue rather than a problem, as the amount of information presented is, in fact, voluminous. A more comprehensive approach likely would have been too hefty and less effective. It doesn’t pretend to be a manual for Vim. Instead it illustrates the best approaches for various issues and situations, suggests improvements on more common operations, and provides lots of references to external resources (primarily Vim internal help and vim.org) to learn more. Examples and illustrations provide insight into some of Vim’s lesser known abilities, while commonly used ones are explained and presented in new and useful ways. Groups of features resolve into solutions.

Chapter by Chapter

Chapter 1, Getting Started with Vim

Primarily a history of the Vim editor. Useful to expand the knowledge of Vim fans, but not really pertinent to hacking your beloved editor. Would probably have been better as an appendix or excised entirely.

Chapter 2, Personalizing Vim

Editing your Vim config, customizing fonts, colors, menu buttons and other UI elements. Lots of great material for tuning the visual appearance. More about vim.org and other resources for colorschemes (such as this gem) would have been helpful. The ability to add tooltip balloons was new to me and quite exciting. Schulz provides a number of great examples for their use. The discussion of abbreviations was a bit confusing, especially considering the recommendation of the more intuitive snippets approach in Chapter 4.

Chapter 3, Better Navigation

By now you might already be feeling overwhelmed by the number of key commands to remember. I recommend starting a cheat sheet of those you find especially interesting. Speaking of that, perhaps it’s just my predilections and lack of a perfect memory, but the vast number of code navigation keys was just a bit too much. Sure, “extra keys pressed equals extra time wasted”, but what about extra time sorting through key commands in your thoughts? Still, plenty of tips should be mind-blowing if new to you. Jumping to files named in the text of the current file, for example, is really handy. The information about search improvements, both in user files and in the help system, was quite good. I’ve yet to really use signs or marks, but found their explanation here illuminating.

Chapter 4, Production (Productivity?) Boosters

Templates! Templates are awesome, and this was a welcome introduction to a topic I’ve barely scratched in my Vim journey. I’ve also not used placeholders in templates before, which look to be quite useful. Tag lists and essential plugins for their use are explained, providing an effective presentation of this feature. I was getting a little worried around pg. 86, as the number of Ctrl + x, Ctrl + SOME_KEY commands started to get cumbersome. Then came the explanation of triggering all completion types using a single key, which was quite refreshing. Complete using dictionaries, words in the current document, language files, and more, all using a single key. The SuperCleverTab function will be a very welcome addition to my configuration. Until seeing the example about macros, I never really felt how useful they might be. This definitely convinced me.

But this meaty chapter isn’t over yet! Sessions felt rather opaque to me before reading this section, and I think they will now definitely serve a role for me. No more ritual of opening the right files, folding them just how I want, etc every morning. Undo branching… I still find this rather too complicated and marginal of a feature to care about. But the examples were at least explanatory. Folding is a great eye-saver, and the coverage was adequate. I’m still not really a fan of vimdiff, as there are other diff utilities out there that make the process faster and more intuitive to me. One exception is finding the diff between the current buffer and the saved file, which is very handy and not something available in most editors for sure! I hadn’t opened remote files in Vim directly before, so the section on this at the end of this chapter was quite useful.

Chapter 5, Advanced Formatting

I felt mostly ambivalent about the beginning of this chapter. To me, if you want text aligned a certain way, or want to create proper lists and use other more advanced document formatting features, you should use a word processor. Adding whitespace to my text files for alignment’s sake doesn’t strike me as a good idea.

The second part covering formatting pertinent to coding was much more useful. I’ve used things like autoindent and formatting of pasted code for a while now, and they are quite essential to sanity. Great coverage for those new to these features. Integration of external formatting tools such as Tidy is also described.

Chapter 6, Basic Vim Scripting

“Now we get to it” was my feeling starting this chapter. There’s some very helpful stuff in here, but it’s strangely organized and should have been moved or at least mentioned earlier in the book to provide the most benefit. Some critically handy items: explanation of Vim configuration file directories, how to properly override layers of configuration, Vimball installation, syntax highlighting and colorscheme creation. Then… comes an introductory language tutorial. Honestly, it’s pretty dull and mostly elementary. I would have rather this been moved to an appendix mentioned early in the book. It does provide broad coverage of the basics one would need to start writing Vim scripts.

Chapter 7, Extended Vim Scripting

Everything you need to know about actually writing Vim scripts: suggested code format, function structure, adding key mappings, detecting OS and Vim version, debugging and distributing scripts, documentation, even integrating programming languages like Python and Ruby! This is certainly a great reference to get started with Vim scripting. Schulz also gives an example script wrapping up a number of these points, providing something like a Vim scripter’s “Hello World”.

Appendix A, Vim Can Do Everything

Examples of the many and varied things you can do with Vim, such as Tweet and play Tetris. Provides amusement, but not a lot of value. The section on Vim as an IDE should really have been expanded to an entire chapter or appendix considering the likely audience for this book.

Appendix B, Vim Configuration Alternatives

A number of tips on how to keep your Vim configuration organized. Spends time explaining a system of scripts created by Jos van RisWick that allows the user to make changes to their configuration from GUI menus and make them permanent, instead of editing config files. I had never heard of this and found it quite interesting.

The last few pages deal with storing your Vim configuration online. While I whole-heartedly agree with the intent, the particular manifestation presented is rather terrible. Using this setup, the user’s .vimrc would be downloaded every time Vim is opened. Then it still has to be parsed, which for heavily customized setups can already take a moment. Not the best when you’re looking for a lean editor. And what about the legion of scripts and other supporting files outside .vimrc? I think not. My approach to the problem is to keep all of my Vim configuration files inside an SCM system, checking it out on each system the first time I want to use Vim.

Issues

• Confused structure: Chapters 6 and 7 felt rather strangely divided in themselves, and I felt most of the content should have been provided earlier. Having a better knowledge of the syntax and nature of ex commands/Vim scripting would have made the content throughout the book more understandable. I felt I was mostly taking the syntax in the code provided for granted, without feeling comfortable enough about all the components that I could have written something of my own design.
• Typos: The text would have greatly benefited from another round of copy-editing. Most of the errors weren’t very distracting. There were, however, a number of typos in the code provided that were more problematic, especially for a work on an editor that can be rather picky about commands. For a first edition, these aren’t overly numerous.
• Lack of color diagrams: I’m all for using black and white images when they will suffice, but when providing illustrations of *color* highlighting files, images without color are downright useless! I was rather surprised at this oversight, first appearing in chapter 2, then in multiple places in chapter 6. They could have at least linked to color images online.

Conclusion

All in all this was a very useful treasure trove of tips. Some I’ve already added to my repertoire, and more I’m trying to understand better. In fact, I learned so much from it that I decided I will likely need to drop most of my current Vim config and remake it cleanly. I know I’m not alone in collecting bits and pieces of configuration for this wonderful editor, in a fashion occasionally reminiscent of a deranged hermit crab. Now that I have a more solid understanding I can rebuild it quickly and effectively.

In summary, I agree with Brian Carper:

The best you can hope for in a book is a broad outline to point the way toward features that you didn’t know much about. Hacking Vim 7.2 achieves this goal.

You have a file already tracked in your git repository, but you don’t want future modifications to it to be tracked.

A perfect example of this is the DB config file for Rails projects (config/database.yml). You’ll probably want to track this to keep the production and staging configuration stored and consistent. But it’s quite likely that individual development configurations will be different. Having a commit for each developer adding their own local configuration and thereby polluting it for others when they push is just silly.

Solution

The fun details

I had initially thought that git-ignore was the thing to use for this. That was wrong: git-ignore’s purpose is to allow ignoring of untracked files. In the case of the Rails DB conf example above, the file is already tracked. It has the instance information that needs to be shared and now we want to add local development details. Since it’s tracked, any modifications are going to be picked up by git-status. When you do a commit including changes to tracked files listed in .gitignore, the changes do indeed get pushed, which isn’t what we want.

When looking around for solutions to this, I saw “git rm –cached FILENAME” suggested as a way to stop tracking currently tracked files. And it does this, but it also deletes the file in the commit, which isn’t what we want either.

git update-index allows you to alter your staging area more manually than usual. With it you can perform a wide range of operations not otherwise possible through standard commands. Continuing with the Rails DB conf example, here’s what the workflow would look like:

1. config/database.yml with permanent instance info is added, committed, and pushed
2. Application code is pulled down by new developer
3. Local modifications made to database.yml for new developer’s local DB setup
4. git update-index –assume-unchanged config/database.yml

Thereafter, the changes to conf/database.yml won’t appear in status or get committed. You can continue making and committing other changes, going about business as usual. But any changes to config/database.yml won’t ever appear.

In case you decide you do want to start tracking changes on a file previously ignored, just run:

Thereafter changes to FILENAME will appear in git-status.

Gotcha

The annoying part about this solution is that it has to be run against every new checkout of the repo with the files whose modifications should not be tracked. The command sets a particular bit per checkout, and it’s not passed on to new checkouts.

Just as I was finishing up some fact checking for this write-up, I came across Jesper Rønn-Jensen’s post on this exact topic. If only it had come up in my initial searches! Here’s hoping the next searcher has better luck.

The title attribute of the anchor tag will appear as a tooltip, potentially obscuring menu items and minimally being a useless distraction. But removing titles from navigation links isn’t a good option, since this attribute is helpful for SEO and accessibility purposes.

When discussing this problem with friend Google, I ran across many examples of how to change the display of anchor tooltips, as well as how to hide them altogether. But what I wanted was removal of the title attribute on navigation links only when the mouse cursor hovered over them, adding it back when the cursor left. The solution I settled on consisted of jQuery’s handy hover function and some basic JavaScript. hover() allows you to specify a function to call when the cursor hovers onto an object and another to call when the cursor hovers off. Perfect! Here’s a simple example:

You can verify the functionality by inspecting one of the MenuItem links with Firebug and watching the title attribute as you move the cursor on and off the same link.

After the page is finished loading, when a cursor hovers onto any links within the div of id “main-menu” the title attribute is stored and set to an empty string (so no tooltip). When the cursor leaves, the title attribute is set back to its original value. Simple but effective!

Beyond simply listing the methods of an object, however, I often find that I want to search through them for something in particular. And eyeballing the output of dir(obj) is only efficient in the simplest of cases. hasattr(obj, “method”) won’t get you far either, as you need to match the “method” name exactly. What if you just have a good guess about the name of a method based on what you need to do? What if you want to know everything you can do with directories in the os module or ISO related methods in datetime.date? I haven’t found anything to help with this sort of problem yet. Approaches like writing a loop to do the search every time or perusing the pertinent API docs are too circuitous for such quick questions. So let’s make a tool to do this more easily!

We start with knowing some object and some string containing all or part of the method(s) we’re interested in:

This simply iterates over the methods and attributes defined for the object passed and looks for the term passed within the name of each. rfind returns the highest index of the substring passed in the string it’s called on and returns -1 if no match is found. Once the matches are collected they are printed out. An example:

For convenience let’s make it available on the Python interactive prompt at every load without any extra effort. This is easy enough using a .pythonstartup file. This file can be used to load various useful items like tab completion for interactive Python sessions. If you haven’t used it before, you’ll need to add the following to your .bashrc:

Then in your home directory create a .pythonstartup file containing something like the following:

You’ll need to change the path specified to wherever you placed utils.py containing the mf() function of course. You can download mine here if you’d like. The del statements are to clean up any trace of this operation once you get to the interactive interpreter. This way you get the added functions without mucking up your namespace.

This also loads in an obinfo(obj) function that I included in the same utils.py file. This is based on the interrogate() function written by Patrick O’Brien in the introspection article mentioned above. My version just adds a check for objects without docstrings and prints more of the docstring:

It’s fairly useful:

One issue I ran into recently was how to catch warnings thrown by this module when running queries. Oftentimes tutorials or forum discussions that cover warnings in the context of MySQLdb describe how to filter them (they can clog up script output). But in a recent case I wanted to grab and check the warning, logging a dependent result. I had hoped this clean implementation would work in a method used for all calls to the MySQL DB:

But the warnings just went right through. Instead I needed the warnings module’s assistance:

This catches the warnings and raises them as errors, although their class is still correct, allowing a clean implementation to call the above code (wrapped into a method called do_query):

Now on top of his suggestions I have one more refinement to add. I’ve defined a snippet in vim for whenever I need to use the debugger. You should be able to define the same in whatever editor you use (and if your editor can’t do snippets, get a real one). When in an .rb file, “debug” + Tab becomes:

In addition to the format Trevor suggested (which calls the necessary module, turns on auto evaluation, and calls the debugger itself) this adds a simple assignment after the debugger is called. I often find this necessary because I want to debug right at the very end of a given suite, a conditional, a method, etc. But if you invoke the debugger as the last statement in such a situation, it won’t actually be called. Here’s an example file:

When you run this, you won’t get a debugger console. All the output you get is “Entering troubled function…” and the script exits. If instead you add the assignment I list above after debugger is called, you will get to the debugger console. Sad, but true. (You can select a less offensive assignment if you wish. I settled on it in disgust.)

Aside from this, the Ruby debugger is a useful and beautiful thing. So add the snippet and forget about it.

The first function determines the OS I am on, in the general categories of “debian” and “redhat”:

I chose these two categories because the package handler is the same within each. This could of course be expanded to more systems, these just happen to be the flavors I am always on. Just after I define this function I also include:

This way the variable CUR_OS is populated each time Bash loads but the output doesn’t dirty up the prompt. Having this variable allows the definition of fairly elegant functions such as:

This next function determines whether the current machine is one I consider non-production:

The idea is that LOCAL_BOXES holds hostnames of machines that aren’t as sensitive to things like shutting down. Then when you create aliases for such potentially destructive actions you define a safe form for the potentially sensitive boxes:

When I first began using them, I ran into a critical point of confusion that wasn’t clearly illuminated in the assorted guides I found for optparse. In response, here is a short overview of how to use callbacks to perform checks and validations against passed options.

First, a very basic script using optparse for option parsing:

Which outputs:

For a more detailed coverage of the basics, review Doug Hellman’s PyMOTW article on optparse. It would be best to verify that this input file exists so that we might inform the user and exit early. Adding that functionality to our example:

We’ve added a check_file() function to perform our check and also added the callback specification to the associated option. The arguments a callback function is passed are described in the module documentation. optparse.OptionValueError provides an elegant way to send an error message about the problem and quit the program in one step.

So what’s the problem? When I first wrote a callback, I didn’t catch the line in the tutorial examples that set the value of the option. I still don’t understand why this is necessary, but without the “parser.values.inputfile = value” line above, you’d find the inputfile variable to have None for its value. Strange, but true. I could understand the callback function having to return the option value if all was well, but why would the option’s value get unset in the first place?

Additionally, it turns out you have to set the option’s type even if the desired value is supposed to be default. In the above example, without ‘type=”string”‘, the callback function would have thrown an error, complaining that we were claiming to use a string and weren’t.

So watch out for these details, and clean up your scripts with callbacks.