sycamore 0.1.0

data/Rakefile

@@ -0,0 +1,31 @@
+require 'bundler/gem_tasks'
+
+begin
+  require 'rspec/core/rake_task'
+  RSpec::Core::RakeTask.new(:spec)
+rescue LoadError
+  puts "Couldn't find RSpec core Rake task"
+end
+
+begin
+  require 'yard'
+  YARD::Rake::YardocTask.new do |t|
+    t.options = ['--verbose']
+    t.files   = ['lib/**/*.rb', 'doc/**/*.md']
+    t.stats_options = ['--list-undoc']
+  end
+rescue LoadError
+  puts "Couldn't find YARD"
+end
+
+begin
+  require 'yard-doctest'
+  YARD::Doctest::RakeTask.new do |task|
+    task.doctest_opts = %w[]
+    task.pattern = 'lib/**/*.rb'
+  end
+rescue LoadError
+  puts "Couldn't find yard-doctest"
+end
+
+task :default => [:spec, 'yard:doctest']

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/bin/console

@@ -0,0 +1,9 @@
+#!/usr/bin/env ruby
+
+require 'bundler/setup'
+require 'sycamore'
+
+require 'pry'
+Pry.start
+
+include Sycamore # TODO: require 'sycamore/extension'

data/bin/setup

@@ -0,0 +1,8 @@
+#!/bin/bash
+set -euo pipefail
+IFS=$'\n\t'
+
+bundle install
+
+# Do any other automated setup that you need to do here
+

data/lib/sycamore.rb

@@ -0,0 +1,13 @@
+require 'sycamore/version'
+require 'sycamore/exceptions'
+require 'sycamore/path'
+require 'sycamore/path_root'
+require 'sycamore/tree'
+require 'sycamore/nothing'
+require 'sycamore/absence'
+
+##
+# see README.md
+#
+module Sycamore
+end

data/lib/sycamore/absence.rb

@@ -0,0 +1,179 @@
+require 'delegate'
+
+module Sycamore
+
+  ##
+  # An Absence object represents the absence of a specific child {Sycamore::Tree}.
+  #
+  # +Absence+ instances get created when accessing non-existent children of a
+  # Tree with {Tree#child_of} or {Tree#child_at}.
+  # It is not intended to be instantiated by the user.
+  #
+  # An +Absence+ object can be used like a normal {Sycamore::Tree}.
+  # {Tree::QUERY_METHODS Query} and {Tree::DESTRUCTIVE_COMMAND_METHODS pure destructive command method}
+  # calls get delegated to {Sycamore::Nothing}, i.e. will behave like an empty Tree.
+  # On every other {Tree::COMMAND_METHODS command} calls, the +Absence+ object
+  # gets resolved, which means the missing tree will be created, added to the
+  # parent tree and the method call gets delegated to the now existing tree.
+  # After the +Absence+ object is resolved all subsequent method calls are
+  # delegated to the created tree.
+  # The type of tree eventually created is determined by the {Tree#new_child}
+  # implementation of the parent tree and the parent node.
+  #
+  class Absence < Delegator
+
+    ##
+    # @api private
+    #
+    def initialize(parent_tree, parent_node)
+      @parent_tree, @parent_node = parent_tree, parent_node
+    end
+
+    class << self
+      alias at new
+    end
+
+    ########################################################################
+    # presence creation
+    ########################################################################
+
+    ##
+    # The tree object to which all method calls are delegated.
+    #
+    # @api private
+    #
+    def presence
+      @tree or Nothing
+    end
+
+    alias __getobj__ presence
+
+    ##
+    # @api private
+    #
+    def create
+      @parent_tree = @parent_tree.add_node_with_empty_child(@parent_node)
+      @tree = @parent_tree[@parent_node]
+    end
+
+    ########################################################################
+    # Absence and Nothing predicates
+    ########################################################################
+
+    ##
+    # (see Tree#absent?)
+    #
+    def absent?
+      @tree.nil?
+    end
+
+    ##
+    # (see Tree#nothing?)
+    #
+    def nothing?
+      false
+    end
+
+    ########################################################################
+    # Element access
+    ########################################################################
+
+    #####################
+    #   query methods   #
+    #####################
+
+    def child_of(node)
+      if absent?
+        raise InvalidNode, "#{node} is not a valid tree node" if node.is_a? Enumerable
+
+        Absence.at(self, node)
+      else
+        presence.child_of(node)
+      end
+    end
+
+    def child_at(*path)
+      if absent?
+        # TODO: This is duplication of Tree#child_at! How can we remove it, without introducing a module for this single method or inherit from Tree?
+        case path.length
+          when 0 then raise ArgumentError, 'wrong number of arguments (given 0, expected 1+)'
+          when 1 then child_of(*path)
+          else child_of(path[0]).child_at(*path[1..-1])
+        end
+      else
+        presence.child_at(*path)
+      end
+    end
+
+    alias [] child_at
+    alias dig child_at
+
+    ##
+    # A developer-friendly string representation of the absent tree.
+    #
+    # @return [String]
+    #
+    def inspect
+      "#{absent? ? 'absent' : 'present'} child of node #{@parent_node.inspect} in #{@parent_tree.inspect}"
+    end
+
+    ##
+    # Duplicates the resolved tree or raises an error, when unresolved.
+    #
+    # @return [Tree]
+    #
+    # @raise [TypeError] when this {Absence} is not resolved yet
+    #
+    def dup
+      presence.dup
+    end
+
+    ##
+    # Clones the resolved tree or raises an error, when unresolved.
+    #
+    # @return [Tree]
+    #
+    # @raise [TypeError] when this {Absence} is not resolved yet
+    #
+    def clone
+      presence.clone
+    end
+
+    ##
+    # Checks if the absent tree is frozen.
+    #
+    # @return [Boolean]
+    #
+    def frozen?
+      if absent?
+        false
+      else
+        presence.frozen?
+      end
+    end
+
+    #####################
+    #  command methods  #
+    #####################
+
+    # TODO: YARD should be informed about this method definitions.
+    Tree.command_methods.each do |command_method|
+      if Tree.pure_destructive_command_methods.include?(command_method)
+        define_method command_method do |*args|
+          if absent?
+            self
+          else
+            presence.send(command_method, *args) # TODO: How can we hand over a possible block? With eval etc.?
+          end
+        end
+      else
+        # TODO: This method should be atomic.
+        define_method command_method do |*args|
+          create if absent?
+          presence.send(command_method, *args) # TODO: How can we hand over a possible block? With eval etc.?
+        end
+      end
+    end
+
+  end
+end

