Cheating with Bondage

A week ago, I was working on my equation graph system (working name matlat), I discovered that Ruby’s Binding objects (a.k.a. environments) are utterly impoverished by the standards set by the rest of the language. My needs were pretty minimal for matlat, so I didn’t want to get off on a tangent wrapping it, but the way to do so was pretty clear.

In fact, I thought it might be a nice separate independent library, so I couldn’t help rolling around name ideas for a Binding wrapper. While getting ready for bed, I came up with Bondage, which was just too humorous to resist, and went to bed giggling.

I finally got around to it Friday. The code itself really only took a few hours. The rest has been learning and tweaking new tools.

Gem Mine

Bondage is a small general library for Ruby. General libraries for Ruby are packaged in ‘gems’ Fortunately there is a gem called newgem that hands you a template. There are still lots of files to examine and modify, and I still don’t know what some things do (scripts?)

You Want Docs with That?

Gems support the two main methods of literate Ruby programming: ri and rdoc. Getting useful output from both of them at once has proven to be a bit of challenge. This might explain the weak ri documentation for some things I’ve used. Finding a useful ri page on GraphvizR was one reason I chose it over ruby-graphviz. (The other being that GraphvizR has DSL-nature while ruby-graphviz has Java-nature, but documentation definitely helps.)

The difficulty is partly self-imposed, as usual. I hate repeating myself. Rdoc will open up on README.rdoc, while “ri Bondage” will open up on the top level information for bondage.rb. Both of these pages want for a summary synopsis (one of the things that sold me on GraphvizR) I discovered that both tools will use an :include: directive. However, neither of them does it recursively, and I, being the difficult person I am, wanted the synopsis to be an included ruby file so I could run it and make sure the syntax was legal. The compromise, of sorts, is that README.rdoc includes the synopsis. bondage.rb includes README.rdoc, and then includes the synopsis. It leaves :include: lines in the Bondage class documentation, but all the information is there.

News At 11: Metaprogramming Hard To Document

The other difficulty with rdoc (and I assume ri, though I hadn’t found it by that point) is that it doesn’t understand metaprogramming. I initially implemented Bondage with a class method to create ‘listers’ for locals, globals, constants, etc, but these didn’t even show up in the documentation. There is an option to add extra attribute words, in the spirit of the attr_x methods. Unfortunately, the convention of these methods is to take a list of attributes, and rdoc processes them as such. Lister took two arguments to create one method, so rdoc generated extra entries. I backed up a step and replaced the metaprogramming with ordinary abstraction.

A Cheating Git

The imaginary people who followed that last link might have noticed that it’s at github instead of bitbucket. “Arn’t you a Mercurial man?” Well, normally, but the Ruby community is pretty solidly git/github based. Since I’m doing a general library, it’s the place to be for any hope of network effects. In any case, it’s about using the right tool for the job. (I’m not switching converting everything to git because I’m a programmer who uses Ruby, not a Ruby programmer.) I may convert some of my other Ruby projects at some point as well. Matlat is kind of a cute use of operators, for instance.

Git is a wash. It has more features for choosing what to commit or leave, but this feature is on by default, where I commit all at least 90% of the time. As much as I like being able to build up commits incrementally, making people do it every time is kind of an unnecessary developer tax. Fortunately, there is a command line switch (git commit -a) to do what you want. It also makes the command cross the annoying-to-type threshold. So I set up a shell alias for ‘gc’ (and ‘hc’ for mercurial while I was at it); I suspect the git developers didn’t consider it a problem because they did something similar.

One thing that is nice is having a pager by default. Typing “hg diff|more” has a been a little annoying, so I set up aliases for gd/hd.

Hubba-Hubba

The killer feature for git, of course is github. The flash network graph is pretty neat. Of course I’m I fine one to talk, since I’ve not collaborated with anyone on either github or bitbucket. Github also has a lot of little automation bits – creating rubygems (never see that at bitbucket), setting up a pledgie, and probably more I haven’t found. Only problem is a broken layout that forces me to turn off CSS to get to certain buttons. StackOverflow has the same problem, so maybe it’s me.

And yes, it does amuse me greatly to post Bondage today. If only I wasn’t a lazy git, and had posted earlier in the day.

Posted Saturday, February 14th, 2009 under Devlog.

Comments are closed.