callable_tree 0.3.11 → 0.3.12

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: aa3020e36165379b1ad6b642240470a33503150fd3bc945206f0685b2dbb80f4
-  data.tar.gz: 0b5314f8b192d2908640df885db697bf7a283878f08568e0ce713aa2bd6fd38b
+  metadata.gz: 2eaeaea579c042e73c734e49279adb3321ab6008e4f6165ff4a701228217af00
+  data.tar.gz: e0c848254ac6802960723abb285423c21a477c228396cc384cd84a22fa31d565
 SHA512:
-  metadata.gz: 2476e82ba6ad533bf752d75aec400bc06e9ce7106ca53a736e1b987641cf0f5d3a375126df90a5963feaf3f887ab589d2c87d61790ff08b583469e1fac13b312
-  data.tar.gz: 7eb64d2ecc3ae2333e60346173675c341b89ae14cc2d28e2f32f6b48d19d08cd580c2392d976ea6c550a2e66fee2b909c2b286e09a56e7c52b473adbbcadb82a
+  metadata.gz: a144f0e3bcd69957274c4eb80008a812aa0f980163339f9aa0f501cc4ee0b63c1c1097df6dcfb2633aa449be79e620214b81f962b1c0a3b9cc81acdbc037beeb
+  data.tar.gz: 1c3c8fb5f5e4043864506b91ee7dd8b87e616ddecefdf593d9a302de92d056f8c505a483e6b6173a6ce01fe016366ccd56d58aa295f46902a7cf70c3bce039f3

data/.rubocop_todo.yml

@@ -27,6 +27,8 @@ Lint/UnderscorePrefixedVariableName:
     - 'examples/builder/identity.rb'
     - 'examples/builder/logging.rb'
     - 'examples/class/logging.rb'
+    - 'examples/factory/identity.rb'
+    - 'examples/factory/logging.rb'
 
 # Offense count: 8
 # This cop supports safe autocorrection (--autocorrect).
@@ -74,6 +76,10 @@ Naming/FileName:
     - 'examples/class/internal-broadcastable.rb'
     - 'examples/class/internal-composable.rb'
     - 'examples/class/internal-seekable.rb'
+    - 'examples/factory/external-verbosify.rb'
+    - 'examples/factory/internal-broadcastable.rb'
+    - 'examples/factory/internal-composable.rb'
+    - 'examples/factory/internal-seekable.rb'
 
 # Offense count: 1
 # Configuration parameters: Mode, AllowedMethods, AllowedPatterns, AllowBangMethods, WaywardPredicates.
@@ -103,6 +109,8 @@ Style/MultilineBlockChain:
     - 'examples/builder/logging.rb'
     - 'examples/class/hooks.rb'
     - 'examples/class/logging.rb'
+    - 'examples/factory/hooks.rb'
+    - 'examples/factory/logging.rb'
     - 'lib/callable_tree/node/internal/strategy/seek.rb'
 
 # Offense count: 1

data/AGENTS.md

@@ -1,7 +1,7 @@
 # Agent Guide for callable_tree
 
 ## Project Overview
-`callable_tree` is a Ruby gem that builds a tree of callable nodes. It allows for complex logic flow (like nested `if`/`case`) to be represented as a tree of objects. Nodes are traversed based on matching conditions (`match?`), and executed (`call`).
+`callable_tree` is a Ruby gem for building tree-structured executable workflows. It provides a framework for organizing complex logic into a tree of callable nodes, offering a structured, modular alternative to complex conditional logic. Nodes are matched against input (`match?`) and executed (`call`) in a chain from root to leaf.
 
 ## Core Concepts
 - **Nodes**:
@@ -15,11 +15,23 @@
   - `match?(input)`: Determines if a node should process the input.
   - `call(input)`: Executes the node logic.
   - `terminate?`: Controls when to stop traversal (mostly for `seekable`).
+- **Hooks** (`hookable`):
+  - Enable instrumentation (logging, debugging) by adding callbacks.
+  - `before_matcher!`, `after_matcher!`: Hook into matching phase.
+  - `before_caller!`, `after_caller!`: Hook into call phase.
+  - `before_terminator!`, `after_terminator!`: Hook into termination phase.
+- **Verbosify** (`verbosify`):
+  - Wraps External node output in `CallableTree::Node::External::Output` struct.
+  - Provides `value`, `options`, and `routes` (call path) for debugging.
 
 ## Directory Structure
 - `lib/`: Source code.
 - `spec/`: RSpec tests.
