philiprehberger-tree 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bd37f9905975c79b4fa407d42276f950c4a267bf3133127f7c631139fe1d4b3e
+  data.tar.gz: b88f671ca4f70ff37dd929decb5fe063e0080bccbe4bd789c01140d48e4a9942
+SHA512:
+  metadata.gz: 6b20812cb1d392ea095dbbe2a2752e76b037f739703ea696de6d79b0dcac69dc47a2210534470f0902191ac611d8c478a57eb85aee95d0a42e86b674f2429b06
+  data.tar.gz: b03f869248187d0e481b122500768bb69ed89587d5cd75653f46e070e737bb50e719fad2debd9d9191a6ede94afc0a35283d04a30bf1330ed6fb979fe91836eb

data/CHANGELOG.md

@@ -0,0 +1,22 @@
+# Changelog
+
+All notable changes to this gem will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [Unreleased]
+
+## [0.1.0] - 2026-03-22
+
+### Added
+- Initial release
+- Generic tree node with value, children, and parent tracking
+- Depth-first (pre-order) and breadth-first traversal
+- Node search with predicate block
+- Path finding from root to target value
+- Leaf node collection
+- Tree metrics: depth, height, and size
+- Hash serialization via `to_h`
+- Visual tree printing via `print_tree`
+- Add and remove child operations

data/LICENSE

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

data/README.md

