ceedling 1.2.0 → 1.2.2

data/lib/ceedling/filesystem/file_tree.rb

@@ -0,0 +1,241 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'fileutils'
+require 'ceedling/constants'
+require 'ceedling/exceptions'
+
+# Walks and copies trees of regular files without `lstat`. On some filesystems `lstat`
+# reports a regular file as a directory, and any copy that classifies by it puts a directory
+# where the file belongs. FileTree lists a directory with `Dir.children`, which reads names
+# without glob syntax, and classifies each entry with `File.stat`, which follows links.
+#
+# Links in a source tree are followed, and a copy holds only regular files and directories.
+# A link loop or a dangling link raises rather than copying part of a tree.
+#
+# This is best effort. It removes the dependence on `lstat`, and trusts `stat` in its place.
+module FileTree
+
+  # Errors that clear on their own, such as a scanner or a sync client holding a file open.
+  # Any other error fails a copy at once.
+  TRANSIENT_ERRORS = %i[EACCES EBUSY EPERM EINTR].filter_map { |name| Errno.const_get( name ) if Errno.const_defined?( name ) }.freeze
+
+  Result = Struct.new( :copied, :unchanged, :healed, keyword_init: true )
+
+  # Yields each regular file below `root` as its path relative to `root` and its full path,
+  # sorted within each directory. Returns an Enumerator without a block. An entry whose name
+  # `skip` accepts is neither yielded nor entered.
+  def self.each_file(root, skip: nil)
+    return enum_for( :each_file, root, skip: skip ) unless block_given?
+
+    each_entry( root, skip: skip ) { |relative, path, directory| yield( relative, path ) unless directory }
+  end
+
+  # Yields each directory and regular file below `root`, a directory ahead of its contents,
+  # as its relative path, its full path, and whether it is a directory
+  def self.each_entry(root, skip: nil, &block)
+    raise CeedlingException, "'#{root}' is not a directory" unless File.directory?( root )
+
+    walk( root, nil, [real_path( root )], skip, &block )
+  end
+
+  # Brings every file below `source` up to date below `destination` and returns a Result. A
+  # file that matches its source is left alone. One that differs or is missing is written by
+  # `publish`, a callable given the source and destination paths. A directory where a file
+  # belongs, or a file where a directory belongs, is removed first. Files `destination` has
+  # beyond `source` are left alone.
+  #
+  # `publish` is retried after each of `retry_delays` on an error in TRANSIENT_ERRORS.
+  # `log`, when given, receives a message, a Verbosity, and a LogLabels value.
+  def self.sync(source, destination, publish:, retry_delays: [], sleep: Kernel.method( :sleep ), log: nil)
+    return Sync.new( publish: publish, retry_delays: retry_delays, sleep: sleep, log: log ).tree( source, destination )
+  end
+
+  # As .sync, for one regular file copied into `destination_dir`
+  def self.sync_file(source, destination_dir, publish:, retry_delays: [], sleep: Kernel.method( :sleep ), log: nil)
+    return Sync.new( publish: publish, retry_delays: retry_delays, sleep: sleep, log: log ).file( source, destination_dir )
+  end
+
+  def self.walk(dir, relative, ancestors, skip, &block)
+    names_in( dir ).each do |name|
+      next if skip&.call( name )
+
+      path  = File.join( dir, name )
+      entry = relative ? File.join( relative, name ) : name
+      next yield( entry, path, false ) unless directory_entry?( path )
+
+      yield( entry, path, true )
+      walk( path, entry, ancestors + [real_directory( path, ancestors )], skip, &block )
+    end
+  end
+
+  def self.names_in(dir)
+    return Dir.children( dir ).sort
+  rescue SystemCallError => e
+    raise CeedlingException, "'#{dir}' could not be listed ⏩️ #{e.message}"
+  end
+
+  # Whether a listed entry is a directory. Anything but a directory or a regular file raises.
+  def self.directory_entry?(path)
+    status = stat_of( path )
+    return true if status.directory?
+    return false if status.file?
+
+    raise CeedlingException, "'#{path}' is a #{status.ftype}, not a file or directory"
+  end
+
+  def self.stat_of(path)
+    return File.stat( path )
+  rescue Errno::ENOENT, Errno::ELOOP
+    raise CeedlingException, "'#{path}' is a dangling or unresolvable link"
+  rescue SystemCallError => e
+    raise CeedlingException, "'#{path}' could not be read ⏩️ #{e.message}"
+  end
+
+  def self.real_directory(path, ancestors)
+    real = real_path( path )
+    raise CeedlingException, "Link loop: '#{path}' resolves to its own ancestor '#{real}'" if ancestors.include?( real )
+
+    return real
+  end
+
+  # A directory's real path, for finding loops. A path that cannot be resolved stands for
+  # itself, so the walk goes on without that safeguard rather than stopping.
+  def self.real_path(path)
+    return File.realpath( path )
+  rescue SystemCallError
+    return File.expand_path( path )
+  end
+
+  private_class_method :walk, :names_in, :directory_entry?, :stat_of, :real_directory, :real_path
+
+  # One copy's settings and tallies
+  class Sync
+    def initialize(publish:, retry_delays:, sleep:, log:)
+      @publish      = publish
+      @retry_delays = retry_delays
+      @sleep        = sleep
+      @log          = log
+      @result       = Result.new( copied: 0, unchanged: 0, healed: 0 )
+    end
+
+    def tree(source, destination)
+      raise CeedlingException, "'#{source}' is not a directory" unless File.directory?( source )
+
+      directory( destination )
+      FileTree.each_entry( source ) do |relative, path, is_directory|
+        target = File.join( destination, relative )
+        is_directory ? directory( target ) : publish_file( path, target )
+      end
+      return @result
+    end
+
+    def file(source, destination_dir)
+      raise CeedlingException, "'#{source}' is not a regular file" unless File.file?( source )
+
+      directory( destination_dir )
+      publish_file( source, File.join( destination_dir, File.basename( source ) ) )
+      return @result
+    end
+
+    private
+
+    # Destination checks follow links, as `stat` does, so they share the source side's view.
+    # A dangling link counts as a file.
+    def directory(path)
+      return if File.directory?( path )
+
+      with_retries( path ) do
+        heal( "Replaced a file where the directory '#{path}' belongs" ) { remove_file( path ) } if File.exist?( path ) || File.symlink?( path )
+        FileUtils.mkdir_p( path )
+      end
+    end
+
+    # Every step is retried, since a scanner or sync client can hold the destination too
+    def publish_file(source, destination)
+      with_retries( destination ) do
+        if File.directory?( destination )
+          heal( "Replaced a directory where the file '#{destination}' belongs" ) { remove_directory( destination ) }
+        elsif identical?( source, destination )
+          next @result.unchanged += 1
+        end
+
+        @publish.call( source, destination )
+        @result.copied += 1
+      end
+    end
+
+    # Counts and logs a heal the block reports it made
+    def heal(message)
+      return unless yield
+
+      @result.healed += 1
+      log( message, Verbosity::COMPLAIN, LogLabels::NOTICE )
+    end
+
+    # Whether this removed the file or link. An error removing it reaches the retries.
+    def remove_file(path)
+      File.unlink( path )
+      return true
+    rescue Errno::ENOENT
+      return false
+    end
+
+    # Whether this removed the directory, or the link to one. Another run healing the same
+    # entry may have removed it already, or published a file in its place, which this run
+    # then publishes over. An error removing it reaches the retries.
+    def remove_directory(path)
+      return remove_file( path ) if File.symlink?( path )
+
+      Dir.rmdir( path )
+      return true
+    rescue Errno::ENOENT, Errno::ENOTDIR
+      return false
+    rescue Errno::ENOTEMPTY, Errno::EEXIST
+      return remove_tree( path )
+    end
+
+    # FileUtils.rm_r classifies by `lstat`, so it is reached only for a directory with
+    # contents. It works on the destination, and never follows a link out of it.
+    def remove_tree(path)
+      FileUtils.rm_r( path )
+      return true
+    rescue Errno::ENOENT
+      return false
+    end
+
+    def identical?(source, destination)
+      return File.file?( destination ) && File.size( source ) == File.size( destination ) && FileUtils.compare_file( source, destination )
+    end
+
+    def with_retries(destination)
+      delays = @retry_delays.dup
+      begin
+        yield
+      rescue *TRANSIENT_ERRORS => e
+        raise_exhausted( destination, e ) if delays.empty?
+
+        log( "Retrying copy to '#{destination}' after a transient error: #{e.message}", Verbosity::DEBUG, LogLabels::AUTO )
+        @sleep.call( delays.shift )
+        retry
+      end
+    end
+
+    def raise_exhausted(destination, error)
+      message = "Failed to copy to '#{destination}' after #{@retry_delays.size} retries ⏩️ #{error.message}\n" \
+                "Try deleting this project's build/ directory and rebuilding -- or, if the error names a " \
+                "path under your Ruby gem install, reinstall the ceedling gem."
+      log( message, Verbosity::ERRORS, LogLabels::AUTO )
+      raise CeedlingException, message
+    end
+
+    def log(message, verbosity, label)
+      @log&.call( message, verbosity, label )
+    end
+  end
+
+end

