vfcsv 1.0.0

data/lib/vfcsv/row.rb

@@ -0,0 +1,296 @@
+# frozen_string_literal: true
+
+class VFCSV
+  # A CSV::Row-compatible class representing a single row of CSV data.
+  # Supports both header-based (Hash-like) and index-based (Array-like) access.
+  class Row
+    include Enumerable
+
+    attr_reader :row
+
+    # Create a new Row
+    # @param headers [Array] Column headers
+    # @param fields [Array] Field values
+    # @param header_row [Boolean] Whether this is a header row (default: false)
+    def initialize(headers, fields, header_row: false)
+      @row = headers.zip(fields).map { |pair| pair }
+      @header_row = header_row
+    end
+
+    # Get headers
+    # @return [Array] Column headers
+    def headers
+      @row.map(&:first)
+    end
+
+    # Get field values
+    # @return [Array] Field values
+    def fields
+      @row.map(&:last)
+    end
+    alias_method :values, :fields
+
+    # Access a field by header name or index
+    # @param header_or_index [String, Integer] Header name or column index
+    # @param minimum_index [Integer] For duplicate headers, start searching from this index
+    # @return [String, nil] Field value
+    def [](header_or_index, minimum_index = 0)
+      if header_or_index.is_a?(Integer)
+        pair = @row[header_or_index]
+        pair&.last
+      else
+        # Search by header name
+        @row.each_with_index do |(header, value), index|
+          next if index < minimum_index
+          return value if header == header_or_index
+        end
+        nil
+      end
+    end
+    alias_method :field, :[]
+
+    # Set a field by header name or index
+    # @param header_or_index [String, Integer] Header name or column index
+    # @param value [Object] New value
+    def []=(header_or_index, value)
+      if header_or_index.is_a?(Integer)
+        if @row[header_or_index]
+          @row[header_or_index][1] = value
+        end
+      else
+        @row.each do |pair|
+          if pair[0] == header_or_index
+            pair[1] = value
+            return value
+          end
+        end
+        # Header not found, add new pair
+        @row << [header_or_index, value]
+      end
+      value
+    end
+
+    # Append a field
+    # @param arg [Array] [header, value] pair
+    # @return [self]
+    def <<(arg)
+      if arg.is_a?(Array) && arg.size == 2
+        @row << arg.dup
+      else
+        @row << [nil, arg]
+      end
+      self
+    end
+
+    # Push a header and value
+    # @param header [String] Header name
+    # @param value [Object] Field value
+    # @return [self]
+    def push(header, value)
+      @row << [header, value]
+      self
+    end
+
+    # Delete a field by header or index
+    # @param header_or_index [String, Integer] Header name or index
+    # @return [Array, nil] Deleted [header, value] pair
+    def delete(header_or_index)
+      if header_or_index.is_a?(Integer)
+        @row.delete_at(header_or_index)
+      else
+        index = @row.index { |pair| pair[0] == header_or_index }
+        index ? @row.delete_at(index) : nil
+      end
+    end
+
+    # Delete fields matching a condition
+    # @yield [header, value] Block that returns true for fields to delete
+    # @return [self]
+    def delete_if(&block)
+      @row.delete_if { |pair| block.call(*pair) }
+      self
+    end
+
+    # Iterate over header/value pairs
+    # @yield [header, value]
+    # @return [Enumerator] if no block given
+    def each(&block)
+      return to_enum(__method__) unless block_given?
+      @row.each { |pair| block.call(*pair) }
+      self
+    end
+    alias_method :each_pair, :each
+
+    # Check if row is empty
+    # @return [Boolean]
+    def empty?
+      @row.empty?
+    end
+
+    # Get number of fields
+    # @return [Integer]
+    def size
+      @row.size
+    end
+    alias_method :length, :size
+
+    # Fetch a field with optional default
+    # @param header_or_index [String, Integer] Header or index
+    # @param default [Object] Default value if not found
+    # @yield Block to call if not found
+    # @return [Object] Field value or default
+    def fetch(header_or_index, *args, &block)
+      value = self[header_or_index]
+      return value unless value.nil?
+
+      # Check if header actually exists with nil value
+      found = if header_or_index.is_a?(Integer)
+        header_or_index >= 0 && header_or_index < @row.size
+      else
+        @row.any? { |pair| pair[0] == header_or_index }
+      end
+
+      return value if found
+
+      if block_given?
+        block.call(header_or_index)
+      elsif args.size > 0
+        args[0]
+      else
+        raise KeyError, "key not found: #{header_or_index.inspect}"
+      end
+    end
+
+    # Check if a value exists in the fields
+    # @param value [Object] Value to find
+    # @return [Boolean]
+    def field?(value)
+      fields.include?(value)
+    end
+    alias_method :include?, :field?
+    alias_method :member?, :field?
+
+    # Check if a header exists
+    # @param header [String] Header to find
+    # @return [Boolean]
+    def header?(header)
+      headers.include?(header)
+    end
+    alias_method :has_key?, :header?
+    alias_method :key?, :header?
+
+    # Find index of a header or value
+    # @param header [String] Header to find
+    # @param minimum_index [Integer] Start index
+    # @return [Integer, nil]
+    def index(header, minimum_index = 0)
+      @row.each_with_index do |(h, _v), i|
+        next if i < minimum_index
+        return i if h == header
+      end
+      nil
+    end
+
+    # Dig into nested data
+    # @param index_or_header [Integer, String] First key
+    # @param identifiers [Array] Additional keys for nested access
+    # @return [Object]
+    def dig(index_or_header, *identifiers)
+      value = self[index_or_header]
+      return nil if value.nil?
+      return value if identifiers.empty?
+
+      if value.respond_to?(:dig)
+        value.dig(*identifiers)
+      else
+        nil
+      end
+    end
+
+    # Get values at specified indices or headers
+    # @param indices_or_headers [Array] List of indices or headers
+    # @return [Array] Values at specified positions
+    def values_at(*indices_or_headers)
+      indices_or_headers.map { |i| self[i] }
+    end
+
+    # Check if this is a header row
+    # @return [Boolean]
+    def header_row?
+      @header_row
+    end
+
+    # Check if this is a field (data) row
+    # @return [Boolean]
+    def field_row?
+      !@header_row
+    end
+
+    # Compare with another row
+    # @param other [Row] Other row
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Row)
+      @row == other.row
+    end
+
+    # Convert to hash
+    # @return [Hash]
+    def to_h
+      result = {}
+      @row.each { |header, value| result[header] = value }
+      result
+    end
+    alias_method :to_hash, :to_h
+
+    # Convert to array of [header, value] pairs
+    # @return [Array<Array>]
+    def to_a
+      @row.map(&:dup)
+    end
+
+    # Allow implicit conversion to array (for splat operations)
+    # @return [Array] Field values only
+    def to_ary
+      fields
+    end
+
+    # Convert to CSV string
+    # @return [String]
+    def to_csv(**options)
+      col_sep = options[:col_sep] || ","
+      quote_char = options[:quote_char] || '"'
+      row_sep = options[:row_sep]
+      row_sep = "\n" if row_sep.nil? || row_sep == :auto
+
+      field_strings = fields.map do |field|
+        field_str = field.to_s
+        if needs_quoting?(field_str, col_sep, quote_char)
+          quote_field(field_str, quote_char)
+        else
+          field_str
+        end
+      end
+
+      field_strings.join(col_sep) + row_sep
+    end
+    alias_method :to_s, :to_csv
+
+    # Inspection string
+    # @return [String]
+    def inspect
+      "#<#{self.class} #{to_h.inspect}>"
+    end
+
+    private
+
+    def needs_quoting?(str, col_sep, quote_char)
+      str.include?(col_sep) || str.include?(quote_char) || str.include?("\n") || str.include?("\r")
+    end
+
+    def quote_field(str, quote_char)
+      escaped = str.gsub(quote_char, quote_char + quote_char)
+      "#{quote_char}#{escaped}#{quote_char}"
+    end
+  end
+end

