class PP - pp: Ruby Standard Library Documentation

# class PP

A pretty-printer for Ruby objects.

## What `PP` Does¶ ↑

Standard output by p returns this:

    #<PP:0x81fedf0 @genspace=#<Proc:0x81feda0>, @group_queue=#<PrettyPrint::GroupQueue:0x81fed3c @queue=[[#<PrettyPrint::Group:0x81fed78 @breakables=[], @depth=0, @break=false>], []]>, @buffer=[], @newline="\n", @group_stack=[#<PrettyPrint::Group:0x81fed78 @breakables=[], @depth=0, @break=false>], @buffer_width=0, @indent=0, @maxwidth=79, @output_width=2, @output=#<IO:0x8114ee4>>

Pretty-printed output returns this:

    #<PP:0x81fedf0
     @buffer=[],
     @buffer_width=0,
     @genspace=#<Proc:0x81feda0>,
     @group_queue=
      #<PrettyPrint::GroupQueue:0x81fed3c
       @queue=
        [[#<PrettyPrint::Group:0x81fed78 @break=false, @breakables=[], @depth=0>],
         []]>,
     @group_stack=
      [#<PrettyPrint::Group:0x81fed78 @break=false, @breakables=[], @depth=0>],
     @indent=0,
     @maxwidth=79,
     @newline="\n",
     @output=#<IO:0x8114ee4>,
     @output_width=2>

## Usage¶ ↑

    pp(obj)             #=> obj
    pp obj              #=> obj
    pp(obj1, obj2, ...) #=> [obj1, obj2, ...]
    pp()                #=> nil

Output `obj(s)` to `$>` in pretty printed format.

It returns `obj(s)`.

## Output Customization¶ ↑

To define a customized pretty printing function for your classes, redefine method `#pretty_print(pp)` in the class. Note that `require 'pp'` is needed before redefining `#pretty_print(pp)`.

`#pretty_print` takes the `pp` argument, which is an instance of the `PP` class. The method uses text, breakable, nest, group and `pp` to print the object.

## Pretty-Print JSON¶ ↑

To pretty-print JSON refer to JSON#pretty_generate.

## Author¶ ↑

Tanaka Akira <akr@fsij.org>

### Constants

VERSION

  The version string

### Public Class Methods

pp(obj, out=$>, width=width_for(out)) click to toggle source

Outputs `obj` to `out` in pretty printed format of `width` columns in width.

If `out` is omitted, `$>` is assumed. If `width` is omitted, the width of `out` is assumed (see `width_for`).

`PP.pp` returns `out`.

    # File pp.rb, line 96
    def PP.pp(obj, out=$>, width=width_for(out))
      q = new(out, width)
      q.guard_inspect_key {q.pp obj}
      q.flush
      #$pp = q
      out << "\n"
    end

sharing_detection() click to toggle source

Returns the sharing detection flag as a boolean value. It is false (nil) by default.

    # File pp.rb, line 125
    def sharing_detection
      Ractor.current[:pp_sharing_detection]
    end

sharing_detection=(b) click to toggle source

Sets the sharing detection flag to b.

    # File pp.rb, line 129
    def sharing_detection=(b)
      Ractor.current[:pp_sharing_detection] = b
    end

singleline_pp(obj, out=$>) click to toggle source

Outputs `obj` to `out` like `PP.pp` but with no indent and newline.

`PP.singleline_pp` returns `out`.

    # File pp.rb, line 108
    def PP.singleline_pp(obj, out=$>)
      q = SingleLine.new(out)
      q.guard_inspect_key {q.pp obj}
      q.flush
      out
    end

width_for(out) click to toggle source

Returns the usable width for `out`. As the width of `out`:

1. If `out` is assigned to a tty device, its width is used.

2. Otherwise, or it could not get the value, the `COLUMN` environment variable is assumed to be set to the width.

3. If `COLUMN` is not set to a non-zero number, 80 is assumed.

And finally, returns the above width value - 1.

- This -1 is for Windows command prompt, which moves the cursor to the next line if it reaches the last column.

    # File pp.rb, line 79
    def PP.width_for(out)
      begin
        require 'io/console'
        _, width = out.winsize
      rescue LoadError, NoMethodError, SystemCallError
      end
      (width || ENV['COLUMNS']&.to_i&.nonzero? || 80) - 1
    end