pile 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 19ad39412c2023f5a744a424e9b940facf3002d1
+  data.tar.gz: 5fc589e24e53245e1aeab8a6674a8264cd0496f6
+SHA512:
+  metadata.gz: f07e56bc2906081397cc58329f34b78af792eab83c48c935c6537ac04eba53d4361dd0f00a65d73bf3581d441c2f8b56428cdee1945af04786668f831b49762f
+  data.tar.gz: 538ed3323cf0b90be97c0cddd29b0ae5fea8a50f96f35cd47707d58fd360db0dd8473e8a69e42a369a175fdb297fea4f8e26787d4b29854e0a935f9a3f43213b

data/Rakefile

@@ -0,0 +1,15 @@
+# encoding: utf-8
+
+require 'rspec/core/rake_task'
+require 'yard'
+require 'yard/rake/yardoc_task'
+
+desc "Run rspec with formatting"
+RSpec::Core::RakeTask.new(:test) do |t|
+  t.rspec_opts = ['--colour', '--format documentation']
+  t.pattern = '*_spec.rb'
+end
+
+desc "Generate YARD documentation"
+YARD::Rake::YardocTask.new :doc do
+end

data/lib/pile.rb

@@ -0,0 +1,3 @@
+# encoding: utf-8
+
+Dir["#{File.dirname(__FILE__)}/pile/*.rb"].each {|r| require_relative r }

data/lib/pile/header.rb

@@ -0,0 +1,116 @@
+# encoding: utf-8
+
+require 'csv'
+
+require_relative 'record'
+
+module Pile
+  # Header that contains the names of each column, used to refer to values of
+  # records by name.
+  #
+  # For example, given a CSV file containing the following header followed by
+  # multiple lines each containing a record,
+  #
+  # "ID,Name,Address Line"
+  #
+  # The parsed array from this row can be passed to +initialize+ after the
+  # +aliases+ hash, which can look like this, assuming +case_sensitive+ is
+  # false:
+  #
+  # \{'id' => ['identity', '#'], 'address line' => ['address']\}
+  class Header
+    # Construct a 'Header' from a CSV-formatted line.
+    def self.from_csv_row row, aliases = {}
+      self.new aliases, *row.parse_csv(converters: [:integer])
+    end
+
+    # @return [Hash<String, Array<String>>] aliases A hash of aliases from the column
+    #   name to an array of names that contains aliases, each of which can be
+    #   used to identify the same column.  Without case sensitivity, each key
+    #   in this hash is downcased.
+    attr_writer :aliases
+    def aliases= aliases
+      @aliases_downcased = nil
+
+      # Ensure each value is an array; create a singleton array for each one
+      # that isn't.
+      @aliases = {}
+      aliases.each_pair {|k, v| @aliases[k] = v.kind_of?(Array) ? v : [v]}
+      @aliases = aliases
+    end
+    def aliases
+      if case_sensitive
+        @aliases
+      elsif @aliases_downcased
+        @aliases_downcased
+      else
+        downcased = {}
+        @aliases.each_pair {|k, v| downcased[k.downcase] = v}
+        @aliases_downcased = downcased
+      end
+    end
+    # @param [Array<String>] indices The name of each value.  Conventionally the
+    #   first row in a CSV file.
+    attr_accessor :indices
+
+    # @return [Boolean] Whether indices are case sensitive; defaults to +false+.
+    def case_sensitive
+      @case_sensitive.nil? ? @case_sensitive = false : @case_sensitive
+    end
+    attr_writer :case_sensitive
+
+    # @return [CSV] (nil) Optional CSV object associated with this header; used
+    #   for utility functions such as +write_header+.
+    attr_accessor :csv
+
+    #
+    # @param [Hash<String, Array<String>>] aliases A hash of aliases from the column
+    #   name to an array of names that contains aliases, each of which can be
+    #   used to identify the same column.
+    # @param [Array<String>] indices The name of each value.
+    def initialize(aliases, *indices)
+      @aliases = aliases
+      @indices = indices
+    end
+
+    # Return the integer position that +i+ refers to.  This takes into
+    # account the name of each column and the alias hash.
+    def column_index i
+      if case_sensitive
+        position = indices.find_index {|column| column == i || (@aliases.has_key?(column) && @aliases[column].member?(i))}
+      else
+        position = indices.find_index {|column| column.downcase == i.to_s.downcase || (aliases.has_key?(column.downcase) && aliases[column.downcase].any? {|the_alias| the_alias.downcase == i.to_s.downcase})}
+      end
+
+      position ||= (i.kind_of?(Fixnum) ? i : nil)
+    end
+
+    # Write this header to the header's CSV object, if present.
+    #
+    # @param [CSV] csv (nil) If present, the header will be written to the
+    #   passed CSV object rather than the header's.
+    def write_header csv = nil
+      csv << indices
+    end
+
+    def ==(other)
+      self.aliases == other.aliases && self.indices == other.indices && self.csv == other.csv
+    end
+
+    def eql?(other)
+      self.aliases.eql?(other.aliases) && self.indices.eql?(other.indices) && self.csv.eql?(other.csv)
+    end
+
+    # Enumerate the record after converting to an array with +to_a+.
+    def each
+      to_a.each
+    end
+
+    # Enumerate each column header.
+    def to_a
+      indices
+    end
+
+    include Enumerable
+  end
+end

