dumb_delimited 1.1.0 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2a4d7deecbbed56e6940058fdc548436cbdb0f081b43164bc841017601c27726
-  data.tar.gz: b94ae4701ae2dec7cee54befe2e85c11ea20a9ae5906d0f7da6a8da1ef377eb6
+  metadata.gz: '049c4e61de54be67ca44c3b01d7f97fd5f1972953415ed339a14c55ec0c6d0c4'
+  data.tar.gz: 38f8e15d6a44ab8af339cf4da8e8addb232c8118ba1b8603e31deb934ca95989
 SHA512:
-  metadata.gz: 9f2994715b89523b10c4fb1375b2a073e306cedfae565f502241a4ad8f82876b1ec02d1b453641842ca331bba2812ea73783c70af7cc1431b0bbaeec83e0ce09
-  data.tar.gz: 36b9db417ddd340f695e1332ea005ad8ec03c3e8d31f5cc395b8479463497bee0e518e89f5916a90d0267ebfe9779abb21995d35e66f8da67b91f282e955b2b1
+  metadata.gz: 47aea2da44d901f3606f9e997f6024dd0413f131bec2f7f53db73863c7975a4102996f45a6eef2ffecdbf97d12c2b27132b9689dbb51f1911b1fa4f3419d9c4f
+  data.tar.gz: a4e067dccc15b8588ab721da6e12e5175be63febce3b25198178324944e60b248a1e9927c23b738beba4df6752525c451a8eeaf65553bacf79a017a069a4dbb4

data/CHANGELOG.md

@@ -1,8 +1,29 @@
+## 2.0.0
+
+* [BREAKING] Do not activate `options[:converters]` by default
+* [BREAKING] Remove *pleasant_path* dependency.  This is considered a
+  breaking change because *pleasant_path* adds extension methods to
+  several Ruby core classes that consumer code may depend on.
+* [BREAKING] Remove `append_to_file` instance method
+* [BREAKING] Rename `each_in_file` class method to `read_each`
+* Add `parse_each` class method
+* Rename `parse_file` class method to `read`, and alias as `parse_file`
+* Rename `parse_text` class method to `parse`, and alias as `parse_text`
+* Add `write` class method
+* Add `append` class method
+* Add `eol` parameter to `to_s` instance method
+* Add `DumbDelimited.csv`, `.psv`, and `.tsv` convenience shortcuts
+* Activate `options[:liberal_parsing]` by default
+* Make `options` inheritable
+* Fix behavior when `options[:headers]` is set
+* Fix behavior when `options[:write_headers]` is set
+
+
 ## 1.1.0
 
-* Fixed gem load on case-sensitive file systems.
-* Added `parse_text` class method.
-* Added `append_to_file` instance method.
+* Add `parse_text` class method
+* Add `append_to_file` instance method
+* Fix gem load on case-sensitive file systems
 
 
 ## 1.0.0

data/README.md

@@ -33,7 +33,7 @@ used as a superclass or simply assigned to a constant.
 ```ruby
 class Product < DumbDelimited[:sku, :name, :base_price, :sale_price]
   def on_sale?
-    sale_price < base_price
+    sale_price.to_f < base_price.to_f
   end
 end
 
@@ -42,57 +42,71 @@ Customer.delimiter = "|"
 ```
 
 Because "customers.psv" is pipe-delimited, we also set the delimiter
-for the Customer class.  By default, model classes use comma (`","`) as
-the delimiter.  Whenever a delimiter is set, it applies to all future
+for the Customer class.  By default, a model class uses a comma (`","`)
+as its delimiter.  Whenever a delimiter is set, it applies to all future
 IO operations for that model class.
 
-Now we can read each flat file, and recieve an array of model objects.
+Convenience shortcuts that create a model class and set its delimiter
+are also provided for a few common delimiters.  Notably,
+`DumbDelimited::psv` for a model class with a pipe (`"|"`) delimiter.
+Thus, the `Customer` class could alternatively be written as:
 
 ```ruby
-products = Product.parse_file("products.csv")
-customers = Customer.parse_file("customers.psv")
+Customer = DumbDelimited.psv(:name, :email, :address)
 ```
 
-This, however, will load the entire contents of each file into memory.
+Using our model classes, we can read each flat file, and recieve an
+array of model objects:
+
+```ruby
+products = Product.read("products.csv")
+customers = Customer.read("customers.psv")
+```
+
+However, this will load the entire contents of each file into memory.
 Let's say our customers file is very large, and we would prefer to
