Class: PrettyPrint

Inherits:
Object show all
Defined in:
lib/rubysl/prettyprint/prettyprint.rb

Overview

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 PrettyPrint.new
  • optional width argument for PrettyPrint#text
  • PrettyPrint#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?

References

Christian Lindig, Strictly Pretty, March 2000, http://www.st.cs.uni-sb.de/~lindig/papers/#pretty

Philip Wadler, A prettier printer, March 1998, http://homepages.inf.ed.ac.uk/wadler/topics/language-design.html#prettier

Author

Tanaka Akira [email protected]

Direct Known Subclasses

PP

Defined Under Namespace

Classes: Breakable, Group, GroupQueue, SingleLine, Text

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(output = '', maxwidth = 79, newline = "\n", &genspace) ⇒ PrettyPrint

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.



78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 78

def initialize(output='', 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

Instance Attribute Details

#genspace ⇒ Object (readonly)

Returns the value of attribute genspace.



93
94
95
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 93

def genspace
  @genspace
end

#group_queue ⇒ Object (readonly)

Returns the value of attribute group_queue.



94
95
96
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 94

def group_queue
  @group_queue
end

#indent ⇒ Object (readonly)

Returns the value of attribute indent.



94
95
96
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 94

def indent
  @indent
end

#maxwidth ⇒ Object (readonly)

Returns the value of attribute maxwidth.



93
94
95
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 93

def maxwidth
  @maxwidth
end

#newline ⇒ Object (readonly)

Returns the value of attribute newline.



93
94
95
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 93

def newline
  @newline
end

#output ⇒ Object (readonly)

Returns the value of attribute output.



93
94
95
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 93

def output
  @output
end

Class Method Details

.format(output = '', maxwidth = 79, newline = "\n", genspace = lambda {|n| ' ' * n}) {|q| ... } ⇒ Object

This is a convenience method which is same as follows:

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

Yields:

  • (q) 


41
42
43
44
45
46
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 41

def PrettyPrint.format(output='', maxwidth=79, newline="\n", genspace=lambda {|n| ' ' * n})
  q = PrettyPrint.new(output, maxwidth, newline, &genspace)
  yield q
  q.flush
  output
end

.singleline_format(output = '', maxwidth = nil, newline = nil, genspace = nil) {|q| ... } ⇒ Object

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.

Yields:

  • (q) 


55
56
57
58
59
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 55

def PrettyPrint.singleline_format(output='', maxwidth=nil, newline=nil, genspace=nil)
  q = SingleLine.new(output)
  yield q
  output
end

Instance Method Details

#break_outmost_groups ⇒ Object

Breaks the buffer into lines that are shorter than #maxwidth



124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 124

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) ⇒ Object

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.



188
189
190
191
192
193
194
195
196
197
198
199
200
201
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 188

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 ⇒ Object

Returns the group most recently added to the stack.



97
98
99
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 97

def current_group
  @group_stack.last
end

#fill_breakable(sep = ' ', width = sep.length) ⇒ Object

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.



176
177
178
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 176

def fill_breakable(sep=' ', width=sep.length)
  group { breakable sep, width }
end

#first? ⇒ Boolean

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.

Returns:

  • (Boolean) 


118
119
120
121
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 118

def first?
  warn "PrettyPrint#first? is obsoleted at 1.8.2."
  current_group.first?
end

#flush ⇒ Object

outputs buffered data.



251
252
253
254
255
256
257
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 251

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) ⇒ Object

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.



213
214
215
216
217
218
219
220
221
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 213

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 ⇒ Object 



223
224
225
226
227
228
229
230
231
232
233
234
235
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 223

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) ⇒ Object

Increases left margin after newline with indent for line breaks added in the block.



240
241
242
243
244
245
246
247
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 240

def nest(indent)
  @indent += indent
  begin
    yield
  ensure
    @indent -= indent
  end
end

#text(obj, width = obj.length) ⇒ Object

This adds obj as a text of width columns in width.

If width is not specified, obj.length is used.



144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
 
# File 'lib/rubysl/prettyprint/prettyprint.rb', line 144

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