Object
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
Box based formatting?
Other (better) model/algorithm?
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@m17n.org>
This is a convenience method which is same as follows:
begin q = PrettyPrint.new(output, maxwidth, newline, &genspace) ... q.flush output end
# File prettyprint.rb, line 41
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 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 prettyprint.rb, line 78
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 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 prettyprint.rb, line 55
def PrettyPrint.singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil)
q = SingleLine.new(output)
yield q
output
end
# File prettyprint.rb, line 122
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 tells “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 prettyprint.rb, line 170
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
# File prettyprint.rb, line 96
def current_group
@group_stack.last
end
# File prettyprint.rb, line 158
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 prettyprint.rb, line 117
def first?
warn "PrettyPrint#first? is obsoleted at 1.8.2."
current_group.first?
end
outputs buffered data.
# File prettyprint.rb, line 233
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 prettyprint.rb, line 195
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
# File prettyprint.rb, line 205
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 prettyprint.rb, line 222
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 prettyprint.rb, line 142
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