rubanok 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: b992103f2ed0900e3f7b9f7aa631ee6b78d7f564c439a978a71ee44411915278
-  data.tar.gz: fcfe5bb16302cc7a45a75499e638fcde7288c269faf36f31c7abadb388cc29c1
+  metadata.gz: 90f6ca9dfd61a6f143eff1f3ab3c2d7e41502c992879af785dcf414af15249fd
+  data.tar.gz: 8807cbb2a680e9fbc739a9f0214fb4753e24ee55e69da72d9b45c7f121900dd9
 SHA512:
-  metadata.gz: bbc24b6c4d71a01f92d458a72a994341972ae8fba49832756cacd994411d8dec6f6d390c7566d44c80d37ca52abcc15981bd34b14edd78d1941cd1fde6379be9
-  data.tar.gz: f0c9ae2bf40cf2db770af48032e1b5665776ad87b3abb37fc111e93bd88091e919136351dadb5d45faf7b11ea7205cd10f3d92e4909a0538317e73bb3f1c3502
+  metadata.gz: 2e015d7c3c517e42e5fe42037035db950cc87f9bd0099b38580c03ad156c36d0133681bd659451e8bdb58f15254799ce8d7b3158a1dc998210e3a425867a521d
+  data.tar.gz: 6c22e9a876e86f144726e8dbbe79b42f9d3052feb6f9c31688f7259872a5eed1e5ac66b031b890e0d1b4eceba7d3903331a073f2e13321b9f3d45c9fe53229d2

data/CHANGELOG.md

@@ -2,6 +2,12 @@
 
 ## master
 
+## 0.4.0 (2021-03-05)
+
+- Ruby 3.0 compatibility. ([@palkan][])
+
+- Add RBS. ([@palkan][])
+
 ## 0.3.0 (2020-10-21)
 
 - Add `filter_with: Symbol | Proc` option to `.map` to allowing filtering the input value. ([@palkan][])

data/README.md

@@ -350,6 +350,42 @@ end
 
 **NOTE:** the `planish` method is still available and it uses `#{controller_path.classify.pluralize}Plane".safe_constantize` under the hood (via the `#implicit_plane_class` method).
 
+## Using with RBS/Steep
+
+_Read ["Climbing Steep hills, or adopting Ruby 3 types with RBS"](https://evilmartians.com/chronicles/climbing-steep-hills-or-adopting-ruby-types) for the context._
+
+Rubanok comes with Ruby type signatures (RBS).
+
+To use them with Steep, add `library "rubanok"` to your Steepfile.
+
+Since Rubanok provides DSL with implicit context switching (via `instance_eval`), you need to provide type hints for the type checker to help it
+figure out the current context. Here is an example:
+
+```ruby
+class MyProcessor < Rubanok::Processor
+  map :q do |q:|
+    # @type self : Rubanok::Processor
+    raw
+  end
+
+  match :sort_by, :sort, activate_on: :sort_by do
+    # @type self : Rubanok::DSL::Matching::Rule
+    having "status", "asc" do
+      # @type self : Rubanok::Processor
+      raw
+    end
+
+    # @type self : Rubanok::DSL::Matching::Rule
+    default do |sort_by:, sort: "asc"|
+      # @type self : Rubanok::Processor
+      raw
+    end
+  end
+end
+```
+
+Yeah, a lot of annotations 😞 Welcome to the type-safe world!
+
 ## Questions & Answers
 
 - **Where to put my processor/plane classes?**

data/lib/rubanok.rb

@@ -5,6 +5,7 @@ require "rubanok/processor"
 
 require "rubanok/railtie" if defined?(Rails)
 
+# @type const ENV: Hash[String, String]
 if defined?(RSpec) && (ENV["RACK_ENV"] == "test" || ENV["RAILS_ENV"] == "test")
   require "rubanok/rspec"
 end

data/lib/rubanok/dsl/mapping.rb

@@ -21,8 +21,8 @@ module Rubanok
       end
 
       module ClassMethods
-        def map(*fields, **options, &block)
-          filter = options[:filter_with]
+        def map(*fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil, &block)
+          filter = filter_with
 
           if filter.is_a?(Symbol)
             respond_to?(filter) || raise(
@@ -30,10 +30,10 @@ module Rubanok
               "Unknown class method #{filter} for #{self}. " \
               "Make sure that a filter method is defined before the call to .map."
             )
-            options[:filter_with] = method(filter)
+            filter = method(filter)
           end
 
-          rule = Rule.new(fields, **options)
+          rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always, ignore_empty_values: ignore_empty_values, filter_with: filter)
 
           define_method(rule.to_method_name, &block)
 

