class PrettyPrint - RDoc Documentation (original) (raw)

This class implements a pretty printing algorithm. It finds line breaks and nice indentations for grouped structure.

By default, the class assumes that primitive elements are strings and each byte in the strings have single column in width. But it can be used for other situations by giving suitable arguments for some methods:

There are several candidate uses:

Bugs ↑

Report any bugs at bugs.ruby-lang.org

References ↑

Christian Lindig, Strictly Pretty, March 2000, www.st.cs.uni-sb.de/~lindig/papers/#pretty

Philip Wadler, A prettier printer, March 1998, homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier

Tanaka Akira akr@fsij.org

Attributes

genspace[R]

A lambda or Proc, that takes one argument, of an Integer, and returns the corresponding number of spaces.

By default this is:

lambda {|n| ' ' * n}

group_queue[R]

The PrettyPrint::GroupQueue of groups in stack to be pretty printed

indent[R]

The number of spaces to be indented

maxwidth[R]

The maximum width of a line, before it is separated in to a newline

This defaults to 79, and should be an Integer

newline[R]

The value that is appended to output to add a new line.

This defaults to “n”, and should be String

output[R]

The output object.

This defaults to '', and should accept the << method

Public Class Methods

format(output=''.dup, maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n}) { |q| ... } click to toggle source

This is a convenience method which is same as follows:

begin q = PrettyPrint.new(output, maxwidth, newline, &genspace) ... q.flush output end

def PrettyPrint.format(output=''.dup, maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n}) q = PrettyPrint.new(output, maxwidth, newline, &genspace) yield q q.flush output end

new(output=''.dup, maxwidth=79, newline="\n", &genspace) click to toggle source

Creates a buffer for pretty printing.

output is an output target. If it is not specified, '' is assumed. It should have a << method which accepts the first argument obj of PrettyPrint#text, the first argument sep of PrettyPrint#breakable, the first argument newline of PrettyPrint.new, and the result of a given block for PrettyPrint.new.

maxwidth specifies maximum line length. If it is not specified, 79 is assumed. However actual outputs may overflow maxwidth if long non-breakable texts are provided.

newline is used for line breaks. “n” is used if it is not specified.

The block is used to generate spaces. {|width| ' ' * width} is used if it is not given.

def initialize(output=''.dup, maxwidth=79, newline="\n", &genspace) @output = output @maxwidth = maxwidth @newline = newline @genspace = genspace || lambda {|n| ' ' * n}

@output_width = 0 @buffer_width = 0 @buffer = []

root_group = Group.new(0) @group_stack = [root_group] @group_queue = GroupQueue.new(root_group) @indent = 0 end

singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil) { |q| ... } click to toggle source

This is similar to PrettyPrint::format but the result has no breaks.

maxwidth, newline and genspace are ignored.

The invocation of breakable in the block doesn't break a line and is treated as just an invocation of text.

def PrettyPrint.singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil) q = SingleLine.new(output) yield q output end

Public Instance Methods

break_outmost_groups() click to toggle source

Breaks the buffer into lines that are shorter than maxwidth

def break_outmost_groups while @maxwidth < @output_width + @buffer_width return unless group = @group_queue.deq until group.breakables.empty? data = @buffer.shift @output_width = data.output(@output, @output_width) @buffer_width -= data.width end while !@buffer.empty? && Text === @buffer.first text = @buffer.shift @output_width = text.output(@output, @output_width) @buffer_width -= text.width end end end

breakable(sep=' ', width=sep.length) click to toggle source

This says “you can break a line here if necessary”, and a width-column text sep is inserted if a line is not broken at the point.

If sep is not specified, “ ” is used.

If width is not specified, sep.length is used. You will have to specify this when sep is a multibyte character, for example.

def breakable(sep=' ', width=sep.length) group = @group_stack.last if group.break? flush @output << @newline @output << @genspace.call(@indent) @output_width = @indent @buffer_width = 0 else @buffer << Breakable.new(sep, width, self) @buffer_width += width break_outmost_groups end end

