walkabout 0.3.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: bb6d40e1b5e2ed9cce8ec9546160fcc140db88d7a832f7f49a9864e801e67c86
+  data.tar.gz: 06eb640637694a06b5f6bf7d32ef02bfb74cda68b3b1b9f29844eb2ccc1affa9
+SHA512:
+  metadata.gz: 7d16e23d55b2b8ceb2c5a3aef3c54037a7ed6ec7a77b9d3b130cb060486c66cd291d822496f3be80cf4aab7a11142a7cc880d5ca5ea092c7545301b79a678e4d
+  data.tar.gz: d7d6548a4c0a4bf81f9f0e33d1969b7ac92dcda796b73aa92da9d1e2f4512c8bcf44ddfee949b57728bb2a390c6363614d312659aa0604168d408958d60d81dd

data/CHANGELOG

@@ -0,0 +1,40 @@
+# walkabout/CHANGELOG
+
+## 20261024
+
+0.3.0: + cycle detection; + walkabout(.rb).gemspec
+
+1. + lib/walkabout.rb
+2. + lib/Walkabout/CycleError.rb: CycleError#nodes, the nodes on a cycle, or on a path between two
+3. ~ DAG#initialize: + check_for_cycles, raising CycleError. A cycle left none of its nodes ever ready, so complete? was true with them not done.
+4. + DAG#cyclic_nodes, + DAG#nodes_with_predecessor_and_successor_among
+5. ~ DAG.parse: flat_map, rather than map for its side effect
+6. ~ DAG.parse_sequence: each_cons(2).to_a
+7. + lib/Walkabout/VERSION.rb
+8. + test/Walkabout/DAG_test.rb, + test/Walkabout/Node_test.rb
+9. + walkabout.gemspec, + walkabout.rb.gemspec: the same gem published under both names
+10. + Rakefile, + README.md, + CHANGELOG, + LICENSE, + TODO
+
+
+## 20260428
+
+0.2.0: /Walkabout::DAG::Node/Walkabout::Node/; nodes held per DAG; /DAG#next/DAG#take/
+
+1. + lib/Walkabout/Node.rb: Node, out of DAG, + Node#name
+2. ~ DAG#initialize: nodes held in @nodes, rather than on the Node class, so that more than one DAG may exist at once
+3. /DAG#next/DAG#take/: take(n) hands out up to n ready nodes
+4. ~ DAG#ready: private
+5. - lib/Walkabout/DAG.rb: the example
+
+
+## 20260423
+
+0.1.0: + Walkabout::DAG::Node; + DAG#ready, #next, #complete?
+
+1. + DAG::Node: predecessors, complete!, complete?
+2. ~ DAG.parse: returns a DAG, rather than the edges
+3. ~ lib/Walkabout/DAG.rb: the example takes the next node and completes it
+
+0.0.0: + Walkabout::DAG.parse
+
+1. + lib/Walkabout/DAG.rb: DAG.parse, and an example of it parsing three sequences

