Sporkmonger

So, after 3 months, I’m back from my excursion to Africa. Don’t worry, I’m not coming back empty-handed.

I thought my fellow rubyists might benefit from the URI implementation I’ve been using in various projects, so I’ve extracted it out into its own library. In the process, I improved a few things here and there, added support for URI Templates, and fleshed out the specifications a bit more.

I introduce to you the Addressable library.

It has about a 2:1 spec to code ratio, 100.0% code coverage, and it has gone through plenty of code heckling. It ought to be pretty reliable.

Hope you like it. Let me know how it works.

Update:

I’ve added URI Template variable extraction and I updated the documentation. The extract_mapping method should be useful for template-based routing systems for frameworks.

Get me rewrite! Again.

I’m not certain exactly how many times I’ve rewritten the base stuff for GentleCMS now, I’m pretty sure it’s been at least 5 times now, and every time it gets better and cleaner and simpler and better specified. I just finished up writing the code for managing resource properties (arbitrary file metadata). This time around, I (re)wrote the whole thing as a fancy subclass of Hash. Complete with 100.0% C0 code coverage and a fairly respectable 1.37:1 spec:code ratio. I’ll probably begin writing the specs for the ResourceNode class (the most important class in GentleCMS) in the next couple days.

I’ve been making a few evolutionary improvements to the URI class lately. (Which, by the way, is now at 100.0% C0 code coverage and 1.63:1 spec:code ratio. Ultimately the goal is to have 100.0% C0 code coverage for every single piece of GentleCMS and at least a 1.0:1 spec:code ratio for every file.) The improvements were mostly related to escaping. I misread parts of the RFC related to escaping certain characters and I had to go back and improve the specs for that. I’m pretty sure there’s still some edge cases that need to be better specified in my RSpec code. Whenever there’s some section of the RFC that supplies an example, I’ve been adding it verbatim to the RSpec code with a comment to allow easy cross-referencing between the executable specification and the RFC. I almost wish RSpec had some functionality similar to RDoc that would merge the comments with the generated HTML specification somehow. The generated stuff tends to be fairly bland (though still somewhat useful), but it would be really cool if it could be fleshed out a bit.

Anyways, since the properties code was what I just finished up, I thought I’d explain a bit about how the feature works exactly. Properties in GentleCMS are loosly modeled on Subversion’s metadata system, which is really quite simple. Metadata in both systems is basically represented as a set of key-value string pairs, which is why it makes a lot of sense to code it up as a Hash subclass. Namespacing is dealt with by simply prefixing the key’s name with the namespace string followed by a colon. So for example, Subversion uses “svn:mime-type” to store the mime-type of a file, while GentleCMS uses “cms:mime-type”. There’s really nothing special about the way namespacing is done, it’s actually not much more than a style convention.

However, GentleCMS’s metadata system is significantly different in one respect from Subversion’s. GentleCMS allows properties to be auto-generated. GentleCMS has a special class called ResourceAdaptor. Subclasses of ResourceAdaptor are able to selectively alter the behavior and state of ResourceNodes depending on the ResourceNode’s state. For example, if you wanted to auto-detect the encoding of an XML file in order to eliminate many of the problems that crop up as a result of RFC 3023, you could write a ResourceAdaptor subclass that only accepts XML file ResourceNodes. The subclass would add a generated property to the ResourceNode, “cms:encoding” whose value was obtained by inspecting the ResourceNode’s content and determining the XML file’s encoding. GentleCMS knows what to do with the “cms:encoding” property and will automatically supply the correct HTTP headers when a representation of the resource is requested.

I have an admission to make.

I hate Ruby’s URI class. There, I’ve said it. It’s out in the open, I can’t take it back. I just really don’t like it. It constantly tells me that my URIs are invalid and that I’m a bad person and it basically just hates me. So yeah. I’m just not gonna take it anymore. URI class, I’m quitting you. I’ve found someone else who treats me nicely, someone who knows how to normalize without making me do lots of extra work, someone who actually understands IRIs, and who makes allowance for the fact that sometimes people are ignorant morons who don’t read the specifications.

I’d like to introduce GentleCMS’s replacement for Ruby’s standard library URI implementation: GentleCMS::URI. It’s based on RFC 3986 instead of RFC 2396 and RFC 2732, so it’s a little bit more modern, it’s fairly close in functionality to Ruby’s URI class, and for the most part, it shares all of the same methods. The opaque method is gone because it’s no longer used in RFC 3986, although if necessary, an alias could be created I suppose, since path now takes opaque’s place.

The class will automatically use Ruby’s bindings for libidn if they’re present:

1
2
3
4
5
6

require 'system/uri'
uri = GentleCMS::URI.parse(
  "http://www.詹姆斯.com/atomtests/iri/詹.html")
uri.normalize.to_s
# => "http://www.xn--8ws00zhy3a.com/atomtests/iri/%E8%A9%B9.html"

I wanted to write a pure-Ruby IDNA implementation, but in the interests of not yak-shaving for the rest of my life, I decided not to bother.

The code, thus far, is checked into the repository if you want to play with it. Complete with an executable specification and 100.0% C0 code coverage according to RCov.

It is my intention to polish it up a bit longer, improve the documentation, run with it for awhile in the real world, and then see what it would take to have it replace the implementation in Ruby’s standard library. I’ll probably start having FeedTools use the code as well.

651 lines of implementation, 739 lines of specification.

I got a lot of work on GentleCMS done while I was at RailsConf. I’ll probably start putting regular entries up on my progress so that it doesn’t get too quiet around here.