class PrettyPrint
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:
-
text formatting using proportional fonts
-
multibyte characters which has columns different to number of bytes
-
non-string formatting
Bugs¶ ↑
-
Box based formatting?
-
Other (better) model/algorithm?
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
Author¶ ↑
Tanaka Akira <akr@fsij.org>
Attributes
The PrettyPrint::GroupQueue of groups in stack to be pretty printed
The number of spaces to be indented
The maximum width of a line, before it is separated in to a newline
This defaults to 79, and should be a Fixnum
The value that is appended to output
to add a new line.
This defaults to “n”, and should be String
The output object.
This defaults to '', and should accept the << method
Public Class Methods
This is a convenience method which is same as follows:
begin q = PrettyPrint.new(output, maxwidth, newline, &genspace) ... q.flush output end
# File lib/prettyprint.rb, line 43 def PrettyPrint.format(output='', maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n}) q = PrettyPrint.new(output, maxwidth, newline, &genspace) yield q q.flush output end
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 #text, the first argument
sep
of #breakable, the first
argument newline
of ::new, and the result of a given
block for ::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.
# File lib/prettyprint.rb, line 80 def initialize(output='', 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
This is similar to ::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
.
# File lib/prettyprint.rb, line 57 def PrettyPrint.singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil) q = SingleLine.new(output) yield q output end
Public Instance Methods
Breaks the buffer into lines that are shorter than maxwidth
# File lib/prettyprint.rb, line 180 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
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.
# File lib/prettyprint.rb, line 244 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
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>
# File lib/prettyprint.rb, line 153 def current_group @group_stack.last end
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.
# File lib/prettyprint.rb, line 232 def fill_breakable(sep=' ', width=sep.length) group { breakable sep, width } end
first? is a predicate to test the call is a first call to first? with current group.
It is useful to format comma separated values as:
q.group(1, '[', ']') { xxx.each {|yyy| unless q.first? q.text ',' q.breakable end ... pretty printing yyy ... } }
first? is obsoleted in 1.8.2.
# File lib/prettyprint.rb, line 174 def first? warn "PrettyPrint#first? is obsoleted at 1.8.2." current_group.first? end
outputs buffered data.
# File lib/prettyprint.rb, line 308 def flush @buffer.each {|data| @output_width = data.output(@output, @output_width) } @buffer.clear @buffer_width = 0 end
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.
# File lib/prettyprint.rb, line 269 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
Takes a block and queues a new group that is indented 1 level further.
# File lib/prettyprint.rb, line 280 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
Increases left margin after newline with indent
for line
breaks added in the block.
# File lib/prettyprint.rb, line 297 def nest(indent) @indent += indent begin yield ensure @indent -= indent end end
This adds obj
as a text of width
columns in
width.
If width
is not specified, obj.length is used.
# File lib/prettyprint.rb, line 200 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