data/lib/vfcsv/table.rb

@@ -0,0 +1,270 @@
+# frozen_string_literal: true
+
+class VFCSV
+  # A CSV::Table-compatible class representing a collection of CSV rows.
+  # Supports multiple access modes: :row, :col, and :col_or_row (default).
+  class Table
+    include Enumerable
+
+    attr_reader :table, :mode
+
+    # Create a new Table
+    # @param rows [Array<Row>] Array of Row objects
+    # @param headers [Array] Column headers (optional, derived from first row if not provided)
+    def initialize(rows = [], headers: nil)
+      @table = rows
+      @headers = headers || (rows.first&.headers || [])
+      @mode = :col_or_row
+    end
+
+    # Get column headers
+    # @return [Array]
+    def headers
+      @headers.dup
+    end
+
+    # Access rows or columns depending on mode
+    # @param index_or_header [Integer, String] Row index or column header
+    # @return [Row, Array] Row object or array of column values
+    def [](index_or_header)
+      case @mode
+      when :row
+        @table[index_or_header]
+      when :col
+        column_values(index_or_header)
+      when :col_or_row
+        if index_or_header.is_a?(Integer)
+          @table[index_or_header]
+        else
+          column_values(index_or_header)
+        end
+      end
+    end
+
+    # Set row or column value depending on mode
+    # @param index_or_header [Integer, String] Row index or column header
+    # @param value [Row, Array] New row or column values
+    def []=(index_or_header, value)
+      case @mode
+      when :row
+        @table[index_or_header] = value
+      when :col
+        set_column(index_or_header, value)
+      when :col_or_row
+        if index_or_header.is_a?(Integer)
+          @table[index_or_header] = value
+        else
+          set_column(index_or_header, value)
+        end
+      end
+    end
+
+    # Append a row
+    # @param row [Row, Array] Row to append
+    # @return [self]
+    def <<(row)
+      if row.is_a?(Row)
+        @table << row
+      else
+        @table << Row.new(@headers, row)
+      end
+      self
+    end
+    alias_method :push, :<<
+
+    # Delete a row or column
+    # @param index_or_header [Integer, String] Row index or column header
+    # @return [Row, Array, nil] Deleted row or column values
+    def delete(index_or_header)
+      case @mode
+      when :row
+        @table.delete_at(index_or_header)
+      when :col
+        delete_column(index_or_header)
+      when :col_or_row
+        if index_or_header.is_a?(Integer)
+          @table.delete_at(index_or_header)
+        else
+          delete_column(index_or_header)
+        end
+      end
+    end
+
+    # Delete rows/columns matching condition
+    # @yield [row_or_col] Block that returns true for items to delete
+    # @return [self]
+    def delete_if(&block)
+      @table.delete_if(&block)
+      self
+    end
+
+    # Iterate over rows
+    # @yield [Row]
+    # @return [Enumerator] if no block given
+    def each(&block)
+      return to_enum(__method__) unless block_given?
+      @table.each(&block)
+      self
+    end
+
+    # Check if table is empty
+    # @return [Boolean]
+    def empty?
+      @table.empty?
+    end
+
+    # Get number of rows
+    # @return [Integer]
+    def size
+      @table.size
+    end
+    alias_method :length, :size
+
+    # Dig into nested data
+    # @param index [Integer] Row index
+    # @param args [Array] Additional keys
+    # @return [Object]
+    def dig(index, *args)
+      row = @table[index]
+      return nil if row.nil?
+      return row if args.empty?
+      row.dig(*args)
+    end
+
+    # Get rows at specified indices
+    # @param indices [Array<Integer>] Row indices
+    # @return [Array<Row>]
+    def values_at(*indices)
+      indices.map { |i| @table[i] }
+    end
+
+    # Switch to row access mode (returns new table with mode set)
+    # @return [Table]
+    def by_row
+      dup_with_mode(:row)
+    end
+
+    # Switch to row access mode (mutates self)
+    # @return [self]
+    def by_row!
+      @mode = :row
+      self
+    end
+
+    # Switch to column access mode (returns new table with mode set)
+    # @return [Table]
+    def by_col
+      dup_with_mode(:col)
+    end
+
+    # Switch to column access mode (mutates self)
+    # @return [self]
+    def by_col!
+      @mode = :col
+      self
+    end
+
+    # Switch to column-or-row access mode (returns new table with mode set)
+    # @return [Table]
+    def by_col_or_row
+      dup_with_mode(:col_or_row)
+    end
+
+    # Switch to column-or-row access mode (mutates self)
+    # @return [self]
+    def by_col_or_row!
+      @mode = :col_or_row
+      self
+    end
+
+    # Compare with another table
+    # @param other [Table] Other table
+    # @return [Boolean]
+    def ==(other)
+      return false unless other.is_a?(Table)
+      @table == other.table && @headers == other.headers
+    end
+
+    # Convert to array (includes headers as first row)
+    # @return [Array<Array>]
+    def to_a
+      [@headers] + @table.map(&:fields)
+    end
+
+    # Convert to CSV string
+    # @param options [Hash] CSV options
+    # @return [String]
+    def to_csv(**options)
+      write_headers = options.fetch(:write_headers, true)
+      col_sep = options[:col_sep] || ","
+      quote_char = options[:quote_char] || '"'
+      row_sep = options[:row_sep]
+      row_sep = "\n" if row_sep.nil? || row_sep == :auto
+
+      result = +""
+
+      if write_headers
+        result << generate_line(@headers, col_sep, quote_char, row_sep)
+      end
+
+      @table.each do |row|
+        result << generate_line(row.fields, col_sep, quote_char, row_sep)
+      end
+
+      result
+    end
+    alias_method :to_s, :to_csv
+
+    # Inspection string
+    # @return [String]
+    def inspect
+      "#<#{self.class} mode:#{@mode} row_count:#{size}>"
+    end
+
+    private
+
+    def column_values(header)
+      @table.map { |row| row[header] }
+    end
+
+    def set_column(header, values)
+      @table.each_with_index do |row, i|
+        row[header] = values[i] if values[i]
+      end
+    end
+
+    def delete_column(header)
+      values = column_values(header)
+      @table.each { |row| row.delete(header) }
+      @headers.delete(header)
+      values
+    end
+
+    def dup_with_mode(new_mode)
+      new_table = self.class.new(@table.dup, headers: @headers.dup)
+      new_table.instance_variable_set(:@mode, new_mode)
+      new_table
+    end
+
+    def generate_line(row, col_sep, quote_char, row_sep)
+      fields = row.map do |field|
+        field_str = field.to_s
+        if needs_quoting?(field_str, col_sep, quote_char)
+          quote_field(field_str, quote_char)
+        else
+          field_str
+        end
+      end
+      fields.join(col_sep) + row_sep
+    end
+
+    def needs_quoting?(str, col_sep, quote_char)
+      str.include?(col_sep) || str.include?(quote_char) || str.include?("\n") || str.include?("\r")
+    end
+
+    def quote_field(str, quote_char)
+      escaped = str.gsub(quote_char, quote_char + quote_char)
+      "#{quote_char}#{escaped}#{quote_char}"
+    end
+  end
+end

data/lib/vfcsv/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+class VFCSV
+  VERSION = "1.0.0"
+end