In Files

  • prettyprint.rb

PrettyPrint

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>

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}) click to toggle source

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 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
            
new(output='', maxwidth=79, newline="\n", &genspace) click to toggle source

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 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
            
singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil) click to toggle source

This is similar to ::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 57
def PrettyPrint.singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil)
  q = SingleLine.new(output)
  yield q
  output
end
            

Public Instance Methods

break_outmost_groups() click to toggle source
 
               # File prettyprint.rb, line 124
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) click to toggle source

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 172
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() click to toggle source
 
               # File prettyprint.rb, line 98
def current_group
  @group_stack.last
end
            
fill_breakable(sep=' ', width=sep.length) click to toggle source
 
               # File prettyprint.rb, line 160
def fill_breakable(sep=' ', width=sep.length)
  group { breakable sep, width }
end
            
first?() click to toggle source

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 119
def first?
  warn "PrettyPrint#first? is obsoleted at 1.8.2."
  current_group.first?
end
            
flush() click to toggle source

outputs buffered data.

 
               # File prettyprint.rb, line 235
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) click to toggle source

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 197
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() click to toggle source
 
               # File prettyprint.rb, line 207
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) click to toggle source

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

 
               # File prettyprint.rb, line 224
def nest(indent)
  @indent += indent
  begin
    yield
  ensure
    @indent -= indent
  end
end
            
text(obj, width=obj.length) click to toggle source

This adds obj as a text of width columns in width.

If width is not specified, obj.length is used.

 
               # File prettyprint.rb, line 144
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