csv 0.1.0 → 3.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
-SHA1:
-  metadata.gz: ad2099f5d8d905cf648927ecbcd076c0725ecf62
-  data.tar.gz: ae7361c59a7f61e93e4264b630966edbec9f8c5b
+SHA256:
+  metadata.gz: 878c0fd11ecaed5d4fb2ac420068c42b707a721144062ba7fe623002a13478be
+  data.tar.gz: 007c48a609bcef16dba46b8f7aca667dbdcd3cb24f05a6b7f2470726dcfeea17
 SHA512:
-  metadata.gz: dac41f73ab3bd16409e90e03d5983d5553d190c4c361361af015dfe2b85973a8219f14114552115a5ad31667e3a37280c243b5a6a5c86801c8f4250f1146a3ad
-  data.tar.gz: 309bca2a3dcdd805c9a45e83283c8ac878af4e0156277ac801d86848aeb7892228ccb7fb9adfd4845579d22d7bd51c39ab8e620e97211ec229b89828eaa2af21
+  metadata.gz: 4daffd50dd28082465a243e17f77eeb8ccd1c6727c9094eeb3f0fcaaa05426949f7e3103fa84fdad87e27e1e493365f13d4491000d8ac61a006094ff2be2602a
+  data.tar.gz: adc33341e6dd75c8d8ab343343fd8d455b7e048e081a2e22992f54397c42b3a70a4c78561fc871324b4424ed562a1fc9e59da4a12a56ff7ade2d3161195c3deb

data/LICENSE.txt

@@ -0,0 +1,33 @@
+Copyright (C) 2005-2016 James Edward Gray II. All rights reserved.
+Copyright (C) 2007-2017 Yukihiro Matsumoto. All rights reserved.
+Copyright (C) 2017 SHIBATA Hiroshi. All rights reserved.
+Copyright (C) 2017 Olivier Lacan. All rights reserved.
+Copyright (C) 2017 Espartaco Palma. All rights reserved.
+Copyright (C) 2017 Marcus Stollsteimer. All rights reserved.
+Copyright (C) 2017 pavel. All rights reserved.
+Copyright (C) 2017-2018 Steven Daniels. All rights reserved.
+Copyright (C) 2018 Tomohiro Ogoke. All rights reserved.
+Copyright (C) 2018 Kouhei Sutou. All rights reserved.
+Copyright (C) 2018 Mitsutaka Mimura. All rights reserved.
+Copyright (C) 2018 Vladislav. All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions
+are met:
+1. Redistributions of source code must retain the above copyright
+notice, this list of conditions and the following disclaimer.
+2. Redistributions in binary form must reproduce the above copyright
+notice, this list of conditions and the following disclaimer in the
+documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE AUTHOR AND CONTRIBUTORS ``AS IS'' AND
+ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+ARE DISCLAIMED.  IN NO EVENT SHALL THE AUTHOR OR CONTRIBUTORS BE LIABLE
+FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
+DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
+OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
+LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
+OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
+SUCH DAMAGE.

data/README.md