data/lib/ceedling/{file_wrapper.rb → filesystem/file_wrapper.rb}

@@ -17,6 +17,7 @@ require 'digest/sha2'
 require 'ceedling/constants'
 require 'ceedling/system_wrapper'
 require 'ceedling/exceptions'
+require 'ceedling/filesystem/file_tree'
 
 
 class FileWrapper
@@ -88,6 +89,13 @@ class FileWrapper
     return File.basename(path)
   end
 
+  # A file's status (size, modification time, ...), or nil when it can't be read
+  def stat(filepath)
+    return File.stat( filepath )
+  rescue SystemCallError
+    return nil
+  end
+
   def exist?(filepath)
     return true if (filepath == NULL_FILE_PATH)
     return File.exist?(filepath)
@@ -118,6 +126,13 @@ class FileWrapper
     return Dir.glob(glob, File::FNM_PATHNAME).sort()
   end
 
+  # Every regular file below dir as a full path, sorted. Unlike a glob, the walk classifies
+  # entries by `stat`, follows links, and reads names without pattern syntax (see FileTree).
+  # An entry whose name `skip` accepts is neither listed nor entered.
+  def tree_files(dir, skip: nil)
+    return FileTree.each_file( dir, skip: skip ).map { |_relative, path| path }.sort
+  end
+
   # Entry names within a single directory, `.` and `..` excluded.
   #
   # Complements `directory_listing()` for the case a glob cannot serve: matching a
