constants | attributes | methods
Class

PrettyPrint

Inheritance
< 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>

Classes & Modules

Attributes

Name Visibility R/W Description
genspace public R
group_queue public R
indent public R
maxwidth public R
newline public R
output public R

Methods

Class

Visibility Signature
public format (output='', maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n} {|q| ...}
public new (output='', maxwidth=79, newline="\n", &genspace)
public singleline_format (output='', maxwidth=nil, newline=nil, genspace=nil) {|q| ...}

Instance

Visibility Signature
public break_outmost_groups ()
public breakable (sep=' ', width=sep.length)
public current_group ()
public fill_breakable (sep=' ', width=sep.length)
public first? ()
public flush ()
public group (indent=0, open_obj='', close_obj='', open_width=open_obj.length, close_width=close_obj.length) {|| ...}
public group_sub () {|| ...}
public nest (indent) {|| ...}
public text (obj, width=obj.length)

Class Method Detail

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

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.

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.

Instance Method Detail

break_outmost_groups()

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.

current_group()

fill_breakable(sep=' ', width=sep.length)

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.

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. 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() {|| ...}

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.