data/lib/rubanok/dsl/matching.rb

@@ -22,8 +22,8 @@ module Rubanok
         class Clause < Rubanok::Rule
           attr_reader :values, :id, :block
 
-          def initialize(id, fields, values = [], **options, &block)
-            super(fields, options)
+          def initialize(id, fields, values, activate_on: fields, activate_always: false, &block)
+            super(fields, activate_on: activate_on, activate_always: activate_always)
             @id = id
             @block = block
             @values = Hash[fields.take(values.size).zip(values)].freeze
@@ -39,7 +39,7 @@ module Rubanok
 
         attr_reader :clauses
 
-        def initialize(*, **)
+        def initialize(fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil)
           super
           @clauses = []
         end
@@ -55,7 +55,7 @@ module Rubanok
         end
 
         def default(&block)
-          clauses << Clause.new("#{to_method_name}_default", fields, activate_always: true, &block)
+          clauses << Clause.new("#{to_method_name}_default", fields, [], activate_always: true, &block)
         end
 
         private
@@ -67,16 +67,21 @@ module Rubanok
       end
 
       module ClassMethods
-        def match(*fields, **options, &block)
-          rule = Rule.new(fields, **options.slice(:activate_on, :activate_always))
+        def match(*fields, activate_on: fields, activate_always: false, fail_when_no_matches: nil, &block)
+          rule = Rule.new(fields, activate_on: activate_on, activate_always: activate_always)
 
           rule.instance_eval(&block)
 
           define_method(rule.to_method_name) do |params = {}|
+            params ||= {} if params.nil?
+
             clause = rule.matching_clause(params)
-            next default_match_handler(rule, params, options[:fail_when_no_matches]) unless clause
 
-            apply_rule! clause, params
+            if clause
+              apply_rule! clause, params
+            else
+              default_match_handler(rule, params, fail_when_no_matches)
+            end
           end
 
           rule.clauses.each do |clause|

data/lib/rubanok/processor.rb

@@ -32,15 +32,15 @@ module Rubanok
     include DSL::Matching
     include DSL::Mapping
 
+    UNDEFINED = Object.new
+
     class << self
-      def call(*args)
-        input, params =
-          if args.size == 1
-            [nil, args.first]
-          else
-            args
-          end
+      def call(input, params = UNDEFINED)
+        input, params = nil, input if params == UNDEFINED
+
+        raise ArgumentError, "Params could not be nil" if params.nil?
 
+        # @type var params: untyped
         new(input).call(params)
       end
 
@@ -75,7 +75,7 @@ module Rubanok
       # by the rules
       def project(params)
         params = params.transform_keys(&:to_sym)
-        params.slice(*fields_set)
+        params.slice(*fields_set.to_a)
       end
 
       # DSL to define the #prepare method
@@ -86,6 +86,7 @@ module Rubanok
 
     def initialize(input)
       @input = input
+      @prepared = false
     end
 
     def call(params)

data/lib/rubanok/rule.rb

@@ -1,15 +1,30 @@
 # frozen_string_literal: true
 
 module Rubanok
+  using(Module.new do
+    refine NilClass do
+      def empty?
+        true
+      end
+    end
+
+    refine Object do
+      def empty?
+        false
+      end
+    end
+  end)
+
   class Rule # :nodoc:
     UNDEFINED = Object.new
 