@@ -238,34 +253,35 @@ class FileWrapper
     false
   end
 
-  # As #cp_r, but retries the whole copy on a transient OS-level error instead of
-  # surfacing it on the first attempt -- the same transient-visibility race
-  # #open_with_retry guards against, here hitting FileUtils.cp_r's own internal
-  # stat-then-open sequence on either the source or destination tree. A source/dest
-  # entry briefly reporting the wrong type (a directory where a file was just stat'd,
-  # or vice versa) mid-copy raises Errno::ENOTDIR/EISDIR from deep inside cp_r; a
-  # retry a moment later re-walks the tree fresh rather than trusting stale type info
-  # from the failed attempt. A failure that never clears still surfaces as a
-  # CeedlingException naming the destination and how many attempts were made, not a
-  # bare, unhelpful Errno.
-  def cp_r_with_retry(source, destination, options={})
-    attempts_remaining = TRANSIENT_IO_RETRY_DELAYS.dup
-    begin
-      cp_r(source, destination, options)
-    rescue SystemCallError => e
-      if attempts_remaining.empty?
-        msg = "Failed to copy into '#{destination}' after #{TRANSIENT_IO_RETRY_DELAYS.size} retries ⏩️ #{e.message}\n" \
-              "This path may be corrupted (a file exists where Ceedling expects a directory, or vice versa). " \
-              "Try deleting this project's build/ directory and rebuilding -- or, if the error names a path " \
-              "under your Ruby gem install, reinstall the ceedling gem."
-        @loginator.log(msg, Verbosity::ERRORS)
-        raise CeedlingException, msg
-      end
-      delay = attempts_remaining.shift
-      @loginator.log("Retrying copy into '#{destination}' after a transient error: #{e.message}", Verbosity::DEBUG)
-      sleep(delay)
-      retry
-    end
+  # Brings every file beneath source_dir up to date beneath destination_dir (see FileTree.sync).
+  # A file that already matches its source is not written, so a reader elsewhere never sees it
+  # change. One that differs or is missing is replaced whole (see #replace_file). An entry of
+  # the wrong type is replaced. Files the destination has beyond the source are left alone.
+  #
+  # A write is retried on an error that clears on its own, such as another process holding a
+  # file open on Windows. One that never clears surfaces as a CeedlingException naming the file.
+  def sync_tree(source_dir, destination_dir)
+    FileTree.sync( source_dir, destination_dir, **sync_options )
+  end
+
+  # As #sync_tree, for a single file copied into destination_dir
+  def sync_file(source, destination_dir)
+    FileTree.sync_file( source, destination_dir, **sync_options )
+  end
+
+  # Copies source to a temporary name beside destination, then renames it over destination.
+  # A concurrent reader sees the old file or the new one, never a partial one. The copy is
+  # owner-writable, and so is a destination file it replaces, since Windows refuses to rename
+  # over a read-only file. A destination link is replaced, and the file it names left alone.
+  def replace_file(source, destination)
+    temp = File.join( File.dirname( destination ), ".#{File.basename( destination )}.#{Process.pid}.#{Thread.current.object_id}.tmp" )
+    check_path_length( temp, origin: 'FileWrapper#replace_file' )
+    FileUtils.cp( source, temp )
+    owner_writable( temp )
+    owner_writable( destination ) if File.file?( destination ) && !File.symlink?( destination )
+    File.rename( temp, destination )
+  ensure
+    FileUtils.rm_f( temp ) if temp
   end
 
   def read(filepath, length=nil)