data/lib/sycamore/exceptions.rb

@@ -0,0 +1,10 @@
+module Sycamore
+  # raised when a value is not a valid node
+  class InvalidNode < ArgumentError ; end
+  # raised when trying to call a additive command method of the {Nothing} tree
+  class NothingMutation < StandardError ; end
+  # raised when calling {Tree#node} on a Tree with multiple nodes
+  class NonUniqueNodeSet < StandardError ; end
+  # raised when trying to fetch the child of a leaf
+  class ChildError < KeyError ; end
+end

data/lib/sycamore/extension.rb

@@ -0,0 +1,2 @@
+require 'sycamore/extension/tree'
+require 'sycamore/extension/nothing'

data/lib/sycamore/extension/nothing.rb

@@ -0,0 +1,4 @@
+require 'sycamore/nothing'
+
+# optional global shortcut constant for {Sycamore::Nothing}
+Nothing = Sycamore::Nothing unless defined? Nothing

data/lib/sycamore/extension/path.rb

@@ -0,0 +1,7 @@
+require 'sycamore'
+
+# optional global shortcut constant for Sycamore::Path
+Path = Sycamore::Path
+
+# optional global shortcut constant for Sycamore::Path
+TreePath = Sycamore::Path

data/lib/sycamore/extension/tree.rb

@@ -0,0 +1,4 @@
+require 'sycamore'
+
+# optional global shortcut constant for Sycamore::Tree
+Tree = Sycamore::Tree

data/lib/sycamore/nothing.rb

