sycamore 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: 367667ecc8ca68b1e4da9252767849e41d85f535
-  data.tar.gz: 04523c2d3b2f7968403cd2bd51c2418136923fd0
+  metadata.gz: 96576ab7442d55fd614afdad27de3ec3aca8d6d5
+  data.tar.gz: 35541c8d3106ee6118521772c5b1f949dee22f5b
 SHA512:
-  metadata.gz: 1c96901b05579d97588ea3652622d2c270f8cc747698eb07462a73b84309dbec14b39668766e0b7aff913b397355f33a88659f8abea34cb40d3ce154e0c35d78
-  data.tar.gz: 92317760649683d727cb3904d6e70a680e9a87cac405dba65f827e93e7ee1f2ca7901895d4c701d73b68bf8c7b79eaf953aebe696542374c5e4c99d471187341
+  metadata.gz: 03b10ac2b86de83ef79fd2ec420ddcbfc0b7482d2aba51b052e338d295e8a975e5ee867e61eebf4dc80e6a339db5fd95cdfb470f747c4e528b07b297c7574d8b
+  data.tar.gz: e11355d50ae83691faabab59def13d2f5e840cb164f90d7db53b62886122c46b176c5c1bcb9bde1113bdbe24fde1c08beae872869659eddc346ef65e3c56c007

data/CHANGELOG.md

