fr 0.9.1

data/lib/fr/szipper/memoized_cursor.rb

@@ -0,0 +1,59 @@
+module Fr
+  module SZipper
+
+    class MemoizedCursor < AbstractCursor
+      # @return [#next, #tail?]
+      attr_reader :node
+
+      def initialize(node, prev)
+        @node, @prev =
+          node, prev
+      end
+
+      def prev(phantom = false)
+        @prev
+      end
+
+      def head?
+        false
+      end
+
+      def tail?
+        @node.tail?
+      end
+
+      def append(node)
+        EditedCursor.new(node.copy(next: @node.next), self)
+      end
+
+      def prepend(node)
+        EditedCursor.new(node.copy(next: @node), @prev)
+      end
+
+      def update(node = nil)
+        if node.nil?
+          EditedCursor.new(yield(@node).copy(next: @node.next), @prev)
+        else
+          EditedCursor.new(node.copy(next: @node.next), @prev)
+        end
+      end
+
+      def replace(node)
+        EditedCursor.new(node, @prev)
+      end
+
+      def delete
+        if @prev.head?
+          HeadCursor.new(@prev.node.copy(next: @node.next))
+        else
+          EditedCursor.new(@prev.node.copy(next: @node.next), @prev.prev)
+        end
+      end
+
+      def inspect
+        "Cursor([..., #{@node.inspect}, ...])"
+      end
+    end
+
+  end
+end

data/lib/fr/szipper/node.rb

@@ -0,0 +1,67 @@
+module Fr
+  module SZipper
+
+    # Example implementation for a stream node. For the
+    # purposes of traversal with a zipper, nodes can be
+    # anything that implements #copy, #next, and #tail?
+    #
+    # You'll probably want access to some datum too, like
+    # #value. Otherwise you'll be traversing a stream of
+    # otherwise useless cells.
+    #
+    class Node
+      attr_reader :value
+
+      attr_reader :next
+
+      def initialize(value, _next = nil)
+        @value, @next =
+          value, _next
+      end
+
+      def tail?
+        @next.nil?
+      end
+
+      def copy(options = {})
+        Node.new \
+          options.fetch(:value, @value),
+          options.fetch(:next,  @next)
+      end
+
+      def inspect
+        "Node(#{@value})"
+      end
+    end
+
+    class << Node
+      def cons(value, _next)
+        Node.new(value, _next)
+      end
+
+      def tail(value)
+        Node.new(value)
+      end
+
+
+      # Convenient constructor to build a chain of Nodes
+      # from any "sequential" enum. That excludes things
+      # like Hash, Set, and Range because their traversal
+      # order isn't deterministic. Otherwise, anything that
+      # implements #reverse and #inject can be converted.
+      #
+      def build(enum)
+        if enum.empty?
+          raise Errors::ZipperError,
+            "enum is empty"
+        end
+
+        tail, *rest = enum.reverse
+        rest.inject(tail(tail)) do |_next, value|
+          cons(value, _next)
+        end
+      end
+    end
+
+  end
+end

data/lib/fr/szipper/tail_next_cursor.rb

@@ -0,0 +1,68 @@
+module Fr
+  module SZipper
+
+    class TailNextCursor < AbstractCursor
+      def initialize(prev)
+        @prev = prev
+      end
+
+      def empty?
+        true
+      end
+
+      def tail?
+        false
+      end
+
+      def head?
+        false
+      end
+
+      def tail
+        @prev
+      end
+
+      def prev(phantom = false)
+        @prev
+      end
+
+      def next(phantom = false)
+        if phantom
+          self
+        else
+          raise Errors::ZipperError,
+            "tail node has no next"
+        end
+      end
+
+      def append(node)
+        @prev.append(node)
+      end
+
+      def prepend(node)
+        @prev.append(node)
+      end
+
+      def update(node = nil)
+        if node.nil?
+          @prev.append(yield(nil).copy(next: nil))
+        else
+          @prev.append(node.copy(next: nil))
+        end
+      end
+
+      def replace(node)
+        EditedCursor.new(node, @prev)
+      end
+
+      def delete
+        @prev
+      end
+
+      def inspect
+        "Cursor([..., #{@prev.node.inspect}, ___])"
+      end
+    end
+
+  end
+end