@@ -0,0 +1,157 @@
+require 'singleton'
+
+module Sycamore
+
+  ##
+  # The Nothing Tree singleton class.
+  #
+  # The Nothing Tree is an empty Sycamore Tree, and means "there are no nodes".
+  #
+  # It is immutable:
+  # - {Tree::QUERY_METHODS Query method} calls will behave like a normal, empty Tree.
+  # - {Tree::DESTRUCTIVE_COMMAND_METHODS Pure destructive command} calls, will be ignored, i.e. being no-ops.
+  # - But all other {Tree::COMMAND_METHODS command} calls, will raise a {NothingMutation}.
+  #
+  # It is the only Tree object that will return +true+ on a {#nothing?} call.
+  # But like {Absence}, it will return +true+ on {#absent?} and +false+ on {#existent?}.
+  #
+  class NothingTree < Tree
+    include Singleton
+
+    ########################################################################
+    # Absence and Nothing predicates
+    ########################################################################
+
+    ##
+    # (see Tree#nothing?)
+    #
+    def nothing?
+      true
+    end
+
+    ##
+    # (see Tree#absent?)
+    #
+    def absent?
+      true
+    end
+
+    ########################################################################
+    # CQS element access
+    ########################################################################
+
+    # TODO: YARD should be informed about this method definitions.
+    command_methods.each do |command_method|
+      define_method command_method do |*args|
+        raise NothingMutation, 'attempt to change the Nothing tree'
+      end
+    end
+
+    # TODO: YARD should be informed about this method definitions.
+    pure_destructive_command_methods.each do |command_method|
+      define_method(command_method) { |*args| self }
+    end
+
+    def child_of(node)
+      self
+    end
+
+    def to_native_object(sleaf_child_as: nil, **args)
+      sleaf_child_as
+    end
+
+    ##
+    # A string representation of the Nothing tree.
+    #
+    # @return [String]
+    #
+    def to_s
+      'Tree[Nothing]'
+    end
+
+    ##
+    # A developer-friendly string representation of the Nothing tree.
+    #
+    # @return [String]
+    #
+    def inspect
+      '#<Sycamore::Nothing>'
+    end
+
+    def freeze
+      super
+    end
+
+    ########################################################################
+    # Equality
+    ########################################################################
+
+    ##
+    # Checks if the given object is an empty tree.
+    #
+    # @return [Boolean]
+    #
+    def ==(other)
+      (other.is_a?(Tree) or other.is_a?(Absence)) and other.empty?
+    end
+
+
+    ########################################################################
+    # Falsiness
+    #
+    # Sadly, in Ruby we can't do that match to reach this goal.
+    #
+    # see http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/
+    ########################################################################
+
+    ##
+    # Try to emulate a falsey value, by negating to +true+.
+    #
+    # @return [Boolean] +true+
+    #
+    # @see http://devblog.avdi.org/2011/05/30/null-objects-and-falsiness/
+    #
+    def !
+      true
+    end
+
+    # def nil?
+    #   true
+    # end
+
+
+    ########################################################################
+    # Some helpers
+    #
+    # Ideally these would be implemented with Refinements, but since they
+    # aren't available anywhere (I'm looking at you, JRuby), we have to be
+    # content with this.
+    #
+    ########################################################################
+
+    def like?(object)
+      object.nil? or object.equal? self
+    end
+
+    ##
+    # @api private
+    class NestedStringPresentation
+      include Singleton
+
+      def inspect
+        'n/a'
+      end
+    end
+
+    ##
+    # @api private
+    NestedString = NestedStringPresentation.instance.freeze
+
+  end
+
+  ############################################################################
+  # The Nothing Tree Singleton object
+  #
+  Nothing = NothingTree.instance.freeze
+
+end

data/lib/sycamore/path.rb