data/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 thoran
+
+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,98 @@
+# walkabout
+
+Walk a directed acyclic graph in dependency order.
+
+## Installation
+
+```
+gem install walkabout
+```
+
+Or add to your Gemfile:
+
+```ruby
+gem 'walkabout'
+```
+
+## Usage
+
+```ruby
+require 'walkabout'
+```
+
+### Building a DAG
+
+From edges, each a pair of predecessor and successor:
+
+```ruby
+dag = Walkabout::DAG.new([[:a, :b], [:b, :c], [:d, :b]])
+```
+
+Or from sequences, each of which is read as edges between its consecutive
+members, and which join at the members they share:
+
+```ruby
+dag = Walkabout::DAG.parse([
+  [:a, :b, :c],
+  [:d, :b, :e],
+  [:f, :g]
+])
+```
+
+Nodes are made from the names in the edges, and so a node appears only where it
+is in at least one edge.
+
+### Walking it
+
+A node is ready once it is incomplete and each of its predecessors is complete.
+`take` hands out the first ready node, or `nil`; `take(n)` up to n of them, as
+an array:
+
+```ruby
+while (node = dag.take)
+  puts node.name
+  node.complete!
+end
+dag.complete?  # => true
+```
+
+`take` does not record that a node has been handed out, so a node taken and not
+yet completed is handed out again. A batch from `take(n)` is therefore to be
+completed before the next is taken.
+
+### Cycles
+
+A DAG with a cycle raises `Walkabout::CycleError` when it is built, rather than
+leaving the nodes on the cycle never ready. Its `nodes` are the nodes on the
+cycle, or on a path between two cycles:
+
+```ruby
+Walkabout::DAG.new([[:x, :a], [:a, :b], [:b, :a]])
+# => Walkabout::CycleError: cycle among: a, b
+```
+
+### Subclassing
+
+`Walkabout::Node` and `Walkabout::DAG` are meant to be subclassed, a node
+carrying whatever the walk is to do:
+
+```ruby
+class Step < Walkabout::Node
+  def run
+    puts "running #{name}"
+    complete!
+  end
+end
+```
+
+## Contributing
+
+1. Fork it [https://github.com/thoran/walkabout/fork](https://github.com/thoran/walkabout/fork)
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create a new pull request
+
+## License
+
+MIT

data/Rakefile

@@ -0,0 +1,7 @@
+require 'rake/testtask'
+
+Rake::TestTask.new do |t|
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+task default: :test

data/lib/Walkabout/CycleError.rb

@@ -0,0 +1,15 @@
+# Walkabout/CycleError.rb
+# Walkabout::CycleError
+
+module Walkabout
+  class CycleError < StandardError
+    attr_reader :nodes
+
+    private
+
+    def initialize(nodes)
+      @nodes = nodes
+      super("cycle among: #{nodes.map(&:name).join(', ')}")
+    end
+  end
+end

data/lib/Walkabout/DAG.rb

@@ -0,0 +1,78 @@
+# Walkabout/DAG.rb
+# Walkabout::DAG
+
+require_relative 'CycleError'
+require_relative 'Node'
+
+module Walkabout
+  class DAG
+    class << self
+      def parse(sequences)
+        self.new(sequences.flat_map{|s| parse_sequence(s)})
+      end
+
+      private
+
+      def parse_sequence(sequence)
+        sequence.each_cons(2).to_a
+      end
+    end # class << self
+
+    def take(n = nil)
+      if n
+        ready.first(n)
+      else
+        ready.first
+      end
+    end
+
+    def complete?
+      ready.empty?
+    end
+
+    private
+
+    def initialize(edges)
+      @nodes = build_nodes(edges)
+      check_for_cycles
+    end
+
+    def build_nodes(edges)
+      nodes = {}
+      edges.each do |a, b|
+        predecessor = (nodes[a] ||= Node.new(a))
+        successor = (nodes[b] ||= Node.new(b))
+        successor.predecessors << predecessor
+      end
+      nodes.values
+    end
+
+    def check_for_cycles
+      nodes = cyclic_nodes
+      raise CycleError.new(nodes) unless nodes.empty?
+    end
+
+    # Trims, until nothing more goes, every node with no predecessor or no
+    # successor left among those remaining. Only nodes on a cycle, or on a path
+    # between two, survive.
+    def cyclic_nodes
+      nodes = @nodes
+      while (trimmed = nodes_with_predecessor_and_successor_among(nodes)) != nodes
+        nodes = trimmed
+      end
+      nodes
+    end
+
+    def nodes_with_predecessor_and_successor_among(nodes)
+      nodes.select do |node|
+        node.predecessors.any?{|p| nodes.include?(p)} && nodes.any?{|n| n.predecessors.include?(node)}
+      end
+    end
+
+    def ready
+      @nodes.select do |n|
+        !n.complete? && n.predecessors.all?(&:complete?)
+      end
+    end
+  end
+end

data/lib/Walkabout/Node.rb

@@ -0,0 +1,25 @@
+# Walkabout/Node.rb
+# Walkabout::Node
+
+module Walkabout
+  class Node
+    attr_accessor :name
+    attr_accessor :predecessors
+
+    def complete!
+      @complete = true
+    end
+
+    def complete?
+      @complete
+    end
+
+    private
+
+    def initialize(name, predecessors = [])
+      @name = name
+      @predecessors = predecessors
+      @complete = false
+    end
+  end
+end

data/lib/Walkabout/VERSION.rb

@@ -0,0 +1,6 @@
+# Walkabout/VERSION.rb
+# Walkabout::VERSION
+
+module Walkabout
+  VERSION = '0.3.0'
+end

data/lib/walkabout.rb

@@ -0,0 +1,6 @@
+# walkabout.rb
+
+require_relative './Walkabout/CycleError'
+require_relative './Walkabout/DAG'
+require_relative './Walkabout/Node'
+require_relative './Walkabout/VERSION'

data/test/Walkabout/DAG_test.rb

@@ -0,0 +1,87 @@
+# test/Walkabout/DAG_test.rb
+
+require 'minitest/autorun'
+
+require_relative '../../lib/Walkabout/DAG'
+
+describe Walkabout::DAG do
+  def names(nodes)
+    nodes.map(&:name)
+  end
+
+  describe '.parse' do
+    it 'turns each sequence into edges between consecutive members' do
+      dag = Walkabout::DAG.parse([[:a, :b, :c], [:d, :b, :e]])
+      _(names(dag.take(5))).must_equal [:a, :d]
+    end
+
+    it 'joins sequences at the members they share' do
+      dag = Walkabout::DAG.parse([[:a, :b], [:c, :b]])
+      dag.take.complete!
+      _(names(dag.take(5))).must_equal [:c]
+      dag.take.complete!
+      _(names(dag.take(5))).must_equal [:b]
+    end
+  end
+
+  describe '#take' do
+    it 'returns the first ready node when given no count' do
+      dag = Walkabout::DAG.new([[:a, :b]])
+      _(dag.take.name).must_equal :a
+    end
+
+    it 'returns up to n ready nodes when given a count' do
+      dag = Walkabout::DAG.parse([[:a, :d], [:b, :d], [:c, :d]])
+      _(names(dag.take(2))).must_equal [:a, :b]
+    end
+
+    it 'returns a node only once its predecessors are complete' do
+      dag = Walkabout::DAG.parse([[:a, :b, :c]])
+      _(names(dag.take(5))).must_equal [:a]
+      dag.take.complete!
+      _(names(dag.take(5))).must_equal [:b]
+    end
+
+    it 'returns nil, or an empty array, when nothing is ready' do
+      dag = Walkabout::DAG.new([])
+      _(dag.take).must_be_nil
+      _(dag.take(2)).must_equal []
+    end
+  end
+
+  describe '#complete?' do
+    it 'is false while any node is incomplete' do
+      dag = Walkabout::DAG.new([[:a, :b]])
+      dag.take.complete!
+      _(dag.complete?).must_equal false
+    end
+
+    it 'is true once every node is complete' do
+      dag = Walkabout::DAG.parse([[:a, :b, :c], [:d, :b]])
+      while (node = dag.take)
+        node.complete!
+      end
+      _(dag.complete?).must_equal true
+    end
+  end
+
+  describe 'cycles' do
+    it 'raises CycleError for a cycle' do
+      _{Walkabout::DAG.new([[:a, :b], [:b, :a]])}.must_raise Walkabout::CycleError
+    end
+
+    it 'raises CycleError for a node which is its own predecessor' do
+      _{Walkabout::DAG.new([[:a, :a]])}.must_raise Walkabout::CycleError
+    end
+
+    it 'names only the nodes on the cycle, and not those before or after it' do
+      error = _{Walkabout::DAG.parse([[:x, :a, :b, :c, :a], [:c, :y]])}.must_raise Walkabout::CycleError
+      _(names(error.nodes).sort).must_equal [:a, :b, :c]
+      _(error.message).must_equal 'cycle among: a, b, c'
+    end
+
+    it 'does not raise where paths diverge and rejoin' do
+      _(Walkabout::DAG.parse([[:a, :b, :d], [:a, :c, :d]]).take.name).must_equal :a
+    end
+  end
+end

data/test/Walkabout/Node_test.rb

@@ -0,0 +1,29 @@
+# test/Walkabout/Node_test.rb
+
+require 'minitest/autorun'
+
+require_relative '../../lib/Walkabout/Node'
+
+describe Walkabout::Node do
+  describe '.new' do
+    it 'has a name' do
+      _(Walkabout::Node.new(:a).name).must_equal :a
+    end
+
+    it 'has no predecessors by default' do
+      _(Walkabout::Node.new(:a).predecessors).must_equal []
+    end
+
+    it 'is not complete' do
+      _(Walkabout::Node.new(:a).complete?).must_equal false
+    end
+  end
+
+  describe '#complete!' do
+    it 'makes the node complete' do
+      node = Walkabout::Node.new(:a)
+      node.complete!
+      _(node.complete?).must_equal true
+    end
+  end
+end

data/walkabout.gemspec

@@ -0,0 +1,38 @@
+require_relative './lib/Walkabout/VERSION'
+
+class Gem::Specification
+  def development_dependencies=(gems)
+    gems.each{|gem| add_development_dependency(*gem)}
+  end
+end
+
+Gem::Specification.new do |spec|
+  spec.name = 'walkabout'
+  spec.version = Walkabout::VERSION
+
+  spec.summary = "Walk a directed acyclic graph in dependency order."
+  spec.description = "Walk a directed acyclic graph in dependency order. A DAG built from edges, or from sequences, hands out the nodes whose predecessors are complete, singly or in batches, and refuses a graph with a cycle."
+
+  spec.author = 'thoran'
+  spec.email = 'code@thoran.com'
+  spec.homepage = 'https://github.com/thoran/walkabout'
+  spec.license = 'MIT'
+
+  spec.required_ruby_version = '>= 3'
+  spec.require_paths = ['lib']
+
+  spec.files = [
+    'walkabout.gemspec',
+    Dir['lib/**/*.rb'],
+    Dir['test/**/*.rb'],
+    'CHANGELOG',
+    'LICENSE',
+    'Rakefile',
+    'README.md',
+  ].flatten
+
+  spec.development_dependencies = %w{
+    rake
+    minitest
+  }
+end

metadata

@@ -0,0 +1,81 @@
+--- !ruby/object:Gem::Specification
+name: walkabout
+version: !ruby/object:Gem::Version
+  version: 0.3.0
+platform: ruby
+authors:
+- thoran
+bindir: bin
+cert_chain: []
+date: 1980-01-02 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: Walk a directed acyclic graph in dependency order. A DAG built from edges,
+  or from sequences, hands out the nodes whose predecessors are complete, singly or
+  in batches, and refuses a graph with a cycle.
+email: code@thoran.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- CHANGELOG
+- LICENSE
+- README.md
+- Rakefile
+- lib/Walkabout/CycleError.rb
+- lib/Walkabout/DAG.rb
+- lib/Walkabout/Node.rb
+- lib/Walkabout/VERSION.rb
+- lib/walkabout.rb
+- test/Walkabout/DAG_test.rb
+- test/Walkabout/Node_test.rb
+- walkabout.gemspec
+homepage: https://github.com/thoran/walkabout
+licenses:
+- MIT
+metadata: {}
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 4.0.22
+specification_version: 4
+summary: Walk a directed acyclic graph in dependency order.
+test_files: []