-- `examples/`: Usage examples (Class-style and Builder-style).
+- `examples/`: Usage examples.
+  - `examples/class/`: Class-style node definitions (using `include CallableTree::Node::*`).
+  - `examples/builder/`: Builder-style definitions (using `Builder.new.matcher { }.caller { }.build`).
+  - `examples/factory/`: Factory-style definitions (using `External.create(caller: ...)` or `External::Pod.new`).
+  - `examples/docs/`: Sample data files (JSON, XML) used by examples.
 
 ## Development
 - **Tool Version Manager**: mise
@@ -41,4 +53,4 @@
 ## Architecture
 - **Composite Pattern**: Used for `Internal` nodes to treat individual objects and compositions uniformly.
 - **Builder Pattern**: `CallableTree::Node::Internal::Builder` and `CallableTree::Node::External::Builder` provide a fluent interface for constructing complex trees.
-
+- **Pod Pattern**: `CallableTree::Node::Internal::Pod` and `CallableTree::Node::External::Pod` enable inline node creation via `External.create` / `Internal.create` factory methods with proc-based behaviors.

data/CHANGELOG.md

@@ -1,5 +1,12 @@
 ## [Unreleased]
 
+## [0.3.12] - 2026-01-07
+
+- Add Factory style for inline node creation as a third option alongside Class and Builder styles.
+  - `CallableTree::Node::External.create` and `CallableTree::Node::Internal.create` factory methods
+  - Supports `hookable: true` option for Hooks (before/around/after callbacks)
+  - See `examples/factory/*.rb` for details.
+
 ## [0.3.11] - 2026-01-03
 
 - Fix a typo in `Strategizable#strategize` where it incorrectly called `strategy!` instead of `strategize!`.`

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:
@@ -32,7 +36,7 @@ Builds a tree of `CallableTree` nodes. Invokes the `call` method on nodes where
 
 ### 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)
 
@@ -257,6 +261,84 @@ 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 input to all child nodes and returns their results as an array. It ignores child `terminate?` methods by default.
@@ -403,6 +485,55 @@ 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 chains child nodes, passing the output of the previous node as input to the next.
@@ -550,6 +681,55 @@ 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`

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'
 

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'
 

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'
 

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'
 

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'
 

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'
 

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'
 

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'
 

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

data/examples/factory/identity.rb

@@ -0,0 +1,93 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+require 'json'
+require 'rexml/document'
+
+# Identity example using Factory style with pre-defined procs
+# Custom identity for each node - _node_: is used here
+
+# === 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
+json_identifier = ->(_node_:) { _node_.object_id }
+
+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
+xml_identifier = ->(_node_:) { _node_.object_id }
+
+animals_json_matcher = ->(input, **) { !input['animals'].nil? }
+animals_json_caller = ->(input, **) { input['animals'].to_h { |e| [e['name'], e['emoji']] } }
+animals_json_identifier = ->(_node_:) { _node_.object_id }
+
+fruits_json_matcher = ->(input, **) { !input['fruits'].nil? }
+fruits_json_caller = ->(input, **) { input['fruits'].to_h { |e| [e['name'], e['emoji']] } }
+fruits_json_identifier = ->(_node_:) { _node_.object_id }
+
+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']] } }
+animals_xml_identifier = ->(_node_:) { _node_.object_id }
+
+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']] } }
+fruits_xml_identifier = ->(_node_:) { _node_.object_id }
+
+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,
+    identifier: json_identifier
+  ).seekable.append(
+    CallableTree::Node::External.create(
+      matcher: animals_json_matcher,
+      caller: animals_json_caller,
+      identifier: animals_json_identifier
+    ).verbosify,
+    CallableTree::Node::External.create(
+      matcher: fruits_json_matcher,
+      caller: fruits_json_caller,
+      identifier: fruits_json_identifier
+    ).verbosify
+  ),
+  CallableTree::Node::Internal.create(
+    matcher: xml_matcher,
+    caller: xml_caller,
+    terminator: terminator_true,
+    identifier: xml_identifier
+  ).seekable.append(
+    CallableTree::Node::External.create(
+      matcher: animals_xml_matcher,
+      caller: animals_xml_caller,
+      identifier: animals_xml_identifier
+    ).verbosify,
+    CallableTree::Node::External.create(
+      matcher: fruits_xml_matcher,
+      caller: fruits_xml_caller,
+      identifier: fruits_xml_identifier
+    ).verbosify
+  )
+)
+
+# === Execution ===
+
+Dir.glob("#{__dir__}/../docs/*") do |file|
+  options = { foo: :bar }
+  pp tree.call(file, **options)
+  puts '---'
+end