data/lib/pile/list.rb

@@ -0,0 +1,199 @@
+# encoding: utf-8
+
+require 'csv'
+require 'matrix'
+
+require_relative 'header'
+require_relative 'record'
+
+module Pile
+  # A database of +Record+s, as an array of records coupled with their header.
+  class List
+    # Construct a +List+ from the contents of a CSV-formatted file.
+    #
+    # @param [String, Array<String>] contents The contents of a file, or an
+    #   array of the lines of the file.
+    # @param [Hash<String, Array<String>>] aliases ({})
+    def self.from_string contents, aliases = {}
+      lines = contents.kind_of?(Array) ? contents : contents.lines
+      header = Header.from_csv_row lines[0], aliases
+      self.new header, lines[1..-1].map{|l| Record.from_csv_row l, header}
+    end
+
+    # Construct a +List+ from a matrix.  Inverse of +render_rows+.
+    #
+    # @param [Array<Array<String>>, Matrix<String>] matrix
+    def self.from_matrix matrix, aliases = {}
+      matrix = matrix.to_a
+      header = Header.new aliases, *(matrix[0] || [])
+      if matrix.length <= 1
+        # Header only.
+        self.new header, []
+      else
+        self.new header, matrix[1..-1].map{|row| Record.new header, *row}
+      end
+    end
+
+    # Read in filepath_from and write to filepath_to, which must refer to a
+    # different file, yielding to the block given with the header as the first
+    # argument and the record as the second; the block should return a new
+    # +Record+.
+    #
+    # The +Header+ must be the same for each +Record+, but it can be changed if
+    # the same one is returned for each record.
+    #
+    # No value is returned from this method.
+    def self.map_csv_file filepath_from, filepath_to, aliases
+      return to_enum :map_csv_file, filepath_from, filepath_to, aliases unless block_given?
+
+      # write
+      CSV.open(filepath_to, 'wb') do |csv|
+        header = nil
+        empty  = true
+
+        # read
+        CSV.foreach(filepath_from, converters: [:integer]) do |row|
+          if !header
+            # Header.
+            header = Header.new aliases, *row
+          else
+            # Record.
+            record = Record.new header, *row
+            record = yield header, record
+
+            if empty
+              empty = false
+              record.write_header csv
+            end
+
+            record.write_record csv
+          end
+        end
+
+        # We wait until we check for the first record before writing the header
+        # in case it changed.  Write the original one if there are no records.
+        if empty
+          empty = false
+          record.write_header csv
+        end
+      end
+    end
+
+    # Like +map_csv_file+, but operates on strings instead of files.
+    def self.map_csv_contents contents, aliases
+      return to_enum :map_csv_contents, contents, aliases unless block_given?
+
+      # write
+      s = CSV.generate do |csv|
+        header = nil
+        empty  = true
+
+        # read
+        CSV.parse contents, converters: [:integer] do |row|
+          if !header
+            # Header.
+            header = Header.new aliases, *row
+          else
+            # Record.
+            record = Record.new header, *row
+            record = yield header, record
+
+            if empty
+              empty = false
+              record.write_header csv
+            end
+
+            record.write_record csv
+          end
+        end
+
+        # We wait until we check for the first record before writing the header
+        # in case it changed.  Write the original one if there are no records.
+        if empty
+          empty = false
+          record.write_header csv
+        end
+      end
+    end
+
+    attr_accessor :header
+    attr_accessor :records
+
+    # @param [Pile::Header] header
+    # @param [Array<Pile::Record>] records
+    def initialize(header, records)
+      @header  = header
+      @records = records
+    end
+
+    # Map each record.
+    #
+    # The +Header+ must be the same for each +Record+, but, unlike +map+, it
+    # can be changed if the same one is returned for each record.
+    def map_records &block
+      records.map &block
+      header = records[0].header unless records.empty?
+    end
+
+    # Generate a CVS-formatted string encoding this list that can be written to
+    # a file.
+    #
+    # @return [String]
+    def csv_string
+      CSV.generate do |csv|
+        header.write_header csv
+        records.each {|r| r.write_record csv}
+      end
+    end
+
+    # Return an unwrapped matrix containing the header and each record.
+    #
+    # @return [Array<Array<String>>]
+    def render_rows
+      [header.indices, *(records.map &:values)]
+    end
+
+    # Returns a matrix containing the header and each record.
+    #
+    # @return [Matrix<String>]
+    def render_matrix
+      Matrix.rows render_rows
+    end
+
+    def ==(other)
+      self.header == other.header && self.records == other.records
+    end
+
+    def eql?(other)
+      self.header.eql?(other.aliases) && self.records.eql?(other.records)
+    end
+
+    # Enumerate the list records after converting to an array with +to_a+.
+    def each
+      to_a.each
+    end
+
+    # Enumerate each record.  Note that the header is not returned.
+    def to_a
+      records
+    end
+
+    # Send everything that the +header+ object recognized to it.  Can be used
+    # for +column_index+, etc.
+    def method_missing method, *args, &block
+      header.send method, *args, &block
+    end
+
+    include Enumerable
+
+    # When used as an array, operates on the records.
+    def [](i)
+      records[i]
+    end
+
+    # When used as an array, operates on the records.
+    def []=(i, v)
+      records[i] = v
+    end
+  end
+end