@@ -4,7 +4,20 @@ All notable changes to this project will be documented in this file.
 This project adheres to [Semantic Versioning](http://semver.org/) and
 [Keep a CHANGELOG](http://keepachangelog.com).
 
+## [Unreleased]
+
+## [0.2.0] - 2016-04-05
+### Added
+
+- assigning `Sycamore::Nothing` via `Tree#[]=` removes a child tree
+- `Tree#search` for searching the tree for one or multiple nodes or a tree
+- `Tree#node!` as a more strict variant of `Tree#node`, which raises an error 
+  when no node present
 
 ## 0.1.0 - 2016-03-28
 
 Initial release
+
+
+[Unreleased]: https://github.com/marcelotto/sycamore/compare/v0.2.0...HEAD
+[0.2.0]: https://github.com/marcelotto/sycamore/compare/v0.1.0...v0.2.0

data/README.md

@@ -4,10 +4,11 @@
 > _"The Egyptians' Holy Sycamore also stood on the threshold of life and death, connecting the two worlds."_  
 >   -- [Wikipedia: Tree of Life](http://en.wikipedia.org/wiki/Tree_of_life)
 
+[![Gem Version](https://badge.fury.io/rb/sycamore.svg)](http://badge.fury.io/rb/sycamore)
 [![Travis CI Build Status](https://secure.travis-ci.org/marcelotto/sycamore.png)](https://travis-ci.org/marcelotto/sycamore?branch=master)
 [![Coverage Status](https://coveralls.io/repos/marcelotto/sycamore/badge.png)](https://coveralls.io/r/marcelotto/sycamore)
 [![Inline docs](http://inch-ci.org/github/marcelotto/sycamore.png)](http://inch-ci.org/github/marcelotto/sycamore)
-[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/spread2rdf/frames)
+[![Documentation](http://img.shields.io/badge/docs-rdoc.info-blue.svg)](http://rubydoc.org/gems/sycamore/frames)
 [![Gitter Chat](http://img.shields.io/badge/chat-gitter.im-orange.svg)](https://gitter.im/marcelotto/sycamore)
 [![License](http://img.shields.io/license/MIT.png?color=green)](http://opensource.org/licenses/MIT)
 
@@ -62,7 +63,7 @@ The recommended installation method is via [RubyGems](http://rubygems.org/).
 
 ## Usage
 
-I will introduce Sycamore's Tree API by comparing it with [Rubys native Hash API](http://ruby-doc.org/core-2.2.3/Hash.html).
+I will introduce Sycamore's Tree API by comparing it with [Ruby's Hash API](http://ruby-doc.org/core-2.2.3/Hash.html).
 
 In the following I'll always write `Tree` for the Sycamore tree class, instead of the fully qualified `Sycamore::Tree`. By default, this global `Tree` constant is not available. If you want this, you'll have to 
 
@@ -92,7 +93,7 @@ tree = Tree.new
 tree.empty?  # => true
 ```
 
-No additional arguments are supported at the time. As you'll see, for a `Sycamore::Tree` the functionality of the Hash constructor to specify the default value behaviour is of too little value to justify its use in the default constructor. The decision of its use can be tracked in [issue #1]().
+No additional arguments are supported at the time. As you'll see, for a `Sycamore::Tree` the functionality of the Hash constructor to specify the default value behaviour is of too little value to justify its use in the default constructor, so I'd like to reserve them for something more useful.
 
 The `[]` operator creates a new `Tree` and adds the arguments as its initial input. It can handle a single node value, a collection of nodes or a complete tree. 
 
@@ -166,13 +167,20 @@ tree[:x][1].node  # => nil
 tree.node  # Sycamore::NonUniqueNodeSet: multiple nodes present: [:x, :y]
 ```
 
+The bang variant `node!` raises an error when the node set is empty, instead of returning `nil`.
+
+```ruby
+tree[:y][2].node!  # => "a"
+tree[:x][1].node!  # => # Sycamore::EmptyNodeSet: no node present
+```
+
 As opposed to Hash, the `[]` operator of `Sycamore::Tree` also supports multiple arguments which get interpreted as a path.
 
 ```ruby
 tree[:y, 2].node  # => "a"
 ```
 
-For compatibility with Ruby 2.3 hashes, this can also be done with the `dig` method.
+For compatibility with Ruby 2.3 Hashes, this can also be done with the `dig` method.
 
 ```ruby
 tree.dig(:y, 2).node  # => "a"
@@ -247,10 +255,15 @@ tree.include? [:x, :y]  # => true
 tree.include?(x: 1, y: 2)  # => true
 ```
 
+`to_h` returns the tree as a Hash.
+
+```ruby
+tree.to_h  # => {:x=>1, :y=>{2=>"a"}}
+```
 
 ### Accessing absent trees
 
-There is another major difference to a hash, which is in fact just a consequence of the already mentioned difference, that the access methods (except `fetch`) **always** return trees, when asked for children: They even return a child tree, when it does not exist. When you ask a hash for a non-existent element with the `[]` operator, you'll get a `nil`, which is an incarnation of the null-problem and the cause of many bug tracking sessions.
+There is another major difference in the access method behaviour of a Scyamore tree in comparison to hashes: The child access methods even return a tree when it does not exist. When you ask a hash for a non-existent element with the `[]` operator, you'll get a `nil`, which is an incarnation of the null-problem and the cause of many bug tracking sessions.
 
 ```ruby
 hash = {x: 1, y: {2 => "a"}}
@@ -274,7 +287,7 @@ Sycamore::Nothing.size    # => 0
 Sycamore::Nothing[42]     # => #<Sycamore::Nothing>
 ```
 
-Sycamore adheres to a strict [command-query-separation (CQS)](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation). A method is either a command changing the state of the tree and returning `self` or a query method, which only computes and returns the results of the query, but leaves the state unchanged. The only exception to this strict separation is made, when it is necessary in order to preserve hash compatibility. All query methods are supported by the `Sycamore::Nothing` tree with empty tree semantics.
+Sycamore adheres to a strict [command-query-separation (CQS)](https://en.wikipedia.org/wiki/Command%E2%80%93query_separation). A method is either a command changing the state of the tree and returning `self` or a query method, which only computes and returns the results of the query, but leaves the state unchanged. The only exception to this strict separation is made, when it is necessary in order to preserve Hash compatibility. All query methods are supported by the `Sycamore::Nothing` tree with empty tree semantics.
 
 Among the command methods are two subclasses: additive command methods, which add elements and destructive command methods, which remove elements. These are further refined into pure additive and pure destructive command methods, which either support additions or deletions only, not both operations at once. The `Sycamore::Tree` extends Ruby's reflection API with class methods to retrieve the respective methods: `query_methods`, `command_methods`, `additive_command_methods`, `destructive_command_methods`, `pure_additive_command_methods`, `pure_destructive_command_methods`.
 
@@ -436,6 +449,12 @@ tree[:foo] = []
 tree[:foo] = {}
 ```
 
+To remove a child tree entirely, you can assign `Nothing` to the parent node.
+
+```ruby
+tree[:foo] = Nothing
+```
+
 Note that these values are interpreted similarly inside tree structures, i.e. empty Enumerables become empty child trees, while `Nothing` or `nil` are used as place holders for the explicit negation of a child.
 
 ```ruby
@@ -500,6 +519,23 @@ Tree['some possibly very big data chunk' => [1, 2]].each_path.to_a
 ```
 
 
+### Searching in trees
+
+`search` returns the set of all paths to child trees containing a node or tree.
+
+```ruby
+tree = Tree[ 1 => {a: 'foo'}, 2 => :b, 3 => [:a, :b, :c] ]
+tree.search :a        # => [#<Sycamore::Path[1]>, #<Sycamore::Path[1]>]
+tree.search a: 'foo'  # => [#<Sycamore::Path[1]>]
+```
+
+If you search for multiple nodes, only the paths to child trees containing all of the given nodes are returned.
+
+```ruby
+tree.search [:b, :c]  # => [#<Sycamore::Path[3]>]
+```
+
+
 ## Getting help
 
 - [RDoc](http://www.rubydoc.info/gems/sycamore/)

data/VERSION

@@ -1 +1 @@
-0.1.0
+0.2.0

data/lib/sycamore/exceptions.rb

@@ -1,10 +1,16 @@
 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
+
+  # raised when calling {Tree#node} or {Tree#node!} on a Tree with multiple nodes
   class NonUniqueNodeSet < StandardError ; end
+
+  # raised when calling {Tree#node!} on a Tree without nodes
+  class EmptyNodeSet < StandardError ; end
+
   # raised when trying to fetch the child of a leaf
   class ChildError < KeyError ; end
 end

data/lib/sycamore/tree.rb

@@ -18,10 +18,12 @@ module Sycamore
     ########################################################################
 
     # the names of all command methods, which add elements to a Tree
-    ADDITIVE_COMMAND_METHODS = %i[add << replace add_node_with_empty_child] << :[]=
+    ADDITIVE_COMMAND_METHODS = %i[add << replace add_node_with_empty_child
+       clear_child_of_node] << :[]=
 
     # the names of all command methods, which delete elements from a Tree
-    DESTRUCTIVE_COMMAND_METHODS = %i[delete >> clear compact replace] << :[]=
+    DESTRUCTIVE_COMMAND_METHODS = %i[delete >> clear compact replace
+        clear_child_of_node] << :[]=
 
     # the names of all additive command methods, which only add elements from a Tree
     PURE_ADDITIVE_COMMAND_METHODS = ADDITIVE_COMMAND_METHODS - DESTRUCTIVE_COMMAND_METHODS
@@ -44,7 +46,7 @@ module Sycamore
     # the names of all methods, which side-effect-freeze return only a value
     QUERY_METHODS = PREDICATE_METHODS +
       %i[new_child dup hash to_native_object to_h to_s inspect
-         node nodes keys child_of child_at dig fetch
+         node node! nodes keys child_of child_at dig fetch search
          size total_size tsize height
          each each_path paths each_node each_key each_pair] << :[]
 
@@ -223,12 +225,6 @@ module Sycamore
     end
 
     ##
-    # Adds a node with an empty child to this tree.
-    #
-    # @return +self+ as a proper command method
-    #
-    # @raise [InvalidNode]
-    #
     # @api private
     #
     def add_node_with_empty_child(node)
@@ -241,6 +237,17 @@ module Sycamore
       self
     end
 
+    ##
+    # @api private
+    #
+    def clear_child_of_node(node)
+      raise InvalidNode, "#{node} is not a valid tree node" if node.is_a? Enumerable
+
+      @data[node] = Nothing
+
+      self
+    end
+
     private def add_child(node, children)
       return add_node(node) if Nothing.like?(children)
 
@@ -289,7 +296,6 @@ module Sycamore
     #   tree.delete "d" => {foo: :baz}
     #   tree.to_h  # => {}
     #
-    # @todo differentiate a greedy and a non-greedy variant
     # @todo support Paths
     #
     def delete(nodes_or_tree)
@@ -374,6 +380,9 @@ module Sycamore
     # Note that even if you assign a {Sycamore::Tree} directly the given tree
     # will not become part of this tree by reference.
     #
+    # An exception is the assignment of the {Nothing} tree: it will delete the
+    # child tree at the given path entirely.
+    #
     # @overload []=(*path, node)
     #   Replaces the contents of the child at the given path with a single node.
     #   @param path [Array<Object>, Sycamore::Path] a path as a sequence of nodes or a {Path} object
@@ -406,12 +415,23 @@ module Sycamore
     #   tree.to_h  # => {:foo => :baz, 1 => :baz}
     #   tree[:foo] << :bar
     #   tree.to_h  # => {:foo => [:baz, :bar], 1 => :baz}
+    #   tree[:foo] = Sycamore::Nothing
+    #   tree.to_h  # => {:foo => nil, 1 => :baz}
     #
     def []=(*args)
       path, nodes_or_tree = args[0..-2], args[-1]
       raise ArgumentError, 'wrong number of arguments (given 1, expected 2)' if path.empty?
 
-      child_at(*path).replace(nodes_or_tree)
+      if nodes_or_tree.equal? Sycamore::Nothing
+        if path.size == 1
+          clear_child_of_node(path.first)
+        else
+          path, node = path[0..-2], path[-1]
+          child_at(*path).clear_child_of_node(node)
+        end
+      else
+        child_at(*path).replace(nodes_or_tree)
+      end
     end
 
     ##
@@ -446,7 +466,7 @@ module Sycamore
     def compact
       @data.each do |node, child| case
           when child.nothing? then next
-          when child.empty?   then @data[node] = Nothing
+          when child.empty?   then clear_child_of_node(node)
           else child.compact
         end
       end
@@ -489,6 +509,8 @@ module Sycamore
     #   tree[:baz].node  # => nil
     #   tree[:bar].node  # => raise Sycamore::NonUniqueNodeSet, "multiple nodes present: [2, 3]"
     #
+    # @see Tree#node!
+    #
     def node
       nodes = self.nodes
       raise NonUniqueNodeSet, "multiple nodes present: #{nodes}" if nodes.size > 1
@@ -496,6 +518,27 @@ module Sycamore
       nodes.first
     end
 
+    ##
+    # The only node of this tree or an exception, if none or more {#nodes nodes} present.
+    #
+    # @return [Object] the single present node
+    #
+    # @raise [EmptyNodeSet] if no nodes present
+    # @raise [NonUniqueNodeSet] if more than one node present
+    #
+    # @example
+    #   tree = Tree[foo: 1, bar: [2,3]]
+    #   tree[:foo].node!  # => 1
+    #   tree[:baz].node!  # => raise Sycamore::EmptyNodeSet, "no node present"
+    #   tree[:bar].node!  # => raise Sycamore::NonUniqueNodeSet, "multiple nodes present: [2, 3]"
+    #
+    # @see Tree#node
+    #
+    def node!
+      raise EmptyNodeSet, 'no node present' if empty?
+      node
+    end
+
     ##
     # The child tree of a node.
     #
@@ -785,6 +828,32 @@ module Sycamore
       end
     end
 
+    ##
+    # Searches the tree for one or multiple nodes or a complete tree.
+    #
+    # @param nodes_or_tree [Object, Array, Tree, Hash]
+    # @return [Array<Path>]
+    #
+    # @example
+    #   tree = Tree[ "a" => [:foo, 100], "b" => { foo: [:bar, :baz] } ]
+    #   tree.search :bar          # => [Sycamore::Path["b", :foo]]
+    #   tree.search :foo          # => [Sycamore::Path["a"], Sycamore::Path["b"]]
+    #   tree.search [:bar, :baz]  # => [Sycamore::Path["b", :foo]]
+    #   tree.search foo: :bar     # => [Sycamore::Path["b"]]
+    #   tree.search 42            # => []
+    #
+    def search(nodes_or_tree)
+      _search(nodes_or_tree)
+    end
+
+    protected def _search(query, current_path: Path::ROOT, results: [])
+      results << current_path if include?(query)
+      each do |node, child|
+        child._search(query, current_path: current_path/node, results: results)
+      end
+      results
+    end
+
     ##
     # The number of {#nodes nodes} in this tree.
     #

data/sycamore.gemspec

@@ -12,6 +12,9 @@ Gem::Specification.new do |spec|
   spec.summary       = %q{An unordered tree data structure for Ruby.}
   spec.description   = %q{Sycamore is an implementation of an unordered tree data structure of immutable values solely based on Ruby Hashes.}
   spec.homepage      = 'https://github.com/marcelotto/sycamore'
+  spec.license       = 'MIT'
+
+  spec.required_ruby_version = '>= 2.1'
 
   spec.files         = `git ls-files -z`.split("\x0").reject { |f| f.match(%r{^(test|spec|features)/}) }
   spec.bindir        = 'exe'

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: sycamore
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Marcel Otto
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-03-28 00:00:00.000000000 Z
+date: 2016-04-04 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler
@@ -152,7 +152,8 @@ files:
 - support/doctest_helper.rb
 - sycamore.gemspec
 homepage: https://github.com/marcelotto/sycamore
-licenses: []
+licenses:
+- MIT
 metadata: {}
 post_install_message: 
 rdoc_options: []
@@ -162,7 +163,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.1'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="