Class: TSV::Parser

Inherits:
Object
  • Object
show all
Defined in:
lib/rbbt/tsv/parser.rb

Defined Under Namespace

Classes: END_PARSING, SKIP_LINE

Instance Attribute Summary collapse

Class Method Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(stream = nil, options = {}) ⇒ Parser

Returns a new instance of Parser.



400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
# File 'lib/rbbt/tsv/parser.rb', line 400

def initialize(stream = nil, options = {})
  @header_hash = Misc.process_options(options, :header_hash) || "#"
  @sep = Misc.process_options(options, :sep) || "\t"
  @tsv_grep = Misc.process_options(options, :tsv_grep) 
  stream = TSV.get_stream stream
  @stream = stream


  @header_options = parse_header(stream)

  options = @header_options.merge options
  options = Misc.add_defaults options, :fields => [1] if options[:type] == :single and options[:fields].nil?

  @type ||= Misc.process_options(options, :type) || :double
  @type ||= :double

  @identifiers = Misc.process_options(options, :identifiers) 

  @filename = Misc.process_options(options, :filename) 
  @filename ||= stream.filename if stream.respond_to? :filename

  @sep2 = Misc.process_options(options, :sep2) || "|"
  @cast = Misc.process_options options, :cast; @cast = @cast.to_sym if String === @cast
  @type ||= Misc.process_options options, :type
  @fix = Misc.process_options(options, :fix) 
  @select= Misc.process_options options, :select
  @zipped = Misc.process_options options, :zipped
  @namespace = Misc.process_options options, :namespace
  merge = Misc.process_options(options, :merge)
  merge = @zipped if merge.nil?
  merge = false if merge.nil?

  fields = options[:fields]
  fix_fields(options)

  @type = @type.strip.to_sym if String === @type
  #@type ||= :double if merge == true

  case @type
  when :double 
    self.instance_eval do alias get_values get_values_double end
    self.instance_eval do alias cast_values cast_values_double end
    case
    when (merge and not zipped)
      self.instance_eval do alias add_to_data add_to_data_merge end
    when (merge and zipped)
      self.instance_eval do alias add_to_data add_to_data_merge_zipped end
    when zipped
      self.instance_eval do alias add_to_data add_to_data_zipped end
    else
      self.instance_eval do alias add_to_data add_to_data_no_merge_double end
    end
  when :single
    if @header_options[:type] == :flat
      self.instance_eval do alias get_values get_values_single_from_flat end
      self.instance_eval do alias cast_values cast_values_single end
      self.instance_eval do alias add_to_data add_to_data_no_merge_double end
    else
      self.instance_eval do alias get_values get_values_single end
      self.instance_eval do alias cast_values cast_values_single end
      self.instance_eval do alias add_to_data add_to_data_no_merge_list end
    end
  when :list
    self.instance_eval do alias get_values get_values_list end
    self.instance_eval do alias cast_values cast_values_list end
    self.instance_eval do alias add_to_data add_to_data_no_merge_list end

  when :flat
    @take_all = true if field_positions.nil?
    self.instance_eval do alias cast_values cast_values_flat end
    merge = true if key_position and key_position != 0 and field_positions.nil?
    if merge 
      self.instance_eval do alias get_values get_values_flat_merge end
      if key_position and key_position != 0 and field_positions.nil?
        self.instance_eval do alias add_to_data add_to_data_flat_merge_keys end
      else
        self.instance_eval do alias add_to_data add_to_data_flat_merge_double end
      end
    else
      self.instance_eval do alias get_values get_values_flat_merge end
      if key_position and key_position != 0 and field_positions.nil?
        self.instance_eval do alias add_to_data add_to_data_flat_merge_keys end
      else
        self.instance_eval do alias add_to_data add_to_data_flat_merge_double end
      end
    end
  else
    raise "Unknown TSV type: #{@type.inspect}"
  end

  @straight = false if @sep != "\t" or not @cast.nil? or merge or (@type == :flat and fields)
end

Instance Attribute Details

#castObject

Returns the value of attribute cast.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def cast
  @cast
end

#field_positionsObject

Returns the value of attribute field_positions.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def field_positions
  @field_positions
end

#fieldsObject

