Awesome CLI gem: Commandable

Ever wanted to drive your ruby code with a CLI?  Well, the commandable gem makes it easy.

At first, I struggled with OptionParser in the stdlib, but I had to duplicate my option handling across CLI code and method invocation.  Then OptionParser didn't handle required parameters at all, requiring me to do required parameters in a non-DRY way.   Also, OptionParse doesn't do sub-commands, git-style, which I needed for the new git plugin I'm working on.

When I saw the pickled_optparse gem (from Mike Bethany), it appeared to solve the missing 'required parameter' feature.  And the subcommand gem seemed to allow for subcommands with their own options, git-style.  However, the duplication across option definition and method invocation was still present.  And even subcommand required you to hook up the command to the class/method that needed to be called.

Finally I found that the author of pickled_optparse had totally rethought CLI in ruby with his commandable gem.  And I really like what he did.

Now there is no real additional logic AT ALL in order to hook your ruby class up to the command line.  Now my option handling code will be in the place it belongs, in the code that is doing the command that I invoked from the command line.

The main awesomeness here is that commandable pushes the CLI code into the appropriate place in your ruby class -- it makes it hard to scatter CLI code all over the place.

My only beef with the gem are the following points:

• it comes with colors enabled by default (unusual for a CLI)
• it clears the screen by default when displaying help (when colors are enabled, very unusual and annoying for a CLI)
• it appears to be hard to do global options like: "cmd --global subcommand [args]"
• there is no support for parsing command CLI-style options into ruby hashes, but this is a minor nit, because that's what OptionParser is for, and it's easy to use inside the method

I fixed a problem where the screen was cleared even if you disabled colors, and I've pushed it up to my fork.

Here is my hello world that shows commandable in action:

And here's the output for a few representative cases:

Subscribing to FamilySearch Updates

Keeping up with all that's going on at FamilySearch is harder than it needs to be, but I finally figured out how.

Most sites give you large categories of feeds to track, but FamilySearch has all of 14 different feeds, some of which overlap or not (the feeds are available by appending '/feed' to the URL).  But I couldn't find any "everything" feed URL.

Because I work for FamilySearch, and because I care about what goes on around me, I want to subscribe to everything, if only just to skim.  The most important announcements get forwarded through internal email, however the additional articles are very useful context, especially for an employee.

Unfortunately, the default "subscribe" link just subscribes you to feeds #2, #3, & #4, or Indexing, Record Search, & Indexing, respectively.  The "Subscribe" link is visible on an individual article's page, but isn't even present on the main blog page.

Here is the feed link you can put in your feed reader to subscribe to everything:

• https://www.familysearch.org/taxonomy/term/1+2+3+4+5+6+7+8+9+10+11+12+13+14/0/feed

When feed/category/blog #15 gets defined, this feed URL will be invalid again.  Maybe there is a better way.  If anyone knows a better way, please let me know.

I want an "everything" subscribe link that I won't have to update in my feed reader, or maybe an "everything but trivia" link.

Using dot from graphviz

The whole graphviz package is an amazingly useful piece of software.  Especially the dot program.

I've watched other people hand-craft Visio documents that go out of date really fast.

I've also watched developers try to use design tools for high-level sketch kind of diagrams and get bogged down with superfluous code-sync features.

When I want to illustrate a point, just plain old boxes and arrows work wonders.  Especially when I can commit the source and be able to tweak it afterwards.

I've found that dot meets and exceeds the my common use goals.  I would guess that 80% of the time, the diagram communicates what I want to say without any tweaking at all.  About 15% of the time, it takes some layout/shape/font/color tweaking to get the message across in a clear & direct manner.  About 5% of the time, I have to output the graph as SVG and load it into Inkscape for further slight tweaking.

Here are some especially helpful links:

• official site
• gallery of examples, also 
• up-to-date language reference, and other documentation
• outdated, but very well-organized Users Guide
• dot-functions.sh

The last piece of software is intended as a helper for invoking dot quickly from the command line as part of a REPL authoring flow.

To use dot-functions.sh, first download it.  The script defines a bash function that can be used from a bash CLI.  Source it into the current shell by doing: source dot-functions.sh, followed by dot somefile.dot.


Here is the source of dot-functions.sh:

Another very helpful article was written on this topic by Diomidis Spinellis.  Now that I think about it, there is another very helpful article about how to get a hand-written sketch into digital form.

DRY plus Proper Responsibilities

It is not sufficient to blindly apply the DRY principle.

Where the single representation ends up living is just as important as avoiding the duplication in the first place.

Having the single, unambiguous, authoritative representation of a piece of knowledge living in a place that it doesn't belong is only slightly better than having it duplicated, once in a place where it seems to belong, and once in a place it does not.

So included in the task of reducing (or avoiding) duplication is the consideration of where to put the common code, *including* the task of inventing a new place if it doesn't seem to fit anywhere, now that it's being used from multiple places.

Usually, a new place is waiting to be invented -- that is why there was duplication in the first place -- the place didn't exist, or else it would have been fairly obvious where to put the logic and how to reuse it in the first place.

Perhaps that is part of what "authoritative" means.