strong_csv 0.3.0 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: a367df39ccd195cbb7f62845c919f9718a4ef536de595294991fa7bc26693ca7
-  data.tar.gz: 220e1d69c32123c78d5a31cb63d2c9c21686bbe76feb68e4f0aeb9762601e0e3
+  metadata.gz: 109d3d3c31812aedff005dc2003a8066d20a551513f0d287c0ba761a9469ac04
+  data.tar.gz: 11a3cd4890a60b27231276d09bcdc05fb29487c100fdbc6afff8cc7febf58694
 SHA512:
-  metadata.gz: bfe0ecbb668a07be731f9f50143812fc42d213993b4e3591e04678a4c6323347f69f18a6241d4dbfa524faa37baada63c7ffc0ab394073c1f435c914910f5d95
-  data.tar.gz: d345d0c12929b60d801c16e8d994fa1570f0e5fc2034f6d74de3f96bf188a7a0e85f7b9c2b1bbe61a1a0f4e4cdb4a41deddf7915cbeb540ace4b0c790c5056b0
+  metadata.gz: 6dd9abc5eb9a9b30f655ed13eae0e699c0471b09196ba5bc8ef265e06056ecf9bce526308f6a1edb28ff7d57ae9e5023e52b9e6bc827021cf186a8a62108026a
+  data.tar.gz: 3e9d411ab432f498639c8532b46be1d52e734188c48089b565a32398b690e8ceed1255b40adcc80ebc3d21256782f186576d7dd5cf8346f88b43fa6c2489ebfd

data/README.md

@@ -2,8 +2,6 @@
 
 <a href="https://rubygems.org/gems/strong_csv"><img alt="strong_csv" src="https://img.shields.io/gem/v/strong_csv"></a>
 