data/examples/factory/internal-broadcastable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+
+# Broadcastable example using Factory style with pre-defined procs
+# All matching child nodes are called and results are collected
+
+# === 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)
+  )
+)
+
+# === Execution ===
+
+(0..10).each do |input|
+  output = tree.call(input)
+  puts "#{input} -> #{output}"
+end

data/examples/factory/internal-composable.rb

@@ -0,0 +1,37 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+
+# Composable example using Factory style with pre-defined procs
+# Output of one node becomes input to the next (pipeline)
+
+# === 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)
+  )
+)
+
+# === Execution ===
+
+(0..10).each do |input|
+  output = tree.call(input)
+  puts "#{input} -> #{output}"
+end

data/examples/factory/internal-seekable.rb

@@ -0,0 +1,71 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+require 'json'
+require 'rexml/document'
+
+# Seekable example using Factory style with pre-defined procs
+# This demonstrates the key difference from Builder style:
+# - Behaviors are defined as procs first
+# - Tree structure is assembled separately, making it clearly visible
+
+# === 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)
+  )
+)
+
+# === Execution ===
+
+Dir.glob("#{__dir__}/../docs/*") do |file|
+  options = { foo: :bar }
+  pp tree.call(file, **options)
+  puts '---'
+end

data/examples/factory/logging.rb

@@ -0,0 +1,121 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+# require 'callable_tree'
+require 'json'
+require 'rexml/document'
+
+# Logging example using Factory style with pre-defined procs
+# Uses hooks to add logging to the tree - _node_: is used in hooks
+
+# === 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 }
+
+# === Logging Module (uses _node_:) ===
+
+module Logging
+  INDENT_SIZE = 2
+  BLANK = ' '
+  LIST_STYLE = '*'
+  INPUT_LABEL  = 'Input :'
+  OUTPUT_LABEL = 'Output:'
+
+  def self.loggable(node)
+    node.after_matcher! do |matched, _node_:, **|
+      prefix = LIST_STYLE.rjust((_node_.depth * INDENT_SIZE) - INDENT_SIZE + LIST_STYLE.length, BLANK)
+      puts "#{prefix} #{_node_.identity}: [matched: #{matched}]"
+      matched
+    end
+
+    return unless node.external?
+
+    node
+      .before_caller! do |input, *, _node_:, **|
+        input_prefix = INPUT_LABEL.rjust((_node_.depth * INDENT_SIZE) + INPUT_LABEL.length, BLANK)
+        puts "#{input_prefix} #{input}"
+        input
+      end
+      .after_caller! do |output, _node_:, **|
+        output_prefix = OUTPUT_LABEL.rjust((_node_.depth * INDENT_SIZE) + OUTPUT_LABEL.length, BLANK)
+        puts "#{output_prefix} #{output}"
+        output
+      end
+  end
+end
+
+loggable = Logging.method(:loggable)
+
+# === Tree Structure ===
+
+tree = CallableTree::Node::Root.new.seekable.append(
+  CallableTree::Node::Internal.create(
+    matcher: json_matcher,
+    caller: json_caller,
+    terminator: terminator_true,
+    hookable: true
+  ).tap(&loggable).seekable.append(
+    CallableTree::Node::External.create(
+      matcher: animals_json_matcher,
+      caller: animals_json_caller,
+      hookable: true
+    ).tap(&loggable).verbosify,
+    CallableTree::Node::External.create(
+      matcher: fruits_json_matcher,
+      caller: fruits_json_caller,
+      hookable: true
+    ).tap(&loggable).verbosify
+  ),
+  CallableTree::Node::Internal.create(
+    matcher: xml_matcher,
+    caller: xml_caller,
+    terminator: terminator_true,
+    hookable: true
+  ).tap(&loggable).seekable.append(
+    CallableTree::Node::External.create(
+      matcher: animals_xml_matcher,
+      caller: animals_xml_caller,
+      hookable: true
+    ).tap(&loggable).verbosify,
+    CallableTree::Node::External.create(
+      matcher: fruits_xml_matcher,
+      caller: fruits_xml_caller,
+      hookable: true
+    ).tap(&loggable).verbosify
+  )
+)
+
+# === Execution ===
+
+Dir.glob("#{__dir__}/../docs/*") do |file|
+  options = { foo: :bar }
+  pp tree.call(file, **options)
+  puts '---'
+end

