In Ruby, when does pp print differently from p, and how can a class customise its pp output with pretty_print?

`Kernel#pp` is the pretty-printing sibling of `Kernel#p`. Both write a developer-facing representation followed by a newline and both return their argument, but `pp` is built on the **pp** and **prettyprint** libraries, which lay text out to fit a width. Interviewers ask about it to see whether you know when the output differs and how the hook works. ## When pp and p differ For a value whose single-line form fits, `pp` and `p` print the same thing. The differences: - **Line breaking.** When the output would exceed the width, `pp` breaks nested arrays, hashes and objects across lines with indentation. `p` always writes one line. - **Width.** `PP.width_for` uses the terminal's width minus one when writing to a terminal, otherwise the `COLUMNS` environment variable, otherwise 80, minus one. - **Plain objects.** For an object that keeps `Kernel#inspect`, `pp` does not call `inspect`; it renders `#<Klass:0x...` and then each instance variable, **sorted by name**, pretty-printing every value. `p` shows them in definition order on one line. - **Custom inspect.** If the class overrides `inspect`, `pp` uses that string verbatim - it has no break points, so it never wraps. Since Ruby 2.5, `pp` needs no `require`; the first call loads the library. ## The pretty_print hook To make a class pretty-print well, define `pretty_print(q)`. The argument is a layout builder; you describe structure and it decides where lines break. | Builder call | Purpose | |---|---| | `q.text(str)` | literal text that is never split | | `q.breakable` | a space that becomes a newline plus indentation if the group does not fit | | `q.group(indent, open, close) { ... }` | a unit that is broken as a whole, with optional brackets | | `q.object_group(obj) { ... }` | a group opened with `#<ClassName` and closed with `>` | | `q.nest(indent) { ... }` | extra indentation for lines broken inside the block | | `q.pp(value)` | pretty-print a nested value with its own `pretty_print` | | `q.seplist(list) { ... }` | yield each element with `q.comma_breakable` between them | | `q.comma_breakable` | a comma followed by a breakable space | The layout algorithm tries to fit each group on the current line; only when it does not fit does it turn that group's breakables into newlines. Inner groups that still fit stay on one line. ## A worked example A timetable object holding a station name and a list of departures: ```ruby class Timetable def initialize(station, departures) @station = station @departures = departures end def pretty_print(q) q.object_group(self) do q.breakable q.text @station q.breakable q.seplist(@departures) { |d| q.pp d } end end end ``` With a short list, `pp timetable` prints `#<Timetable Leeds "08:15", "09:40">` on one line. With forty departures, the group no longer fits, so each breakable becomes a newline and the departures run down the screen, indented by one column. ## Related methods 1. **`pretty_inspect`** returns the pretty-printed text as a String instead of writing it, handy for a log message. 2. **`PP.pp(obj, out, width)`** writes to any object that accepts `<<`, such as a String or an IO, with an explicit width. 3. **`PP.singleline_pp(obj, out)`** runs the same `pretty_print` logic without line breaks. 4. **`pretty_print_inspect`** can be aliased as `inspect` so `p` reuses the `pretty_print` layout on one line; it raises if the class did not override `pretty_print`. ## When to bother ## Cycles and shared objects The pp library also guards against infinite recursion. If an object is reached again while it is still being printed - a parent node pointing back at its child's parent, say - pp calls `pretty_print_cycle` instead, which by default prints `#<Klass:0x... ...>` with an ellipsis. Arrays and hashes print `[...]` and `{...}` in the same situation. A custom `pretty_print` that uses `q.pp` for nested values inherits this protection automatically, whereas code that concatenates `inspect` strings by hand can recurse until the stack overflows. ## When to bother Most classes never need `pretty_print`: `Struct`, `Data`, arrays and hashes already pretty-print well, and a short custom `inspect` is enough for small objects. The hook pays off for objects that wrap long collections - a parsed timetable, a configuration tree, an abstract syntax tree - that you dump often while debugging. Keep in mind that the ivar list `pp` shows by default is built separately from `Kernel#inspect`, so a class that filters `inspect` should check that `pp` honours the same filter.