dsv 0.12.4

data/lib/dsv.rb

@@ -0,0 +1,472 @@
+# dsv.rb
+# DSV
+
+# Description: Delimiter-separated values: reading and writing CSV and its relatives, tabulated data to and from files and strings, with any delimiter on either side.
+
+require 'stringio'
+
+require 'DSV/VERSION'
+require 'DSV/File'
+require 'DSV/String'
+
+class DSV
+
+  class << self
+
+    # The trailing Hash of an argument list, removed from it; or none.
+    def extract_options(args)
+      args.last.is_a?(::Hash) ? args.pop : {}
+    end
+
+    # A mode as Ruby's File spells it, from any of the spellings the library accepts, a Symbol included; unspecified is r.
+    def normalised_mode(mode)
+      case mode.to_s
+      when 'r', 'r+', 'w', 'w+', 'a', 'a+' then mode.to_s
+      when 'read_only', 'read-only', 'readonly' then 'r'
+      when 'rw', 'read_write', 'read-write', 'readwrite' then 'r+'
+      when 'write_only', 'write-only', 'writeonly' then 'w'
+      when 'append' then 'a'
+      else 'r'
+      end
+    end
+
+    def source_type(source)
+      if ::File.exist?(source)
+        DSV::File
+      else
+        DSV::String
+      end
+    end
+
+    def open(source, *args, &block)
+      csv_file = new(source, *args)
+      if block
+        begin
+          yield csv_file
+          csv_file
+        ensure
+          csv_file.close
+        end
+      else
+        csv_file
+      end
+    end
+
+    # The class-level read, parse and each take a column selection before the options, as the instance-level ones take it as arguments.
+    def each(source, *args, &block)
+      options = DSV.extract_options(args)
+      new(source, options).each(*args, &block)
+    end
+    alias_method :foreach, :each
+
+    def collect(source, *args, &block)
+      new_collection = []
+      each(source, *args){|row| new_collection << block.call(row)}
+      new_collection
+    end
+    alias_method :map, :collect
+
+    def select(source, *args, &block)
+      new_collection = []
+      each(source, *args){|row| new_collection << row if block.call(row)}
+      new_collection
+    end
+    alias_method :find_all, :select
+
+    def reject(source, *args, &block)
+      new_collection = []
+      each(source, *args){|row| new_collection << row unless block.call(row)}
+      new_collection
+    end
+
+    def detect(source, *args, &block)
+      each(source, *args){|row| return row if block.call(row)}
+      nil
+    end
+    alias_method :find, :detect
+
+    def read(source, *args, &block)
+      if block
+        parse(source, *args, &block)
+      else
+        options = DSV.extract_options(args)
+        new(source, options).read_csv(*args)
+      end
+    end
+    alias_method :read_csv, :read
+
+    def parse(source, *args, &block)
+      if block
+        each(source, *args, &block)
+      else
+        read(source, *args)
+      end
+    end
+    alias_method :parse_csv, :parse
+
+    def write(source, *args)
+      new(source, *args).write_csv
+    end
+    alias_method :write_csv, :write
+
+    # The header row as names, or nil where there is none; first_row is the raw line.
+    def header_row(source, *args)
+      new(source, *args).attributes
+    end
+
+    def first_row(source, *args)
+      new(source, *args).first_row
+    end
+
+    def attributes(source, *args)
+      new(source, *args).attributes
+    end
+
+    def columns(source, *args)
+      new(source, *args).columns
+    end
+
+    def parse_line(raw_row, *args) # For FasterCSV compatibility.
+      options = DSV.extract_options(args)
+      row_separator = options[:row_separator] || options[:row_sep] || "\n"
+      column_separator = options[:column_separator] || options[:col_sep] || ','
+      sc = DSV.new(raw_row, :quote => nil, :as_array => true, :row_separator => row_separator, :column_separator => column_separator)
+      sc.parse_row(raw_row)
+    end
+
+  end # class << self
+
+  include Enumerable
+
+  attr_accessor :header_row, :mode, :quote, :row_separator, :selected_columns, :as_array, :rows
+
+  def initialize(source, *args)
+    @source = (
+      if source.is_a?(::String)
+        DSV.source_type(source).new(source, *args).source
+      else
+        source
+      end
+    )
+    options = DSV.extract_options(args)
+    @header_row = options[:header_row] || options[:headers] || options[:header] || false
+    @mode = DSV.normalised_mode(options[:mode])
+    @quote = options[:quote] || nil
+    @row_separator = options[:row_separator] || options[:row_sep] || "\n"
+    @column_separator = options[:column_separator] || options[:col_sep] || ','
+    @selected_columns = options[:selected_columns]
+    @as_array = options[:as_array] || false
+    @render_row = row_renderer
+    if options[:columns]
+      self.columns = options[:columns]
+    else
+      self.columns
+    end
+    @rows = []
+  end
+
+  def close
+    @source.close
+  end
+
+  # A call's own selection, or the instance's selected_columns: where the call gives none.
+  def selection(selected_columns)
+    selected_columns.empty? ? Array(@selected_columns) : selected_columns
+  end
+
+  def read(*selected_columns, &block)
+    selected_columns = selection(selected_columns)
+    if block
+      parse(*selected_columns, &block)
+    else
+      read_header
+      @rows = []
+      @source.each(@row_separator){|raw_row| @rows << parse_row(complete_quoted_row(raw_row), *selected_columns)}
+      @rows
+    end
+  end
+  alias_method :read_csv, :read
+
+  def read_header
+    columns
+    if header_row?
+      (@source.rewind; @source.gets(@row_separator))
+    else
+      @source.rewind
+    end
+  end
+  alias_method :read_csv_header, :read_header
+
+  def parse(*selected_columns, &block)
+    if block
+      each(*selected_columns, &block)
+    else
+      read(*selected_columns)
+    end
+  end
+  alias_method :parse_csv, :parse
+
+  # Memoised upon whether the header has been looked for rather than upon what it gave, since a source with no header row yields nil legitimately and ||= would look again, reading and rewinding the source, on every call.
+  def columns
+    return @columns if defined?(@columns)
+    @columns = (
+      if header_row? && ['r', 'r+', 'a+'].include?(@mode) && (first_row = first_row?)
+        columns, i = {}, -1
+        split_row(first_row).each do |column_name|
+          columns[column_name] = columns.key?(column_name) ? [*columns[column_name], i += 1] : (i += 1)
+        end
+        columns
+      else
+        nil
+      end
+    )
+  end
+
+  def columns=(*column_order)
+    @columns = {}
+    @attributes = @repeated_names = nil
+    column_order.flatten!
+    if column_order[0].is_a?(Hash)
+      column_order[0].each{|column_name, column_position| @columns[column_name.to_s] = column_position}
+    else
+      i = -1
+      column_order.each{|column| @columns[column.to_s] = @columns.key?(column.to_s) ? [*@columns[column.to_s], i += 1] : (i += 1)}
+    end
+  end
+
+  # The names that occur at more than one position; under such a name a row holds an Array of values, one per position, in order.
+  def repeated_names
+    @repeated_names ||= (columns || {}).select{|name, position| position.is_a?(::Array)}.keys
+  end
+
+  # A row's value for a name, keyed for the row: assigned where the name occurs once, gathered where it repeats.
+  def store_field(parsed_row, name, value)
+    if repeated_names.include?(name)
+      (parsed_row[name] ||= []) << value
+    else
+      parsed_row[name] = value
+    end
+  end
+
+  # A row's values in position order: an Array under a repeated name is spread back over its positions, and a single value under one is written at each.
+  def values_in_order(row)
+    occurrence = ::Hash.new(0)
+    attributes.collect do |name|
+      value = row[name]
+      value = value[occurrence[name]] if value.is_a?(::Array) && repeated_names.include?(name)
+      occurrence[name] += 1
+      value
+    end
+  end
+
+  # nil or empty, which a Hash of columns, an Array of names and an unset selection all may be.
+  def blank?(value)
+    value.nil? || value.empty?
+  end
+
+  # One row into its fields, by the quote mode: :none splits; :double splits a wholly quoted row on quote-separator-quote and a wholly unquoted one plainly; unspecified splits and reassembles a quoted field that held the separator, a doubled quote inside it reading as one. Direct string operations throughout; the scanner-based parser is on the branch scanner-parser.
+  def split_row(raw_row)
+    row = raw_row.chomp(@row_separator)
+    case @quote
+    when :none, :unquoted
+      row.split(@column_separator, -1)
+    when :double, :double_quoted, :double_quotes
+      if row.start_with?('"')
+        row.delete_prefix('"').delete_suffix('"').split('"' + @column_separator + '"', -1).collect{|field| field.gsub('""', '"')}
+      else
+        row.split(@column_separator, -1)
+      end
+    else
+      reassemble_quoted_fields(row.split(@column_separator, -1))
+    end
+  end
+
+  # Pieces of a row split on the separator, the pieces of a quoted field that held the separator joined back with it; a piece that is a lone quote opens or closes a field.
+  def reassemble_quoted_fields(pieces)
+    fields = []
+    buffer = nil
+    pieces.each do |piece|
+      if buffer && !piece.end_with?('"')
+        buffer << @column_separator << piece
+      elsif buffer
+        fields << (buffer << @column_separator << piece.delete_suffix('"')).gsub('""', '"')
+        buffer = nil
+      elsif piece.start_with?('"') && (piece.length == 1 || !piece.end_with?('"'))
+        buffer = +piece.delete_prefix('"')
+      elsif piece.start_with?('"') && piece.end_with?('"')
+        fields << piece.delete_prefix('"').delete_suffix('"').gsub('""', '"')
+      else
+        fields << piece
+      end
+    end
+    fields
+  end
+
+  # A quoted field may hold the row separator: while the quotes in a row are unbalanced the next line belongs to it.
+  def complete_quoted_row(raw_row)
+    raw_row << @source.gets(@row_separator).to_s while @quote.nil? && raw_row.count('"').odd? && !@source.eof?
+    raw_row
+  end
+
+  def parse_row(raw_row, *selected_columns)
+    parsed_row = {}
+    i = -1
+    if selected_columns.empty?
+      if blank?(@columns)
+        split_row(raw_row).each{|column_value| parsed_row[i += 1] = column_value}
+      elsif repeated_names.empty?
+        split_row(raw_row).each{|column_value| parsed_row[attributes[i += 1]] = column_value}
+      else
+        split_row(raw_row).each{|column_value| store_field(parsed_row, attributes[i += 1], column_value)}
+      end
+    else
+      selected_columns.flatten!
+      case selected_columns[0]
+      when Integer
+        split_row(raw_row).each{|column_value| parsed_row[i] = column_value unless !selected_columns.include?(i += 1)}
+      else
+        split_row(raw_row).each{|column_value| store_field(parsed_row, attributes[i], column_value) unless !selected_columns.include?(attributes[i += 1])}
+      end
+    end
+    if @as_array
+      if blank?(@columns)
+        (0..(parsed_row.size - 1)).inject([]){|a,i| a << parsed_row[i]}
+      else
+        values_in_order(parsed_row)
+      end
+    else
+      parsed_row
+    end
+  end
+
+  # With no columns defined, rows keyed by name supply them, and the header, from the first row's keys; rows keyed by position write positionally and have no header to write.
+  def write(*selected_columns)
+    prepare_to_rewrite if @mode == 'r+'
+    self.columns = @rows[0].keys if blank?(columns) && @rows[0].is_a?(::Hash) && @rows[0].keys[0].is_a?(::String)
+    write_header(*selected_columns) if header_row? && attributes
+    each{|row| write_row(row, *selected_columns)}
+  end
+  alias_method :write_csv, :write
+
+  # Under r+ a write replaces the file: the rows are read first if they have not been, then the file is emptied, once, here, rather than at the end of every read.
+  def prepare_to_rewrite
+    read_csv unless @rows[0]
+    @source.rewind
+    @source.truncate(0)
+  end
+
+  def write_header(*selected_columns)
+    selected_columns.flatten!
+    names = selected_columns.empty? ? attributes : selected_columns
+    write_values(names)
+  end
+  alias_method :write_csv_header, :write_header
+
+  # A nil value is an empty field, so the columns after it keep their places; with no columns defined a row's values are written in the row's own order.
+  def write_row(row, *selected_columns)
+    selected_columns.flatten!
+    values = if !selected_columns.empty?
+               selected_columns.collect{|column| row[column]}
+             elsif attributes
+               values_in_order(row)
+             else
+               row.values
+             end
+    write_values(values)
+  end
+  alias_method :write_csv_row, :write_row
+
+  def write_values(values)
+    @source.write(@render_row.call(values))
+  end
+
+  # Chosen once from the quote mode: how a row of values is rendered, with the instance's separators, a quote inside a quoted value doubled as RFC 4180 has it. The spacey modes put a space after each separator, as Array#to_csv_row did.
+  def row_renderer
+    quote, spacey = case @quote&.to_sym
+                    when :none, :unquoted then [nil, false]
+                    when :spacey_none, :spacey_unquoted then [nil, true]
+                    when :single then ["'", false]
+                    when :spacey_single then ["'", true]
+                    when :spacey_double then ['"', true]
+                    else ['"', false]
+                    end
+    joiner = spacey ? @column_separator + ' ' : @column_separator
+    if quote
+      doubled = quote * 2
+      ->(values){values.collect{|value| quote + value.to_s.gsub(quote, doubled) + quote}.join(joiner) + @row_separator}
+    else
+      ->(values){values.join(joiner) + @row_separator}
+    end
+  end
+
+  def each(*selected_columns)
+    return to_enum(:each, *selected_columns) unless block_given?
+    selected_columns = selection(selected_columns)
+    selected_columns.flatten!
+    if @rows[0]
+      if selected_columns.empty?
+        @rows.each{|row| yield row}
+      else
+        @rows.each do |row|
+          yield selected_columns.inject({}){|hash, column_name| hash[column_name] = row[column_name]; hash}
+        end
+      end
+    else
+      if selected_columns.empty?
+        read_csv.each{|row| yield row}
+      else
+        read_csv(selected_columns).each do |row|
+          yield selected_columns.inject({}){|hash, column_name| hash[column_name] = row[column_name]; hash}
+        end
+      end
+    end
+  end
+  alias_method :each_row, :each
+
+  def attributes
+    @attributes ||= (
+      if blank?(columns)
+        nil
+      else
+        a = []
+        columns.each do |k,v|
+          case v
+          when Array
+            v.each{|e| a << [k, e]}
+          else
+            a << [k, v]
+          end
+        end
+        a.sort{|a,b| a[1] <=> b[1]}.collect{|a| a[0]}
+      end
+    )
+  end
+
+  def attributes=(attributes)
+    @attributes = attributes
+  end
+
+  def header_row?
+    @header_row
+  end
+
+  def first_row
+    @source.rewind
+    return_value = @source.gets(@row_separator)
+    @source.rewind
+    return_value
+  end
+  alias_method :first_row?, :first_row
+
+  def to_a
+    read_csv unless @rows[0]
+    if @as_array
+      @rows
+    elsif blank?(@columns)
+      @rows.collect(&:values)
+    else
+      @rows.collect{|row| values_in_order(row)}
+    end
+  end
+
+end # class DSV

data/test/VERSION_test.rb

@@ -0,0 +1,20 @@
+# test/VERSION_test.rb
+
+require_relative './helper'
+
+describe DSV do
+  describe "VERSION" do
+    it "is a string" do
+      _(DSV::VERSION).must_be_instance_of String
+    end
+
+    it "is three numbers separated by dots" do
+      _(DSV::VERSION).must_match(/\A\d+\.\d+\.\d+\z/)
+    end
+
+    it "matches the newest entry in the CHANGELOG" do
+      changelog = File.read(File.expand_path('../CHANGELOG', __dir__))
+      _(changelog[/^(\d+\.\d+\.\d+):/, 1]).must_equal(DSV::VERSION)
+    end
+  end
+end