@@ -0,0 +1,109 @@
+# philiprehberger-tree
+
+[![Tests](https://github.com/philiprehberger/rb-tree/actions/workflows/ci.yml/badge.svg)](https://github.com/philiprehberger/rb-tree/actions/workflows/ci.yml)
+[![Gem Version](https://badge.fury.io/rb/philiprehberger-tree.svg)](https://rubygems.org/gems/philiprehberger-tree)
+[![License](https://img.shields.io/github/license/philiprehberger/rb-tree)](LICENSE)
+
+Generic tree data structure with traversal, search, and serialization
+
+## Requirements
+
+- Ruby >= 3.1
+
+## Installation
+
+Add to your Gemfile:
+
+```ruby
+gem "philiprehberger-tree"
+```
+
+Or install directly:
+
+```bash
+gem install philiprehberger-tree
+```
+
+## Usage
+
+```ruby
+require "philiprehberger/tree"
+
+root = Philiprehberger::Tree::Node.new('root')
+child = root.add_child('child')
+child.add_child('grandchild')
+
+root.size      # => 3
+root.height    # => 2
+root.leaf?     # => false
+child.depth    # => 1
+```
+
+### Traversal
+
+```ruby
+root.each_dfs { |node| puts node.value }   # depth-first pre-order
+root.each_bfs { |node| puts node.value }   # breadth-first
+```
+
+### Search and Path Finding
+
+```ruby
+node = root.find { |n| n.value == 'grandchild' }
+path = root.path_to('grandchild')
+path.map(&:value)  # => ['root', 'child', 'grandchild']
+```
+
+### Serialization
+
+```ruby
+root.to_h
+# => { value: 'root', children: [{ value: 'child', children: [...] }] }
+
+puts root.print_tree
+# root
+# └── child
+#     └── grandchild
+```
+
+### Leaf Collection
+
+```ruby
+root.leaves.map(&:value)  # => ['grandchild']
+```
+
+## API
+
+### `Node`
+
+| Method | Description |
+|--------|-------------|
+| `.new(value)` | Create a new tree node |
+| `#add_child(value)` | Add a child node and return it |
+| `#remove_child(value)` | Remove a child by value |
+| `#children` | Array of child nodes |
+| `#parent` | Parent node or nil |
+| `#root?` | True if node has no parent |
+| `#leaf?` | True if node has no children |
+| `#depth` | Distance from root |
+| `#height` | Height of subtree |
+| `#size` | Total nodes in subtree |
+| `#each_dfs` | Depth-first pre-order iteration |
+| `#each_bfs` | Breadth-first iteration |
+| `#find { \|n\| }` | Find first node matching predicate |
+| `#path_to(value)` | Array of nodes from root to target |
+| `#leaves` | All leaf nodes in subtree |
+| `#to_h` | Serialize subtree to hash |
+| `#print_tree` | Visual string representation |
+
+## Development
+
+```bash
+bundle install
+bundle exec rspec      # Run tests
+bundle exec rubocop    # Check code style
+```
+
+## License
+
+MIT

data/lib/philiprehberger/tree/node.rb

@@ -0,0 +1,182 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Tree
+    # A generic tree node with traversal, search, and serialization.
+    class Node
+      # @return [Object] the value stored in this node
+      attr_reader :value
+
+      # @return [Array<Node>] child nodes
+      attr_reader :children
+
+      # @return [Node, nil] parent node (nil for root)
+      attr_reader :parent
+
+      # Create a new tree node.
+      #
+      # @param value [Object] the value to store
+      def initialize(value)
+        @value = value
+        @children = []
+        @parent = nil
+      end
+
+      # Add a child node with the given value.
+      #
+      # @param value [Object] value for the new child node
+      # @return [Node] the newly created child node
+      def add_child(value)
+        child = value.is_a?(Node) ? value : Node.new(value)
+        child.instance_variable_set(:@parent, self)
+        @children << child
+        child
+      end
+
+      # Remove a child node by value.
+      #
+      # @param value [Object] value of the child to remove
+      # @return [Node, nil] the removed child node, or nil if not found
+      def remove_child(value)
+        index = @children.index { |c| c.value == value }
+        return nil unless index
+
+        child = @children.delete_at(index)
+        child.instance_variable_set(:@parent, nil)
+        child
+      end
+
+      # Check if this node is the root (has no parent).
+      #
+      # @return [Boolean]
+      def root?
+        @parent.nil?
+      end
+
+      # Check if this node is a leaf (has no children).
+      #
+      # @return [Boolean]
+      def leaf?
+        @children.empty?
+      end
+
+      # Return the depth of this node (distance from root).
+      #
+      # @return [Integer]
+      def depth
+        node = self
+        d = 0
+        while node.parent
+          d += 1
+          node = node.parent
+        end
+        d
+      end
+
+      # Return the height of the subtree rooted at this node.
+      #
+      # @return [Integer]
+      def height
+        return 0 if leaf?
+
+        1 + @children.map(&:height).max
+      end
+
+      # Return the total number of nodes in the subtree rooted at this node.
+      #
+      # @return [Integer]
+      def size
+        1 + @children.sum(&:size)
+      end
+
+      # Iterate depth-first (pre-order) over the subtree.
+      #
+      # @yield [Node] each node in depth-first order
+      # @return [Enumerator] if no block given
+      def each_dfs(&block)
+        return enum_for(:each_dfs) unless block
+
+        block.call(self)
+        @children.each { |child| child.each_dfs(&block) }
+      end
+
+      # Iterate breadth-first over the subtree.
+      #
+      # @yield [Node] each node in breadth-first order
+      # @return [Enumerator] if no block given
+      def each_bfs(&block)
+        return enum_for(:each_bfs) unless block
+
+        queue = [self]
+        until queue.empty?
+          node = queue.shift
+          block.call(node)
+          queue.concat(node.children)
+        end
+      end
+
+      # Find the first node matching the block.
+      #
+      # @yield [Node] predicate block
+      # @return [Node, nil] the first matching node, or nil
+      def find(&block)
+        return nil unless block
+
+        each_dfs { |node| return node if block.call(node) }
+        nil
+      end
+
+      # Return the path from root to the first node with the given value.
+      #
+      # @param value [Object] value to search for
+      # @return [Array<Node>, nil] array of nodes from root to target, or nil if not found
+      def path_to(value)
+        target = find { |n| n.value == value }
+        return nil unless target
+
+        path = []
+        node = target
+        while node
+          path.unshift(node)
+          node = node.parent
+        end
+        path
+      end
+
+      # Return all leaf nodes in the subtree.
+      #
+      # @return [Array<Node>]
+      def leaves
+        each_dfs.select(&:leaf?)
+      end
+
+      # Serialize the subtree to a hash.
+      #
+      # @return [Hash] hash with :value and :children keys
+      def to_h
+        {
+          value: @value,
+          children: @children.map(&:to_h)
+        }
+      end
+
+      # Print a visual representation of the tree.
+      #
+      # @param indent [String] prefix for indentation (used internally)
+      # @param last [Boolean] whether this is the last sibling (used internally)
+      # @return [String] the tree as a formatted string
+      def print_tree(indent: '', last: true)
+        lines = []
+        connector = root? ? '' : (last ? '└── ' : '├── ')
+        lines << "#{indent}#{connector}#{@value}"
+
+        child_indent = indent + (root? ? '' : (last ? '    ' : '│   '))
+        @children.each_with_index do |child, i|
+          lines << child.print_tree(indent: child_indent, last: i == @children.size - 1)
+        end
+
+        lines.join("\n")
+      end
+    end
+  end
+end

data/lib/philiprehberger/tree/version.rb

@@ -0,0 +1,7 @@
+# frozen_string_literal: true
+
+module Philiprehberger
+  module Tree
+    VERSION = '0.1.0'
+  end
+end

data/lib/philiprehberger/tree.rb

@@ -0,0 +1,10 @@
+# frozen_string_literal: true
+
+require_relative 'tree/version'
+require_relative 'tree/node'
+
+module Philiprehberger
+  module Tree
+    class Error < StandardError; end
+  end
+end

metadata

@@ -0,0 +1,56 @@
+--- !ruby/object:Gem::Specification
+name: philiprehberger-tree
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Philip Rehberger
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2026-03-22 00:00:00.000000000 Z
+dependencies: []
+description: A generic tree data structure supporting depth-first and breadth-first
+  traversal, node search, path finding, and hash serialization. Each node tracks its
+  parent, children, depth, height, and size.
+email:
+- me@philiprehberger.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG.md
+- LICENSE
+- README.md
+- lib/philiprehberger/tree.rb
+- lib/philiprehberger/tree/node.rb
+- lib/philiprehberger/tree/version.rb
+homepage: https://github.com/philiprehberger/rb-tree
+licenses:
+- MIT
+metadata:
+  homepage_uri: https://github.com/philiprehberger/rb-tree
+  source_code_uri: https://github.com/philiprehberger/rb-tree
+  changelog_uri: https://github.com/philiprehberger/rb-tree/blob/main/CHANGELOG.md
+  bug_tracker_uri: https://github.com/philiprehberger/rb-tree/issues
+  rubygems_mfa_required: 'true'
+post_install_message:
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.5.22
+signing_key:
+specification_version: 4
+summary: Generic tree data structure with traversal, search, and serialization
+test_files: []