Generates nicely-formatted ruby source code given a ruby abstract syntax tree (from seattlerb's ruby_parser).
Ruby Scribe attempts to intelligently format code (from an AST) much as a real developer would, through a series of configurable option.
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.
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:
And out pops this, nice and clean:
module RubyScribe # My Comment class Sample < Base def method do_something_here end end end
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..."
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.
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.
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.