-iterate over it rather than load it all into memory at once.  To do so,
-we can use the `each_in_file` method that the model class provides.
-Below is a complete example in which we load our product data, create a
-listing of products on sale, and iterate over our customers, notifying
-each customer of the sale products:
+iterate over it one row at a time rather than load it all into memory at
+once.  To do so, we can use the `read_each` method.  Below is a complete
+example in which we load our product data, create a listing of products
+on sale, and iterate over our customers, notifying each customer of the
+sale products:
 
 ```ruby
-products = Product.parse_file("products.csv")
+products = Product.read("products.csv")
 
 listing = products.select(&:on_sale?).map do |product|
   "* #{product.name} (#{product.sale_price})"
 end.join("\n")
 
-Customer.each_in_file("customers.psv") do |customer|
-  message =
-    "Hi #{customer.name}!\n\n" \
-    "The following products are on sale:\n\n#{listing}"
+Customer.read_each("customers.psv") do |customer|
+  message = <<~MESSAGE
+    Hi #{customer.name}!
+
+    The following products are on sale:
+
+    #{listing}
+  MESSAGE
 
   notify(customer.email, message)
 end
 ```
 
 Let's say the sale is now over, and we want to change our sale prices
-back to our base prices.  *dumb_delimited* includes the
-[*pleasant_path*](https://rubygems.org/gems/pleasant_path) gem, which
-offers a fluent API for writing files.  To finish our task, we use the
-`Array#write_to_file` method provided by *pleasant_path*, which in turn
-invokes `Product#to_s` (provided by *dumb_delimited*) on each model
-object.
+back to our base prices.  We can load our product data, modify it
+directly, and finally persist it back with the `write` method:
 
 ```ruby
-Product.parse_file("products.csv").each do |product|
+products = Product.read("products.csv")
+
+products.each do |product|
   product.sale_price = product.base_price
-end.write_to_file("products.csv")
+end
+
+Product.write("products.csv", products)
 ```
 
 For a more detailed explanation of the *dumb_delimited* API, browse the
-[full documentation](http://www.rubydoc.info/gems/dumb_delimited/).
+[API documentation](http://www.rubydoc.info/gems/dumb_delimited/).
 
 
 ## Installation

data/dumb_delimited.gemspec

@@ -20,8 +20,6 @@ Gem::Specification.new do |spec|
   spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
   spec.require_paths = ["lib"]
 
-  spec.add_runtime_dependency "pleasant_path", "~> 1.0"
-
   spec.add_development_dependency "bundler", "~> 1.15"
   spec.add_development_dependency "rake", "~> 10.0"
   spec.add_development_dependency "minitest", "~> 5.0"

data/lib/dumb_delimited.rb

@@ -1,28 +1,29 @@
 require "csv"
-require "pleasant_path"
 require_relative "dumb_delimited/version"
 
 
 module DumbDelimited
 
   # Returns a model class for delimited data consisting of the specified
-  # columns.  The returned class inherits from Ruby's
-  # {https://ruby-doc.org/core/Struct.html +Struct+}, allowing data
-  # manipulation via accessor methods, via indexing by column name, and
-  # via indexing by column number.  See {ClassMethods} and
-  # {InstanceMethods} for the IO methods the returned class provides.
+  # +columns+.  The returned class inherits from Ruby's
+  # {https://docs.ruby-lang.org/en/trunk/Struct.html +Struct+}, allowing
+  # data manipulation via accessor methods, via indexing by column name,
+  # and via indexing by column number.  See {ClassMethods} and
+  # {InstanceMethods} for the additional methods the returned class
+  # provides.
   #
   # @example
   #   class Product < DumbDelimited[:sku, :name, :base_price, :sale_price]
   #     def on_sale?
-  #       sale_price < base_price
+  #       sale_price.to_f < base_price.to_f
   #     end
   #   end
   #
+  # @example
   #   Customer = DumbDelimited[:name, :email, :address]
   #
-  # @param columns [*Symbol]
-  # @return [Class]
+  # @param columns [Array<Symbol>]
+  # @return [Class<Struct>]
   def self.[](*columns)
     Struct.new(*columns) do
       extend DumbDelimited::ClassMethods
@@ -30,42 +31,111 @@ module DumbDelimited
     end
   end
 
+  # Convenience shortcut to create a model class and set
+  # {ClassMethods#delimiter} to +","+.
+  #
+  # Note: This method exists mostly for parity with {psv} and {tsv}.
+  # Unless +CSV::DEFAULT_OPTIONS+ has been modified, the delimiter will
+  # already default to +","+.
+  #
+  # @example
+  #   # This...
+  #   Point = DumbDelimited.csv(:x, :y, :z)
+  #
+  #   # ...is equivalent to:
+  #   Point = DumbDelimited[:x, :y, :z]
+  #   Point.delimiter = ","
+  #
+  # @param columns [Array<Symbol>]
+  # @return [Class<Struct>]
+  def self.csv(*columns)
+    klass = self[*columns]
+    klass.delimiter = ","
+    klass
+  end
+
+  # Convenience shortcut to create a model class and set
+  # {ClassMethods#delimiter} to +"|"+.
+  #
+  # @example
+  #   # This...
+  #   Point = DumbDelimited.psv(:x, :y, :z)
+  #
+  #   # ...is equivalent to:
+  #   Point = DumbDelimited[:x, :y, :z]
+  #   Point.delimiter = "|"
+  #
+  # @param columns [Array<Symbol>]
+  # @return [Class<Struct>]
+  def self.psv(*columns)
+    klass = self[*columns]
+    klass.delimiter = "|"
+    klass
+  end
+
+  # Convenience shortcut to create a model class and set
+  # {ClassMethods#delimiter} to <code>"\t"</code>.
+  #
+  # @example
+  #   # This...
+  #   Point = DumbDelimited.tsv(:x, :y, :z)
+  #
+  #   # ...is equivalent to:
+  #   Point = DumbDelimited[:x, :y, :z]
+  #   Point.delimiter = "\t"
+  #
+  # @param columns [Array<Symbol>]
+  # @return [Class<Struct>]
+  def self.tsv(*columns)
+    klass = self[*columns]
+    klass.delimiter = "\t"
+    klass
+  end
+
 end
 
 
 module DumbDelimited::ClassMethods
 
-  # Returns the advanced options Hash.  The Hash is not +dup+ed and can
-  # be modified directly.  Any modifications will be applied to all
-  # future IO operations for the model class.  For detailed information
-  # about available options, see Ruby's
-  # {http://ruby-doc.org/stdlib/libdoc/csv/rdoc/CSV.html#method-c-new
-  # CSV module}.
+  # Returns the CSV options Hash.  The Hash is not +dup+ed and can be
+  # modified directly.  Any modifications will be applied to all future
+  # IO operations for the model class.
   #
-  # @return [Hash]
+  # For detailed information about available options, see Ruby's
+  # {https://docs.ruby-lang.org/en/trunk/CSV.html#method-c-new CSV
+  # class}.
+  #
+  # @return [Hash<Symbol, Object>]
   def options
-    @options ||= {
-      col_sep: ",",
-      skip_blanks: true,
-      converters: :numeric,
-    }
+    @options ||= if superclass == Struct
+      CSV::DEFAULT_OPTIONS.merge(
+        skip_blanks: true,
+        liberal_parsing: true,
+      )
+    else
+      superclass.options.dup
+    end
   end
 
-  # Sets the advanced options Hash.  The entire Hash is replaced, and
-  # the new value will be applied to all future IO operations for the
-  # model class.  To set options individually, see {options}.  For
-  # detailed information about available options, see Ruby's
-  # {http://ruby-doc.org/stdlib/libdoc/csv/rdoc/CSV.html#method-c-new
-  # CSV module}.
+  # Sets the CSV options Hash.  The entire Hash is replaced, and the new
+  # values will be applied to all future IO operations for the model
+  # class.  To set options individually, see {options}.
   #
-  # @param o [Hash]
-  def options=(o)
-    @options = o
+  # For detailed information about available options, see Ruby's
+  # {https://docs.ruby-lang.org/en/trunk/CSV.html#method-c-new CSV
+  # class}.
+  #
+  # @param opts [Hash<Symbol, Object>]
+  # @return [Hash<Symbol, Object>]
+  def options=(opts)
+    @options = opts
   end
 
   # Returns the column delimiter used in IO operations.  Defaults to a
   # comma (<code>","</code>).
   #
+  # Equivalent to <code>options[:col_sep]</code>.
+  #
   # @return [String]
   def delimiter
     self.options[:col_sep]
@@ -76,6 +146,8 @@ module DumbDelimited::ClassMethods
   # delimiter can be safely chosen, and all IO operations will quote
   # field values as necessary.
   #
+  # Equivalent to <code>options[:col_sep] = delim</code>.
+  #
   # @example
   #   Point = DumbDelimited[:x, :y, :z]
   #   p = Point.new(1, 2, 3)
@@ -83,9 +155,10 @@ module DumbDelimited::ClassMethods
   #   Point.delimiter = "|"
   #   p.to_s  # == "1|2|3"
   #
-  # @param d [String]
-  def delimiter=(d)
-    self.options[:col_sep] = d
+  # @param delim [String]
+  # @return [String]
+  def delimiter=(delim)
+    self.options[:col_sep] = delim
   end
 
   # Parses a single delimited line into a model object.
@@ -95,34 +168,53 @@ module DumbDelimited::ClassMethods
   #   Point.parse_line("1,2,3")  # == Point.new(1, 2, 3)
   #
   # @param line [String]
-  # @return [self]
+  # @return [Struct]
   def parse_line(line)
-    self.new(*CSV.parse_line(line, self.options))
+    parse_each(line).first
   end
 
-  # Parses a string into an array of model objects.
+  # Parses a string or IO object into an array of model objects.
   #
   # @example
   #   Point = DumbDelimited[:x, :y, :z]
-  #   Point.parse_text("1,2,3\n4,5,6\n7,8,9\n")
+  #   Point.parse("1,2,3\n4,5,6\n7,8,9\n")
   #     # == [
   #     #      Point.new(1, 2, 3),
   #     #      Point.new(4, 5, 6),
   #     #      Point.new(7, 8, 9)
   #     #    ]
   #
-  # @param text [String]
-  # @return [Array<self>]
-  def parse_text(text)
-    # using CSV.new.each instead of CSV.parse to avoid unnecessary mass
-    # memory allocation and deallocation
-    CSV.new(text, self.options).each.map{|row| self.new(*row) }
+  # @param data [String, IO]
+  # @return [Array<Struct>]
+  def parse(data)
+    parse_each(data).to_a
+  end
+
+  alias_method :parse_text, :parse
+
+  # Parses a string or IO object one line at a time, yielding a model
+  # object for each line.
+  #
+  # An Enumerator is returned if no block is given.
+  #
+  # @overload parse_each(data, &block)
+  #   @param data [String, IO]
+  #   @yieldparam model [Struct]
+  #   @return [void]
+  #
+  # @overload parse_each(data)
+  #   @param data [String, IO]
+  #   @return [Enumerator<Struct>]
+  def parse_each(data, &block)
+    return to_enum(__method__, data) unless block_given?
+
+    csv_each(CSV.new(data, self.options), &block)
   end
 
-  # Parses an entire delimited file into an array of model objects.
-  # This will load the entire contents of the file into memory, and may
-  # not be suitable for large files.  To iterate over file contents
-  # without loading it all into memory at once, use {each_in_file}.
+  # Parses a file into an array of model objects.  This will load the
+  # entire contents of the file into memory, and may not be suitable for
+  # large files.  To iterate over file contents without loading it all
+  # into memory at once, use {read_each}.
   #
   # @example
   #   # CONTENTS OF FILE "points.csv":
@@ -131,7 +223,7 @@ module DumbDelimited::ClassMethods
   #   # 7,8,9
   #
   #   Point = DumbDelimited[:x, :y, :z]
-  #   Point.parse_file("points.csv")
+  #   Point.read("points.csv")
   #     # == [
   #     #      Point.new(1, 2, 3),
   #     #      Point.new(4, 5, 6),
@@ -139,27 +231,77 @@ module DumbDelimited::ClassMethods
   #     #    ]
   #
   # @param path [String, Pathname]
-  # @return [Array<self>]
-  def parse_file(path)
-    each_in_file(path).to_a
+  # @return [Array<Struct>]
+  def read(path)
+    read_each(path).to_a
   end
 
-  # Iterates over a delimited file, parsing one row at a time into model
-  # objects.  This avoids loading the entire contents of the file into
-  # memory at once.  If a block is given, it will be passed a model
-  # object for each row in the file.  Otherwise, if a block is not
-  # given, an Enumerator will be returned.  Note that some Enumerator
-  # methods, such as +Enumerator#to_a+, will cause the entire contents
-  # of the file to be loaded into memory regardless.
+  alias_method :parse_file, :read
+
+  # Parses a file one line at a time, yielding a model object for each
+  # line.  This avoids loading the entire contents of the file into
+  # memory at once.
   #
-  # @param path [String, Pathname]
-  # @yieldparam [self] current model object
-  # @return [Enumerator<self>, nil]
-  def each_in_file(path)
+  # An Enumerator is returned if no block is given.  Note that some
+  # Enumerator methods, such as +Enumerator#to_a+, can cause the entire
+  # contents of the file to be loaded into memory.
+  #
+  # @overload read_each(path, &block)
+  #   @param path [String, Pathname]
+  #   @yieldparam model [Struct]
+  #   @return [void]
+  #
+  # @overload read_each(path)
+  #   @param path [String, Pathname]
+  #   @return [Enumerator<Struct>]
+  def read_each(path, &block)
     return to_enum(__method__, path) unless block_given?
 
-    CSV.foreach(path, self.options) do |row|
-      yield self.new(*row)
+    CSV.open(path, self.options) do |csv|
+      csv_each(csv, &block)
+    end
+  end
+
+  # Writes a collection of model objects to a file in delimited format.
+  # The previous contents of the file are overwritten, unless +append+
+  # is set to true.
+  #
+  # Column headers are written to the file if +:write_headers+ in
+  # {options} is set to true *and* either +append+ is false or the file
+  # is empty / non-existent.  The column headers will be derived from
+  # either the value of +:headers+ in {options} if it is an Array, or
+  # otherwise from the columns defined by the model.
+  #
+  # @param path [String, Pathname]
+  # @param models [Enumerable<Struct>]
+  # @param append [Boolean]
+  # @return [void]
+  def write(path, models, append: false)
+    mode = append ? "a" : "w"
+    write_headers = options[:write_headers] && !(append && File.exist?(path) && File.size(path) > 0)
+    headers = (!options[:headers].is_a?(Array) && write_headers) ? members : options[:headers]
+
+    CSV.open(path, mode, **options, write_headers: write_headers, headers: headers) do |csv|
+      models.each{|model| csv << model }
+    end
+  end
+
+  # Appends a collection of model objects to a file in delimited format.
+  # Convenience shortcut for {write} with +append: true+.
+  #
+  # @param path [String, Pathname]
+  # @param models [Enumerable<Struct>]
+  # @return [void]
+  def append(path, models)
+    write(path, models, append: true)
+  end
+
+  private
+
+  def csv_each(csv, &block)
+    csv.each do |row|
+      row = row.fields if row.is_a?(CSV::Row)
+      block.call(self.new(*row))
     end
   end
 
@@ -169,33 +311,19 @@ end
 module DumbDelimited::InstanceMethods
 
   # Serializes a model object to a delimited string, using the delimiter
-  # specified by {ClassMethods.delimiter}.
+  # specified by {ClassMethods#delimiter}.  By default, the string will
+  # not end with a line terminator.  To end the string with a line
+  # terminator designated by +:row_sep+ in {ClassMethods#options}, set
+  # +eol+ to true.
   #
+  # @param eol [Boolean]
   # @return [String]
-  def to_s
-    CSV.generate_line(self, self.class.options).chomp!
-  end
+  def to_s(eol = false)
+    row_sep = eol ? self.class.options[:row_sep] : -""
 
-  # Serializes a model object to a delimited string, using the delimiter
-  # specified by {ClassMethods.delimiter}, and appends the string plus a
-  # row separator to the specified file.  Returns the model object.
-  # This method is convenient when working with single model objects,
-  # for example, appending a single entry to a log file.  However, it is
-  # not recommended for use with an array of model objects, due to the
-  # overhead of opening and closing the file for each append.
-  #
-  # @example
-  #   Point = DumbDelimited[:x, :y, :z]
-  #   Point.new(1, 2, 3).append_to_file("out.txt")  # == Point.new(1, 2, 3)
-  #   File.read("out.txt")                          # == "1,2,3\n"
-  #   Point.new(4, 5, 6).append_to_file("out.txt")  # == Point.new(4, 5, 6)
-  #   File.read("out.txt")                          # == "1,2,3\n4,5,6\n"
-  #
-  # @param file [String, Pathname]
-  # @return [self]
-  def append_to_file(file)
-    CSV.generate_line(self, self.class.options).append_to_file(file)
-    self
+    CSV.generate(**self.class.options, row_sep: row_sep, write_headers: false) do |csv|
+      csv << self
+    end
   end
 
 end

data/lib/dumb_delimited/version.rb

@@ -1,3 +1,3 @@
 module DumbDelimited
-  VERSION = "1.1.0"
+  VERSION = "2.0.0"
 end

metadata

@@ -1,29 +1,15 @@
 --- !ruby/object:Gem::Specification
 name: dumb_delimited
 version: !ruby/object:Gem::Version
-  version: 1.1.0
+  version: 2.0.0
 platform: ruby
 authors:
 - Jonathan Hefner
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2018-07-16 00:00:00.000000000 Z
+date: 2019-07-03 00:00:00.000000000 Z
 dependencies:
-- !ruby/object:Gem::Dependency
-  name: pleasant_path
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
-  type: :runtime
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - "~>"
-      - !ruby/object:Gem::Version
-        version: '1.0'
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement
@@ -116,8 +102,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubyforge_project: 
-rubygems_version: 2.7.6
+rubygems_version: 3.0.1
 signing_key: 
 specification_version: 4
 summary: Library for unsophisticated delimited flat file IO