<img src=“https://secure.travis-ci.org/rubiety/ruby_scribe.png?branch=master” alt=“Build Status” />

Ruby Scribe

Generates nicely-formatted ruby source code given a ruby abstract syntax tree (from seattlerb’s ruby_parser).

Introduction

Ruby Scribe attempts to intelligently format code (from an AST) much as a real developer would, through a series of configurable option.

Approach

To approach creating a solid pretty-printer, I used the Rails codebase as “ideal” coding style for the emitter with default parameters. As I continued to refine ruby_scribe, I ran it (with no AST transformations) against every ruby file in the Rails codebase. The smaller the remaining git diff after each iteration, the better the emitter was.

There are even some instances I think ruby_scribe emits more consistent code than what currently exists in the Rails codebase.

Example

Imagine this crappily-formatted Ruby code:

module RubyScribe
  # My Comment
  class Sample  < Base; 
       def method; do_something_here; end
 end

Parse that with RubyParser:

sexp = RubyParser.new.parse(File.read("bad_code.rb"))

Then emit it with Ruby Scribe:

RubyScribe::Emitter.new.emit(sexp)

And out pops this, nice and clean:

module RubyScribe
  # My Comment
  class Sample < Base
    def method
      do_something_here
    end
  end
end

Usage

The entire project simply takes an incoming Sexp object (from the ruby_parser project) and emits a single string. To do this just use an Emitter:

RubyScribe::Emitter.new.emit(sexp)  # => "module Something..."

Emitter Implementation

The Emitter class is nothing but a bunch of recursion. The main emit method is a big case block to offload handling of individual types to separate methods which handle and compose a big string, all through recursion.

To extend or implement your own Emitter, just subclass RubyScribe::Emitter and override the necessary methods.

Known Issues

  • Since there are still some holes in the implementation, any s-expression type that is unknown will cause the following to be emitted: “## RubyScribe-UNKNOWN: :type ##”. Once stable any unknown type will instead throw an exception.

  • Anything involving order of operations currently much surround the expression in ( ). Will probably expand later to omit this when order of operations is implied, but this requires a context stack. There may actually be other issues related to order of operations. To do this properly requires maintaining context of operations and, starting with the case for parenthesis, remove parentheses when the emitter determines that the order of operations is implied by Ruby syntax rules. Right now the emitter more or less assumes order of operations is implied and does not use parentheses, except in the cases of || and && in which case it does.

  • Only comments on methods, class, and module declarations are retained. This is actually a limitation of ruby_parser as for whatever reason

in-line comments cannot be parsed correctly.

  • Markers such as __FILE__ and __LINE__ are not parsed as you would expect from ruby_parser. A monkey patch to ruby_parser is required for this to work.

Future Features

  • Maintain a context stack so emit methods can emit different content dependent on context in the stack

  • Configuration options for things such as block style, preference for quote style, etc.