@@ -330,6 +346,13 @@ class FileWrapper
     return FileUtils.mkdir_p(folder)
   end
 
+  # Makes the directory a file is about to be written in and returns the filepath. Safe
+  # when build threads make the same directory at once.
+  def mkdir_for(filepath)
+    mkdir( File.dirname( filepath ) )
+    return filepath
+  end
+
   # Creates a uniquely-named, empty directory nested inside `parent` and returns its path.
   # `parent` must already exist. Collision-free even across concurrent callers targeting
   # the same `parent` -- Dir.mktmpdir retries internally on name clash.
@@ -371,6 +394,20 @@ class FileWrapper
 
   private
 
+  def sync_options
+    return {
+      publish:      method( :replace_file ),
+      retry_delays: TRANSIENT_IO_RETRY_DELAYS,
+      sleep:        ->( delay ) { sleep( delay ) },
+      log:          ->( message, verbosity, label ) { @loginator.log( message, verbosity, label ) }
+    }
+  end
+
+  def owner_writable(path)
+    mode = File.stat( path ).mode & 0o7777
+    File.chmod( mode | 0o200, path ) if (mode & 0o200).zero?
+  end
+
   def path_length_limit
     return PATH_LENGTH_LIMITS[:windows] if SystemWrapper.windows?
     return PATH_LENGTH_LIMITS[:macos] if SystemWrapper.macos?

data/lib/ceedling/filesystem/path_exclusions.rb

@@ -0,0 +1,30 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'set'
+require 'ceedling/filesystem/path_spellings'
+
+# What collection leaves out, each a set of spellings: `-:` entries' places, outweighed by
+# an entry based nearer; excluded places, outweighed by an entry based no farther away; and
+# reserved places, never collected
+PathExclusions = Struct.new( :minus, :excluded, :reserved ) do
+  def self.of(minus, excluded, reserved)
+    return new( *[minus, excluded, reserved].map { |paths| PathSpellings.of( paths ) } )
+  end
+
+  def none?
+    return [minus, excluded, reserved].all?( &:empty? )
+  end
+
+  # Whether a place, by `spellings` of it and `distance` below the base of the entry naming
+  # it, is collected
+  def keeps?(spellings, distance)
+    return distance < PathSpellings.nearer( spellings, minus ) &&
+           distance <= PathSpellings.nearer( spellings, excluded ) &&
+           PathSpellings.nearer( spellings, reserved ) == Float::INFINITY
+  end
+end

data/lib/ceedling/{path_matcher.rb → filesystem/path_matcher.rb}

