Class: PrettyPrint
- Inherits:
-
Object
- Object
- PrettyPrint
- 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:
-
newline object and space generation block for PrettyPrint.new
-
optional width argument for PrettyPrint#text
-
PrettyPrint#breakable
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 <[email protected]>
Defined Under Namespace
Classes: Breakable, Group, GroupQueue, SingleLine, Text
Instance Attribute Summary collapse
-
#genspace ⇒ Object
readonly
A lambda or Proc, that takes one argument, of a Fixnum, and returns the corresponding number of spaces.
-
#group_queue ⇒ Object
readonly
The PrettyPrint::GroupQueue of groups in stack to be pretty printed.
-
#indent ⇒ Object
readonly
The number of spaces to be indented.
-
#maxwidth ⇒ Object
readonly
The maximum width of a line, before it is separated in to a newline.
-
#newline ⇒ Object
readonly
The value that is appended to
output
to add a new line. -
#output ⇒ Object
readonly
The output object.
Class Method Summary collapse
-
.format(output = '', maxwidth = 79, newline = "\n", genspace = lambda {|n| ' ' * n}) {|q| ... } ⇒ Object
This is a convenience method which is same as follows:.
-
.singleline_format(output = '', maxwidth = nil, newline = nil, genspace = nil) {|q| ... } ⇒ Object
This is similar to PrettyPrint::format but the result has no breaks.
Instance Method Summary collapse
-
#break_outmost_groups ⇒ Object
Breaks the buffer into lines that are shorter than #maxwidth.
-
#breakable(sep = ' ', width = sep.length) ⇒ Object
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 ⇒ Object
Returns the group most recently added to the stack.
-
#fill_breakable(sep = ' ', width = sep.length) ⇒ Object
This is similar to #breakable except the decision to break or not is determined individually.
-
#first? ⇒ Boolean
first? is a predicate to test the call is a first call to first? with current group.
-
#flush ⇒ Object
outputs buffered data.
-
#group(indent = 0, open_obj = '', close_obj = '', open_width = open_obj.length, close_width = close_obj.length) ⇒ Object
Groups line break hints added in the block.
-
#group_sub ⇒ Object
Takes a block and queues a new group that is indented 1 level further.
-
#initialize(output = '', maxwidth = 79, newline = "\n", &genspace) ⇒ PrettyPrint
constructor
Creates a buffer for pretty printing.
-
#nest(indent) ⇒ Object
Increases left margin after newline with
indent
for line breaks added in the block. -
#text(obj, width = obj.length) ⇒ Object
This adds
obj
as a text ofwidth
columns in width.
Constructor Details
#initialize(output = '', 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 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.
80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 |
# 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 |
Instance Attribute Details
#genspace ⇒ Object (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}
116 117 118 |
# File 'lib/prettyprint.rb', line 116 def genspace @genspace end |
#group_queue ⇒ Object (readonly)
The PrettyPrint::GroupQueue of groups in stack to be pretty printed
122 123 124 |
# File 'lib/prettyprint.rb', line 122 def group_queue @group_queue end |
#indent ⇒ Object (readonly)
The number of spaces to be indented
119 120 121 |
# File 'lib/prettyprint.rb', line 119 def indent @indent end |
#maxwidth ⇒ Object (readonly)
The maximum width of a line, before it is separated in to a newline
This defaults to 79, and should be a Fixnum
104 105 106 |
# File 'lib/prettyprint.rb', line 104 def maxwidth @maxwidth end |
#newline ⇒ Object (readonly)
The value that is appended to output
to add a new line.
This defaults to “n”, and should be String
109 110 111 |
# File 'lib/prettyprint.rb', line 109 def newline @newline end |
#output ⇒ Object (readonly)
The output object.
This defaults to ”, and should accept the << method
99 100 101 |
# File 'lib/prettyprint.rb', line 99 def output @output end |
Class Method Details
.format(output = '', maxwidth = 79, newline = "\n", genspace = lambda {|n| ' ' * n}) {|q| ... } ⇒ Object
This is a convenience method which is same as follows:
begin
q = PrettyPrint.new(output, maxwidth, newline, &genspace)
...
q.flush
output
end
43 44 45 46 47 48 |
# 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 |
.singleline_format(output = '', maxwidth = nil, newline = nil, genspace = nil) {|q| ... } ⇒ Object
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
.
57 58 59 60 61 |
# 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 |
Instance Method Details
#break_outmost_groups ⇒ Object
Breaks the buffer into lines that are shorter than #maxwidth
180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 |
# 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 |
#breakable(sep = ' ', width = sep.length) ⇒ Object
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.
244 245 246 247 248 249 250 251 252 253 254 255 256 257 |
# 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 |
#current_group ⇒ Object
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>
153 154 155 |
# File 'lib/prettyprint.rb', line 153 def current_group @group_stack.last end |
#fill_breakable(sep = ' ', width = sep.length) ⇒ Object
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.
232 233 234 |
# File 'lib/prettyprint.rb', line 232 def fill_breakable(sep=' ', width=sep.length) group { breakable sep, width } end |
#first? ⇒ Boolean
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.
174 175 176 177 |
# File 'lib/prettyprint.rb', line 174 def first? warn "PrettyPrint#first? is obsoleted at 1.8.2." current_group.first? end |
#flush ⇒ Object
outputs buffered data.
308 309 310 311 312 313 314 |
# File 'lib/prettyprint.rb', line 308 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) ⇒ Object
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.
269 270 271 272 273 274 275 276 277 |
# 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 |
#group_sub ⇒ Object
Takes a block and queues a new group that is indented 1 level further.
280 281 282 283 284 285 286 287 288 289 290 291 292 |
# 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 |
#nest(indent) ⇒ Object
Increases left margin after newline with indent
for line breaks added in the block.
297 298 299 300 301 302 303 304 |
# File 'lib/prettyprint.rb', line 297 def nest(indent) @indent += indent begin yield ensure @indent -= indent end end |
#text(obj, width = obj.length) ⇒ Object
This adds obj
as a text of width
columns in width.
If width
is not specified, obj.length is used.
200 201 202 203 204 205 206 207 208 209 210 211 212 213 214 |
# 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 |