data/lib/pile/record.rb

@@ -0,0 +1,85 @@
+# encoding: utf-8
+
+require 'csv'
+
+module Pile
+  # Individual record in list of contributors, as an array of values coupled
+  # with its header.
+  #
+  # @param [Pile::Header] header The header defining the structure of
+  #   each record; used to determine the type of each entry in the record
+  #   by its position.
+  class Record
+    # Construct a 'Header' from a CSV-formatted line.
+    def self.from_csv_row row, header
+      self.new header, *row.parse_csv(converters: [:integer])
+    end
+
+    # @return [Pile::Header] The header associated with this record.
+    attr_accessor :header
+    # @return [Array<Object>] The values associated with this record.  See
+    # below for helper methods that operate on a record's values.
+    attr_accessor :values
+    # @return [CSV] An optional CSV object, which some helper methods use; e.g.
+    # see +add_record_to_csv+
+    attr_accessor :csv
+
+    # @param [Pile::Header] header The header associated with this record,
+    #   defining the structure of the record, and by what names (e.g. 'id' and
+    #   'name') values can be indexed.
+    # @param [Array<Object>] values The values in the row of the record.
+    def initialize header, *values
+      @header = header
+      @values = values
+    end
+
+    # Send everything that the +header+ object recognized to it.  Can be used
+    # for +column_index+, etc.
+    def method_missing method, *args, &block
+      header.send method, *args, &block
+    end
+
+    # Retrieve a value in the record by its position, or by the column name.
+    # Aliases are recognized.
+    def [](i)
+      values[column_index i]
+    end
+
+    # Set a value in the record by its position, or by the column name.
+    # Aliases are recognized.
+    def []=(i, v)
+      values[column_index i] = v
+    end
+
+    # Write this record to its CSV object, if present.
+    #
+    # @param [CSV] csv (nil) If present, the values will be written to the
+    #   passed CSV object rather than the header's.
+    def write_record csv = nil
+      csv ||= self.csv
+      raise 'Record#add_record_to_csv: no associated CSV object.' unless csv
+
+      csv << values
+    end
+
+    def ==(other)
+      self.header == other.header && self.values == other.values && self.csv == other.csv
+    end
+
+    def eql?(other)
+      self.header.eql?(other.header) && self.values.eql?(other.values) && self.csv.eql?(other.csv)
+    end
+
+    # Enumerate the record after converting to an array with +to_a+.
+    def each
+      to_a.each
+    end
+
+    # Enumerate each value.
+    def to_a
+      values
+    end
+
+    include Enumerable
+  end
+end

