ruby_scribe

{}[http://travis-ci.org/rubiety/ruby_scribe]

= 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.