класс PrettyPrint

# File lib/prettyprint.rb, line 48
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

Это вспомогательный метод, эквивалентный следующему:

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

# File lib/prettyprint.rb, line 85
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

Создаёт буфер для красивого форматирования.

output — это целевой объект вывода. Если он не задан, используется ”. Объект должен иметь метод <<, принимающий первый аргумент obj метода PrettyPrint#text, первый аргумент sep метода PrettyPrint#breakable, первый аргумент newline метода PrettyPrint.new и результат переданного блока для PrettyPrint.new.

maxwidth задаёт максимальную длину строки. Если значение не задано, используется 79. Однако фактический вывод может превысить maxwidth, если переданы длинные фрагменты текста без возможности переноса.

newline используется для переноса строк. Если значение не задано, используется «n».

Блок используется для генерации пробелов. Если блок не задан, используется {|width| ‘ ’ * width}.

# File lib/prettyprint.rb, line 62
def PrettyPrint.singleline_format(output=''.dup, maxwidth=nil, newline=nil, genspace=nil)
  q = SingleLine.new(output)
  yield q
  output
end

Этот метод похож на PrettyPrint::format, но результат не содержит переносов строк.

maxwidth, newline и genspace игнорируются.

Вызов breakable в блоке не переносит строку и обрабатывается просто как вызов text.

# File lib/prettyprint.rb, line 163
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

Разбивает буфер на строки, длина которых не превышает maxwidth

# File lib/prettyprint.rb, line 227
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

Этот метод указывает, что «при необходимости здесь можно перенести строку»; если в этом месте строка не переносится, вставляется текст width шириной в sep столбцов.

Если sep не задан, используется « ».

Если width не задан, используется sep.length. Например, его необходимо указать, если sep является многобайтовым символом.

# File lib/prettyprint.rb, line 158
def current_group
  @group_stack.last
end

Возвращает группу, последней добавленную в стек.

Пример для наглядности:

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 lib/prettyprint.rb, line 215
def fill_breakable(sep=' ', width=sep.length)
  group { breakable sep, width }
end

Этот метод похож на breakable, за исключением того, что решение о переносе принимается для каждого места отдельно.

Два вызова fill_breakable в одной группе могут привести к 4 результатам: (перенос, перенос), (перенос, без переноса), (без переноса, перенос), (без переноса, без переноса). Это отличается от breakable, поскольку два вызова breakable в одной группе могут привести к 2 результатам: (перенос, перенос), (без переноса, без переноса).

Если в этом месте строка не переносится, вставляется текст sep.

Если sep не задан, используется « ».

Если width не задан, используется sep.length. Например, его необходимо указать, если sep является многобайтовым символом.

# File lib/prettyprint.rb, line 291
def flush
  @buffer.each {|data|
    @output_width = data.output(@output, @output_width)
  }
  @buffer.clear
  @buffer_width = 0
end

выводит буферизованные данные.

# File lib/prettyprint.rb, line 252
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

Объединяет подсказки о переносе строк, добавленные в блоке. Все подсказки о переносе строк должны быть либо применены, либо проигнорированы.

Если задан indent, вызов метода рассматривается как вложенный вызов nest(indent) { … }.

Если задан open_obj, перед группировкой вызывается text open_obj, open_width. Если задан close_obj, после группировки вызывается text close_obj, close_width.

# File lib/prettyprint.rb, line 263
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

Принимает блок и ставит в очередь новую группу с отступом на один уровень глубже.

# File lib/prettyprint.rb, line 280
def nest(indent)
  @indent += indent
  begin
    yield
  ensure
    @indent -= indent
  end
end

Увеличивает левое поле после новой строки на indent для переносов строк, добавленных в блоке.

# File lib/prettyprint.rb, line 183
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

Добавляет obj как текст шириной width столбцов.

Если width не задан, используется obj.length.