callable_tree 0.3.10 → 0.3.12

data/README.md

@@ -3,6 +3,10 @@
 [![build](https://github.com/jsmmr/ruby_callable_tree/actions/workflows/build.yml/badge.svg)](https://github.com/jsmmr/ruby_callable_tree/actions/workflows/build.yml)
 [![CodeQL](https://github.com/jsmmr/ruby_callable_tree/actions/workflows/codeql-analysis.yml/badge.svg)](https://github.com/jsmmr/ruby_callable_tree/actions/workflows/codeql-analysis.yml)
 
+A framework for building tree-structured executable workflows in Ruby.
+
+Construct trees of callable nodes to handle complex execution flows. Supports strategies to seek specific handlers, broadcast to multiple listeners, or compose processing pipelines. Nodes are matched against input and executed in a chain, offering a structured, modular alternative to complex conditional logic.
+
 ## Installation
 
 Add this line to your application's Gemfile:
@@ -21,22 +25,22 @@ Or install it yourself as:
 
 ## Usage
 
-Builds a tree by linking `CallableTree` node instances. The `call` methods of the nodes where the `match?` method returns a truthy value are called in a chain from the root node to the leaf node.
+Builds a tree of `CallableTree` nodes. Invokes the `call` method on nodes where `match?` returns a truthy value, chaining execution from root to leaf.
 
 - `CallableTree::Node::Internal`
-  - This `module` is used to define a node that can have child nodes. This node has several strategies (`seekable`, `broadcastable`, `composable`).
+  - Defines a node that can have child nodes. Supports several strategies (`seekable`, `broadcastable`, `composable`).
 - `CallableTree::Node::External`
-  - This `module` is used to define a leaf node that cannot have child nodes.
+  - Defines a leaf node, which 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`.
+  - Includes `CallableTree::Node::Internal`. Use this class when customization of the internal node is not required.
 
 ### Basic
 
-There are two ways to define the nodes: class style and builder style.
+There are three ways to define nodes: class style, builder style, and factory style.
 
 #### `CallableTree::Node::Internal#seekable` (default strategy)
 
-This strategy does not call the next sibling node if the `call` method of the current node returns a value other than `nil`. This behavior is changeable by overriding the `terminate?` method.
+This strategy stops processing subsequent sibling nodes if the current node's `call` method returns a non-nil value. This behavior is changeable by overriding the `terminate?` method.
 
 ##### Class style
 
@@ -51,8 +55,7 @@ module Node
         File.extname(input) == '.json'
       end
 
-      # If there is need to convert the input values for
-      # child nodes, override the `call` method.
+      # Override `call` if you need to transform input values for child nodes.
       def call(input, **options)
         File.open(input) do |file|
           json = ::JSON.load(file)
@@ -60,9 +63,7 @@ module Node
         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`.
+      # Override `terminate?` to return `true` to stop processing sibling nodes even if `call` returns `nil`.
       def terminate?(_output, *_inputs, **_options)
         true
       end
@@ -94,17 +95,14 @@ module Node
         File.extname(input) == '.xml'
       end
 
-      # If there is need to convert the input values for
-      # child nodes, override the `call` method.
+      # Override `call` if you need to transform input values for child nodes.
       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`.
+      # Override `terminate?` to return `true` to stop processing sibling nodes even if `call` returns `nil`.
       def terminate?(_output, *_inputs, **_options)
         true
       end
@@ -131,7 +129,7 @@ module Node
   end
 end
 
-# The `seekable` method call can be omitted since it is the default strategy.
+# The `seekable` call can be omitted as it is the default strategy.
 tree = CallableTree::Node::Root.new.seekable.append(
   Node::JSON::Parser.new.seekable.append(
     Node::JSON::Scraper.new(type: :animals),
@@ -263,9 +261,87 @@ Run `examples/builder/internal-seekable.rb`:
 ---
 ```
 
+##### Factory style
+
+Factory style defines behaviors as procs first, then assembles the tree structure separately. This makes the tree structure clearly visible.
+
+`examples/factory/internal-seekable.rb`:
+```ruby
+# === Behavior Definitions ===
+
+json_matcher = ->(input, **) { File.extname(input) == '.json' }
+json_caller = lambda do |input, **options, &original|
+  File.open(input) do |file|
+    json = JSON.parse(file.read)
+    original.call(json, **options)
+  end
+end
+
+xml_matcher = ->(input, **) { File.extname(input) == '.xml' }
+xml_caller = lambda do |input, **options, &original|
+  File.open(input) do |file|
+    original.call(REXML::Document.new(file), **options)
+  end
+end
+
+animals_json_matcher = ->(input, **) { !input['animals'].nil? }
+animals_json_caller = ->(input, **) { input['animals'].to_h { |e| [e['name'], e['emoji']] } }
+
+fruits_json_matcher = ->(input, **) { !input['fruits'].nil? }
+fruits_json_caller = ->(input, **) { input['fruits'].to_h { |e| [e['name'], e['emoji']] } }
+
+animals_xml_matcher = ->(input, **) { !input.get_elements('//animals').empty? }
+animals_xml_caller = ->(input, **) { input.get_elements('//animals').first.to_h { |e| [e['name'], e['emoji']] } }
+
+fruits_xml_matcher = ->(input, **) { !input.get_elements('//fruits').empty? }
+fruits_xml_caller = ->(input, **) { input.get_elements('//fruits').first.to_h { |e| [e['name'], e['emoji']] } }
+
+terminator_true = ->(*) { true }
+
+# === Tree Structure (clearly visible!) ===
+
+tree = CallableTree::Node::Root.new.seekable.append(
+  CallableTree::Node::Internal.create(
+    matcher: json_matcher,
+    caller: json_caller,
+    terminator: terminator_true
+  ).seekable.append(
+    CallableTree::Node::External.create(matcher: animals_json_matcher, caller: animals_json_caller),
+    CallableTree::Node::External.create(matcher: fruits_json_matcher, caller: fruits_json_caller)
+  ),
+  CallableTree::Node::Internal.create(
+    matcher: xml_matcher,
+    caller: xml_caller,
+    terminator: terminator_true
+  ).seekable.append(
+    CallableTree::Node::External.create(matcher: animals_xml_matcher, caller: animals_xml_caller),
+    CallableTree::Node::External.create(matcher: fruits_xml_matcher, caller: fruits_xml_caller)
+  )
+)
+
+Dir.glob("#{__dir__}/../docs/*") do |file|
+  options = { foo: :bar }
+  pp tree.call(file, **options)
+  puts '---'
+end
+```
+
+Run `examples/factory/internal-seekable.rb`:
+```sh
+% ruby examples/factory/internal-seekable.rb
+{"Dog"=>"🐶", "Cat"=>"🐱"}
+---
+{"Dog"=>"🐶", "Cat"=>"🐱"}
+---
+{"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+---
+{"Red Apple"=>"🍎", "Green Apple"=>"🍏"}
+---
+```
+
 #### `CallableTree::Node::Internal#broadcastable`
 
-This strategy broadcasts to output a result of the child nodes as array. It also ignores their `terminate?` methods by default.
+This strategy broadcasts input to all child nodes and returns their results as an array. It ignores child `terminate?` methods by default.
 
 ##### Class style
 
@@ -409,9 +485,58 @@ Run `examples/builder/internal-broadcastable.rb`:
 10 -> [nil, nil]
 ```
 
+##### Factory style
+
+`examples/factory/internal-broadcastable.rb`:
+```ruby
+# === Behavior Definitions ===
+
+less_than_5_matcher = ->(input, **, &original) { original.call(input) && input < 5 }
+less_than_10_matcher = ->(input, **, &original) { original.call(input) && input < 10 }
+
+multiply_2_caller = ->(input, **) { input * 2 }
+add_1_caller = ->(input, **) { input + 1 }
+multiply_3_caller = ->(input, **) { input * 3 }
+subtract_1_caller = ->(input, **) { input - 1 }
+
+# === Tree Structure ===
+
+tree = CallableTree::Node::Root.new.broadcastable.append(
+  CallableTree::Node::Internal.create(matcher: less_than_5_matcher).broadcastable.append(
+    CallableTree::Node::External.create(caller: multiply_2_caller),
+    CallableTree::Node::External.create(caller: add_1_caller)
+  ),
+  CallableTree::Node::Internal.create(matcher: less_than_10_matcher).broadcastable.append(
+    CallableTree::Node::External.create(caller: multiply_3_caller),
+    CallableTree::Node::External.create(caller: subtract_1_caller)
+  )
+)
+
+(0..10).each do |input|
+  output = tree.call(input)
+  puts "#{input} -> #{output}"
+end
+```
+
+Run `examples/factory/internal-broadcastable.rb`:
+```sh
+% ruby examples/factory/internal-broadcastable.rb
+0 -> [[0, 1], [0, -1]]
+1 -> [[2, 2], [3, 0]]
+2 -> [[4, 3], [6, 1]]
+3 -> [[6, 4], [9, 2]]
+4 -> [[8, 5], [12, 3]]
+5 -> [nil, [15, 4]]
+6 -> [nil, [18, 5]]
+7 -> [nil, [21, 6]]
+8 -> [nil, [24, 7]]
+9 -> [nil, [27, 8]]
+10 -> [nil, nil]
+```
+
 #### `CallableTree::Node::Internal#composable`
 
-This strategy composes the child nodes to input the output of the previous node into the next node and to output a result.
+This strategy chains child nodes, passing the output of the previous node as input to the next.
 It also ignores their `terminate?` methods by default.
 
 ##### Class style
@@ -556,11 +681,60 @@ Run `examples/builder/internal-composable.rb`:
 10 -> 10
 ```
 
+##### Factory style
+
+`examples/factory/internal-composable.rb`:
+```ruby
+# === Behavior Definitions ===
+
+less_than_5_matcher = ->(input, **, &original) { original.call(input) && input < 5 }
+less_than_10_matcher = ->(input, **, &original) { original.call(input) && input < 10 }
+
+multiply_2_caller = ->(input, **) { input * 2 }
+add_1_caller = ->(input, **) { input + 1 }
+multiply_3_caller = ->(input, **) { input * 3 }
+subtract_1_caller = ->(input, **) { input - 1 }
+
+# === Tree Structure ===
+
+tree = CallableTree::Node::Root.new.composable.append(
+  CallableTree::Node::Internal.create(matcher: less_than_5_matcher).composable.append(
+    CallableTree::Node::External.create(caller: multiply_2_caller),
+    CallableTree::Node::External.create(caller: add_1_caller)
+  ),
+  CallableTree::Node::Internal.create(matcher: less_than_10_matcher).composable.append(
+    CallableTree::Node::External.create(caller: multiply_3_caller),
+    CallableTree::Node::External.create(caller: subtract_1_caller)
+  )
+)
+
+(0..10).each do |input|
+  output = tree.call(input)
+  puts "#{input} -> #{output}"
+end
+```
+
+Run `examples/factory/internal-composable.rb`:
+```sh
+% ruby examples/factory/internal-composable.rb
+0 -> 2
+1 -> 8
+2 -> 14
+3 -> 20
+4 -> 26
+5 -> 14
+6 -> 17
+7 -> 20
+8 -> 23
+9 -> 26
+10 -> 10
+```
+
 ### Advanced
 
 #### `CallableTree::Node::External#verbosify`
 
-If you want verbose output results, call this method.
+Use this method to enable verbose output.
 
 `examples/builder/external-verbosify.rb`:
 ```ruby
@@ -739,7 +913,7 @@ Run `examples/builder/logging.rb`:
 
 #### `CallableTree::Node#identity`
 
-If you want to customize the node identity, specify identifier.
+Specify an identifier to customize the node identity.
 
 `examples/builder/identity.rb`:
 ```ruby

data/callable_tree.gemspec

@@ -8,8 +8,14 @@ Gem::Specification.new do |spec|
   spec.authors       = ['jsmmr']
   spec.email         = ['jsmmr@icloud.com']
 
-  spec.summary       = 'Builds a tree by linking callable nodes. The nodes that match the conditions are called in a chain from the root node to the leaf node. These are like nested `if` or `case` expressions.'
-  spec.description   = 'Builds a tree by linking callable nodes. The nodes that match the conditions are called in a chain from the root node to the leaf node. These are like nested `if` or `case` expressions.'
+  spec.summary       = 'Builds executable trees of callable nodes with flexible strategies like seek, broadcast, and compose.'
+  spec.description = <<~DESC
+    CallableTree provides a framework for organizing complex logic into a tree of callable nodes.
+    It allows you to chain execution from a root node to leaf nodes based on matching conditions.
+    Key features include multiple traversal strategies: `seekable` (like nested `if`/`case`),
+    `broadcastable` (one-to-many execution), and `composable` (pipelined processing).
+    Supports class-based, builder-style and factory-style definitions.
+  DESC
   spec.homepage      = 'https://github.com/jsmmr/ruby_callable_tree'
   spec.license       = 'MIT'
   spec.required_ruby_version = Gem::Requirement.new('>= 2.4.0')

data/examples/builder/external-verbosify.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -12,7 +13,7 @@ JSONParser =
   end
   .caller do |input, **options, &block|
     File.open(input) do |file|
-      json = JSON.load(file)
+      json = JSON.parse(file.read)
       # The following block call is equivalent to calling `super` in the class style.
       block.call(json, **options)
     end

data/examples/builder/hooks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 HooksSample =
   CallableTree::Node::Internal::Builder

data/examples/builder/identity.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -12,7 +13,7 @@ JSONParser =
   end
   .caller do |input, **options, &block|
     File.open(input) do |file|
-      json = JSON.load(file)
+      json = JSON.parse(file.read)
       # The following block call is equivalent to calling `super` in the class style.
       block.call(json, **options)
     end

data/examples/builder/internal-broadcastable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 def less_than(num)
   # The following block call is equivalent to calling `super` in the class style.

data/examples/builder/internal-composable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 def less_than(num)
   # The following block call is equivalent to calling `super` in the class style.

data/examples/builder/internal-seekable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -12,7 +13,7 @@ JSONParser =
   end
   .caller do |input, **options, &original|
     File.open(input) do |file|
-      json = JSON.load(file)
+      json = JSON.parse(file.read)
       # The following block call is equivalent to calling `super` in the class style.
       original.call(json, **options)
     end

data/examples/builder/logging.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -12,7 +13,7 @@ JSONParser =
   end
   .caller do |input, **options, &original|
     File.open(input) do |file|
-      json = JSON.load(file)
+      json = JSON.parse(file.read)
       # The following block call is equivalent to calling `super` in the class style.
       original.call(json, **options)
     end

data/examples/class/external-verbosify.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -15,7 +16,7 @@ module Node
 
       def call(input, **options)
         File.open(input) do |file|
-          json = ::JSON.load(file)
+          json = ::JSON.parse(file.read)
           super(json, **options)
         end
       end

data/examples/class/hooks.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 module Node
   class HooksSample

data/examples/class/identity.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -28,7 +29,7 @@ module Node
 
       def call(input, **options)
         File.open(input) do |file|
-          json = ::JSON.load(file)
+          json = ::JSON.parse(file.read)
           super(json, **options)
         end
       end

data/examples/class/internal-broadcastable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 module Node
   class LessThan

data/examples/class/internal-composable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 
 module Node
   class LessThan

data/examples/class/internal-seekable.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -15,7 +16,7 @@ module Node
 
       def call(input, **options)
         File.open(input) do |file|
-          json = ::JSON.load(file)
+          json = ::JSON.parse(file.read)
           super(json, **options)
         end
       end

data/examples/class/logging.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
-require 'callable_tree'
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
 require 'json'
 require 'rexml/document'
 
@@ -29,7 +30,7 @@ module Node
 
       def call(input, **options)
         File.open(input) do |file|
-          json = ::JSON.load(file)
+          json = ::JSON.parse(file.read)
           super(json, **options)
         end
       end

data/examples/factory/external-verbosify.rb

@@ -0,0 +1,69 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+require 'json'
+require 'rexml/document'
+
+# Verbosify example using Factory style with pre-defined procs
+# Shows verbose output including route information
+
+# === Behavior Definitions ===
+
+json_matcher = ->(input, **) { File.extname(input) == '.json' }
+json_caller = lambda do |input, **options, &block|
+  File.open(input) do |file|
+    json = JSON.parse(file.read)
+    block.call(json, **options)
+  end
+end
+
+xml_matcher = ->(input, **) { File.extname(input) == '.xml' }
+xml_caller = lambda do |input, **options, &block|
+  File.open(input) do |file|
+    block.call(REXML::Document.new(file), **options)
+  end
+end
+
+animals_json_matcher = ->(input, **) { !input['animals'].nil? }
+animals_json_caller = ->(input, **) { input['animals'].to_h { |e| [e['name'], e['emoji']] } }
+
+fruits_json_matcher = ->(input, **) { !input['fruits'].nil? }
+fruits_json_caller = ->(input, **) { input['fruits'].to_h { |e| [e['name'], e['emoji']] } }
+
+animals_xml_matcher = ->(input, **) { !input.get_elements('//animals').empty? }
+animals_xml_caller = ->(input, **) { input.get_elements('//animals').first.to_h { |e| [e['name'], e['emoji']] } }
+
+fruits_xml_matcher = ->(input, **) { !input.get_elements('//fruits').empty? }
+fruits_xml_caller = ->(input, **) { input.get_elements('//fruits').first.to_h { |e| [e['name'], e['emoji']] } }
+
+terminator_true = ->(*) { true }
+
+# === Tree Structure ===
+
+tree = CallableTree::Node::Root.new.seekable.append(
+  CallableTree::Node::Internal.create(
+    matcher: json_matcher,
+    caller: json_caller,
+    terminator: terminator_true
+  ).seekable.append(
+    CallableTree::Node::External.create(matcher: animals_json_matcher, caller: animals_json_caller).verbosify,
+    CallableTree::Node::External.create(matcher: fruits_json_matcher, caller: fruits_json_caller).verbosify
+  ),
+  CallableTree::Node::Internal.create(
+    matcher: xml_matcher,
+    caller: xml_caller,
+    terminator: terminator_true
+  ).seekable.append(
+    CallableTree::Node::External.create(matcher: animals_xml_matcher, caller: animals_xml_caller).verbosify,
+    CallableTree::Node::External.create(matcher: fruits_xml_matcher, caller: fruits_xml_caller).verbosify
+  )
+)
+
+# === Execution ===
+
+Dir.glob("#{__dir__}/../docs/*") do |file|
+  options = { foo: :bar }
+  pp tree.call(file, **options)
+  puts '---'
+end

data/examples/factory/hooks.rb

@@ -0,0 +1,67 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+
+# Hooks example using Factory style with pre-defined procs
+# Demonstrates before/around/after callbacks on matcher, caller, and terminator
+
+# === Behavior Definitions ===
+
+external_caller = lambda do |input, **_options|
+  puts "external input: #{input}"
+  input * 2
+end
+
+# === Tree Structure with Hooks ===
+
+CallableTree::Node::Root.new.append(
+  CallableTree::Node::Internal.create(hookable: true)
+    .append(external_caller)
+    .before_matcher do |input, **_options|
+      puts "before_matcher input: #{input}"
+      input + 1
+    end
+    .around_matcher do |input, **_options, &block|
+      puts "around_matcher input: #{input}"
+      matched = block.call
+      puts "around_matcher matched: #{matched}"
+      !matched
+    end
+    .after_matcher do |matched, **_options|
+      puts "after_matcher matched: #{matched}"
+      !matched
+    end
+    .before_caller do |input, **_options|
+      puts "before_caller input: #{input}"
+      input + 1
+    end
+    .around_caller do |input, **_options, &block|
+      puts "around_caller input: #{input}"
+      output = block.call
+      puts "around_caller output: #{output}"
+      output * input
+    end
+    .after_caller do |output, **_options|
+      puts "after_caller output: #{output}"
+      output * 2
+    end
+    .before_terminator do |output, *_inputs, **_options|
+      puts "before_terminator output: #{output}"
+      output + 1
+    end
+    .around_terminator do |output, *_inputs, **_options, &block|
+      puts "around_terminator output: #{output}"
+      terminated = block.call
+      puts "around_terminator terminated: #{terminated}"
+      !terminated
+    end
+    .after_terminator do |terminated, **_options|
+      puts "after_terminator terminated: #{terminated}"
+      !terminated
+    end
+).tap do |tree|
+  options = { foo: :bar }
+  output = tree.call(1, **options)
+  puts "result: #{output}"
+end