current_group() click to toggle source

Returns the group most recently added to the stack.

Contrived example:

out = "" => "" q = PrettyPrint.new(out) => #<PrettyPrint:0x82f85c0 @output="", @maxwidth=79, @newline="\n", @genspace=#<Proc:0x82f8368@/home/vbatts/.rvm/rubies/ruby-head/lib/ruby/2.0.0/prettyprint.rb:82 (lambda)>, @output_width=0, @buffer_width=0, @buffer=[], @group_stack=[#<PrettyPrint::Group:0x82f8138 @depth=0, @breakables=[], @break=false>], @group_queue=#<PrettyPrint::GroupQueue:0x82fb7c0 @queue=[[#<PrettyPrint::Group:0x82f8138 @depth=0, @breakables=[], @break=false>]]>, @indent=0> q.group { q.text q.current_group.inspect q.text q.newline q.group(q.current_group.depth + 1) { q.text q.current_group.inspect q.text q.newline q.group(q.current_group.depth + 1) { q.text q.current_group.inspect q.text q.newline q.group(q.current_group.depth + 1) { q.text q.current_group.inspect q.text q.newline } } } } => 284 puts out #<PrettyPrint::Group:0x8354758 @depth=1, @breakables=[], @break=false> #<PrettyPrint::Group:0x8354550 @depth=2, @breakables=[], @break=false> #<PrettyPrint::Group:0x83541cc @depth=3, @breakables=[], @break=false> #<PrettyPrint::Group:0x8347e54 @depth=4, @breakables=[], @break=false>

def current_group @group_stack.last end

fill_breakable(sep=' ', width=sep.length) click to toggle source

This is similar to breakable except the decision to break or not is determined individually.

Two fill_breakable under a group may cause 4 results: (break,break), (break,non-break), (non-break,break), (non-break,non-break). This is different to breakable because two breakable under a group may cause 2 results: (break,break), (non-break,non-break).

The text sep is inserted if a line is not broken at this point.

If sep is not specified, “ ” is used.

If width is not specified, sep.length is used. You will have to specify this when sep is a multibyte character, for example.

def fill_breakable(sep=' ', width=sep.length) group { breakable sep, width } end

flush() click to toggle source

outputs buffered data.

def flush @buffer.each {|data| @output_width = data.output(@output, @output_width) } @buffer.clear @buffer_width = 0 end

group(indent=0, open_obj='', close_obj='', open_width=open_obj.length, close_width=close_obj.length) { || ... } click to toggle source

Groups line break hints added in the block. The line break hints are all to be used or not.

If indent is specified, the method call is regarded as nested by nest(indent) { … }.

If open_obj is specified, text open_obj, open_width is called before grouping. If close_obj is specified, text close_obj, close_width is called after grouping.

def group(indent=0, open_obj='', close_obj='', open_width=open_obj.length, close_width=close_obj.length) text open_obj, open_width group_sub { nest(indent) { yield } } text close_obj, close_width end

group_sub() { || ... } click to toggle source

Takes a block and queues a new group that is indented 1 level further.

def group_sub group = Group.new(@group_stack.last.depth + 1) @group_stack.push group @group_queue.enq group begin yield ensure @group_stack.pop if group.breakables.empty? @group_queue.delete group end end end

nest(indent) { || ... } click to toggle source

Increases left margin after newline with indent for line breaks added in the block.

def nest(indent) @indent += indent begin yield ensure @indent -= indent end end

text(obj, width=obj.length) click to toggle source

This adds obj as a text of width columns in width.

If width is not specified, obj.length is used.

def text(obj, width=obj.length) if @buffer.empty? @output << obj @output_width += width else text = @buffer.last unless Text === text text = Text.new @buffer << text end text.add(obj, width) @buffer_width += width break_outmost_groups end end