tabreader 0.1.0 → 1.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: '093433817ddd93e79af07604a115964639269b2a'
-  data.tar.gz: 85d0c1333b75670230133e73f91cda27c1bb68ba
+  metadata.gz: 67dbbade5c8b10576053c868e1514c1f87ebb6c7
+  data.tar.gz: 2a65adb418fbb89876c47f0427473c0ec7cc3448
 SHA512:
-  metadata.gz: 0c254861cd86e97d23b7f020d9a1323314b036964f3b14551da66f8e6f4c2948ea6c6874b3121c82f34070c13606f4631721d532408899a0393064311dcc71ff
-  data.tar.gz: 9baa9df8979c3eb1923c31ae4344e57926f4c1e431c3d6c4b7567e92cf5bbf9348e55b08756e04cc2a98cfd5978f0c12792d17fb6d713525ab80d008ae2511d5
+  metadata.gz: e15ec15bf2e2ee097ef9e58aafca69a68c0796e3ccea125367b47a0ca81497373d7058e4e66c9328e463bc915cc7e6c6c7eb6e105612d6a558e2baecdc4c70ca
+  data.tar.gz: a900e51d7b15a509b8457b848c46ffc73fc3c26e41850671d5bc46416a99f45b5b006d6af38f3d23f2c0ee2ff5062ca4f515450d460742dd0551f5183d8f1db4

data/Manifest.txt

@@ -5,8 +5,10 @@ README.md
 Rakefile
 lib/tabreader.rb
 lib/tabreader/reader.rb
+lib/tabreader/reader_hash.rb
 lib/tabreader/version.rb
 test/data/empty.tab
 test/data/test.tab
 test/helper.rb
 test/test_reader.rb
+test/test_reader_hash.rb

data/README.md

@@ -1,7 +1,7 @@
-# tabreader - read in tabular datafiles in text in the tab format
+# tabreader - read in tabular datafiles in text in the tabular (TAB) format
 