-    attr_reader :owner, :fields, :activate_on, :activate_always, :ignore_empty_values, :filter_with
+    attr_reader :fields, :activate_on, :activate_always, :ignore_empty_values, :filter_with
 
     def initialize(fields, activate_on: fields, activate_always: false, ignore_empty_values: Rubanok.ignore_empty_values, filter_with: nil)
-      @owner = owner
       @fields = fields.freeze
-      @activate_on = Array(activate_on).freeze
+      # @type var activate_on: Array[Symbol]
+      activate_on = Array(activate_on)
+      @activate_on = activate_on.freeze
       @activate_always = activate_always
       @ignore_empty_values = ignore_empty_values
       @filter_with = filter_with
@@ -18,9 +33,7 @@ module Rubanok
     def project(params)
       fields.each_with_object({}) do |field, acc|
         val = fetch_value params, field
-        next acc if val == UNDEFINED
-
-        acc[field] = val
+        acc[field] = val if val != UNDEFINED
         acc
       end
     end
@@ -46,27 +59,13 @@ module Rubanok
 
       val = params[field]
 
-      val = filter_with.call(val) if filter_with
+      val = filter_with&.call(val) if filter_with
 
       return UNDEFINED if empty?(val)
 
       val
     end
 
-    using(Module.new do
-      refine NilClass do
-        def empty?
-          true
-        end
-      end
-
-      refine Object do
-        def empty?
-          false
-        end
-      end
-    end)
-
     def empty?(val)
       return false unless ignore_empty_values
 

data/lib/rubanok/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Rubanok
-  VERSION = "0.3.0"
+  VERSION = "0.4.0"
 end

data/sig/rubanok.rbs

@@ -0,0 +1,6 @@
+module Rubanok
+  def self.fail_when_no_matches: () -> bool
+  def self.fail_when_no_matches=: (bool) -> bool
+  def self.ignore_empty_values: () -> bool
+  def self.ignore_empty_values=: (bool) -> bool
+end

data/sig/rubanok/dsl/mapping.rbs

@@ -0,0 +1,18 @@
+module Rubanok
+  module DSL
+    module Mapping : Processor
+      class Rule < Rubanok::Rule
+        METHOD_PREFIX: String
+
+        private
+        def build_method_name: () -> String
+      end
+
+      module ClassMethods : Module, _RulesAdding
+        def map: (*field fields, ?activate_on: (field | Array[field]), ?activate_always: bool, ?ignore_empty_values: bool, ?filter_with: Symbol) { () -> input } -> void
+      end
+
+      def self.included: (singleton(Processor) base) -> void
+    end
+  end
+end

data/sig/rubanok/dsl/matching.rbs

@@ -0,0 +1,44 @@
+module Rubanok
+  class UnexpectedInputError < StandardError
+  end
+
+  module DSL
+    module Matching : Processor
+      class Rule < Rubanok::Rule
+        METHOD_PREFIX: String
+        @method_name: String
+        @fields: Array[field]
+
+        class Clause < Rubanok::Rule
+          @fields: Array[field]
+
+          attr_reader values: params
+          attr_reader id: String
+          attr_reader block: ^() -> input
+
+          def initialize: (String id, Array[field] fields, untyped values, ?activate_on: field | Array[field], ?activate_always: bool) { () -> input } -> void
+          def applicable?: (params) -> bool
+
+          alias to_method_name id
+        end
+
+        attr_reader clauses: Array[Clause]
+
+        def matching_clause: (hash params) -> Clause?
+        def having: (*untyped values) { () -> input } -> void
+        def default: () { () -> input } -> void
+
+        private
+        def build_method_name: () -> String
+      end
+
+      module ClassMethods : Module, _RulesAdding, Matching
+        def match: (*field fields, ?activate_on: field | Array[field], ?activate_always: bool, ?fail_when_no_matches: bool?) { (Rule) -> void } -> void
+      end
+
+      def self.included: (singleton(Processor) base) -> void
+
+      def default_match_handler: (Rule rule, hash params, bool? fail_when_no_matches) -> void
+    end
+  end
+end

data/sig/rubanok/processor.rbs

@@ -0,0 +1,53 @@
+module Rubanok
+  # Transformation parameters
+  type params = Hash[Symbol | String, untyped]
+  # Untyped Hash
+  type hash =  Hash[untyped, untyped]
+  type field = Symbol
+  # Transformation target (we assume that input and output types are the same)
+  type input = Object?
+
+  interface _RulesAdding
+    def add_rule: (Rule rule) -> void
+  end
+
+  class Processor
+    extend DSL::Matching::ClassMethods
+
+    extend DSL::Mapping::ClassMethods
+
+    extend _RulesAdding
+
+    UNDEFINED: Object
+
+    self.@rules: Array[Rule]
+    self.@fields_set: Set[field]
+
+    def self.superclass: () -> singleton(Processor)
+
+    def self.call: (input, params) -> input
+                 | (params) -> input
+    def self.rules: () -> Array[Rule]
+    def self.fields_set: () -> Set[field]
+    def self.project: (params) -> params
+    def self.prepare: () { () -> input } -> void
+
+    def initialize: (input) -> void
+    def call: (params) -> input
+
+    attr_accessor input: input
+
+    private
+    attr_accessor prepared: bool
+
+    alias raw input
+    alias prepared? prepared
+
+    def apply_rule!: (Rule rule, params) -> void
+    def prepare: () -> input
+    def prepare!: () -> void
+    def rules: () -> Array[Rule]
+  end
+
+  Plane: singleton(Processor)
+end

data/sig/rubanok/rule.rbs

@@ -0,0 +1,29 @@
+module Rubanok
+  class Rule
+    UNDEFINED: Object
+
+    @method_name: String
+
+    attr_reader fields: Array[field]
+    attr_reader activate_on: Array[field]
+    attr_reader activate_always: bool
+    attr_reader ignore_empty_values: bool
+    attr_reader filter_with: Method?
+
+    %a{rbs:test:skip} def initialize: (
+      Array[field] fields,
+      ?activate_on: field | Array[field],
+      ?activate_always: bool,
+      ?ignore_empty_values: bool,
+      ?filter_with: Method?
+    ) -> void
+    def project: (params) -> params
+    def applicable?: (params) -> bool
+    def to_method_name: () -> String
+
+    private
+    def build_method_name: () -> String
+    def fetch_value: (params, field) -> Object
+    def empty?: (untyped) -> bool
+  end
+end

data/sig/rubanok/version.rbs

@@ -0,0 +1,3 @@
+module Rubanok
+  VERSION: String
+end

data/sig/typeprof.rb

@@ -0,0 +1,25 @@
+# frozen_string_literal: true
+
+# Run typeprofiler:
+#
+#   typeprof -Ilib sig/typeprof.rb
+require "rubanok"
+
+processor = Class.new(Rubanok::Processor) do
+  map :q do |q:|
+    raw
+  end
+
+  match :sort_by, :sort, activate_on: :sort_by do
+    having "status", "asc" do
+      raw
+    end
+
+    default do |sort_by:, sort: "asc"|
+      raw
+    end
+  end
+end
+
+processor.project({q: "search", sort_by: "name"})
+processor.call([], {q: "search", sort_by: "name"})

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: rubanok
 version: !ruby/object:Gem::Version
-  version: 0.3.0
+  version: 0.4.0
 platform: ruby
 authors:
 - Vladimir Dementyev
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2020-10-21 00:00:00.000000000 Z
+date: 2021-03-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: actionpack
@@ -113,6 +113,13 @@ files:
 - lib/rubanok/rspec.rb
 - lib/rubanok/rule.rb
 - lib/rubanok/version.rb
+- sig/rubanok.rbs
+- sig/rubanok/dsl/mapping.rbs
+- sig/rubanok/dsl/matching.rbs
+- sig/rubanok/processor.rbs
+- sig/rubanok/rule.rbs
+- sig/rubanok/version.rbs
+- sig/typeprof.rb
 homepage: https://github.com/palkan/rubanok
 licenses:
 - MIT