Merge branch 'develop'

* develop:
  chore: prepare release 0.3.12
  docs(examples): add commented gem require line for easy switching
  feat(factory): add Factory style for inline node creation
  docs(agents): improve documentation with hooks, verbosify, and examples details
  docs(readme): add conceptual overview
  docs(gemspec): update summary and description

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

@@ -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.

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!`.`

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`

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')

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'
 

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

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'
 

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.

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.