-NOTE: This repository is still under development 🚧🚜🚧
-
 Type checker for a CSV file inspired by [strong_json](https://github.com/soutaro/strong_json).
 
 ## Motivation
@@ -78,8 +76,6 @@ strong_csv = StrongCSV.new do
     end
   end
 
-  # TODO: The followings are not implemented so far.
-
   # Regular expressions
   let :url, %r{\Ahttps://}
 
@@ -105,12 +101,30 @@ strong_csv.parse(data, field_size_limit: 2048) do |row|
     row[:active] # => true
     # do something with row
   else
-    row.errors # => { user_id: ["must be present", "must be an integer"] }
+    row.errors # => { user_id: ["`nil` can't be casted to Integer"] }
     # do something with row.errors
   end
 end
 ```
 
+You can also define types without CSV headers by specifying column numbers.
+Note the numbers must start from `0` (zero-based index).
+
+```ruby
+StrongCSV.new do
+  let 0, integer
+  let 1, string
+  let 2, 1..10
+end
+```
+
+This declaration expects a CSV has the contents like this:
+
+```csv
+123,abc,3
+830,mno,10
+```
+
 ## Available types
 
 <table>
@@ -158,6 +172,10 @@ end
         <td><a href="#literal"><code>"abc"</code> (String literal)</a></td>
         <td>The value must be casted to the specific <code>String</code> literal.</td>
     </tr>
+    <tr>
+        <td><a href="#literal"><code>%r{\Ahttps://}</code> (Regexp literal)</a></td>
+        <td>The value must be casted to a <code>String</code> that matches the specified Regexp.</td>
+    </tr>
     <tr>
         <td><a href="#union"><code>,</code> (Union type)</a></td>
         <td>The value must satisfy one of the subtypes.</td>
@@ -167,7 +185,7 @@ end
 ### `integer` and `integer?`
 
 The value must be casted to Integer. `integer?` allows the value to be `nil`, so you can declare optional integer type
-for columns.
+for columns. It also lets you allow values that satisfy the specified limitation through `:constraint`.
 
 _Example_
 
@@ -175,25 +193,30 @@ _Example_
 strong_csv = StrongCSV.new do
   let :stock, integer
   let :state, integer?
+  let :user_id, integer(constraint: ->(v) { user_ids.include?(v)})
+  pick :user_id, as: :user_ids do |values|
+    User.where(id: values).ids
+  end
 end
 
 result = strong_csv.parse(<<~CSV)
-  stock,state
-  12,0
-  20,
-  non-integer,1
+  stock,state,user_id
+  12,0,1
+  20,,2
+  non-integer,1,4
 CSV
 
 result.map(&:valid?) # => [true, true, false]
-result[0].slice(:stock, :state) # => {:stock=>12, :state=>0}
-result[1].slice(:stock, :state) # => {:stock=>20, :state=>nil}
-result[2].slice(:stock, :state) # => {:stock=>"non-integer", :state=>1} ("non-integer" cannot be casted to Integer)
+result[0].slice(:stock, :state, :user_id) # => {:stock=>12, :state=>0, :user_id=>1}
+result[1].slice(:stock, :state, :user_id) # => {:stock=>20, :state=>nil, :user_id=>2}
+result[2].slice(:stock, :state, :user_id) # => {:stock=>"non-integer", :state=>1, :user_id=>"4"}
+result[2].errors.slice(:stock, :user_id) # => {:stock=>["`\"non-integer\"` can't be casted to Integer"], :user_id=>["`\"4\"` does not satisfy the specified constraint"]}
 ```
 
 ### `float` and `float?`
 
 The value must be casted to Float. `float?` allows the value to be `nil`, so you can declare optional float type for
-columns.
+columns. It also lets you allow values that satisfy the specified limitation through `:constraint`.
 
 _Example_
 
@@ -338,18 +361,19 @@ strong_csv = StrongCSV.new do
   let 1, "test"
   let 2, 2.5
   let 3, 1..10
+  let 4, /[a-z]+/
 end
 
 result = strong_csv.parse(<<~CSV)
-  123,test,2.5,9
-  123,test,2.5,0
-  123,Hey,2.5,10
+  123,test,2.5,9,abc
+  123,test,2.5,0,xyz
+  123,Hey,2.5,10,!
 CSV
 
 result.map(&:valid?) # => [true, false, false]
-result[0].slice(0, 1, 2, 3) # => {0=>123, 1=>"test", 2=>2.5, 3=>9}
-result[1].slice(0, 1, 2, 3) # => {0=>123, 1=>"test", 2=>2.5, 3=>"0"} (0 is out of 1..10)
-result[2].slice(0, 1, 2, 3) # => {0=>123, 1=>"Hey", 2=>2.5, 3=>10} ("Hey" is not equal to "test")
+result[0].slice(0, 1, 2, 3, 4) # => {0=>123, 1=>"test", 2=>2.5, 3=>9, 4=>"abc"}
+result[1].slice(0, 1, 2, 3, 4) # => {0=>123, 1=>"test", 2=>2.5, 3=>"0", 4=>"xyz"} (0 is out of 1..10)
+result[2].slice(0, 1, 2, 3, 4) # => {0=>123, 1=>"Hey", 2=>2.5, 3=>10, 4=>"!"} ("Hey" is not equal to "test", and "!" does not match /[a-z]+/)
 ```
 
 ### Union
@@ -391,8 +415,10 @@ ja:
       cant_be_casted: "`%{value}`はBooleanに変換できません"
     float:
       cant_be_casted: "`%{value}`はFloatに変換できません"
+      constraint_error: "`%{value}`は指定された成約を満たしていません",
     integer:
       cant_be_casted: "`%{value}`はIntegerに変換できません"
+      constraint_error: "`%{value}`は指定された成約を満たしていません",
     literal:
       integer:
         unexpected: "`%{expected}`ではなく`%{value}`が入力されています"
@@ -405,6 +431,9 @@ ja:
       range:
         cant_be_casted: "`%{value}`は`%{expected}`の始端に変換できません"
         out_of_range: "`%{value}`は`%{range}`の範囲外です"
+      regexp:
+        cant_be_casted: "`%{value}`はStringに変換できません"
+        unexpected: "`%{value}`は`%{expected}`とマッチしませんでした"
     string:
       cant_be_casted: "`%{value}`はStringに変換できません"
       out_of_range: "`%{value}`の文字数は`%{range}`の範囲外です"

data/lib/strong_csv/i18n.rb

