[フレーム]

Class: PrettyPrint

Inherits:
Object show all
Defined in:
opal/stdlib/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?

Report any bugs at http://bugs.ruby-lang.org

== 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 = ''.dup, 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.

82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
# File 'opal/stdlib/prettyprint.rb', line 82
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

Instance Attribute Details

#genspace ⇒ Object (readonly)

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}

118
119
120
# File 'opal/stdlib/prettyprint.rb', line 118
def genspace
 @genspace
end

#group_queue ⇒ Object (readonly)

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

124
125
126
# File 'opal/stdlib/prettyprint.rb', line 124
def group_queue
 @group_queue
end

#indent ⇒ Object (readonly)

The number of spaces to be indented

121
122
123
# File 'opal/stdlib/prettyprint.rb', line 121
def indent
 @indent
end

#maxwidth ⇒ Object (readonly)

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

This defaults to 79, and should be a Fixnum

106
107
108
# File 'opal/stdlib/prettyprint.rb', line 106
def maxwidth
 @maxwidth
end

#newline ⇒ Object (readonly)

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

This defaults to "\n", and should be String

111
112
113
# File 'opal/stdlib/prettyprint.rb', line 111
def newline
 @newline
end

#output ⇒ Object (readonly)

The output object.

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

101
102
103
# File 'opal/stdlib/prettyprint.rb', line 101
def output
 @output
end

Class Method Details

.format(output = ''.dup, 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) 
45
46
47
48
49
50
# File 'opal/stdlib/prettyprint.rb', line 45
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

.singleline_format(output = ''.dup, 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) 
59
60
61
62
63
# File 'opal/stdlib/prettyprint.rb', line 59
def PrettyPrint .singleline_format(output=''.dup, 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

160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
# File 'opal/stdlib/prettyprint.rb', line 160
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.

224
225
226
227
228
229
230
231
232
233
234
235
236
237
# File 'opal/stdlib/prettyprint.rb', line 224
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.

Contrived example: out = "" => "" q = PrettyPrint.new(out) => #, @output_width=0, @buffer_width=0, @buffer=[], @group_stack=[#], @group_queue=#]]>, @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 # # # #

155
156
157
# File 'opal/stdlib/prettyprint.rb', line 155
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.

212
213
214
# File 'opal/stdlib/prettyprint.rb', line 212
def fill_breakable(sep='', width=sep.length)
 group { breakable sep, width }
end

#flush ⇒ Object

outputs buffered data.

288
289
290
291
292
293
294
# File 'opal/stdlib/prettyprint.rb', line 288
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.

249
250
251
252
253
254
255
256
257
# File 'opal/stdlib/prettyprint.rb', line 249
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

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

260
261
262
263
264
265
266
267
268
269
270
271
272
# File 'opal/stdlib/prettyprint.rb', line 260
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.

277
278
279
280
281
282
283
284
# File 'opal/stdlib/prettyprint.rb', line 277
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.

180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
# File 'opal/stdlib/prettyprint.rb', line 180
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

AltStyle によって変換されたページ (->オリジナル) /