@@ -88,37 +88,40 @@ class PathMatcher
     query_segments = segments(query)
     return query unless query_segments.include?('..')
 
-    if anchor.nil?
-      raise CeedlingException.new(
-        "Relative path reference '..' in '#{query}' has no file context to resolve against here."
-      )
-    end
+    require_anchor!(query, anchor)
 
     # segments() strips the empty string a leading "/" splits off, so a Unix
     # absolute anchor's own "/"-ness has to be remembered separately here and
     # reapplied below -- otherwise the result quietly turns into a relative-looking
     # path carrying the same text minus its leading "/".
-    anchor_was_absolute = anchor.start_with?('/')
+    absolute = anchor.start_with?('/')
     resolved = segments(anchor)
-
-    # A `..` beyond a relative anchor's own segments names a directory above it, as a
-    # project's paths outside its own root do (`../shared`), so it stays in the result.
-    # Nothing lies above an absolute anchor's root.
-    query_segments.each do |segment|
-      if segment != '..'
-        resolved << segment
-      elsif !resolved.empty? and resolved.last != '..'
-        resolved.pop
-      elsif anchor_was_absolute
-        raise CeedlingException.new("Relative path reference '..' in '#{query}' climbs above the filesystem root.")
-      else
-        resolved << '..'
-      end
-    end
+    query_segments.each { |segment| step(resolved, segment, query, absolute) }
 
     joined = resolved.join('/')
-    anchor_was_absolute ? "/#{joined}" : joined
+    absolute ? "/#{joined}" : joined
+  end
+
+  def self.require_anchor!(query, anchor)
+    return unless anchor.nil?
+
+    raise CeedlingException.new( "Relative path reference '..' in '#{query}' has no file context to resolve against here." )
+  end
+  private_class_method :require_anchor!
+
+  # Applies one query segment to the segments resolved so far. A `..` beyond a relative
+  # anchor's own segments names a directory above it, as a project's paths outside its own
+  # root do (`../shared`), so it stays in the result. Nothing lies above an absolute
+  # anchor's root.
+  def self.step(resolved, segment, query, absolute)
+    return resolved << segment if segment != '..'
+    return resolved.pop if !resolved.empty? and resolved.last != '..'
+
+    raise CeedlingException.new("Relative path reference '..' in '#{query}' climbs above the filesystem root.") if absolute
+
+    resolved << '..'
   end
+  private_class_method :step
 
   # Two filepaths correspond if the shorter one's path segments equal the longer
   # one's own trailing segments, exactly, in order -- checked without regard for
@@ -138,8 +141,9 @@ class PathMatcher
 
   ### Private ###
 
+  # A `.` segment names nothing, so it is dropped with the empty ones
   def self.segments(path)
-    path.split(/[\\\/]/).reject(&:empty?)
+    path.split(/[\\\/]/).reject { |segment| segment.empty? || segment == '.' }
   end
   private_class_method :segments
 

data/lib/ceedling/{path_mirror.rb → filesystem/path_mirror.rb}

@@ -5,7 +5,8 @@
 #   SPDX-License-Identifier: MIT
 # =========================================================================
 
-require 'ceedling/file_path_utils'
+require 'ceedling/filesystem/file_path_utils'
+require 'ceedling/filesystem/project_paths'
 
 # Answers the question build output asks when it wants to avoid same-basename
 # collisions: given a resolved file and the raw (still possibly glob/decorator-laden)
@@ -23,12 +24,13 @@ class PathMirror
   end
 
   # Strips decorators and glob specifiers from each entry in `roots`, dropping any that
-  # end up empty. A caller mirroring many files against the same `roots` list -- a whole
+  # end up empty and every `-:` exclusion, which names no place a file lives below. A caller mirroring many files against the same `roots` list -- a whole
   # build's worth of sources against one project's configured paths, say -- can compute
   # this once and feed the result to `relative_subdir_from_clean_roots` for every file,
   # rather than every file's own call re-parsing the same still-decorated list from scratch.
   def self.clean_roots(roots)
     roots
+      .select { |root| FilePathUtils.add_path?(root) }
       .map { |root| FilePathUtils.no_decorators(root) }
       .reject(&:empty?)
   end
