metaractor-sycamore 0.4.1

data/devenv.lock

@@ -0,0 +1,210 @@
+{
+  "nodes": {
+    "devenv": {
+      "locked": {
+        "dir": "src/modules",
+        "lastModified": 1686054274,
+        "narHash": "sha256-93aebyN7EMmeFFXisFIvp28UEbrozu79vd3pKPjvNR0=",
+        "owner": "cachix",
+        "repo": "devenv",
+        "rev": "c51a56bac8853c019241fe8d821c0a0d82422835",
+        "type": "github"
+      },
+      "original": {
+        "dir": "src/modules",
+        "owner": "cachix",
+        "repo": "devenv",
+        "type": "github"
+      }
+    },
+    "flake-compat": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1673956053,
+        "narHash": "sha256-4gtG9iQuiKITOjNQQeQIpoIB6b16fm+504Ch3sNKLd8=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "35bb57c0c8d8b62bbfd284272c928ceb64ddbde9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-compat_2": {
+      "flake": false,
+      "locked": {
+        "lastModified": 1673956053,
+        "narHash": "sha256-4gtG9iQuiKITOjNQQeQIpoIB6b16fm+504Ch3sNKLd8=",
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "rev": "35bb57c0c8d8b62bbfd284272c928ceb64ddbde9",
+        "type": "github"
+      },
+      "original": {
+        "owner": "edolstra",
+        "repo": "flake-compat",
+        "type": "github"
+      }
+    },
+    "flake-utils": {
+      "locked": {
+        "lastModified": 1667395993,
+        "narHash": "sha256-nuEHfE/LcWyuSWnS8t12N1wc105Qtau+/OdUAjtQ0rA=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "5aed5285a952e0b949eb3ba02c12fa4fcfef535f",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "flake-utils_2": {
+      "inputs": {
+        "systems": "systems"
+      },
+      "locked": {
+        "lastModified": 1685518550,
+        "narHash": "sha256-o2d0KcvaXzTrPRIo0kOLV0/QXHhDQ5DTi+OxcjO8xqY=",
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "rev": "a1720a10a6cfe8234c0e93907ffe81be440f4cef",
+        "type": "github"
+      },
+      "original": {
+        "owner": "numtide",
+        "repo": "flake-utils",
+        "type": "github"
+      }
+    },
+    "gitignore": {
+      "inputs": {
+        "nixpkgs": [
+          "pre-commit-hooks",
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1660459072,
+        "narHash": "sha256-8DFJjXG8zqoONA1vXtgeKXy68KdJL5UaXR8NtVMUbx8=",
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "rev": "a20de23b925fd8264fd7fad6454652e142fd7f73",
+        "type": "github"
+      },
+      "original": {
+        "owner": "hercules-ci",
+        "repo": "gitignore.nix",
+        "type": "github"
+      }
+    },
+    "nixpkgs": {
+      "locked": {
+        "lastModified": 1685938391,
+        "narHash": "sha256-96Jw6TbWDLSopt5jqCW8w1Fc1cjQyZlhfBnJ3OZGpME=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "31cd1b4afbaf0b1e81272ee9c31d1ab606503aed",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixpkgs-unstable",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "nixpkgs-ruby": {
+      "inputs": {
+        "flake-compat": "flake-compat",
+        "flake-utils": "flake-utils",
+        "nixpkgs": [
+          "nixpkgs"
+        ]
+      },
+      "locked": {
+        "lastModified": 1685159223,
+        "narHash": "sha256-rwHYapZEvxDJ8dw3hMGY/AE9c6qls9CifAUvObnx7e0=",
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "rev": "dfaf58567eda18bad5340a9432e601d96c497943",
+        "type": "github"
+      },
+      "original": {
+        "owner": "bobvanderlinden",
+        "repo": "nixpkgs-ruby",
+        "type": "github"
+      }
+    },
+    "nixpkgs-stable": {
+      "locked": {
+        "lastModified": 1685801374,
+        "narHash": "sha256-otaSUoFEMM+LjBI1XL/xGB5ao6IwnZOXc47qhIgJe8U=",
+        "owner": "NixOS",
+        "repo": "nixpkgs",
+        "rev": "c37ca420157f4abc31e26f436c1145f8951ff373",
+        "type": "github"
+      },
+      "original": {
+        "owner": "NixOS",
+        "ref": "nixos-23.05",
+        "repo": "nixpkgs",
+        "type": "github"
+      }
+    },
+    "pre-commit-hooks": {
+      "inputs": {
+        "flake-compat": "flake-compat_2",
+        "flake-utils": "flake-utils_2",
+        "gitignore": "gitignore",
+        "nixpkgs": [
+          "nixpkgs"
+        ],
+        "nixpkgs-stable": "nixpkgs-stable"
+      },
+      "locked": {
+        "lastModified": 1686050334,
+        "narHash": "sha256-R0mczWjDzBpIvM3XXhO908X5e2CQqjyh/gFbwZk/7/Q=",
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "rev": "6881eb2ae5d8a3516e34714e7a90d9d95914c4dc",
+        "type": "github"
+      },
+      "original": {
+        "owner": "cachix",
+        "repo": "pre-commit-hooks.nix",
+        "type": "github"
+      }
+    },
+    "root": {
+      "inputs": {
+        "devenv": "devenv",
+        "nixpkgs": "nixpkgs",
+        "nixpkgs-ruby": "nixpkgs-ruby",
+        "pre-commit-hooks": "pre-commit-hooks"
+      }
+    },
+    "systems": {
+      "locked": {
+        "lastModified": 1681028828,
+        "narHash": "sha256-Vy1rq5AaRuLzOxct8nz4T6wlgyUR7zLU309k9mBC768=",
+        "owner": "nix-systems",
+        "repo": "default",
+        "rev": "da67096a3b9bf56a91d16901293e51ba5b49a27e",
+        "type": "github"
+      },
+      "original": {
+        "owner": "nix-systems",
+        "repo": "default",
+        "type": "github"
+      }
+    }
+  },
+  "root": "root",
+  "version": 7
+}

data/devenv.nix

@@ -0,0 +1,25 @@
+{ pkgs, ... }:
+
+{
+  # https://devenv.sh/packages/
+  packages = with pkgs; [
+    git
+  ];
+
+  # https://devenv.sh/languages/
+  languages.ruby.enable = true;
+  # Uses bobvanderlinden/nixpkgs-ruby to supply any version of ruby
+  languages.ruby.versionFile = ./.ruby-version;
+
+  enterShell = ''
+    export BUNDLE_BIN="$DEVENV_ROOT/.devenv/bin"
+    export PATH="$DEVENV_PROFILE/bin:$DEVENV_ROOT/bin:$BUNDLE_BIN:$PATH"
+    export BOOTSNAP_CACHE_DIR="$DEVENV_ROOT/.devenv/state"
+  '';
+
+  # The unix socket path can't be "too long".
+  # Make sure it's short for when we need it.
+  env.RUBY_DEBUG_SOCK_DIR = "/tmp/";
+
+  # See full reference at https://devenv.sh/reference/options/
+}

data/devenv.yaml

@@ -0,0 +1,8 @@
+inputs:
+  nixpkgs:
+    url: github:NixOS/nixpkgs/nixpkgs-unstable
+  nixpkgs-ruby:
+    url: github:bobvanderlinden/nixpkgs-ruby
+    inputs:
+      nixpkgs:
+        follows: nixpkgs

data/lib/outstand_sycamore.rb

@@ -0,0 +1 @@
+require 'sycamore'

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,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} 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/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/extension.rb

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

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