Returns the value of attribute fields.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def fields
  @fields
end

#filenameObject

Returns the value of attribute filename.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def filename
  @filename
end

#first_lineObject

Returns the value of attribute first_line.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def first_line
  @first_line
end

#fixObject

Returns the value of attribute fix.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def fix
  @fix
end

#header_hashObject

Returns the value of attribute header_hash.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def header_hash
  @header_hash
end

#header_optionsObject

Returns the value of attribute header_options.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def header_options
  @header_options
end

#identifiersObject

Returns the value of attribute identifiers.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def identifiers
  @identifiers
end

#key_fieldObject

Returns the value of attribute key_field.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def key_field
  @key_field
end

#key_positionObject

Returns the value of attribute key_position.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def key_position
  @key_position
end

#namespaceObject

Returns the value of attribute namespace.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def namespace
  @namespace
end

#preambleObject

Returns the value of attribute preamble.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def preamble
  @preamble
end

#selectObject

Returns the value of attribute select.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def select
  @select
end

#sepObject

Returns the value of attribute sep.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def sep
  @sep
end

#sep2Object

Returns the value of attribute sep2.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def sep2
  @sep2
end

#serializerObject

Returns the value of attribute serializer.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def serializer
  @serializer
end

#straightObject

Returns the value of attribute straight.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def straight
  @straight
end

#streamObject

Returns the value of attribute stream.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def stream
  @stream
end

#take_allObject

Returns the value of attribute take_all.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def take_all
  @take_all
end

#typeObject

Returns the value of attribute type.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def type
  @type
end

#zippedObject

Returns the value of attribute zipped.



4
5
6
# File 'lib/rbbt/tsv/parser.rb', line 4

def zipped
  @zipped
end

Class Method Details

.traverse(stream, options = {}, &block) ⇒ Object



649
650
651
652
# File 'lib/rbbt/tsv/parser.rb', line 649

def self.traverse(stream, options = {}, &block)
  parser = Parser.new(stream, options)
  parser.traverse(options, &block)
end

Instance Method Details

#add_to_data_flat(data, key, values) ⇒ Object



188
189
190
191
# File 'lib/rbbt/tsv/parser.rb', line 188

def add_to_data_flat(data, key, values)
  data[key] = values unless data.include? key
  nil
end

#add_to_data_flat_keys(data, key, values) ⇒ Object



183
184
185
186
# File 'lib/rbbt/tsv/parser.rb', line 183

def add_to_data_flat_keys(data, key, values)
  data[key] = values unless data.include? key
  nil
end

#add_to_data_flat_merge(data, key, values) ⇒ Object



193
194
195
196
197
198
199
200
# File 'lib/rbbt/tsv/parser.rb', line 193

def add_to_data_flat_merge(data, key, values)
  if data.include? key
    data[key] = data[key].concat values
  else
    data[key] = values
  end
  nil
end

#add_to_data_flat_merge_double(data, keys, values) ⇒ Object



202
203
204
205
206
207
208
209
210
211
# File 'lib/rbbt/tsv/parser.rb', line 202

def add_to_data_flat_merge_double(data, keys, values)
  keys.each do |key|
    if data.include? key
      data[key] = data[key].concat values
    else
      data[key] = values
    end
  end
  nil
end

#add_to_data_flat_merge_keys(data, keys, values) ⇒ Object



213
214
215
216
217
218
219
220
221
222
# File 'lib/rbbt/tsv/parser.rb', line 213

def add_to_data_flat_merge_keys(data, keys, values)
  keys.each do |key|
    if data.include? key
      data[key] = data[key].concat values
    else
      data[key] = values.dup
    end
  end
  nil
end

#add_to_data_merge(data, keys, values) ⇒ Object



233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
# File 'lib/rbbt/tsv/parser.rb', line 233

def add_to_data_merge(data, keys, values)
  keys.uniq.each do |key|
    if data.include? key
      new = data[key]
      new.each_with_index do |old, i|
        next if values[i].nil?
        if old.nil?
          new[i] = values[i] 
        else
          old.concat values[i]
        end
      end
      data[key] = new
    else
      data[key] = values
    end
  end
  nil
end

#add_to_data_merge_zipped(data, keys, values) ⇒ Object



253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
# File 'lib/rbbt/tsv/parser.rb', line 253

def add_to_data_merge_zipped(data, keys, values)
  num = keys.length

  values = values.collect do |v|
    (v.nil? || v.empty?) ? [""] : v
  end

  if values.first.length > 1 and num == 1
    keys = keys * values.first.length
    num = keys.length
  end

  values = values.collect{|v| v.length != num ? [v.first] * num : v}
  all = values.unshift keys
  Misc.zip_fields(all).each do |values|
    key = values.shift
    if data.include? key
      data[key] = data[key].zip(values).collect do |old, new|
        old.push new
        old
      end
    else
      data[key] = values.collect{|v| [v]}
    end
  end
  nil
end

#add_to_data_no_merge_double(data, keys, values) ⇒ Object



224
225
226
227
228
229
230
231
# File 'lib/rbbt/tsv/parser.rb', line 224

def add_to_data_no_merge_double(data, keys, values)
  keys = [keys] unless Array === keys
  keys.each do |key|
    next if data.include? key
    data[key] = values 
  end
  nil
end

#add_to_data_no_merge_list(data, key, values) ⇒ Object



178
179
180
181
# File 'lib/rbbt/tsv/parser.rb', line 178

def add_to_data_no_merge_list(data, key, values)
  data[key] = values unless data.include? key
  nil
end

#add_to_data_zipped(data, keys, values) ⇒ Object



281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
# File 'lib/rbbt/tsv/parser.rb', line 281

def add_to_data_zipped(data, keys, values)
  num = keys.length

  if values.first.length > 1 and num == 1
    keys = keys * values.first.length
    num = keys.length
  end

  values = values.collect{|v| v.length != num ? [v.first] * num : v}
  all = values.unshift keys
  Misc.zip_fields(all).each do |values|
    key = values.shift
    next if data.include? key
    data[key] = values.collect{|v| [v]}
  end
  nil
end

#all_fieldsObject



9
10
11
12
# File 'lib/rbbt/tsv/parser.rb', line 9

def all_fields
  all = [key_field] + fields
  NamedArray.setup all, all
end

#annotate(data) ⇒ Object



505
506
507
# File 'lib/rbbt/tsv/parser.rb', line 505

def annotate(data)
  setup(data)
end

#cast?Boolean

Returns:

  • (Boolean)


70
71
72
# File 'lib/rbbt/tsv/parser.rb', line 70

def cast?
  !! @cast
end

#cast_values_double(values) ⇒ Object



329
330
331
332
333
334
335
336
# File 'lib/rbbt/tsv/parser.rb', line 329

def cast_values_double(values)
  case
  when Symbol === cast
    values.collect{|list| list.collect{|v| v.nil? or v.empty? ? nil : v.send(cast)}}
  when Proc === cast
    values.collect{|list| list.collect{|v| v.nil? or v.empty? ? nil : cast.call(v) }}
  end
end

#cast_values_flat(values) ⇒ Object



320
321
322
323
324
325
326
327
# File 'lib/rbbt/tsv/parser.rb', line 320

def cast_values_flat(values)
  case
  when Symbol === cast
    values.collect{|v| v.nil? or v.empty? ? nil : v.send(cast)}
  when Proc === cast
    values.collect{|v| v.nil? or v.empty? ? nil : cast.call(v) }
  end
end

#cast_values_list(values) ⇒ Object



311
312
313
314
315
316
317
318
# File 'lib/rbbt/tsv/parser.rb', line 311

def cast_values_list(values)
  case
  when Symbol === cast
    values.collect{|v| v.nil? or v.empty? ? nil : v.send(cast)}
  when Proc === cast
    values.collect{|v| v.nil? or v.empty? ? nil : cast.call(v)}
  end
end

#cast_values_single(value) ⇒ Object



300
301
302
303
304
305
306
307
308
309
# File 'lib/rbbt/tsv/parser.rb', line 300

def cast_values_single(value)
  case
  when (value.nil? or value.empty?)
    nil
  when Symbol === cast
    value.send(cast)
  when Proc === cast
    cast.call value
  end
end

#chop_line(line) ⇒ Object



74
75
76
# File 'lib/rbbt/tsv/parser.rb', line 74

def chop_line(line)
  @sep == " " ? line.split(/ /, -1) : line.split(@sep, -1)
end

#fix_fields(options) ⇒ Object



342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
# File 'lib/rbbt/tsv/parser.rb', line 342

def fix_fields(options)
  key_field = Misc.process_options options, :key_field
  fields    = Misc.process_options options, :fields


  if (key_field.nil? or key_field == 0 or key_field == :key) and
    (fields.nil? or fields == @fields or (not @fields.nil? and fields == (1..@fields.length).to_a))

    @straight = true
    return
  else
    @straight = false

    case
    when (key_field.nil? or (not Integer === key_field and @key_field.nil?) or key_field == @key_field or key_field == 0)
      @key_position = 0
    when Integer === key_field
      @key_position = key_field
    when String === key_field
      @key_position = @fields.dup.unshift(@key_field).index key_field
      raise "Key field #{ key_field } was not found" if @key_position.nil?
    when :key == key_field
      @key_position = 0
    else
      raise "Format of key_field not understood: #{key_field.inspect}"
    end

    if (fields.nil? or (not (Array === fields and Integer === fields.first) and @fields.nil?) or fields == @fields or (not @fields.nil? and fields == (1..@fields.length).to_a))
      if not @fields.nil? and type != :flat
        @field_positions = (0..@fields.length).to_a
        @field_positions.delete @key_position
      end
    else
      fields = [fields] if not Array === fields
      @field_positions = fields.collect{|field|
        case
        when Integer === field
          field
        when String === field
          pos = @fields.dup.unshift(@key_field).index field
          raise "Field not identified: #{ field }" if pos.nil?
          pos
        else
          raise "Format of fields not understood: #{field.inspect}"
        end
      }
    end

    new_key_field = @fields.dup.unshift(@key_field)[@key_position] if not @fields.nil?
    @fields = @fields.dup.unshift(@key_field).values_at *@field_positions if not @fields.nil? and not @field_positions.nil?
    @fields ||= fields if Array === fields and String === fields.first
    @fields = [@key_field] if new_key_field != @key_field and type == :flat and @field_positions.nil?
    @key_field = new_key_field 
    @key_field ||= key_field if String === key_field

  end
end

#get_values_double(parts) ⇒ Object



112
113
114
115
116
117
118
119
120
121
122
123
124
# File 'lib/rbbt/tsv/parser.rb', line 112

def get_values_double(parts)
  return parts.shift.split(@sep2, -1), parts.collect{|value| value.split(@sep2, -1)} if field_positions.nil? and key_position.nil?
  keys = parts[key_position].split(@sep2, -1)
  values = case
           when field_positions.nil?
            parts.tap{|o| o.delete_at key_position}
           when field_positions.empty?
             []
           else
             parts.values_at *field_positions
           end.collect{|value| value.nil? ? [] : value.split(@sep2, -1) }
  [keys, values]
end

#get_values_flat(parts) ⇒ Object



172
173
174
175
# File 'lib/rbbt/tsv/parser.rb', line 172

def get_values_flat(parts)
  keys, values = get_values_flat_merge(parts)
  [keys.first, values]
end

#get_values_flat_inverse(parts) ⇒ Object



126
127
128
129
130
# File 'lib/rbbt/tsv/parser.rb', line 126

def get_values_flat_inverse(parts)
  value = parts.shift
  keys = parts
  [keys, [value]]
end

#get_values_flat_merge(parts) ⇒ Object



133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
# File 'lib/rbbt/tsv/parser.rb', line 133

def get_values_flat_merge(parts)
  begin
    orig = parts

    if key_position and key_position != 0 and field_positions.nil?
      value = parts.shift.split(@sep2, -1)
      keys = parts.collect{|p| p.split(@sep2, -1) }.flatten
      return [keys, value]
    end

    return parts.shift.split(@sep2, -1), parts.collect{|value| value.split(@sep2, -1)}.flatten if 
    field_positions.nil? and (key_position.nil? or key_position == 0)
  rescue
    raise $!
  end

  if key_position and key_position != 0 and @header_options[:type] == :flat
    keys = parts[1..-1]
  else
    str = parts[key_position]
    keys = str.split(@sep2, -1)
  end

  if @take_all
    values = parts.collect{|e| e.split(@sep2, -1) }.flatten
  else
    if field_positions.nil?
      parts.delete_at key_position
      values = parts.first
    else
      values = parts[field_positions.first]
    end

    values = values.split(@sep2, -1)
  end

  [keys, values]
end

#get_values_list(parts) ⇒ Object



96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
# File 'lib/rbbt/tsv/parser.rb', line 96

def get_values_list(parts)
  return parts.shift, parts if field_positions.nil? and key_position.nil?
  key = parts[key_position]

  values = case
           when field_positions.nil?
            parts.tap{|o| o.delete_at key_position}
           when field_positions.empty?
             []
           else
            parts.values_at *field_positions
           end

  [key, values]
end

#get_values_single(parts) ⇒ Object



89
90
91
92
93
94
# File 'lib/rbbt/tsv/parser.rb', line 89

def get_values_single(parts)
  return parts.shift, parts.first if field_positions.nil? and key_position.nil?
  key = parts[key_position]
  value = parts[(field_positions.nil? or field_positions.empty?) ? 0 : field_positions.first]
  [key, value]
end

#get_values_single_from_flat(parts) ⇒ Object



78
79
80
81
82
83
84
85
86
87
# File 'lib/rbbt/tsv/parser.rb', line 78

def get_values_single_from_flat(parts)
  return parts.shift, parts.first if field_positions.nil? and key_position.nil?
  if key_position == 0
    [parts.shift, parts.first]
  else
    key = parts.shift
    [parts, key]
  end

end

#identify_field(field) ⇒ Object



640
641
642
# File 'lib/rbbt/tsv/parser.rb', line 640

def identify_field(field)
  TSV.identify_field(key_field, fields, field)
end

#optionsObject



509
510
511
512
513
514
515
516
517
518
519
# File 'lib/rbbt/tsv/parser.rb', line 509

def options
  options = {}
  TSV::ENTRIES.each do |entry|
    if self.respond_to? entry
      value = self.send(entry) 
      options[entry.to_sym] = value unless value.nil?
    end
  end
  options[:sep] = @sep if @sep and @sep != "\t" and @sep != /\t/
  IndiferentHash.setup options
end

#parse_header(stream) ⇒ Object



14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
# File 'lib/rbbt/tsv/parser.rb', line 14

def parse_header(stream)
  options = {}
  @preamble = []

  # Get line

  #Thread.pass while IO.select([stream], nil, nil, 1).nil? if IO === stream
  line = stream.gets
  return {} if line.nil?
  #raise "Empty content: #{ stream.inspect }" if line.nil?
  line = Misc.fixutf8 line.chomp

  # Process options line

  if line and (String === @header_hash and line =~ /^#{@header_hash}: (.*)/)
    options = Misc.string2hash $1.chomp
    line = stream.gets
    line = Misc.fixutf8 line.chomp if line
  end

  # Determine separator

  @sep = options[:sep] if options[:sep]

  # Process fields line

  preamble << line if line
  while line and (TrueClass === @header_hash or (String === @header_hash and Misc.fixutf8(line) =~ /^#{@header_hash}/ ))
    @fields = line.split(@sep, -1)
    @key_field = @fields.shift
    @key_field = @key_field[(0 + header_hash.length)..-1] if String === @header_hash

    #Thread.pass while IO.select([stream], nil, nil, 1).nil? if IO === stream
    line = (@header_hash != "" ?  stream.gets : nil)
    line = Misc.fixutf8 line.chomp if line
    preamble << line if line
    @header_hash = false if TrueClass === @header_hash
  end

  @preamble = preamble[0..-3] * "\n"

  line ||= stream.gets

  @first_line = line

  options
end

#process(line) ⇒ Object

Raises:



62
63
64
65
66
67
68
# File 'lib/rbbt/tsv/parser.rb', line 62

def process(line)
  l = line.chomp
  raise SKIP_LINE if l[0] == "#"[0] or (Proc === @select and not @select.call l)
  l = @fix.call l if Proc === @fix
  raise END_PARSING unless l
  l
end

#rescue_first_lineObject



338
339
340
# File 'lib/rbbt/tsv/parser.rb', line 338

def rescue_first_line
  @first_line
end

#rewindObject



644
645
646
647
# File 'lib/rbbt/tsv/parser.rb', line 644

def rewind
  stream.reopen(filename, "r") if stream.closed? and filename
  stream.rewind
end

#setup(data) ⇒ Object



493
494
495
496
497
498
499
500
501
502
503
# File 'lib/rbbt/tsv/parser.rb', line 493

def setup(data)
  data.extend TSV unless TSV === data
  data.type = @type
  data.key_field = @key_field
  data.fields = @fields
  data.namespace = @namespace
  data.filename = @filename
  data.identifiers = @identifiers
  data.cast = @cast if Symbol === @cast
  data
end

#traverse(options = {}) ⇒ Object



521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
# File 'lib/rbbt/tsv/parser.rb', line 521

def traverse(options = {})
  monitor, bar, grep, invert_grep, head = Misc.process_options options, :monitor, :bar, :grep, :invert_grep, :head
  monitor = bar if bar and monitor.nil?
  raise "No block given in TSV::Parser#traverse" unless block_given?

  stream = @stream


  # first line
  line = self.rescue_first_line

  if @tsv_grep

    stream = Open.grep(stream, @tsv_grep, invert_grep)
    stream.no_fail = true
    begin
      match = Open.grep(StringIO.new(line), @tsv_grep, invert_grep).read
      line = stream.gets if match.empty?
    rescue Exception
      Log.exception $!
      line = stream.gets 
    end
  end

  progress_monitor, monitor = monitor, nil if Log::ProgressBar === monitor

  # setup monitor
  if monitor and (stream.respond_to?(:size) or (stream.respond_to?(:stat) and stream.stat.respond_to? :size and stream.respond_to?(:pos)))
    size = case
           when stream.respond_to?(:size)
             stream.size
           else
             stream.stat.size
           end
    size = nil if size.to_i == 0
    desc = "Parsing Stream"
    step = 100
    if Hash === monitor
      desc = monitor[:desc] if monitor.include? :desc 
      step = monitor[:step] if monitor.include? :step 
    end
    progress_monitor = Log::ProgressBar.new_bar(size, :desc => desc, :bytes => true)
  elsif progress_monitor 

    size = case
           when stream.respond_to?(:size)
             stream.size
           else
             stream.stat.size
           end

    progress_monitor.bytes = true
    progress_monitor.max =  size unless size.to_i == 0
  elsif monitor
    desc = "Parsing Stream"
    step = 100
    size = nil
    if Hash === monitor
      desc = monitor[:desc] if monitor.include? :desc 
      step = monitor[:step] if monitor.include? :step 
    end
    progress_monitor = Log::ProgressBar.new_bar(size, :desc => desc, :bytes => true)
  end

  # parser 
  line_num = 1
  begin

    while not line.nil? 
      begin
        if progress_monitor
          progress_monitor.tick(line.bytesize)
        end

        raise SKIP_LINE if line.empty?

        line = Misc.fixutf8(line)
        line = self.process line
        raise SKIP_LINE if line.empty?
        parts = self.chop_line line
        key, values = self.get_values parts
        values = self.cast_values values if self.cast?
        
        yield key, values

        line = stream.gets

        line_num += 1
        raise END_PARSING if head and line_num > head.to_i
      rescue SKIP_LINE
        begin
          line = stream.gets
          next
        rescue IOError
          break
        end
      rescue END_PARSING
        stream.close unless stream.closed?
        begin stream.join; rescue Exception; end if stream.respond_to? :join and not stream.joined?
        break
      rescue Errno::EPIPE
        Log.error "Pipe closed while parsing #{Misc.fingerprint stream}: #{$!.message}"
        stream.abort if stream.respond_to? :abort
        raise $!
      rescue Exception
        Log.error "Exception parsing #{Misc.fingerprint stream}: #{$!.message}"
        stream.abort $! if stream.respond_to? :abort
        raise $!
      end
    end
  ensure
    Log::ProgressBar.remove_bar(progress_monitor)
    stream.close unless stream.closed?
    stream.join if stream.respond_to? :join and not stream.joined?
  end

  self
end