data/lib/fr/thunk.rb

@@ -0,0 +1,73 @@
+module Fr
+
+  # Beware, there's no way to make a thunk value 100%
+  # compatible with the value it computes. For instance,
+  #
+  #   String === "a"            #=> true
+  #   String === thunk { "a" }  #=> false
+  #
+  #   "a" == "a"                #=> true
+  #   "a" == thunk { "a" }      #=> false
+  #
+  #   x = "abc"
+  #   y = thunk { x }
+  #
+  #   x.equal?(x) #=> true
+  #   y.equal?(y) #=> true
+  #   x.equal?(y) #=> false
+  #   y.equal?(x) #=> false
+  #
+  class Thunk < BasicObject
+    def initialize(block)
+      unless block.arity.zero?
+        raise ArgumentError,
+          "block must have zero arity"
+      end
+
+      @block = block
+    end
+
+    def thunk?
+      true
+    end
+
+    # Silence warnings about redefining __send__
+    verbose  = $VERBOSE
+    $VERBOSE = nil
+
+    undef_method :!
+    undef_method :==
+    undef_method :!=
+    undef_method :instance_eval
+    undef_method :instance_exec
+
+  private
+
+    def __send__(name, *args, &block)
+      unless defined? @value
+        @value = @block.call
+        @block = nil
+      end
+
+      @value.__send__(name, *args, &block)
+    end
+
+    $VERBOSE = verbose
+
+    def method_missing(name, *args, &block)
+      unless defined? @value
+        @value = @block.call
+        @block = nil
+      end
+
+      @value.__send__(name, *args, &block)
+    end
+  end
+
+end
+
+class Object
+  def thunk?
+    false
+  end
+end

data/lib/fr/tzipper.rb

@@ -0,0 +1,38 @@
+module Fr
+  module TZipper
+    autoload :AbstractCursor, "fr/tzipper/abstract_cursor"
+    autoload :DanglingCursor, "fr/tzipper/dangling_cursor"
+    autoload :EditedCursor,   "fr/tzipper/edited_cursor"
+    autoload :MemoizedCursor, "fr/tzipper/memoized_cursor"
+    autoload :RootCursor,     "fr/tzipper/root_cursor"
+
+    autoload :AbstractPath, "fr/tzipper/path"
+    autoload :Hole,         "fr/tzipper/path"
+    autoload :Root,         "fr/tzipper/path"
+    autoload :Node,         "fr/tzipper/node"
+  end
+
+  class << TZipper
+
+    # Constructors a zipper for traversing the given tree or
+    # subtree. The `node` value can be any structure where
+    #
+    #   node#children
+    #     an array of child nodes
+    #
+    #   node#leaf?
+    #     true if the node is not allowed have children
+    #
+    #   node#copy(children: [...])
+    #     creates a new node with the given children
+    #
+    #   node#cons(xs)
+    #     returns a new list [node, *xs]
+    #
+    # @return [AbstractCursor]
+    def build(node)
+      Fr::TZipper::RootCursor.new(node)
+    end
+  end
+
+end

data/lib/fr/tzipper/abstract_cursor.rb