@@ -0,0 +1,52 @@
+# CSV
+
+[![Build Status](https://travis-ci.org/ruby/csv.svg?branch=master)](https://travis-ci.org/ruby/csv)
+
+This library provides a complete interface to CSV files and data. It offers tools to enable you to read and write to and from Strings or IO objects, as needed.
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'csv'
+```
+
+And then execute:
+
+    $ bundle
+
+Or install it yourself as:
+
+    $ gem install csv
+
+## Usage
+
+```ruby
+require "csv"
+
+CSV.foreach("path/to/file.csv") do |row|
+  # use row here...
+end
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake test` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and tags, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/ruby/csv.
+
+### NOTE: About RuboCop
+
+We don't use RuboCop because we can manage our coding style by ourselves. We want to accept small fluctuations in our coding style because we use Ruby.
+Please do not submit issues and PRs that aim to introduce RuboCop in this repository.
+
+## License
+
+The gem is available as open source under the terms of the [2-Clause BSD License](https://opensource.org/licenses/BSD-2-Clause).
+
+See LICENSE.txt for details.

data/lib/csv/core_ext/array.rb

@@ -0,0 +1,9 @@
+class Array # :nodoc:
+  # Equivalent to CSV::generate_line(self, options)
+  #
+  #   ["CSV", "data"].to_csv
+  #     #=> "CSV,data\n"
+  def to_csv(**options)
+    CSV.generate_line(self, options)
+  end
+end

data/lib/csv/core_ext/string.rb

@@ -0,0 +1,9 @@
+class String # :nodoc:
+  # Equivalent to CSV::parse_line(self, options)
+  #
+  #   "CSV,data".parse_csv
+  #     #=> ["CSV", "data"]
+  def parse_csv(**options)
+    CSV.parse_line(self, options)
+  end
+end

data/lib/csv/row.rb

@@ -0,0 +1,388 @@
+# frozen_string_literal: true
+
+require "forwardable"
+
+class CSV
+  #
+  # A CSV::Row is part Array and part Hash.  It retains an order for the fields
+  # and allows duplicates just as an Array would, but also allows you to access
+  # fields by name just as you could if they were in a Hash.
+  #
+  # All rows returned by CSV will be constructed from this class, if header row
+  # processing is activated.
+  #
+  class Row
+    #
+    # Construct a new CSV::Row from +headers+ and +fields+, which are expected
+    # to be Arrays.  If one Array is shorter than the other, it will be padded
+    # with +nil+ objects.
+    #
+    # The optional +header_row+ parameter can be set to +true+ to indicate, via
+    # CSV::Row.header_row?() and CSV::Row.field_row?(), that this is a header
+    # row.  Otherwise, the row is assumes to be a field row.
+    #
+    # A CSV::Row object supports the following Array methods through delegation:
+    #
+    # * empty?()
+    # * length()
+    # * size()
+    #
+    def initialize(headers, fields, header_row = false)
+      @header_row = header_row
+      headers.each { |h| h.freeze if h.is_a? String }
+
+      # handle extra headers or fields
+      @row = if headers.size >= fields.size
+        headers.zip(fields)
+      else
+        fields.zip(headers).each(&:reverse!)
+      end
+    end
+
+    # Internal data format used to compare equality.
+    attr_reader :row
+    protected   :row
+
+    ### Array Delegation ###
+
+    extend Forwardable
+    def_delegators :@row, :empty?, :length, :size
+
+    # Returns +true+ if this is a header row.
+    def header_row?
+      @header_row
+    end
+
+    # Returns +true+ if this is a field row.
+    def field_row?
+      not header_row?
+    end
+
+    # Returns the headers of this row.
+    def headers
+      @row.map(&:first)
+    end
+
+    #
+    # :call-seq:
+    #   field( header )
+    #   field( header, offset )
+    #   field( index )
+    #
+    # This method will return the field value by +header+ or +index+.  If a field
+    # is not found, +nil+ is returned.
+    #
+    # When provided, +offset+ ensures that a header match occurs on or later
+    # than the +offset+ index.  You can use this to find duplicate headers,
+    # without resorting to hard-coding exact indices.
+    #
+    def field(header_or_index, minimum_index = 0)
+      # locate the pair
+      finder = (header_or_index.is_a?(Integer) || header_or_index.is_a?(Range)) ? :[] : :assoc
+      pair   = @row[minimum_index..-1].send(finder, header_or_index)
+
+      # return the field if we have a pair
+      if pair.nil?
+        nil
+      else
+        header_or_index.is_a?(Range) ? pair.map(&:last) : pair.last
+      end
+    end
+    alias_method :[], :field
+
+    #
+    # :call-seq:
+    #   fetch( header )
+    #   fetch( header ) { |row| ... }
+    #   fetch( header, default )
+    #
+    # This method will fetch the field value by +header+. It has the same
+    # behavior as Hash#fetch: if there is a field with the given +header+, its
+    # value is returned. Otherwise, if a block is given, it is yielded the
+    # +header+ and its result is returned; if a +default+ is given as the
+    # second argument, it is returned; otherwise a KeyError is raised.
+    #
+    def fetch(header, *varargs)
+      raise ArgumentError, "Too many arguments" if varargs.length > 1
+      pair = @row.assoc(header)
+      if pair
+        pair.last
+      else
+        if block_given?
+          yield header
+        elsif varargs.empty?
+          raise KeyError, "key not found: #{header}"
+        else
+          varargs.first
+        end
+      end
+    end
+
+    # Returns +true+ if there is a field with the given +header+.
+    def has_key?(header)
+      !!@row.assoc(header)
+    end
+    alias_method :include?, :has_key?
+    alias_method :key?,     :has_key?
+    alias_method :member?,  :has_key?
+
+    #
+    # :call-seq:
+    #   []=( header, value )
+    #   []=( header, offset, value )
+    #   []=( index, value )
+    #
+    # Looks up the field by the semantics described in CSV::Row.field() and
+    # assigns the +value+.
+    #
+    # Assigning past the end of the row with an index will set all pairs between
+    # to <tt>[nil, nil]</tt>.  Assigning to an unused header appends the new
+    # pair.
+    #
+    def []=(*args)
+      value = args.pop
+
+      if args.first.is_a? Integer
+        if @row[args.first].nil?  # extending past the end with index
+          @row[args.first] = [nil, value]
+          @row.map! { |pair| pair.nil? ? [nil, nil] : pair }
+        else                      # normal index assignment
+          @row[args.first][1] = value
+        end
+      else
+        index = index(*args)
+        if index.nil?             # appending a field
+          self << [args.first, value]
+        else                      # normal header assignment
+          @row[index][1] = value
+        end
+      end
+    end
+
+    #
+    # :call-seq:
+    #   <<( field )
+    #   <<( header_and_field_array )
+    #   <<( header_and_field_hash )
+    #
+    # If a two-element Array is provided, it is assumed to be a header and field
+    # and the pair is appended.  A Hash works the same way with the key being
+    # the header and the value being the field.  Anything else is assumed to be
+    # a lone field which is appended with a +nil+ header.
+    #
+    # This method returns the row for chaining.
+    #
+    def <<(arg)
+      if arg.is_a?(Array) and arg.size == 2  # appending a header and name
+        @row << arg
+      elsif arg.is_a?(Hash)                  # append header and name pairs
+        arg.each { |pair| @row << pair }
+      else                                   # append field value
+        @row << [nil, arg]
+      end
+
+      self  # for chaining
+    end
+
+    #
+    # A shortcut for appending multiple fields.  Equivalent to:
+    #
+    #   args.each { |arg| csv_row << arg }
+    #
+    # This method returns the row for chaining.
+    #
+    def push(*args)
+      args.each { |arg| self << arg }
+
+      self  # for chaining
+    end
+
+    #
+    # :call-seq:
+    #   delete( header )
+    #   delete( header, offset )
+    #   delete( index )
+    #
+    # Used to remove a pair from the row by +header+ or +index+.  The pair is
+    # located as described in CSV::Row.field().  The deleted pair is returned,
+    # or +nil+ if a pair could not be found.
+    #
+    def delete(header_or_index, minimum_index = 0)
+      if header_or_index.is_a? Integer                 # by index
+        @row.delete_at(header_or_index)
+      elsif i = index(header_or_index, minimum_index)  # by header
+        @row.delete_at(i)
+      else
+        [ ]
+      end
+    end
+
+    #
+    # The provided +block+ is passed a header and field for each pair in the row
+    # and expected to return +true+ or +false+, depending on whether the pair
+    # should be deleted.
+    #
+    # This method returns the row for chaining.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    def delete_if(&block)
+      return enum_for(__method__) { size } unless block_given?
+
+      @row.delete_if(&block)
+
+      self  # for chaining
+    end
+
+    #
+    # This method accepts any number of arguments which can be headers, indices,
+    # Ranges of either, or two-element Arrays containing a header and offset.
+    # Each argument will be replaced with a field lookup as described in
+    # CSV::Row.field().
+    #
+    # If called with no arguments, all fields are returned.
+    #
+    def fields(*headers_and_or_indices)
+      if headers_and_or_indices.empty?  # return all fields--no arguments
+        @row.map(&:last)
+      else                              # or work like values_at()
+        all = []
+        headers_and_or_indices.each do |h_or_i|
+          if h_or_i.is_a? Range
+            index_begin = h_or_i.begin.is_a?(Integer) ? h_or_i.begin :
+                                                        index(h_or_i.begin)
+            index_end   = h_or_i.end.is_a?(Integer)   ? h_or_i.end :
+                                                        index(h_or_i.end)
+            new_range   = h_or_i.exclude_end? ? (index_begin...index_end) :
+                                                (index_begin..index_end)
+            all.concat(fields.values_at(new_range))
+          else
+            all << field(*Array(h_or_i))
+          end
+        end
+        return all
+      end
+    end
+    alias_method :values_at, :fields
+
+    #
+    # :call-seq:
+    #   index( header )
+    #   index( header, offset )
+    #
+    # This method will return the index of a field with the provided +header+.
+    # The +offset+ can be used to locate duplicate header names, as described in
+    # CSV::Row.field().
+    #
+    def index(header, minimum_index = 0)
+      # find the pair
+      index = headers[minimum_index..-1].index(header)
+      # return the index at the right offset, if we found one
+      index.nil? ? nil : index + minimum_index
+    end
+
+    # Returns +true+ if +name+ is a header for this row, and +false+ otherwise.
+    def header?(name)
+      headers.include? name
+    end
+    alias_method :include?, :header?
+
+    #
+    # Returns +true+ if +data+ matches a field in this row, and +false+
+    # otherwise.
+    #
+    def field?(data)
+      fields.include? data
+    end
+
+    include Enumerable
+
+    #
+    # Yields each pair of the row as header and field tuples (much like
+    # iterating over a Hash). This method returns the row for chaining.
+    #
+    # If no block is given, an Enumerator is returned.
+    #
+    # Support for Enumerable.
+    #
+    def each(&block)
+      return enum_for(__method__) { size } unless block_given?
+
+      @row.each(&block)
+
+      self  # for chaining
+    end
+
+    alias_method :each_pair, :each
+
+    #
+    # Returns +true+ if this row contains the same headers and fields in the
+    # same order as +other+.
+    #
+    def ==(other)
+      return @row == other.row if other.is_a? CSV::Row
+      @row == other
+    end
+
+    #
+    # Collapses the row into a simple Hash.  Be warned that this discards field
+    # order and clobbers duplicate fields.
+    #
+    def to_h
+      hash = {}
+      each do |key, _value|
+        hash[key] = self[key] unless hash.key?(key)
+      end
+      hash
+    end
+    alias_method :to_hash, :to_h
+
+    alias_method :to_ary, :to_a
+
+    #
+    # Returns the row as a CSV String.  Headers are not used.  Equivalent to:
+    #
+    #   csv_row.fields.to_csv( options )
+    #
+    def to_csv(**options)
+      fields.to_csv(options)
+    end
+    alias_method :to_s, :to_csv
+
+    #
+    # Extracts the nested value specified by the sequence of +index+ or +header+ objects by calling dig at each step,
+    # returning nil if any intermediate step is nil.
+    #
+    def dig(index_or_header, *indexes)
+      value = field(index_or_header)
+      if value.nil?
+        nil
+      elsif indexes.empty?
+        value
+      else
+        unless value.respond_to?(:dig)
+          raise TypeError, "#{value.class} does not have \#dig method"
+        end
+        value.dig(*indexes)
+      end
+    end
+
+    # A summary of fields, by header, in an ASCII compatible String.
+    def inspect
+      str = ["#<", self.class.to_s]
+      each do |header, field|
+        str << " " << (header.is_a?(Symbol) ? header.to_s : header.inspect) <<
+               ":" << field.inspect
+      end
+      str << ">"
+      begin
+        str.join('')
+      rescue  # any encoding error
+        str.map do |s|
+          e = Encoding::Converter.asciicompat_encoding(s.encoding)
+          e ? s.encode(e) : s.force_encoding("ASCII-8BIT")
+        end.join('')
+      end
+    end
+  end
+end