@@ -8,9 +8,11 @@ I18n.backend.store_translations(
       },
       float: {
         cant_be_casted: "`%{value}` can't be casted to Float",
+        constraint_error: "`%{value}` does not satisfy the specified constraint",
       },
       integer: {
         cant_be_casted: "`%{value}` can't be casted to Integer",
+        constraint_error: "`%{value}` does not satisfy the specified constraint",
       },
       literal: {
         integer: {
@@ -28,6 +30,10 @@ I18n.backend.store_translations(
           cant_be_casted: "`%{value}` can't be casted to the beginning of `%{expected}`",
           out_of_range: "`%{value}` is not within `%{range}`",
         },
+        regexp: {
+          cant_be_casted: "`%{value}` can't be casted to String",
+          unexpected: "`%{value}` did not match `%{expected}`",
+        },
       },
       string: {
         cant_be_casted: "`%{value}` can't be casted to String",

data/lib/strong_csv/let.rb

@@ -9,9 +9,14 @@ class StrongCSV
     # @return [Boolean]
     attr_reader :headers
 
+    # @return [Hash]
+    attr_reader :pickers
+
     def initialize
       @types = {}
       @headers = false
+      @pickers = {}
+      @picked = {}
     end
 
     # @param name [String, Symbol, Integer]
@@ -30,12 +35,35 @@ class StrongCSV
       validate_columns
     end
 
-    def integer
-      Types::Integer.new
+    # #pick is intended for defining a singleton method with `:as`.
+    # This might be useful for the case where you want to receive IDs that are stored in a database,
+    # and you want to make sure the IDs actually exist.
+    #
+    # @example
+    #  pick :user_id, as: :user_ids do |user_ids|
+    #    User.where(id: user_ids).ids
+    #  end
+    #
+    # @param column [Symbol, Integer]
+    # @param as [Symbol]
+    # @yieldparam values [Array<String>] The values for the column. NOTE: This is an array of String, not casted values.
+    def pick(column, as:, &block)
+      define_singleton_method(as) do
+        @picked[as]
+      end
+      @pickers[as] = lambda do |csv|
+        @picked[as] = block.call(csv.map { |row| row[column] })
+      end
     end
 
-    def integer?
-      optional(integer)
+    # @param options [Hash] See `Types::Integer#initialize` for more details.
+    def integer(**options)
+      Types::Integer.new(**options)
+    end
+
+    # @param options [Hash] See `Types::Integer#initialize` for more details.
+    def integer?(**options)
+      optional(integer(**options))
     end
 
     def boolean
@@ -46,12 +74,14 @@ class StrongCSV
       optional(boolean)
     end
 
-    def float
-      Types::Float.new
+    # @param options [Hash] See `Types::Float#initialize` for more details.
+    def float(**options)
+      Types::Float.new(**options)
     end
 
-    def float?
-      optional(float)
+    # @param options [Hash] See `Types::Float#initialize` for more details.
+    def float?(**options)
+      optional(float(**options))
     end
 
     # @param options [Hash] See `Types::String#initialize` for more details.
@@ -59,6 +89,7 @@ class StrongCSV
       Types::String.new(**options)
     end
 
+    # @param options [Hash] See `Types::String#initialize` for more details.
     def string?(**options)
       optional(string(**options))
     end
@@ -68,6 +99,7 @@ class StrongCSV
       Types::Time.new(**options)
     end
 
+    # @param options [Hash] See `Types::Time#initialize` for more details.
     def time?(**options)
       optional(time(**options))
     end

data/lib/strong_csv/row.rb

@@ -28,6 +28,9 @@ class StrongCSV
       end
     end
 
+    # It returns true if the row has no errors.
+    #
+    # @return [Boolean]
     def valid?
       @errors.empty?
     end

data/lib/strong_csv/types/float.rb

@@ -4,11 +4,25 @@ class StrongCSV
   module Types
     # Float type
     class Float < Base
+      DEFAULT_CONSTRAINT = ->(_) { true }
+      private_constant :DEFAULT_CONSTRAINT
+
+      # @param constraint [Proc]
+      def initialize(constraint: DEFAULT_CONSTRAINT)
+        super()
+        @constraint = constraint
+      end
+
       # @todo Use :exception for Float after we drop the support of Ruby 2.5
       # @param value [Object] Value to be casted to Float
       # @return [ValueResult]
       def cast(value)
-        ValueResult.new(value: Float(value), original_value: value)
+        float = Float(value)
+        if @constraint.call(float)
+          ValueResult.new(value: float, original_value: value)
+        else
+          ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.float.constraint_error", value: value.inspect, default: :"_strong_csv.float.constraint_error")])
+        end
       rescue ArgumentError, TypeError
         ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.float.cant_be_casted", value: value.inspect, default: :"_strong_csv.float.cant_be_casted")])
       end

data/lib/strong_csv/types/integer.rb

@@ -4,11 +4,25 @@ class StrongCSV
   module Types
     # Integer type
     class Integer < Base
+      DEFAULT_CONSTRAINT = ->(_) { true }
+      private_constant :DEFAULT_CONSTRAINT
+
+      # @param constraint [Proc]
+      def initialize(constraint: DEFAULT_CONSTRAINT)
+        super()
+        @constraint = constraint
+      end
+
       # @todo Use :exception for Integer after we drop the support of Ruby 2.5
       # @param value [Object] Value to be casted to Integer
       # @return [ValueResult]
       def cast(value)
-        ValueResult.new(value: Integer(value), original_value: value)
+        int = Integer(value)
+        if @constraint.call(int)
+          ValueResult.new(value: int, original_value: value)
+        else
+          ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.integer.constraint_error", value: value.inspect, default: :"_strong_csv.integer.constraint_error")])
+        end
       rescue ArgumentError, TypeError
         ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.integer.cant_be_casted", value: value.inspect, default: :"_strong_csv.integer.cant_be_casted")])
       end

data/lib/strong_csv/types/literal.rb

@@ -72,6 +72,20 @@ class StrongCSV
           end
         end
       end
+
+      refine ::Regexp do
+        # @param value [Object] Value to be casted to String
+        # @return [ValueResult]
+        def cast(value)
+          return ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.literal.regexp.cant_be_casted", value: value.inspect, default: :"_strong_csv.literal.regexp.cant_be_casted")]) if value.nil?
+
+          if self =~ value
+            ValueResult.new(value: value, original_value: value)
+          else
+            ValueResult.new(original_value: value, error_messages: [I18n.t("strong_csv.literal.regexp.unexpected", value: value.inspect, expected: inspect, default: :"_strong_csv.literal.regexp.unexpected")])
+          end
+        end
+      end
     end
   end
 end

data/lib/strong_csv/value_result.rb

@@ -1,7 +1,7 @@
 # frozen_string_literal: true
 
 class StrongCSV
-  # ValueResult represents a CSV field is valid or not and contains its casted value if it's valid.
+  # ValueResult represents whether a CSV field is valid or not, and contains its casted value if it's valid.
   class ValueResult
     DEFAULT_VALUE = Object.new
     private_constant :DEFAULT_VALUE
@@ -15,11 +15,13 @@ class StrongCSV
       @error_messages = error_messages
     end
 
-    # @return [Object] The casted value if it's valid. Otherwise, returns the original value.
+    # @return [::Float, ::Integer, ::Object, ::String, ::Range, Boolean, ::Time, nil] The casted value if it's valid. Otherwise, returns the original value.
     def value
       success? ? @value : @original_value
     end
 
+    # It returns true if the value is successfully casted.
+    #
     # @return [Boolean]
     def success?
       @error_messages.nil?

data/lib/strong_csv/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 class StrongCSV
-  VERSION = "0.3.0"
+  VERSION = "0.6.0"
 end

data/lib/strong_csv.rb

@@ -21,7 +21,7 @@ require_relative "strong_csv/types/union"
 require_relative "strong_csv/let"
 require_relative "strong_csv/row"
 
-# The top-level namespace for the strong_csv gem.
+# StrongCSV is a library for parsing CSV contents with type checking.
 class StrongCSV
   class Error < StandardError; end
 
@@ -37,6 +37,12 @@ class StrongCSV
     options.delete(:nil_value)
     options = options.merge(headers: @let.headers, header_converters: :symbol)
     csv = CSV.new(csv, **options)
+
+    @let.pickers.each_value do |picker|
+      picker.call(csv)
+      csv.rewind
+    end
+
     if block_given?
       csv.each do |row|
         yield Row.new(row: row, types: @let.types, lineno: csv.lineno)

data/sig/strong_csv.rbs

@@ -0,0 +1,163 @@
+# TypeProf 0.21.2
+
+type literals = ::Integer | ::Float | ::Range[untyped] | ::String | ::Regexp
+type declarable = StrongCSV::Types::Base | literals
+type casted = bool | ::Float | ::Integer | ::Range[untyped] | ::String | ::Regexp | ::Time
+type column = ::Integer | ::Symbol
+
+# Classes
+class StrongCSV
+  VERSION: String
+
+  @let: Let
+
+  def initialize: -> void
+
+  def parse: (String | IO, **untyped) -> Array[Row]
+    | (String | IO, **untyped) { (Row) -> void } -> untyped
+
+  class ValueResult
+    DEFAULT_VALUE: Object
+
+    @value: (casted)?
+    @original_value: untyped
+
+    attr_reader error_messages: [::String]?
+
+    def initialize: (original_value: ::String | nil, ?value: (casted | ::Object)?, ?error_messages: [::String]?) -> void
+
+    def value: -> ((casted | ::Object | nil)?)
+
+    def success?: -> bool
+  end
+
+  module Types
+    class Base
+      def cast: (untyped _value) -> bot
+    end
+
+    class Boolean < Base
+      TRUE_VALUES: Set[::String]
+      FALSE_VALUES: Set[::String]
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    class Float < Base
+      DEFAULT_CONSTRAINT: ^(::Float) -> true
+
+      @constraint: ^(::Float) -> boolish
+
+      def initialize: (?constraint: ^(::Float) -> boolish) -> void
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    class Integer < Base
+      DEFAULT_CONSTRAINT: ^(::Integer) -> true
+
+      @constraint: ^(::Integer) -> boolish
+
+      def initialize: (?constraint: ^(::Integer) -> boolish) -> void
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    module Literal
+      def cast: (untyped value) -> ValueResult
+        | (untyped value) -> ValueResult
+        | (untyped value) -> ValueResult
+        | (untyped value) -> ValueResult
+        | (untyped value) -> ValueResult
+    end
+
+    class Optional < Base
+      @type: Boolean | Float | Integer | String | Time | Literal
+
+      def initialize: (declarable) -> void
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    class String < Base
+      @within: Range[untyped] | nil
+
+      def initialize: (?within: Range[untyped] | nil) -> void
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    class Time < Base
+      @format: ::String
+
+      def initialize: (?format: ::String) -> void
+
+      def cast: (::String | nil) -> ValueResult
+    end
+
+    class Union < Base
+      @types: Array[untyped]
+
+      def initialize: (untyped `type`, *untyped types) -> void
+
+      def cast: (::String | nil) -> untyped
+    end
+  end
+
+  class Let
+    @picked: Hash[untyped, untyped]
+
+    attr_reader types: Hash[column, [declarable, ^(casted) -> untyped | nil]]
+    attr_reader headers: bool
+    attr_reader pickers: Hash[untyped, Proc]
+
+    def initialize: -> void
+
+    def let: (::String | column, declarable, *declarable) -> void
+      | (::String | column, declarable, *declarable) { (casted) -> untyped } -> void
+
+    def pick: (column, as: ::Symbol) { (Array[::String]) -> untyped } -> void
+
+    def integer: (**untyped) -> Types::Integer
+
+    def integer?: (**untyped) -> Types::Optional
+
+    def boolean: -> Types::Boolean
+
+    def boolean?: -> Types::Optional
+
+    def float: (**untyped) -> Types::Float
+
+    def float?: (**untyped) -> Types::Optional
+
+    def string: (**untyped) -> Types::String
+
+    def string?: (**untyped) -> Types::Optional
+
+    def time: (**untyped) -> Types::Time
+
+    def time?: (**untyped) -> Types::Optional
+
+    def optional: (*declarable) -> Types::Optional
+
+    private
+
+    def validate_columns: -> bool
+  end
+
+  class Row
+    extend Forwardable
+
+    @values: Hash[column, casted | ::Object | nil]
+
+    attr_reader errors: Hash[column, Array[::String]]
+    attr_reader lineno: ::Integer
+
+    def initialize: (row: Array[::String] | CSV::Row, types: Hash[column, [declarable, (^(casted | ::Object | nil) -> untyped | nil)]], lineno: ::Integer) -> void
+
+    def valid?: -> bool
+  end
+
+  class Error < StandardError
+  end
+end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: strong_csv
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.6.0
 platform: ruby
 authors:
 - Yutaka Kamei
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2022-05-04 00:00:00.000000000 Z
+date: 2022-07-14 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: i18n
@@ -55,6 +55,7 @@ files:
 - lib/strong_csv/types/union.rb
 - lib/strong_csv/value_result.rb
 - lib/strong_csv/version.rb
+- sig/strong_csv.rbs
 homepage: https://github.com/yykamei/strong_csv
 licenses:
 - MIT