Merge branch 'feature/factory-style' into develop

* feature/factory-style:
  feat(factory): add Factory style for inline node creation

Author: jsmmr

.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

AGENTS.md

@@ -30,6 +30,7 @@
 - `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
@@ -52,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.

CHANGELOG.md

@@ -1,5 +1,11 @@
 ## [Unreleased]
 
+- Add Factory style for inline node creation as a third option alongside Class and Builder styles.
+  - `CallableTree::Node::External::Pod` and `CallableTree::Node::Internal::Pod` classes
+  - `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!`.`

README.md

@@ -36,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)
 
@@ -261,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.
@@ -407,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.
@@ -554,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`

callable_tree.gemspec

@@ -9,7 +9,13 @@ Gem::Specification.new do |spec|
   spec.email         = ['jsmmr@icloud.com']
 
   spec.summary       = 'Builds executable trees of callable nodes with flexible strategies like seek, broadcast, and compose.'
-  spec.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 both class-based and builder-style definitions.'
+  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')

examples/factory/external-verbosify.rb

@@ -0,0 +1,68 @@
+# frozen_string_literal: true
+
+require_relative '../../lib/callable_tree'
+require 'json'
+require 'rexml/document'
+
+# Verbosify example using Pod 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