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:
-
newline object and space generation block for
PrettyPrint.new
-
optional width argument for
PrettyPrint#text
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>
The output object.
This defaults to ”, and should accept the << method
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
A lambda or Proc
, that takes one argument, of a Fixnum, and returns the corresponding number of spaces.
By default this is:
lambda {|n| ' ' * n}
The number of spaces to be indented
The PrettyPrint::GroupQueue of groups in stack to be pretty printed
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 45
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
This is a convenience method which is same as follows:
begin q = PrettyPrint.new(output, maxwidth, newline, &genspace) ... q.flush output end
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 82
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
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.
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 59
def PrettyPrint.singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil)
q = SingleLine.new(output)
yield q
output
end
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
.
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 160
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
Breaks the buffer into lines that are shorter than maxwidth
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 224
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
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 tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 155
def current_group
@group_stack.last
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 tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 212
def fill_breakable(sep=' ', width=sep.length)
group { breakable sep, width }
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 tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 288
def flush
@buffer.each {|data|
@output_width = data.output(@output, @output_width)
}
@buffer.clear
@buffer_width = 0
end
outputs buffered data.
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 249
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
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 tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 260
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
Takes a block and queues a new group that is indented 1 level further.
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 277
def nest(indent)
@indent += indent
begin
yield
ensure
@indent -= indent
end
end
Increases left margin after newline with indent
for line breaks added in the block.
# File tmp/rubies/ruby-2.4.10/lib/prettyprint.rb, line 180
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
This adds obj
as a text of width
columns in width.
If width
is not specified, obj.length is used.