data/lib/callable_tree/node/external/pod.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CallableTree
+  module Node
+    module External
+      # Pod: A node that can be instantiated directly with proc-based behavior.
+      # Provides an alternative to Builder style for inline node creation.
+      #
+      # Usage patterns:
+      #   Constructor style: Pod.new(caller: ->(input, **) { input * 2 })
+      #   Factory style: External.create(caller: ->(input, **) { input * 2 })
+      #   Block style: External.create { |node| node.caller { |input, **| input * 2 } }
+      class Pod
+        include External
+
+        def initialize(matcher: nil, caller: nil, terminator: nil, identifier: nil)
+          @_matcher = matcher
+          @_caller = caller
+          @_terminator = terminator
+          @_identifier = identifier
+
+          yield self if block_given?
+        end
+
+        # DSL setters for block syntax
+        def matcher(proc = nil, &block)
+          @_matcher = proc || block
+          self
+        end
+
+        def caller(proc = nil, &block)
+          @_caller = proc || block
+          self
+        end
+
+        def terminator(proc = nil, &block)
+          @_terminator = proc || block
+          self
+        end
+
+        def identifier(proc = nil, &block)
+          @_identifier = proc || block
+          self
+        end
+
+        def match?(*inputs, **options)
+          return super unless @_matcher
+
+          @_matcher.call(*inputs, **options, _node_: self) do |*a, **o|
+            super(*a, **o)
+          end
+        end
+
+        def call(*inputs, **options)
+          raise ::CallableTree::Error, 'caller is not set' unless @_caller
+
+          @_caller.call(*inputs, **options, _node_: self) do |*a, **o|
+            super(*a, **o)
+          end
+        end
+
+        def terminate?(output, *inputs, **options)
+          return super unless @_terminator
+
+          @_terminator.call(output, *inputs, **options, _node_: self) do |o, *a, **opts|
+            super(o, *a, **opts)
+          end
+        end
+
+        def identity
+          return super unless @_identifier
+
+          @_identifier.call(_node_: self) { super }
+        end
+      end
+
+      # HookablePod: Pod with Hooks support (before/around/after callbacks).
+      class HookablePod < Pod
+        prepend Hooks::Matcher
+        prepend Hooks::Caller
+        prepend Hooks::Terminator
+      end
+
+      # Factory method
+      def self.create(matcher: nil, caller: nil, terminator: nil, identifier: nil, hookable: false, &block)
+        klass = hookable ? HookablePod : Pod
+        klass.new(matcher: matcher, caller: caller, terminator: terminator, identifier: identifier, &block)
+      end
+    end
+  end
+end

data/lib/callable_tree/node/internal/pod.rb

@@ -0,0 +1,91 @@
+# frozen_string_literal: true
+
+module CallableTree
+  module Node
+    module Internal
+      # Pod: A node that can be instantiated directly with proc-based behavior.
+      # Provides an alternative to Builder style for inline node creation.
+      #
+      # Usage patterns:
+      #   Constructor style: Pod.new(caller: ->(input, **) { input * 2 })
+      #   Factory style: Internal.create(caller: ->(input, **) { input * 2 })
+      #   Block style: Internal.create { |node| node.caller { |input, **| input * 2 } }
+      class Pod
+        include Internal
+
+        def initialize(matcher: nil, caller: nil, terminator: nil, identifier: nil)
+          @_matcher = matcher
+          @_caller = caller
+          @_terminator = terminator
+          @_identifier = identifier
+
+          yield self if block_given?
+        end
+
+        # DSL setters for block syntax
+        def matcher(proc = nil, &block)
+          @_matcher = proc || block
+          self
+        end
+
+        def caller(proc = nil, &block)
+          @_caller = proc || block
+          self
+        end
+
+        def terminator(proc = nil, &block)
+          @_terminator = proc || block
+          self
+        end
+
+        def identifier(proc = nil, &block)
+          @_identifier = proc || block
+          self
+        end
+
+        def match?(*inputs, **options)
+          return super unless @_matcher
+
+          @_matcher.call(*inputs, **options, _node_: self) do |*a, **o|
+            super(*a, **o)
+          end
+        end
+
+        def call(*inputs, **options)
+          return super unless @_caller
+
+          @_caller.call(*inputs, **options, _node_: self) do |*a, **o|
+            super(*a, **o)
+          end
+        end
+
+        def terminate?(output, *inputs, **options)
+          return super unless @_terminator
+
+          @_terminator.call(output, *inputs, **options, _node_: self) do |o, *a, **opts|
+            super(o, *a, **opts)
+          end
+        end
+
+        def identity
+          return super unless @_identifier
+
+          @_identifier.call(_node_: self) { super }
+        end
+      end
+
+      # HookablePod: Pod with Hooks support (before/around/after callbacks).
+      class HookablePod < Pod
+        prepend Hooks::Matcher
+        prepend Hooks::Caller
+        prepend Hooks::Terminator
+      end
+
+      # Factory method
+      def self.create(matcher: nil, caller: nil, terminator: nil, identifier: nil, hookable: false, &block)
+        klass = hookable ? HookablePod : Pod
+        klass.new(matcher: matcher, caller: caller, terminator: terminator, identifier: identifier, &block)
+      end
+    end
+  end
+end