data/lib/pile/version.rb

@@ -0,0 +1,3 @@
+module Pile
+  VERSION = '0.1.0'
+end

data/spec/header_spec.rb

@@ -0,0 +1,104 @@
+# encoding: utf-8
+
+require 'csv'
+
+require_relative '../lib/pile/header.rb'
+include Pile
+
+require_relative 'spec_helper'
+
+describe Header, 'column_index' do
+  include Pile::Helpers
+
+  it 'should return the same integer indices' do
+    header = new_example_header
+
+    header.column_index(2).should == 2
+    header.column_index(0).should == 0
+  end
+
+  it 'should recognized column names' do
+    header = new_example_header
+
+    header.column_index('name').should == 1
+  end
+
+  it 'should recognize aliases' do
+    header = new_example_header
+
+    header.column_index('id').should == 0
+    header.column_index('identity').should == 0
+
+    header.column_index('address line').should == 2
+    header.column_index('address').should == 2
+  end
+
+  it 'should respect case sensitivity' do
+    header = new_example_header
+
+    header.column_index('address line').should == 2
+    header.case_sensitive = true
+    header.column_index('address line').should == nil
+    header.column_index('Address Line').should == 2
+    header.case_sensitive = false
+    header.column_index('address line').should == 2
+  end
+end
+
+describe Header, 'write_header' do
+  include Pile::Helpers
+
+  it 'writes the example header that matches our string' do
+    header = new_example_header
+
+    read_write_tempfile 'csv-spec' do |file, step|
+      case step
+      when :write
+        file.write (CSV.generate {|csv| header.write_header csv})
+      when :read
+        file.read.should == "ID,Name,Address Line\n"
+      end
+    end
+  end
+
+  it 'is the right-inverse of from_csv_row' do
+    header = new_example_header
+
+    read_write_tempfile 'csv-spec' do |file, step|
+      case step
+      when :write
+        file.write (CSV.generate {|csv| header.write_header csv})
+      when :read
+        header2 = Header.from_csv_row file.read, header.aliases
+        header2.should == header
+      end
+    end
+  end
+end
+
+describe Header, '==' do
+  include Pile::Helpers
+
+  it 'should not consider headers with different indices the same' do
+    header = new_example_header
+    header2 = new_example_header
+    header2.indices[3] = 'Country'
+
+    header2.should_not == header
+  end
+
+  it 'should not consider headers with different indices the same' do
+    header = new_example_header
+    header2 = new_example_header
+    header2.aliases['name'] = ['handle', 'nick']
+
+    header2.should_not == header
+  end
+
+  it 'should consider headers with the same indices and aliases as equal' do
+    header = new_example_header
+    header2 = new_example_header
+
+    header2.should == header
+  end
+end