@@ -0,0 +1,351 @@
+module Fr
+  module TZipper
+
+    class AbstractCursor
+
+      # @return [#leaf?, #children, #copy, #cons]
+      # abstract :node
+
+      # @return [AbstractPath]
+      # abstract :path
+
+      # @group Querying the Tree Location
+      #########################################################################
+
+      # (see AbstractPath#depth)
+      def depth
+        path.depth
+      end
+
+      # (see AbstractPath#first?)
+      def first?
+        path.first?
+      end
+
+      # (see AbstractPath#last?)
+      def last?
+        path.last?
+      end
+
+      # True if the node has no children
+      # abstract :leaf?
+
+      # True if the node has no parent
+      # abstract :root?
+
+      # Returns nodes between this zipper and the other, including `self.node`
+      # and `other.node` as end points. When this and the other zipper point to
+      # the same node within the tree, a single node is returned. Otherwise, the
+      # nodes are returned in order according to a left-to-right depth-first
+      # pre-order traversal.
+      #
+      # @note This method assumes `other` is a zipper for the same tree as the
+      #   tree wrapped by `this`. In general, there is no way to know if that is
+      #   or isn't the case, without comparing the entire tree. If this method
+      #   is called on two different trees, the results are undefined.
+      #
+      # @return [Array]
+      def between(other)
+        # Collect ancestors of self, sorted oldest first (deepest last). This
+        # forms a boundary of nodes, which is called a "spine" below
+        zipper = self
+        lspine = [self]
+
+        until zipper.root?
+          zipper = zipper.up
+          lspine.unshift(zipper)
+        end
+
+        # Collect ancestors of self, sorted oldest first (deepest last). This
+        # forms a list of boundary nodes, which is called a "spine" below
+        zipper = other
+        rspine = [other]
+
+        until zipper.root?
+          zipper = zipper.up
+          rspine.unshift(zipper)
+        end
+
+        # Now we have two spines, both beginning with the root node. We remove
+        # the prefix common to both spines.
+        while a = lspine.first and b = rspine.first
+          if a.path == b.path
+            lspine.shift
+            rspine.shift
+          else
+            break
+          end
+        end
+
+        if lspine.empty?
+          # The other node is a child of self's node, and rspine contains all
+          # the nodes along the path between the two nodes, not including the
+          # self node.
+          return node.cons(rspine.map(&:node))
+
+        elsif rspine.empty?
+          # Self's node is a child of other's node, and lspine contains all
+          # the nodes along the path between the two nodes, not including the
+          # other node
+          return other.node.cons(lspine.map(&:node))
+
+        elsif lspine.head.path.position > rspine.head.path.position
+          # The first elements of lspine and rspine are siblings that share a
+          # common parent. Arrange them such that lspine is on the left, and
+          # so rspine is on the right
+          lspine, rspine = rspine, lspine
+        end
+
+        between = []
+
+        # Starting at the bottom of the left spine working upward, accumulate
+        # all the nodes to the right of the spine. Remember this is contained
+        # within the subtree under lspine.head
+        lspine.each{|z| between << z.node }
+        lspine.tail.reverse.each do |zipper|
+          until zipper.last?
+            zipper = zipper.next
+            between.concat(zipper.flatten)
+          end
+        end
+
+        # For the sibling nodes directly between (not including) lspine.head
+        # and rspine.head, we can accumulate the entire subtrees.
+        count  = rspine.head.path.position - lspine.head.path.position - 1
+        zipper = lspine.head
+
+        count.times do
+          zipper = zipper.next
+          between.concat(zipper.flatten)
+        end
+
+        between << rspine.head.node
+
+        rspine.tail.each do |zipper|
+          count  = zipper.path.position
+          zipper = zipper.first
+
+          # We have to do a bit more work to traverse the siblings in left-to-
+          # right order, because `zipper` is now the left spine. We start on
+          # the first sibling and move left a fixed number of times
+          count.times do
+            between.concat(zipper.flatten)
+            zipper = zipper.next
+          end
+
+          # Now zipper is along the left spine. We don't expand it here, but the
+          # next item in rspine is the next child along the left spine
+          between << zipper.node
+        end
+
+        between
+      end
+
+      # Flattens the subtree into an Array of nodes. The nodes are arranged
+      # according to a depth-first left-to-right preorder traversal.
+      #
+      # @return [Array]
+      def flatten
+        nodes = []
+        queue = [node]
+
+        while node = queue.shift
+          nodes << node
+          queue.unshift(*node.children) unless node.leaf?
+        end
+
+        nodes
+      end
+
+      # @group Traversing the Tree
+      #########################################################################
+
+      # Navigate to the first child node
+      #
+      # @return [MemoizedCursor]
+      def down
+        @__down ||= begin
+          if leaf?
+            raise Errors::ZipperError,
+              "cannot descend into leaf node"
+          end
+
+          head, *tail = @node.children
+
+          MemoizedCursor.new(head,
+            Hole.new([], @path, tail), self)
+        end
+      end
+
+      # Navigate to the first child node, or if there are no children,
+      # create a placeholder where the first child node will be placed
+      #
+      # @return [AbstractCursor]
+      def dangle
+        if node.leaf?
+          raise Errors::ZipperError,
+            "cannot descend into leaf node"
+        end
+
+        if leaf?
+          DanglingCursor.new(self)
+        else
+          down
+        end
+      end
+
+      # Navigate to the `nth` child node
+      #
+      # @return [AbstractCursor]
+      def child(n)
+        if n < 0
+          raise Errors::ZipperError,
+            "child index cannot be negative"
+        end
+
+        cursor = down
+        until n.zero?
+          cursor = cursor.next
+          n -= 1
+        end
+        cursor
+      end
+
+      # Returns a list of cursors, one pointing to each child node.
+      #
+      # @return [Array<MemoizedCursor>]
+      def children
+        children = []
+
+        unless leaf?
+          zipper    = down
+          children << zipper
+
+          until zipper.last?
+            zipper    = zipper.next
+            children << zipper
+          end
+        end
+
+        children
+      end
+
+      # Recursively descend to each node's `nth` child
+      #
+      # @return [AbstractCursor]
+      def descendant(n, *ns)
+        cursor = self
+
+        n.cons(ns).each do |n|
+          cursor = cursor.child(n)
+        end
+
+        cursor
+      end
+
+      # Navigate to the parent node
+      #
+      # @return [AbstractCursor]
+      # abstract :up
+
+      # Navigate to the next (rightward) sibling node
+      #
+      # @return [AbstractCursor]
+      # abstract :next
+
+      # Navigate to the previous (leftward) sibling node
+      #
+      # @return [AbstractCursor]
+      # abstract :prev
+
+      # Navigate to the first (leftmost) sibling node
+      #
+      # @return [AbstractCursor]
+      # abstract :first
+
+      # Navigate to the last (rightmost) sibling node
+      #
+      # @return [AbstractCursor]
+      # abstract :last
+
+      # Navigate to the root node
+      #
+      # @return [RootCursor]
+      def root
+        cursor = self
+        cursor = cursor.up until cursor.root?
+        cursor
+      end
+
+      # @group Editing the Tree
+      #########################################################################
+
+      # Insert a new sibling node after (to the right of) the current node,
+      # and navigate to the new sibling node
+      #
+      # @return [EditedCursor]
+      # abstract :append, :args => %w(sibling)
+
+      # Insert a new sibling node before (to the left of) the current node,
+      # and navigate to the new sibling node
+      #
+      # @return [EditedCursor]
+      # abstract :prepend, :args => %w(sibling)
+
+      # (see #append)
+      def insert_right(sibling)
+        append(sibling)
+      end
+
+      # (see #prepend)
+      def insert_left(sibling)
+        prepend(sibling)
+      end
+
+      # Insert a new child node before (to the left of) any existing children
+      # nodes and navigate to the new child node
+      #
+      # @return [EditedCursor]
+      def prepend_child(child)
+        if node.leaf?
+          raise Errors::ZipperError,
+            "cannot add child to leaf node"
+        end
+
+        EditedCursor.new(child,
+          Hole.new([], path, node.children), self)
+      end
+
+      # Insert a new child node after (to the right of) any existing children
+      # nodes and navigate to the new child node
+      #
+      # @return [EditedCursor]
+      def append_child(child)
+        if node.leaf?
+          raise Errors::ZipperError,
+            "cannot add child to leaf node"
+        end
+
+        EditedCursor.new(child,
+          Hole.new(node.children.reverse, path, []), self)
+      end
+
+      # Replace the current node with the given node
+      #
+      # @return [AbstractCursor]
+      # abstract :replace, :args => %w(node)
+
+      # Remove the current node, and navigate to the next (rightward) node if
+      # one exists. Otherwise, navigate to the previous (leftward) node if one
+      # exists. Otherwise, create a placeholder where the next sibling node will
+      # be created.
+      #
+      # @return [EditedCursor]
+      # abstract :delete
+
+      # @endgroup
+      #########################################################################
+    end
+
+  end
+end