123456789_123456789_123456789_123456789_123456789_

Class: PrettyPrint

Relationships & Source Files
Namespace Children
Classes:
Breakable, Group, GroupQueue, SingleLine, Text
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:

  • newline object and space generation block for .new

  • optional width argument for #text

  • #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, lindig.github.io/papers/strictly-pretty-2000.pdf

Philip Wadler, A prettier printer, March 1998, homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier

Author

Tanaka Akira <akr@fsij.org>

Constant Summary

Class Method Summary

Instance Attribute Summary

  • #genspace readonly

    A lambda or Proc, that takes one argument, of an Integer, 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

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.

[ GitHub ] 

  


# File 'lib/prettyprint.rb', line 84



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| ... } 
  



  

    

This is a convenience method which is same as follows:



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


  





  
Yields:


    
  
  • 
    (q)
  
    • 





  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 47



def PrettyPrint.format(output=''.dup, maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n})
  q = PrettyPrint.new(output, maxwidth, newline, &genspace)
  yield q
  q.flush
  output
end


  








  

    .singleline_format(output = ''.dup, maxwidth = nil, newline = nil, genspace = nil) {|q| ... } 
  



  

    

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.


  





  
Yields:


    
  
  • 
    (q)
  
    • 





  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 61



def PrettyPrint.singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil)
  q = SingleLine.new(output)
  yield q
  output
end


  







Instance Attribute Details



  

    #genspace   (readonly)
  



  

    

A lambda or Proc, that takes one argument, of an Integer, and returns the corresponding number of spaces.



By default this is:



lambda {|n| ' ' * n}


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 120



attr_reader :genspace


  








  

    #group_queue   (readonly)
  



  

    

The ::PrettyPrint::GroupQueue of groups in stack to be pretty printed


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 126



attr_reader :group_queue


  








  

    #indent   (readonly)
  



  

    

The number of spaces to be indented


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 123



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 an Integer


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 108



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


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 113



attr_reader :newline


  








  

    #output   (readonly)
  



  

    

The output object.



This defaults to ”, and should accept the << method


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 103



attr_reader :output


  







Instance Method Details



  

    #break_outmost_groups  
  



  

    

Breaks the buffer into lines that are shorter than #maxwidth


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 162



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.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 226



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>


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 157



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.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 214



def fill_breakable(sep=' ', width=sep.length)
  group { breakable sep, width }
end


  








  

    #flush  
  



  

    

outputs buffered data.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 290



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.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 251



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  
  



  

    

Takes a block and queues a new group that is indented 1 level further.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 262



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)  
  



  

    

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


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 279



def nest(indent)
  @indent += indent
  begin
    yield
  ensure
    @indent -= indent
  end
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.


  



  [ GitHub ]


  

  


# File 'lib/prettyprint.rb', line 182



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