Class PrettyPrint
In: lib/prettyprint.rb
Parent: 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:

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?

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@m17n.org>

Methods

break_outmost_groups   breakable   current_group   fill_breakable   first?   flush   format   group   group_sub   nest   new   singleline_format   text  

Classes and Modules

Class PrettyPrint::Breakable
Class PrettyPrint::Group
Class PrettyPrint::GroupQueue
Class PrettyPrint::SingleLine
Class PrettyPrint::Text

Attributes

genspace  [R] 
group_queue  [R] 
indent  [R] 
maxwidth  [R] 
newline  [R] 
output  [R] 

Public Class methods

format(output='', maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n} {|q| ...}

This is a convenience method which is same as follows: 

  begin
    q = PrettyPrint.new(output, maxwidth, newline, &genspace)
    ...
    q.flush
    output
  end

[Source]

    # File lib/prettyprint.rb, line 43
43:   def PrettyPrint.format(output='', maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n})
44:     q = PrettyPrint.new(output, maxwidth, newline, &genspace)
45:     yield q
46:     q.flush
47:     output
48:   end
new(output='', maxwidth=79, newline="\n", &genspace)

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.

[Source]

    # File lib/prettyprint.rb, line 80
80:   def initialize(output='', maxwidth=79, newline="\n", &genspace)
81:     @output = output
82:     @maxwidth = maxwidth
83:     @newline = newline
84:     @genspace = genspace || lambda {|n| ' ' * n}
85: 
86:     @output_width = 0
87:     @buffer_width = 0
88:     @buffer = []
89: 
90:     root_group = Group.new(0)
91:     @group_stack = [root_group]
92:     @group_queue = GroupQueue.new(root_group)
93:     @indent = 0
94:   end
singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil) {|q| ...}

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.

[Source]

    # File lib/prettyprint.rb, line 57
57:   def PrettyPrint.singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil)
58:     q = SingleLine.new(output)
59:     yield q
60:     output
61:   end

Public Instance methods

break_outmost_groups()

[Source]

     # File lib/prettyprint.rb, line 124
124:   def break_outmost_groups
125:     while @maxwidth < @output_width + @buffer_width
126:       return unless group = @group_queue.deq
127:       until group.breakables.empty?
128:         data = @buffer.shift
129:         @output_width = data.output(@output, @output_width)
130:         @buffer_width -= data.width
131:       end
132:       while !@buffer.empty? && Text === @buffer.first
133:         text = @buffer.shift
134:         @output_width = text.output(@output, @output_width)
135:         @buffer_width -= text.width
136:       end
137:     end
138:   end
breakable(sep=' ', width=sep.length)

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.

[Source]

     # File lib/prettyprint.rb, line 172
172:   def breakable(sep=' ', width=sep.length)
173:     group = @group_stack.last
174:     if group.break?
175:       flush
176:       @output << @newline
177:       @output << @genspace.call(@indent)
178:       @output_width = @indent
179:       @buffer_width = 0
180:     else
181:       @buffer << Breakable.new(sep, width, self)
182:       @buffer_width += width
183:       break_outmost_groups
184:     end
185:   end
current_group()

[Source]

     # File lib/prettyprint.rb, line 98
 98:   def current_group
 99:     @group_stack.last
100:   end
fill_breakable(sep=' ', width=sep.length)

[Source]

     # File lib/prettyprint.rb, line 160
160:   def fill_breakable(sep=' ', width=sep.length)
161:     group { breakable sep, width }
162:   end
first?()

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.

[Source]

     # File lib/prettyprint.rb, line 119
119:   def first?
120:     warn "PrettyPrint#first? is obsoleted at 1.8.2."
121:     current_group.first?
122:   end
flush()

outputs buffered data.

[Source]

     # File lib/prettyprint.rb, line 235
235:   def flush
236:     @buffer.each {|data|
237:       @output_width = data.output(@output, @output_width)
238:     }
239:     @buffer.clear
240:     @buffer_width = 0
241:   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.

[Source]

     # File lib/prettyprint.rb, line 197
197:   def group(indent=0, open_obj='', close_obj='', open_width=open_obj.length, close_width=close_obj.length)
198:     text open_obj, open_width
199:     group_sub {
200:       nest(indent) {
201:         yield
202:       }
203:     }
204:     text close_obj, close_width
205:   end
group_sub() {|| ...}

[Source]

     # File lib/prettyprint.rb, line 207
207:   def group_sub
208:     group = Group.new(@group_stack.last.depth + 1)
209:     @group_stack.push group
210:     @group_queue.enq group
211:     begin
212:       yield
213:     ensure
214:       @group_stack.pop
215:       if group.breakables.empty?
216:         @group_queue.delete group
217:       end
218:     end
219:   end
nest(indent) {|| ...}

Increases left margin after newline with indent for line breaks added in the block.

[Source]

     # File lib/prettyprint.rb, line 224
224:   def nest(indent)
225:     @indent += indent
226:     begin
227:       yield
228:     ensure
229:       @indent -= indent
230:     end
231:   end
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.

[Source]

     # File lib/prettyprint.rb, line 144
144:   def text(obj, width=obj.length)
145:     if @buffer.empty?
146:       @output << obj
147:       @output_width += width
148:     else
149:       text = @buffer.last
150:       unless Text === text
151:         text = Text.new
152:         @buffer << text
153:       end
154:       text.add(obj, width)
155:       @buffer_width += width
156:       break_outmost_groups
157:     end
158:   end

[Validate]