Class: PrettyPrint
Relationships & Source Files | |
Namespace Children | |
Classes:
| |
Inherits: | Object |
Defined in: | lib/prettyprint.rb |
Overview
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>
Class Method Summary
-
.format(output = ''.dup, maxwidth = 79, newline = "\n", genspace = lambda {|n| ' ' * n}) {|q| ... }
This is a convenience method which is same as follows:
-
.new(output = ''.dup, maxwidth = 79, newline = "\n", &genspace) ⇒ PrettyPrint
constructor
Creates a buffer for pretty printing.
-
.singleline_format(output = ''.dup, maxwidth = nil, newline = nil, genspace = nil) {|q| ... }
This is similar to .format but the result has no breaks.
Instance Attribute Summary
-
#genspace
readonly
A lambda or Proc, that takes one argument, of a Fixnum, and returns the corresponding number of spaces.
-
#group_queue
readonly
The GroupQueue of groups in stack to be pretty printed.
-
#indent
readonly
The number of spaces to be indented.
-
#maxwidth
readonly
The maximum width of a line, before it is separated in to a newline.
-
#newline
readonly
The value that is appended to #output to add a new line.
-
#output
readonly
The output object.
Instance Method Summary
-
#break_outmost_groups
Breaks the buffer into lines that are shorter than #maxwidth
-
#breakable(sep = ' ', width = sep.length)
This says “you can break a line here if necessary”, and a
width
-column textsep
is inserted if a line is not broken at the point. -
#current_group
Returns the group most recently added to the stack.
-
#fill_breakable(sep = ' ', width = sep.length)
This is similar to #breakable except the decision to break or not is determined individually.
-
#flush
outputs buffered data.
-
#group(indent = 0, open_obj = '', close_obj = '', open_width = open_obj.length, close_width = close_obj.length)
Groups line break hints added in the block.
-
#group_sub
Takes a block and queues a new group that is indented 1 level further.
-
#nest(indent)
Increases left margin after newline with #indent for line breaks added in the block.
-
#text(obj, width = obj.length)
This adds
obj
as a text ofwidth
columns in width.
Constructor Details
.new(output = ''.dup, maxwidth = 79, newline = "\n", &genspace) ⇒ PrettyPrint
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 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
Class Method Details
.format(output = ''.dup, maxwidth = 79, newline = "\n", genspace = lambda {|n| ' ' * n}) {|q| ... }
.singleline_format(output = ''.dup, maxwidth = nil, newline = nil, genspace = nil) {|q| ... }
Instance Attribute Details
#genspace (readonly)
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}
# File 'lib/prettyprint.rb', line 118
attr_reader :genspace
#group_queue (readonly)
The ::PrettyPrint::GroupQueue of groups in stack to be pretty printed
# File 'lib/prettyprint.rb', line 124
attr_reader :group_queue
#indent (readonly)
The number of spaces to be indented
# File 'lib/prettyprint.rb', line 121
attr_reader :indent
#maxwidth (readonly)
The maximum width of a line, before it is separated in to a newline
This defaults to 79, and should be a Fixnum
# File 'lib/prettyprint.rb', line 106
attr_reader :maxwidth
#newline (readonly)
The value that is appended to #output to add a new line.
This defaults to “n”, and should be String
# File 'lib/prettyprint.rb', line 111
attr_reader :newline
#output (readonly)
The output object.
This defaults to '', and should accept the << method
# File 'lib/prettyprint.rb', line 101
attr_reader :output
Instance Method Details
#break_outmost_groups
Breaks the buffer into lines that are shorter than #maxwidth
# File '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
#breakable(sep = ' ', width = sep.length)
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 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
#current_group
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 155
def current_group @group_stack.last end
#fill_breakable(sep = ' ', width = sep.length)
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.
#flush
outputs buffered data.
# File 'lib/prettyprint.rb', line 288
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)
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.
#group_sub
Takes a block and queues a new group that is indented 1 level further.
#nest(indent)
Increases left margin after newline with #indent for line breaks added in the block.
#text(obj, width = obj.length)
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 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