data/lib/callable_tree/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module CallableTree
-  VERSION = '0.3.11'
+  VERSION = '0.3.12'
 end

data/lib/callable_tree.rb

@@ -18,6 +18,8 @@ require_relative 'callable_tree/node/internal/strategizable'
 require_relative 'callable_tree/node/external/verbose'
 require_relative 'callable_tree/node/external'
 require_relative 'callable_tree/node/internal'
+require_relative 'callable_tree/node/external/pod'
+require_relative 'callable_tree/node/internal/pod'
 require_relative 'callable_tree/node/builder'
 require_relative 'callable_tree/node/internal/builder'
 require_relative 'callable_tree/node/external/builder'

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: callable_tree
 version: !ruby/object:Gem::Version
-  version: 0.3.11
+  version: 0.3.12
 platform: ruby
 authors:
 - jsmmr
@@ -9,9 +9,12 @@ bindir: exe
 cert_chain: []
 date: 1980-01-02 00:00:00.000000000 Z
 dependencies: []
-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.
+description: |
+  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.
 email:
 - jsmmr@icloud.com
 executables: []
@@ -54,17 +57,26 @@ files:
 - examples/docs/animals.xml
 - examples/docs/fruits.json
 - examples/docs/fruits.xml
+- examples/factory/external-verbosify.rb
+- examples/factory/hooks.rb
+- examples/factory/identity.rb
+- examples/factory/internal-broadcastable.rb
+- examples/factory/internal-composable.rb
+- examples/factory/internal-seekable.rb
+- examples/factory/logging.rb
 - lib/callable_tree.rb
 - lib/callable_tree/node.rb
 - lib/callable_tree/node/builder.rb
 - lib/callable_tree/node/external.rb
 - lib/callable_tree/node/external/builder.rb
+- lib/callable_tree/node/external/pod.rb
 - lib/callable_tree/node/external/verbose.rb
 - lib/callable_tree/node/hooks/caller.rb
 - lib/callable_tree/node/hooks/matcher.rb
 - lib/callable_tree/node/hooks/terminator.rb
 - lib/callable_tree/node/internal.rb
 - lib/callable_tree/node/internal/builder.rb
+- lib/callable_tree/node/internal/pod.rb
 - lib/callable_tree/node/internal/strategizable.rb
 - lib/callable_tree/node/internal/strategy.rb
 - lib/callable_tree/node/internal/strategy/broadcast.rb
@@ -79,7 +91,7 @@ licenses:
 metadata:
   homepage_uri: https://github.com/jsmmr/ruby_callable_tree
   source_code_uri: https://github.com/jsmmr/ruby_callable_tree
-  changelog_uri: https://github.com/jsmmr/ruby_callable_tree/blob/v0.3.11/CHANGELOG.md
+  changelog_uri: https://github.com/jsmmr/ruby_callable_tree/blob/v0.3.12/CHANGELOG.md
   rubygems_mfa_required: 'true'
 rdoc_options: []
 require_paths:
@@ -97,7 +109,6 @@ required_rubygems_version: !ruby/object:Gem::Requirement
 requirements: []
 rubygems_version: 4.0.3
 specification_version: 4
-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.
+summary: Builds executable trees of callable nodes with flexible strategies like seek,
+  broadcast, and compose.
 test_files: []