callable_tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 3d3a8425d7d4634140f8ae67d37b00212909bfefb2055fd75d98e8d6f851b5be
+  data.tar.gz: 0103f8cda6b99b7f122b79f95f6b70bfdd8c8b5aecc01791e870941b0d5d2f36
+SHA512:
+  metadata.gz: 6722db751a4b784f8983aa9164371bf9f933c3ea7a1e00b3e0595970a3842f93fd86357da48fc6958babdb7add5d0018d5ace986049ae286961bf328ddcc36ab
+  data.tar.gz: 74fd411e58ef8b04d810504f2003809f50488e6fabcc8ff9ff4b596e509b750eaeb4e333698d259dd6a39ce3293f84f2755bcaa3d296a5364d17bbb315128ff9

data/.github/workflows/build.yml

@@ -0,0 +1,25 @@
+name: build
+on: [push]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        ruby: ['2.4', '2.5', '2.6', '2.7', '3.0']
+    steps:
+      - uses: actions/checkout@v2
+      - uses: ruby/setup-ruby@v1
+        with:
+          ruby-version: ${{ matrix.ruby }}
+      - run: gem install bundler:2.2.4
+      - uses: actions/cache@v2
+        with:
+          path: vendor/bundle
+          key: ${{ runner.os }}-ruby-${{ matrix.ruby }}-gems-${{ hashFiles('**/Gemfile.lock') }}
+          restore-keys: |
+            ${{ runner.os }}-gems-
+      - name: Run bundle install
+        run: |
+          bundle config path vendor/bundle
+          bundle install --jobs 4 --retry 3
+      - run: bundle exec rspec

data/.gitignore

@@ -0,0 +1,11 @@
+/.bundle/
+/.yardoc
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/
+
+# rspec failure tracking
+.rspec_status

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.ruby-version

@@ -0,0 +1 @@
+3.0.0

data/CHANGELOG.md

@@ -0,0 +1,5 @@
+## [Unreleased]
+
+## [0.1.0] - 2021-05-19
+
+- Initial release

data/Gemfile

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in callable_tree.gemspec
+gemspec
+
+gem 'rake', '~> 13.0'
+
+gem 'rspec', '~> 3.0'

data/Gemfile.lock