@@ -0,0 +1,261 @@
+module Sycamore
+
+  ##
+  # A compact, immutable representation of Tree paths, i.e. node sequences.
+  #
+  # This class is optimized for its usage in {Tree#each_path}, where it
+  # can efficiently represent the whole tree as a set of paths by sharing the
+  # parent paths.
+  # It is not intended to be instantiated by the user.
+  #
+  # @example
+  #   tree = Tree[foo: [:bar, :baz]]
+  #   path1, path2 = tree.paths.to_a
+  #   path1 == Sycamore::Path[:foo, :bar] # => true
+  #   path2 == Sycamore::Path[:foo, :baz] # => true
+  #   path1.parent.equal? path2.parent # => true
+  #
+  # @todo Measure the performance and memory consumption in comparison with a
+  #   pure Array-based implementation (where tree nodes are duplicated), esp. in
+  #   the most common use case of property-value structures.
+  #
+  class Path
+    include Enumerable
+
+    attr_reader :node, :parent
+
+    ########################################################################
+    # @group Construction
+    ########################################################################
+
+    ##
+    # @private
+    #
+    def initialize(parent, node)
+      @parent, @node = parent, node
+    end
+
+    ##
+    # @return the root of all Paths
+    #
+    def self.root
+      ROOT
+    end
+
+    ##
+    # Creates a new path.
+    #
+    # Depending on whether the first argument is a {Path}, the new Path is
+    # {#branch}ed from this path or the {root}.
+    #
+    # @overload of(path, nodes)
+    #   @param path [Path] the path from which should be {#branch}ed
+    #   @param nodes [nodes]
+    #   @return [Path] the {#branch}ed path from the given path, with the given nodes expanded
+    #
+    # @overload of(nodes)
+    #   @param nodes [nodes]
+    #   @return [Path] the {#branch}ed path from the {root}, with the given nodes
+    #
+    def self.of(*args)
+      if (parent = args.first).is_a? Path
+        parent.branch(*args[1..-1])
+      else
+        root.branch(*args)
+      end
+    end
+
+    class << self
+      private :new  # disable Path.new
+
+      alias [] of
+    end
+
+    ########################################################################
+    # @group Elements
+    ########################################################################
+
+    ##
+    # Returns a new path based on this path, but with the given nodes extended.
+    #
+    # @param nodes [nodes] an arbitrary number of nodes
+    # @return [Path]
+    #
+    # @raise [InvalidNode] if one or more of the given nodes is an Enumerable
+    #
+    # @example
+    #   path = Sycamore::Path[:foo, :bar]
+    #   path.branch(:baz, :qux) ==
+    #     Sycamore::Path[:foo, :bar, :baz, :qux]  # => true
+    #   path / :baz / :qux ==
+    #     Sycamore::Path[:foo, :bar, :baz, :qux]  # => true
+    #
+    def branch(*nodes)
+      return branch(*nodes.first) if nodes.size == 1 and nodes.first.is_a? Enumerable
+
+      parent = self
+      nodes.each do |node|
+        raise InvalidNode, "#{node} in Path #{nodes.inspect} is not a valid tree node" if
+          node.is_a? Enumerable
+        parent = Path.__send__(:new, parent, node)
+      end
+
+      parent
+    end
+
+    alias + branch
+    alias / branch
+
+    ##
+    # @return [Path] the n-th last parent path
+    # @param distance [Integer] the number of nodes to go up
+    #
+    # @example
+    #   path = Sycamore::Path[:foo, :bar, :baz]
+    #   path.up     # => Sycamore::Path[:foo, :bar]
+    #   path.up(2)  # => Sycamore::Path[:foo]
+    #   path.up(3)  # => Sycamore::Path[]
+    #
+    def up(distance = 1)
+      raise TypeError, "expected an integer, but got #{distance.inspect}" unless
+        distance.is_a? Integer
+
+      case distance
+        when 1 then @parent
+        when 0 then self
+        else parent.up(distance - 1)
+      end
+    end
+
+    ##
+    # @return [Boolean] if this is the root path
+    #
+    def root?
+      false
+    end
+
+    ##
+    # @return [Integer] the number of nodes on this path
+    #
+    def length
+      i, parent = 1, self
+      i += 1 until (parent = parent.parent).root?
+      i
+    end
+
+    alias size length
+
+    ##
+    # Iterates over all nodes on this path.
+    #
+    # @overload each_node
+    #   @yield [node] each node
+    #
+    # @overload each_node
+    #   @return [Enumerator<node>]
+    #
+    def each_node(&block)
+      return enum_for(__callee__) unless block_given?
+
+      if @parent
+        @parent.each_node(&block)
+        yield @node
+      end
+    end
+
+    alias each each_node
+
+    ##
+    # If a given structure contains this path.
+    #
+    # @param struct [Object]
+    # @return [Boolean] if the given structure contains the nodes on this path
+    #
+    # @example
+    #   hash = {foo: {bar: :baz}}
+    #   Sycamore::Path[:foo, :bar].present_in? hash  # => true
+    #   Sycamore::Path[:foo, :bar].present_in? Tree[hash]  # => true
+    #
+    def present_in?(struct)
+      each do |node|
+        case
+          when struct.is_a?(Enumerable)
+            return false unless struct.include? node
+            struct = (Tree.like?(struct) ? struct[node] : Nothing )
+          else
+            return false unless struct.eql? node
+            struct = Nothing
+        end
+      end
+      true
+    end
+
+    alias in? present_in?
+
+    ########################################################################
+    # @group Equality
+    ########################################################################
+
+    ##
+    # @return [Fixnum] hash code for this path
+    #
+    def hash
+      to_a.hash ^ self.class.hash
+    end
+
+    ##
+    # @return [Boolean] if the other is a Path with the same nodes in the same order
+    # @param other [Object]
+    #
+    def eql?(other)
+      other.is_a?(self.class) and
+        self.length == other.length and begin
+          i = other.each ; all? { |node| node.eql? i.next }
+        end
+    end
+
+    ##
+    # @return [Boolean] if the other is an Enumerable with the same nodes in the same order
+    # @param other [Object]
+    #
+    def ==(other)
+      other.is_a?(Enumerable) and self.length == other.length and begin
+        i = other.each ; all? { |node| node == i.next }
+      end
+    end
+
+    ########################################################################
+    # @group Conversion
+    ########################################################################
+
+    ##
+    # @return [String] a string created by converting each node on this path to a string, separated by the given separator
+    # @param separator [String]
+    #
+    # @note Since the root path with no node is at the beginning of each path,
+    #   the returned string always begins with the given separator.
+    #
+    # @example
+    #   Sycamore::Path[1,2,3].join       # => '/1/2/3'
+    #   Sycamore::Path[1,2,3].join('|')  # => '|1|2|3'
+    #
+    def join(separator = '/')
+      @parent.join(separator) + separator + node.to_s
+    end
+
+    ##
+    # @return [String] a compact string representation of this path
+    #
+    def to_s
+      "#<Path: #{join}>"
+    end
+
+    ##
+    # @return [String] a more verbose string representation of this path
+    #
+    def inspect
+      "#<Sycamore::Path[#{each_node.map(&:inspect).join(',')}]>"
+    end
+  end
+
+end