@@ -38,12 +40,13 @@ class PathMirror
   # fallback for placing build output but hides the difference from a caller deciding
   # whether a path belongs to a configured tree at all.
   def self.relative_subdir_if_rooted(filepath, roots)
-    clean    = clean_roots( roots )
-    file_dir = File.dirname( filepath )
-
-    return nil unless clean.any? { |root| file_dir == root || file_dir.start_with?( root + '/' ) }
+    return relative_subdir_if_rooted_in_clean_roots( filepath, clean_roots( roots ) )
+  end
 
-    return relative_subdir_from_clean_roots( filepath, clean )
+  # As `relative_subdir_if_rooted`, but takes roots already reduced by `clean_roots`, or
+  # canonical roots such as configuration's mirror roots
+  def self.relative_subdir_if_rooted_in_clean_roots(filepath, clean_roots)
+    return containing_subdir( File.dirname( filepath ), clean_roots )
   end
 
   # A path as lowercased segments, split on either separator. One spelling for every caller
@@ -56,18 +59,16 @@ class PathMirror
   # As `relative_subdir`, but takes roots already reduced by `clean_roots` instead of
   # raw, possibly glob/decorator-laden `:paths` entries.
   def self.relative_subdir_from_clean_roots(filepath, clean_roots)
-    file_dir = File.dirname(filepath)
-
-    matching_roots = clean_roots.select do |root|
-      file_dir == root || file_dir.start_with?(root + '/')
-    end
-
-    return '' if matching_roots.empty?
-
-    best_root = matching_roots.max_by(&:length)
-    return '' if file_dir == best_root
+    return containing_subdir( File.dirname( filepath ), clean_roots ) || ''
+  end
 
-    file_dir[(best_root.length + 1)..]
+  # The directories from the most specific root truly containing `dir` down to it, or nil
+  # when no root does. Roots and `dir` are compared as places, however each is spelled, so
+  # the result never climbs out of its root.
+  def self.containing_subdir(dir, clean_roots)
+    subdirs = clean_roots.map { |root| ProjectPaths.subdir_below( root, dir ) }.compact
+    return subdirs.min_by( &:length )
   end
+  private_class_method :containing_subdir
 
 end

data/lib/ceedling/filesystem/path_spellings.rb

@@ -0,0 +1,55 @@
+# =========================================================================
+#   Ceedling - Test-Centered Build System for C
+#   ThrowTheSwitch.org
+#   Copyright (c) 2010-26 Mike Karlesky, Mark VanderVoord, & Greg Williams
+#   SPDX-License-Identifier: MIT
+# =========================================================================
+
+require 'set'
+require 'ceedling/filesystem/project_paths'
+
+# A place reached through a symlink has two spellings: as listed and as it really is.
+# Collection compares places by both, and measures how far one lies below another.
+module PathSpellings
+
+  # A path as compared: Windows compares paths without regard to case
+  def self.key(path)
+    return ProjectPaths::WINDOWS ? path.downcase : path
+  end
+
+  # Both spellings of each of `paths`, as compared, so either reaches it
+  def self.of(paths)
+    return Set.new( paths.flat_map { |path| [ProjectPaths.absolute( path ), ProjectPaths.real_absolute( path )] }.map { |path| key( path ) } )
+  end
+
+  # How many directories above a place, by any of `spellings` of it, the nearest one in
+  # `spelled` lies: 0 for the place itself, or infinity for none
+  def self.nearer(spellings, spelled)
+    return Float::INFINITY if spelled.empty?
+
+    return spellings.map { |path| distance( path, spelled ) }.min
+  end
+
+  # `paths`, found below `base`, respelled below the base's real path
+  def self.through_real(paths, base)
+    real = ProjectPaths.real_absolute( base )
+    return paths if base == real
+
+    return paths.map { |path| ProjectPaths.same?( path, base ) || ProjectPaths.starts_with?( path, "#{base}/" ) ? real + path[base.length..] : path }
+  end
+
+  def self.distance(path, spelled)
+    steps = 0
+    loop do
+      return steps if spelled.include?( key( path ) )
+
+      parent = File.dirname( path )
+      return Float::INFINITY if parent == path
+
+      path   = parent
+      steps += 1
+    end
+  end
+  private_class_method :distance
+
+end