@@ -0,0 +1,35 @@
+PATH
+  remote: .
+  specs:
+    callable_tree (0.1.0)
+
+GEM
+  remote: https://rubygems.org/
+  specs:
+    diff-lcs (1.4.4)
+    rake (13.0.3)
+    rspec (3.10.0)
+      rspec-core (~> 3.10.0)
+      rspec-expectations (~> 3.10.0)
+      rspec-mocks (~> 3.10.0)
+    rspec-core (3.10.1)
+      rspec-support (~> 3.10.0)
+    rspec-expectations (3.10.1)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-mocks (3.10.2)
+      diff-lcs (>= 1.2.0, < 2.0)
+      rspec-support (~> 3.10.0)
+    rspec-support (3.10.2)
+
+PLATFORMS
+  x86_64-darwin-19
+  x86_64-darwin-20
+
+DEPENDENCIES
+  callable_tree!
+  rake (~> 13.0)
+  rspec (~> 3.0)
+
+BUNDLED WITH
+   2.2.17

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2021 　
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,436 @@
+# CallableTree
+
+## Installation
+
+Add this line to your application's Gemfile:
+
+```ruby
+gem 'callable_tree'
+```
+
+And then execute:
+
+    $ bundle install
+
+Or install it yourself as:
+
+    $ gem install callable_tree
+
+## Usage
+
+- `CallableTree::Node::Internal`
+  - This `module` is used to define a node that can have child nodes.
+- `CallableTree::Node::External`
+  - This `module` is used to define a leaf node that cannot have child nodes.
+- `CallableTree::Node::Root`
+  - This `class` includes `CallableTree::Node::Internal`. When there is no need to customize the internal node, use this `class`.
+
+Builds a tree by linking instances of the nodes. The `call` method of the node where the `match?` method returns a truthy value is called in a chain from the root node to the leaf node.
+If the `call` method returns a value other than `nil`, the next sibling node does not be called. This behavior is changeable by overriding the `terminate?` method.
+
+### Basic
+
+`examples/example1.rb`:
+```ruby
+module Node
+  module JSON
+    class Parser
+      include CallableTree::Node::Internal
+
+      def match?(input, **options)
+        File.extname(input) == '.json'
+      end
+
+      # If there is need to convert the input value for
+      # child nodes, override the `call` method.
+      def call(input, **options)
+        File.open(input) do |file|
+          json = ::JSON.load(file)
+          super(json, **options)
+        end
+      end
+
+      # If a returned value of the `call` method is `nil`,
+      # but there is no need to call the sibling nodes,
+      # override the `terminate?` method to return `true`.
+      def terminate?(output, **options)
+        true
+      end
+    end
+
+    class Scraper
+      include CallableTree::Node::External
+
+      def initialize(type:)
+        @type = type
+      end
+
+      def match?(input, **options)
+        !!input[@type.to_s]
+      end
+
+      def call(input, **options)
+        input[@type.to_s]
+          .map { |element| [element['name'], element['emoji']] }
+          .to_h
+      end
+    end
+  end
+
+  module XML
+    class Parser
+      include CallableTree::Node::Internal
+
+      def match?(input, **options)
+        File.extname(input) == '.xml'
+      end
+
+      # If there is need to convert the input value for
+      # child nodes, override the `call` method.
+      def call(input, **options)
+        File.open(input) do |file|
+          super(REXML::Document.new(file), **options)
+        end
+      end
+
+      # If a returned value of the `call` method is `nil`,
+      # but there is no need to call the sibling nodes,
+      # override the `terminate?` method to return `true`.
+      def terminate?(output, **options)
+        true
+      end
+    end
+
+    class Scraper
+      include CallableTree::Node::External
+
+      def initialize(type:)
+        @type = type
+      end
+
+      def match?(input, **options)
+        !input.get_elements("//#{@type}").empty?
+      end
+
+      def call(input, **options)
+        input
+          .get_elements("//#{@type}")
+          .first
+          .map { |element| [element['name'], element['emoji']] }
+          .to_h
+      end
+    end
+  end
+end
+
+tree = CallableTree::Node::Root.new.append(
+  Node::JSON::Parser.new.append(
+    Node::JSON::Scraper.new(type: :animals),
+    Node::JSON::Scraper.new(type: :fruits)
+  ),
+  Node::XML::Parser.new.append(
+    Node::XML::Scraper.new(type: :animals),
+    Node::XML::Scraper.new(type: :fruits)
+  )
+)
+
+Dir.glob(__dir__ + '/docs/*') do |file|
+  options = { foo: :bar }
+  puts tree.call(file, **options)
+  puts '---'
+end
+```
+
+Run `examples/example1.rb`:
+```sh
+% ruby examples/example1.rb
+{"Dog"=>"🐶", "Cat"=>"🐱"}
+---
+{"Dog"=>"🐶", "Cat"=>"🐱"}
+---
+{"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+---
+{"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+---
+```
+
+### Advanced
+
+#### `CallableTree::Node::External#verbosify`
+
+If you want verbose result, call it.
+
+`examples/example2.rb`:
+```ruby
+...
+
+tree = CallableTree::Node::Root.new.append(
+  Node::JSON::Parser.new.append(
+    Node::JSON::Scraper.new(type: :animals).verbosify,
+    Node::JSON::Scraper.new(type: :fruits).verbosify
+  ),
+  Node::XML::Parser.new.append(
+    Node::XML::Scraper.new(type: :animals).verbosify,
+    Node::XML::Scraper.new(type: :fruits).verbosify
+  )
+)
+
+...
+```
+
+Run `examples/example2.rb`:
+```sh
+% ruby examples/example2.rb
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[Node::JSON::Scraper, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[Node::XML::Scraper, Node::XML::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[Node::JSON::Scraper, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[Node::XML::Scraper, Node::XML::Parser, CallableTree::Node::Root]>
+---
+```
+
+At first glance, this looks good, but the `routes` are ambiguous when there are multiple nodes of the same class.
+You can work around it by overriding the `identity` method of the node.
+
+#### `CallableTree::Node#identity`
+
+If you want to customize the node identity, override it.
+
+`examples/example3.rb`:
+```ruby
+module Node
+  class Identity
+    attr_reader :klass, :type
+
+    def initialize(klass:, type:)
+      @klass = klass
+      @type = type
+    end
+
+    def to_s
+      "#{klass}(#{type})"
+    end
+  end
+
+  module JSON
+    ...
+
+    class Scraper
+      include CallableTree::Node::External
+
+      def initialize(type:)
+        @type = type
+      end
+
+      def identity
+        Identity.new(klass: super, type: @type)
+      end
+
+      ...
+    end
+  end
+
+  module XML
+     ...
+
+    class Scraper
+      include CallableTree::Node::External
+
+      def initialize(type:)
+        @type = type
+      end
+
+      def identity
+        Identity.new(klass: super, type: @type)
+      end
+
+      ...
+    end
+  end
+end
+
+...
+```
+
+Run `examples/example3.rb`:
+```sh
+% ruby examples/example3.rb
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007ff1f78e09e0 @klass=Node::JSON::Scraper, @type=:animals>, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007ff1e7885208 @klass=Node::XML::Scraper, @type=:animals>, Node::XML::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007ff1e78771a8 @klass=Node::JSON::Scraper, @type=:fruits>, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007ff1f20d7f50 @klass=Node::XML::Scraper, @type=:fruits>, Node::XML::Parser, CallableTree::Node::Root]>
+---
+```
+
+#### Logging
+
+This is an example of logging.
+
+`examples/example4.rb`:
+```ruby
+module Node
+  module Logging
+    INDENT_SIZE = 2
+    BLANK = ' '.freeze
+
+    module Match
+      LIST_STYLE = '*'.freeze
+
+      def match?(_input, **)
+        super.tap do |matched|
+          prefix = LIST_STYLE.rjust(self.depth * INDENT_SIZE - INDENT_SIZE + LIST_STYLE.length, BLANK)
+          puts "#{prefix} #{self.identity}: [matched: #{matched}]"
+        end
+      end
+    end
+
+    module Call
+      INPUT_LABEL  = 'Input :'.freeze
+      OUTPUT_LABEL = 'Output:'.freeze
+
+      def call(input, **)
+        super.tap do |output|
+          input_prefix = INPUT_LABEL.rjust(self.depth * INDENT_SIZE + INPUT_LABEL.length, BLANK)
+          puts "#{input_prefix} #{input}"
+          output_prefix = OUTPUT_LABEL.rjust(self.depth * INDENT_SIZE + OUTPUT_LABEL.length, BLANK)
+          puts "#{output_prefix} #{output}"
+        end
+      end
+    end
+  end
+
+  ...
+
+  module JSON
+    class Parser
+      include CallableTree::Node::Internal
+      prepend Logging::Match
+
+      ...
+    end
+
+    class Scraper
+      include CallableTree::Node::External
+      prepend Logging::Match
+      prepend Logging::Call
+
+      ...
+    end
+  end
+
+  module XML
+    class Parser
+      include CallableTree::Node::Internal
+      prepend Logging::Match
+
+      ...
+    end
+
+    class Scraper
+      include CallableTree::Node::External
+      prepend Logging::Match
+      prepend Logging::Call
+
+      ...
+    end
+  end
+end
+
+...
+```
+
+Run `examples/example4.rb`:
+```sh
+% ruby examples/example4.rb
+* Node::JSON::Parser: [matched: true]
+  * Node::JSON::Scraper(animals): [matched: true]
+    Input : {"animals"=>[{"name"=>"Dog", "emoji"=>"🐶"}, {"name"=>"Cat", "emoji"=>"🐱"}]}
+    Output: {"Dog"=>"🐶", "Cat"=>"🐱"}
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007f9737074060 @klass=Node::JSON::Scraper, @type=:animals>, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+* Node::JSON::Parser: [matched: false]
+* Node::XML::Parser: [matched: true]
+  * Node::XML::Scraper(animals): [matched: true]
+    Input : <root><animals><animal emoji='🐶' name='Dog'/><animal emoji='🐱' name='Cat'/></animals></root>
+    Output: {"Dog"=>"🐶", "Cat"=>"🐱"}
+#<struct CallableTree::Node::External::Output value={"Dog"=>"🐶", "Cat"=>"🐱"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007f973710d0f8 @klass=Node::XML::Scraper, @type=:animals>, Node::XML::Parser, CallableTree::Node::Root]>
+---
+* Node::JSON::Parser: [matched: true]
+  * Node::JSON::Scraper(animals): [matched: false]
+  * Node::JSON::Scraper(fruits): [matched: true]
+    Input : {"fruits"=>[{"name"=>"Red Apple", "emoji"=>"🍎"}, {"name"=>"Green Apple", "emoji"=>"🍏"}]}
+    Output: {"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007f97370ffed0 @klass=Node::JSON::Scraper, @type=:fruits>, Node::JSON::Parser, CallableTree::Node::Root]>
+---
+* Node::JSON::Parser: [matched: false]
+* Node::XML::Parser: [matched: true]
+  * Node::XML::Scraper(animals): [matched: false]
+  * Node::XML::Scraper(fruits): [matched: true]
+    Input : <root><fruits><fruit emoji='🍎' name='Red Apple'/><fruit emoji='🍏' name='Green Apple'/></fruits></root>
+    Output: {"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+#<struct CallableTree::Node::External::Output value={"Red Apple"=>"🍎", "Green Apple"=>"🍏"}, options={:foo=>:bar}, routes=[#<Node::Identity:0x00007f97370cceb8 @klass=Node::XML::Scraper, @type=:fruits>, Node::XML::Parser, CallableTree::Node::Root]>
+---
+```
+
+#### `CallableTree::Node::Hooks::Call` (experimental)
+
+`examples/example5.rb`:
+```ruby
+module Node
+  class HooksSample
+    include CallableTree::Node::Internal
+    prepend CallableTree::Node::Hooks::Call
+  end
+end
+
+Node::HooksSample.new
+  .before_call do |input, **options|
+    puts "before_call input: #{input}";
+    input + 1
+  end
+  .append(
+    lambda do |input, **options|
+      puts "external input: #{input}"
+      input * 2
+    end
+  )
+  .around_call do |input, **options, &block|
+    puts "around_call input: #{input}"
+    output = block.call
+    puts "around_call output: #{output}"
+    output * input
+  end
+  .after_call do |output, **options|
+    puts "after_call output: #{output}"
+    output * 2
+  end
+  .tap do |tree|
+    options = { foo: :bar }
+    output = tree.call(1, **options)
+    puts "result: #{output}"
+  end
+```
+
+Run `examples/example5.rb`:
+```sh
+% ruby examples/example5.rb
+before_call input: 1
+external input: 2
+around_call input: 2
+around_call output: 4
+after_call output: 8
+result: 16
+```
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/jsmmr/callable_tree.
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).