data/spec/list_spec.rb

@@ -0,0 +1,92 @@
+# encoding: utf-8
+
+require_relative '../lib/pile/list.rb'
+include Pile
+
+require_relative 'spec_helper'
+
+describe List, '::map_csv_contents' do
+  include Pile::Helpers
+
+  it 'responds to mappings as we expect' do
+    file_contents = "ID,Name,Address Line\n1,Alice,123 1st St\n2,Bob,234 2nd St\n3,Charles,345 3rd St\n"
+    aliases = {'Address Line' => ['address']}
+
+    updated_contents = List.map_csv_contents file_contents, aliases do |header, record|
+      record['id'] += 1
+      record
+    end
+
+    updated_contents.should == "ID,Name,Address Line\n2,Alice,123 1st St\n3,Bob,234 2nd St\n4,Charles,345 3rd St\n"
+  end
+end
+
+describe List, '::csv_string' do
+  it 'returns the contents we expect' do
+    file_contents = example_list_csv_string
+
+    list = List.from_string file_contents
+    output = list.csv_string
+
+    list.csv_string.should == "ID,Name,Address Line\n1,Alice,123 1st St\n2,Bob,234 2nd St\n3,Charles,345 3rd St\n"
+  end
+
+  it 'is the right-inverse of from_string' do
+    list = List.from_string example_list_csv_string
+
+    read_write_tempfile 'csv-list-spec' do |file, step|
+      case step
+      when :write
+        file.write list.csv_string
+      when :read
+        list2 = List.from_string file.read
+
+        list2.should == list
+      end
+    end
+  end
+end
+
+describe List, '::render_rows' do
+  it 'returns the output we expect' do
+    file_contents = example_list_csv_string
+
+    list = List.from_string file_contents
+    output = list.render_rows
+
+    output.should == [["ID", "Name", "Address Line"], [1, "Alice", "123 1st St"], [2, "Bob", "234 2nd St"], [3, "Charles", "345 3rd St"]]
+  end
+
+  it 'is the right-inverse of from_matrix' do
+    list = List.from_string example_list_csv_string
+    list2 = List.from_matrix list.render_rows
+
+    list2.should == list
+  end
+end
+
+describe List, '::render_matrix' do
+  it 'is the right-inverse of from_matrix' do
+    list = List.from_string example_list_csv_string
+    list2 = List.from_matrix list.render_matrix
+
+    list2.should == list
+  end
+end
+
+describe List, '==' do
+  it 'should not consider lists with different headers the same' do
+    list = new_example_list
+    list2 = new_example_list
+    list2.header.indices[0] = 'ID#'
+
+    list2.should_not == list
+  end
+
+  it 'should consider lists with the same headers and records as equal' do
+    list = new_example_list
+    list2 = new_example_list
+
+    list2.should == list
+  end
+end

data/spec/record_spec.rb