-* home  :: [github.com/datatxt/tabreader](https://github.com/datatxt/tabreader)
-* bugs  :: [github.com/datatxt/tabreader/issues](https://github.com/datatxt/tabreader/issues)
+* home  :: [github.com/csv11/tabreader](https://github.com/csv11/tabreader)
+* bugs  :: [github.com/csv11/tabreader/issues](https://github.com/csv11/tabreader/issues)
 * gem   :: [rubygems.org/gems/tabreader](https://rubygems.org/gems/tabreader)
 * rdoc  :: [rubydoc.info/gems/tabreader](http://rubydoc.info/gems/tabreader)
 * forum :: [wwwmake](http://groups.google.com/group/wwwmake)
@@ -22,7 +22,7 @@ or the "magic" packaged up in `TabReader`:
 
 ``` ruby
 line = "1\t2\t3"
-values = TabReader.parse_line( line )
+values = Tab.parse_line( line )   ## or TAB.parse_line or TabReader.parse_line
 pp values
 # => ["1","2","3"]
 ```
@@ -30,58 +30,84 @@ pp values
 or use the convenience helpers:
 
 ``` ruby
-txt <<=TAB
+txt <<=TXT
 1\t2\t3
 4\t5\t6
-TAB
+TXT
 
-records = TabReader.parse( txt )
+records = Tab.parse( txt )   ## or TAB.parse or TabReader.parse
 pp records
 # => [["1","2","3"],
-#     ["5","6","7"]]
+#     ["4","5","6"]]
 
 # -or-
 
-records = TabReader.read( "values.tab" )
+records = Tab.read( "values.tab" )  ## or TAB.read or TabReader.read
 pp records
 # => [["1","2","3"],
-#     ["5","6","7"]]
+#     ["4","5","6"]]
 
 # -or-
 
-TabReader.foreach( "values.tab" ) do |rec|
+Tab.foreach( "values.tab" ) do |rec|  ## or TAB.foreach or TabReader.foreach
   pp rec
 end
 # => ["1","2","3"]
-# => ["5","6","7"]
+# => ["4","5","6"]
+```
+
+
+
+### What about Enumerable?
+
+Yes, every reader includes `Enumerable` and runs on `each`.
+Use `new` or `open` without a block
+to get the enumerator (iterator).
+Example:
+
+
+``` ruby
+tab = Tab.new( "a\tb\tc" )   ## or TAB.new or TabReader.new
+it  = tab.to_enum
+pp it.next  
+# => ["a","b","c"]
+
+# -or-
+
+tab = Tab.open( "values.tab" ) ## or TAB.open or TabReader.open
+it  = tab.to_enum
+pp it.next
+# => ["1","2","3"]
+pp it.next
+# => ["4","5","6"]
 ```
 
 
 ### What about headers?
 
-Use the `TabHashReader`
+Use the `TabHash`
 if the first line is a header (or if missing pass in the headers
 as an array) and you want your records as hashes instead of arrays of values.
 Example:
 
 ``` ruby
-txt <<=TAB
+txt <<=TXT
 A\tB\tC
 1\t2\t3
 4\t5\t6
-TAB
+TXT
 
-records = TabHashReader.parse( txt )
+records = TabHash.parse( txt )   ## or TabHashReader
 pp records
 
 # -or-
 
-txt2 <<=TAB
+txt2 <<=TXT
 1\t2\t3
 4\t5\t6
-TAB
+TXT
 
-records = TabHashReader.parse( txt2, headers: ["A","B","C"] )
+records = TabHash.parse( txt2, headers: ["A","B","C"] )
 pp records
 
 # => [{"A": "1", "B": "2", "C": "3"},
@@ -89,14 +115,14 @@ pp records
 
 # -or-
 
-records = TabHashReader.read( "hash.tab" )
+records = TabHash.read( "hash.tab" )
 pp records
 # => [{"A": "1", "B": "2", "C": "3"},
 #     {"A": "4", "B": "5", "C": "6"}]
 
 # -or-
 
-TabHashReader.foreach( "hash.tab" ) do |rec|
+TabHash.foreach( "hash.tab" ) do |rec|
   pp rec
 end
 # => {"A": "1", "B": "2", "C": "3"}
@@ -109,11 +135,11 @@ end
 
 ## Frequently Asked Questions (FAQ) and Answers
 
-### Q: Why NOT use `CSV.read( col_sep: "\t", quote_char: "∅" )`?
+### Q: Why NOT use `Csv.read( sep: "\t" )`?
 
-Tab != CSV
+TAB != CSV
 
-The tab format is an (even) simpler format than
+The tabulator (TAB) format is an (even) simpler format than
 the comma-separated values (CSV) classic format. How?
 
 The tab format has NO escape rules.
@@ -138,23 +164,23 @@ for adding "literal" double quotes in CSV:
 
 ```
 """1""","""2""","""3"""
-4,5,"Six says, ""Hello, World!"""
+4,5,"Hamlet says, ""Seems,"" madam! Nay it is; I know not ""seems."""
 ```
 
 vs
 
 ```
 "1"→"2"→"3"
-4→5→Six says, "Hello, World!"
+4→5→Hamlet says, "Seems," madam! Nay it is; I know not "seems."
 ```
 
 Thus, to avoid any surprises, do NOT use
-`CSV.read( col_sep: "\t", quote_char: "∅" )` and friends for tab.
+`Csv.read( sep: "\t" )` and friends for tab.
 Note: Simpler also equals faster :-).
 
 
 
-### Q: What's the tab format?
+### Q: What's the tabulator (TAB) format?
 
 Let's reprint the (complete) tab spec(ification) right here
 (in an edited simpler version):

data/Rakefile

@@ -5,10 +5,10 @@ Hoe.spec 'tabreader' do
 
   self.version = TabReader::VERSION
 
-  self.summary = "tabreader - read in tabular datafiles in text in the tab format"
+  self.summary = "tabreader - read in tabular datafiles in text in the tabular (TAB) format"
   self.description = summary
 
-  self.urls = ['https://github.com/datatext/tabreader']
+  self.urls = ['https://github.com/csv11/tabreader']
 
   self.author = 'Gerald Bauer'
   self.email = 'wwwmake@googlegroups.com'
@@ -20,7 +20,7 @@ Hoe.spec 'tabreader' do
   self.licenses = ['Public Domain']
 
   self.spec_extras = {
-   :required_ruby_version => '>= 2.2.2'
+    required_ruby_version: '>= 2.2.2'
   }
 
 end

data/lib/tabreader.rb

@@ -2,15 +2,23 @@
 
 
 require 'pp'
+require 'logger'
 
 
 ###
 # our own code
+#   check: use require_relative - why? why not?
 require 'tabreader/version' # let version always go first
 require 'tabreader/reader'
+require 'tabreader/reader_hash'
 
 
 
+## add some "convenience" shortcuts
+TAB     = TabReader
+Tab     = TabReader
+TabHash = TabHashReader
+
 
 
 puts TabReader.banner   # say hello

data/lib/tabreader/reader.rb

@@ -14,124 +14,164 @@ class TabReader
 ##  todo: add  converters: e.g. strip (akk trim / ltrim / rtrim )
 
 
-def self.read( path, headers: false )
-  txt = File.open( path, 'r:utf-8' ).read
-	## puts "#{path}:"
-  ## pp txt
-  parse( txt, headers: headers )
-end
 
-def self.parse( txt, headers: false )   ## use parse_rows or parse_lines for array or array results
-   rows = []
-
-   if headers.is_a?( Array )
-     columns = headers
-   else
-     columns = nil    ## header row a.k.a. columns / fields
-   end
-
-   txt.each_line do |line|
-     values = parse_line( line )
-     if headers  ## add values as name/value pairs e.g. array of hashes
-       if columns.nil?
-         columns = values    ## first row is header row
-       else
-         ## note: will cut-off values if values.size > columns.size
-         ##   add warning/error - why? why not?
-         ##  if values.size <= columns.size will get filled-up with nil
-         pairs = columns.zip(values)
-         ## pp pairs
-         h = pairs.to_h
-         ## pp h
-
-         rows << h
-       end
-     else       ## add values as is e.g. array of array
-       rows << values
-     end
-   end
-   rows
+###################################
+## add simple logger with debug flag/switch
+#
+#  use Parser.debug = true   # to turn on
+#
+#  todo/fix: use logutils instead of std logger - why? why not?
+
+def self.build_logger()
+  l = Logger.new( STDOUT )
+  l.level = :info    ## set to :info on start; note: is 0 (debug) by default
+  l
 end
+def self.logger() @@logger ||= build_logger; end
+def logger()  self.class.logger; end
 
-def self.foreach( path, headers: false )
-  if headers.is_a?( Array )
-    columns = headers
-  else
-    columns = nil    ## header row a.k.a. columns / fields
-  end
 
-	File.open( path, 'r:utf-8' ).each_line do |line|
-		pp line
-		values = parse_line( line )
-		if headers  ## add values as name/value pairs e.g. array of hashes
-			if columns.nil?
-				columns = values    ## first row is header row
-			else
-				pairs = columns.zip(values)
-				h = pairs.to_h
-				yield( h )
-			end
-		else       ## add values as is e.g. array of array
-			yield( values )
-		end
-	end
-
-	# return nil
-	nil
-end
 
 
 def self.parse_line( line )
   ## check - can handle comments and blank lines too - why? why not?
   ## remove trailing newlines
 
+  logger.debug  "line:"             if logger.debug?
+  logger.debug line.pretty_inspect  if logger.debug?
+
+
   ##  note: chomp('') if is an empty string,
   ##    it will remove all trailing newlines from the string.
-	##    use line.sub(/[\n\r]*$/, '') or similar instead - why? why not?
-  line = line.chomp('')
+  ##    use line.sub(/[\n\r]*$/, '') or similar instead - why? why not?
+  line = line.chomp( '' )
+
+  ## line = line.strip         ## strip leading and trailing whitespaces (space/tab) too
+
+  logger.debug line.pretty_inspect    if logger.debug?
+
+#      if line.empty?             ## skip blank lines
+#        logger.debug "skip blank line"    if logger.debug?
+#        next
+#      end
+
+#      if line.start_with?( "#" )  ## skip comment lines
+#        logger.debug "skip comment line"   if logger.debug?
+#        next
+#      end
+
+  values = line.split( "\t" )
+  logger.debug values.pretty_inspect   if logger.debug?
 
-  values = line.split("\t")
   values
 end
 
-def self.header( path )
-  line =  File.open( path, 'r:utf-8' ) do |f|
-     if f.eof?
-			 ## handle empty file; return empty string; no readline call possible
-			 ##  todo/check: return nil from header is no header or [] - why? why not?
-			 ##   or throw exception  end of file reached (EOFError) - why? why not?
-			  ""
-		 else
-			 f.readline
-		 end
-  end
 
-  ## note: line includes \n or \r\n at the end
-  ## pp line
-  parse_line( line )
-end
 
-end # class TabReader
 
+def self.open( path, mode=nil, &block )   ## rename path to filename or name - why? why not?
 
+    ## note: default mode (if nil/not passed in) to 'r:bom|utf-8'
+    f = File.open( path, mode ? mode : 'r:bom|utf-8' )
+    tab = new( f )
 
+    # handle blocks like Ruby's open()
+    if block_given?
+      begin
+        block.call( tab )
+      ensure
+        tab.close
+      end
+    else
+      tab
+    end
+end # method self.open
 
-class TabHashReader
 
-def self.read( path, headers: true )
-  TabReader.read( path, headers: headers )
+def self.read( path )
+    open( path ) { |tab| tab.read }
 end
 
-def self.parse( txt, headers: true )
-  TabReader.parse( txt, headers: headers )
-end
 
-def self.foreach( path, headers: true, &block )
-  TabReader.foreach( path, headers: headers, &block )
+def self.foreach( path, &block )
+  tab = open( path )
+
+  if block_given?
+    begin
+      tab.each( &block )
+    ensure
+      tab.close
+    end
+  else
+    tab.to_enum    ## note: caller (responsible) must close file!!!
+    ## remove version without block given - why? why not?
+    ## use Tab.open().to_enum  or Tab.open().each
+    ##   or Tab.new( File.new() ).to_enum or Tab.new( File.new() ).each ???
+  end
+end # method self.foreach
+
+
+def self.parse( data, &block )
+  tab = new( data )
+
+  if block_given?
+    tab.each( &block )  ## note: caller (responsible) must close file!!! - add autoclose - why? why not?
+  else  # slurp contents, if no block is given
+    tab.read            ## note: caller (responsible) must close file!!! - add autoclose - why? why not?
+  end
+end # method self.parse
+
+
+
+## convenience helper for header (first row with column names)
+def self.header( path )   ## use header or headers - or use both (with alias)?
+  # read first lines (only)
+
+  records = []
+  open( path ) do |tab|
+    tab.each do |record|
+      records << record
+      break   ## only parse/read first record
+    end
+  end
+
+  ## unwrap record if empty return nil - why? why not?
+  ##  return empty record e.g. [] - why? why not?
+  ##  returns nil for empty (for now) - why? why not?
+  records.size == 0 ? nil : records.first
+end  # method self.header
+
+
+
+
+def initialize( data )
+  if data.is_a?( String )
+    @input = data   # note: just needs each for each_line
+  else  ## assume io
+    @input = data
+  end
 end
 
-def self.header( path )   ## add header too? why? why not?
-  TabReader.header( path )
+
+include Enumerable
+
+def each( &block )
+  if block_given?
+    @input.each_line do |line|
+
+      values = self.class.parse_line( line )
+
+      block.call( values )
+    end
+  else
+     to_enum
+  end
+end # method each
+
+def read() to_a; end # method read
+
+def close
+  @input.close   if @input.respond_to?(:close)   ## note: string needs no close
 end
 
-end # class TabHashReader
+end # class TabReader

data/lib/tabreader/reader_hash.rb

@@ -0,0 +1,111 @@
+# encoding: utf-8
+
+class TabHashReader
+
+
+def self.open( path, mode=nil, headers: nil, &block )   ## rename path to filename or name - why? why not?
+
+    ## note: default mode (if nil/not passed in) to 'r:bom|utf-8'
+    f = File.open( path, mode ? mode : 'r:bom|utf-8' )
+    tab = new(f, headers: headers )
+
+    # handle blocks like Ruby's open()
+    if block_given?
+      begin
+        block.call( tab )
+      ensure
+        tab.close
+      end
+    else
+      tab
+    end
+end # method self.open
+
+
+def self.read( path, headers: nil )
+    open( path, headers: headers ) { |tab| tab.read }
+end
+
+
+
+def self.foreach( path, headers: nil, &block )
+  tab = open( path, headers: headers)
+
+  if block_given?
+    begin
+      tab.each( &block )
+    ensure
+      tab.close
+    end
+  else
+    tab.to_enum    ## note: caller (responsible) must close file!!!
+    ## remove version without block given - why? why not?
+    ## use Tab.open().to_enum  or Tab.open().each
+    ##   or Tab.new( File.new() ).to_enum or Tab.new( File.new() ).each ???
+  end
+end # method self.foreach
+
+
+def self.parse( data, headers: nil, &block )
+  tab = new( data, headers: headers )
+
+  if block_given?
+    tab.each( &block )  ## note: caller (responsible) must close file!!! - add autoclose - why? why not?
+  else  # slurp contents, if no block is given
+    tab.read            ## note: caller (responsible) must close file!!! - add autoclose - why? why not?
+  end
+end # method self.parse
+
+
+
+
+def initialize( data, headers: nil )
+      raise ArgumentError.new( "Cannot parse nil as TAB" )  if data.nil?
+
+      if data.is_a?( String )
+        @input = data   # note: just needs each for each_line
+      else  ## assume io
+        @input = data
+      end
+
+      ## pass in headers as array e.g. ['A', 'B', 'C']
+      @names = headers ? headers : nil
+end
+
+
+
+ include Enumerable
+
+
+ def each( &block )
+
+   ## todo/fix:
+   ##   add case for headers/names.size != values.size
+   ##   - add rest option? for if less headers than values (see python csv.DictReader - why? why not?)
+   ##
+   ##   handle case with duplicate and empty header names etc.
+
+
+   if block_given?
+     TabReader.parse( @input ) do |values|
+        if @names.nil?    ## check for (first) headers row
+          @names = values   ## store header row / a.k.a. field/column names
+        else    ## "regular" record
+          record = @names.zip( values ).to_h    ## todo/fix: check for more values than names/headers!!!
+          block.call( record )
+        end
+     end
+   else
+     to_enum
+   end
+ end # method each
+
+ def read() to_a; end # method read
+
+
+ def close
+   @input.close   if @input.respond_to?(:close)   ## note: string needs no close
+ end
+
+
+end # class TabHashReader

data/lib/tabreader/version.rb

@@ -4,8 +4,8 @@
 ## note: for now TabReader is a class!!! NOT a module - change - why? why not?
 class TabReader
 
-  MAJOR = 0    ## todo: namespace inside version or something - why? why not??
-  MINOR = 1
+  MAJOR = 1    ## todo: namespace inside version or something - why? why not??
+  MINOR = 0
   PATCH = 0
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 

data/test/helper.rb

@@ -14,3 +14,7 @@ class TabReader
     "#{root}/test/data"
   end
 end
+
+
+
+TabReader.logger.level = :debug   ## turn on "global" logging

data/test/test_reader.rb

@@ -26,11 +26,9 @@ TXT
 
 puts "== parse:"
 pp TabReader.parse( txt1 )
-pp TabReader.parse( txt1, headers: true )
 
 puts "== parse:"
 pp TabReader.parse( txt2 )
-pp TabReader.parse( txt2, headers: true )
 
 puts "== parse_line:"
 pp TabReader.parse_line( "1\t2\t3" )
@@ -49,16 +47,12 @@ def test_read
 
 puts "== read:"
 pp TabReader.read( "#{TabReader.test_data_dir}/test.tab" )
-pp TabReader.read( "#{TabReader.test_data_dir}/test.tab", headers: true )
 puts "== header:"
 pp TabReader.header( "#{TabReader.test_data_dir}/test.tab" )
 puts "== foreach:"
 TabReader.foreach( "#{TabReader.test_data_dir}/test.tab" ) do |row|
   pp row
 end
-TabReader.foreach( "#{TabReader.test_data_dir}/test.tab", headers: true ) do |row|
-  pp row
-end
 end
 
 

data/test/test_reader_hash.rb

@@ -0,0 +1,60 @@
+# encoding: utf-8
+
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_reader_hash.rb
+
+
+require 'helper'
+
+class TestReader < MiniTest::Test
+
+
+def test_parse
+
+txt1 = <<TXT
+a\tb\tc
+1\t2\t3
+4\t5\t6
+TXT
+
+txt2 = <<TXT
+a	b	c	d
+1	2	3	4
+5	6	7	8
+TXT
+
+puts "== parse:"
+pp TabHashReader.parse( txt1 )
+
+puts "== parse:"
+pp TabHashReader.parse( txt2 )
+
+  assert true
+end
+
+
+def test_read
+
+puts "== read:"
+pp TabHashReader.read( "#{TabReader.test_data_dir}/test.tab" )
+puts "== foreach:"
+TabHashReader.foreach( "#{TabReader.test_data_dir}/test.tab" ) do |row|
+  pp row
+end
+end
+
+
+def test_read_empty
+
+puts "== read (empty):"
+pp TabHashReader.read( "#{TabReader.test_data_dir}/empty.tab" )
+puts "== foreach (empty):"
+TabHashReader.foreach( "#{TabReader.test_data_dir}/empty.tab" ) do |row|
+	pp row
+end
+puts "== parse (empty):"
+pp TabHashReader.parse( "" )
+end
+
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: tabreader
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 1.0.0
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2018-08-17 00:00:00.000000000 Z
+date: 2018-10-16 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rdoc
@@ -38,7 +38,7 @@ dependencies:
     - - "~>"
       - !ruby/object:Gem::Version
         version: '3.16'
-description: tabreader - read in tabular datafiles in text in the tab format
+description: tabreader - read in tabular datafiles in text in the tabular (TAB) format
 email: wwwmake@googlegroups.com
 executables: []
 extensions: []
@@ -55,12 +55,14 @@ files:
 - Rakefile
 - lib/tabreader.rb
 - lib/tabreader/reader.rb
+- lib/tabreader/reader_hash.rb
 - lib/tabreader/version.rb
 - test/data/empty.tab
 - test/data/test.tab
 - test/helper.rb
 - test/test_reader.rb
-homepage: https://github.com/datatext/tabreader
+- test/test_reader_hash.rb
+homepage: https://github.com/csv11/tabreader
 licenses:
 - Public Domain
 metadata: {}
@@ -85,5 +87,5 @@ rubyforge_project:
 rubygems_version: 2.5.2
 signing_key: 
 specification_version: 4
-summary: tabreader - read in tabular datafiles in text in the tab format
+summary: tabreader - read in tabular datafiles in text in the tabular (TAB) format
 test_files: []