Class: PrettyPrint (Ruby 2.3.7)
Description: Class : PrettyPrint - Ruby 2.3.7

- Home
- Core 2.3.7
- Std-lib 2.3.7
- Downloads

Support for the Ruby 2.3 series has ended. See here for reference.

### Home Classes Methods

### In Files

- prettyprint.rb

### Parent

Object

### Namespace

- CLASS PrettyPrint::SingleLine

### Methods

- ::format
- ::new
- ::singleline_format
- #break_outmost_groups
- #breakable
- #current_group
- #fill_breakable
- #flush
- #group
- #group_sub
- #nest
- #text

### Class/Module Index

Quicksearch

- PrettyPrint
- PrettyPrint::SingleLine

No matching classes.

# 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:

- 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, 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@fsij.org>

### Attributes

genspace[R]

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}

group_queue[R]

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

indent[R]

The number of spaces to be indented

maxwidth[R]

The maximum width of a line, before it is separated in to a newline

This defaults to 79, and should be a Fixnum

newline[R]

The value that is appended to `output` to add a new line.

This defaults to “n”, and should be String

output[R]

The output object.

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

### Public Class Methods

format(output=''.dup, 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 44
    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

new(output=''.dup, 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 81
    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

singleline_format(output=''.dup, 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 58
    def PrettyPrint.singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil)
      q = SingleLine.new(output)
      yield q
      output
    end

### Public Instance Methods

break_outmost_groups() click to toggle source

Breaks the buffer into lines that are shorter than maxwidth

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

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

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>

                   # File prettyprint.rb, line 154
    def current_group
      @group_stack.last
    end

fill_breakable(sep=' ', width=sep.length) click to toggle source

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.

                   # File prettyprint.rb, line 211
    def fill_breakable(sep=' ', width=sep.length)
      group { breakable sep, width }
    end

flush() click to toggle source

outputs buffered data.

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

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

                   # File prettyprint.rb, line 259
    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 276
    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 179
    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