@@ -0,0 +1,87 @@
+# encoding: utf-8
+
+require 'csv'
+
+require_relative '../lib/pile/record.rb'
+include Pile
+include Helpers
+
+require_relative 'spec_helper'
+
+describe Record, '[]' do
+  it 'should return the appropriate values' do
+    record = new_example_record
+
+    record[1].should         == 'Bob Smith'
+    record['name'].should    == 'Bob Smith'
+    record['address'].should == '123 1st St'
+  end
+end
+
+describe Record, '[]=' do
+  it 'should update values' do
+    record = new_example_record
+
+    record[1].should         == 'Bob Smith'
+    record['name'].should    == 'Bob Smith'
+    record['address'].should == '123 1st St'
+  end
+end
+
+describe Record, 'write_record' do
+  it 'writes the example record that matches our string' do
+    record = new_example_record
+
+    read_write_tempfile 'csv-record-spec' do |file, step|
+      case step
+      when :write
+        contents = CSV.generate do |csv|
+          record.write_header csv
+          record.write_record csv
+        end
+        file.write contents
+      when :read
+        file.read.should == "ID,Name,Address Line\n3,Bob Smith,123 1st St\n"
+      end
+    end
+  end
+
+  it 'is the right-inverse of from_csv_row' do
+    record = new_example_record
+
+    read_write_tempfile 'csv-record-spec' do |file, step|
+      case step
+      when :write
+        contents = CSV.generate do |csv|
+          record.write_header csv
+          record.write_record csv
+        end
+        file.write contents
+      when :read
+        lines = file.readlines
+
+        header2 = Header.from_csv_row lines[0], record.aliases
+        record2 = Record.from_csv_row lines[1], header2
+
+        record2.should == record
+      end
+    end
+  end
+end
+
+describe Record, '==' do
+  it 'should not consider records with different values the same' do
+    record = new_example_record
+    record2 = new_example_record
+    record2[1] = 'Bob Johnson'
+
+    record2.should_not == record
+  end
+
+  it 'should consider records with the same indices and aliases as equal' do
+    record = new_example_record
+    record2 = new_example_record
+
+    record2.should == record
+  end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,48 @@
+module Pile
+  module Helpers
+    require 'tempfile'
+
+    # Construct a new header as specified in the example in the documentation
+    # of the +Header+ class.
+    def new_example_header
+      header = Header.new ({'id' => ['identity', '#'], 'address line' => ['address']}),
+                          'ID', 'Name', 'Address Line'
+    end
+
+    # Open and close a +Tempfile+ around a block yielded to with the +Tempfile+
+    # object.
+    def with_tempfile name
+      file = Tempfile.new name
+      begin
+        yield file
+      ensure
+        file.close
+        file.unlink
+      end
+    end
+
+    # Calls the block twice: first with +:write+ as the second argument, and
+    # then second with +:read+ as the second argument.  The file is rewound to
+    # the beginning in between.
+    def read_write_tempfile name
+      with_tempfile name do |file|
+        yield file, :write
+        file.rewind
+        yield file, :read
+      end
+    end
+
+    def new_example_record
+      Record.new new_example_header, 3, 'Bob Smith', '123 1st St'
+    end
+
+    def new_example_list
+      header = new_example_header
+      List.new header, [Record.new(header), *new_example_record.values]
+    end
+
+    def example_list_csv_string
+      "ID,Name,Address Line\n1,Alice,123 1st St\n2,Bob,234 2nd St\n3,Charles,345 3rd St\n"
+    end
+  end
+end

metadata

@@ -0,0 +1,74 @@
+--- !ruby/object:Gem::Specification
+name: pile
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Byron Johnson
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2013-08-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rspec
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - '>='
+      - !ruby/object:Gem::Version
+        version: '0'
+description: pile provides classes for updating, reading, and writing CSV files that
+  consist of a header and a number of records.
+email:
+- byron@byronjohnson.net
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- Rakefile
+- lib/pile/version.rb
+- lib/pile/record.rb
+- lib/pile/list.rb
+- lib/pile/header.rb
+- lib/pile.rb
+- spec/spec_helper.rb
+- spec/record_spec.rb
+- spec/list_spec.rb
+- spec/header_spec.rb
+homepage: https://github.com/bairyn/pile
+licenses:
+- BSD3
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - '>='
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.0.6
+signing_key: 
+specification_version: 4
+summary: CSV file manipulation library.
+test_files:
+- spec/spec_helper.rb
+- spec/record_spec.rb
+- spec/list_spec.rb
+- spec/header_spec.rb
+has_rdoc: