y-rb 0.1.0

data/lib/y/array.rb

@@ -0,0 +1,352 @@
+# frozen_string_literal: true
+
+module Y
+  # An array can be used to store and retrieve elements.
+  #
+  # The array is the replicated counterpart to a Ruby Array. It supports a
+  # subset of the Ruby Array operations, like adding, getting and deleting
+  # values by position or ranges.
+  #
+  # Someone should not instantiate an array directly, but use {Y::Doc#get_array}
+  # instead.
+  #
+  # @example
+  #   doc = Y::Doc.new
+  #   array = doc.get_array("my array")
+  #
+  #   array << 1
+  #   array.push(2)
+  #   array.concat([3, 4, 5])
+  #
+  #   array.to_a == [1, 2, 3, 4, 5] # true
+  class Array
+    # @!attribute [r] document
+    #
+    # @return [Y::Doc] The document this array belongs to
+    attr_accessor :document
+
+    # Create a new array instance
+    #
+    # @param [Y::Doc] doc
+    def initialize(doc = nil)
+      @document = doc || Y::Doc.new
+
+      super()
+    end
+
+    # Retrieves element at position
+    #
+    # @return [Object]
+    def [](index)
+      yarray_get(index)
+    end
+
+    # Inserts value at position
+    #
+    # @param [Integer] index
+    # @param [true|false|Float|Integer|String|Array|Hash] value
+    # @return [void]
+    def []=(index, value)
+      yarray_insert(transaction, index, value)
+    end
+
+    # Adds an element to the end of the array
+    #
+    # @return [void]
+    def <<(value)
+      yarray_push_back(transaction, value)
+    end
+
+    # Attach listener to array changes
+    #
+    # @example Listen to changes in array type
+    #   local = Y::Doc.new
+    #
+    #   arr = local.get_array("my array")
+    #   arr.attach(->(delta) { pp delta })
+    #
+    #   local.transact do
+    #     arr << 1
+    #   end
+    #
+    # @param [Proc] callback
+    # @param [Block] block
+    # @return [Integer]
+    def attach(callback, &block)
+      return yarray_observe(callback) unless callback.nil?
+
+      yarray_observe(block.to_proc) unless block.nil?
+    end
+
+    # Adds to array all elements from each Array in `other_arrays`.
+    #
+    # If one of the arguments isn't an Array, it is silently ignored.
+    #
+    # @example Add multiple values to array
+    #   doc = Y::Doc.new
+    #   arr = doc.get_array("my array")
+    #   arr.concat([1, 2, 3])
+    #
+    #   arr.to_a == [1, 2, 3] # true
+    #
+    # @param [Array<Array<Object>>] other_arrays
+    # @return [void]
+    def concat(*other_arrays)
+      combined = other_arrays.reduce([]) do |values, arr|
+        values.concat(arr) if arr.is_a?(::Array)
+      end
+
+      yarray_insert_range(transaction, size, combined)
+    end
+
+    # Detach listener
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
+    def detach(subscription_id)
+      yarray_unobserve(subscription_id)
+    end
+
+    # @return [void]
+    def each(&block)
+      yarray_each(block)
+    end
+
+    # Check if the array is empty
+    #
+    # @return [true|false]
+    def empty?
+      size.zero?
+    end
+
+    # Returns first element in array if there is at least one
+    #
+    # @return [Object|nil]
+    def first
+      yarray_get(0)
+    end
+
+    # Returns last element in array if there is at least one element
+    #
+    # @return [Object|nil]
+    def last
+      len = yarray_length
+      return yarray_get(yarray_length - 1) if len.positive?
+
+      nil
+    end
+
+    # rubocop:disable Naming/MethodParameterName
+
+    # Removes last (n) element(s) from array
+    #
+    # @param [Integer|nil] n Number of elements to remove
+    # @return [void]
+    def pop(n = nil)
+      len = size
+      yarray_remove(transaction, len - 1) if n.nil?
+      yarray_remove_range(transaction, len - n, n) unless n.nil?
+    end
+
+    # rubocop:enable Naming/MethodParameterName
+
+    alias push <<
+
+    # rubocop:disable Naming/MethodParameterName
+
+    # Removes first (n) element(s) from array
+    #
+    # @param [Integer|nil] n Number of elements to remove
+    # @return [void]
+    def shift(n = nil)
+      yarray_remove(transaction, 0) if n.nil?
+      yarray_remove_range(transaction, 0, n) unless nil?
+    end
+
+    # rubocop:enable Naming/MethodParameterName
+
+    # Size of array
+    #
+    # @return [Integer]
+    def size
+      yarray_length
+    end
+
+    alias length size
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    # Removes one or more elements from array
+    #
+    # **Attention:** In comparison to Array#slice, {Array#slice!} will not
+    # return the values that got removed. Even this being technically
+    # possible, it requires us to read the elements before removing them, which
+    # is not desirable in most situations.
+    #
+    # @example Removes a single element
+    #   doc = Y::Doc.new
+    #
+    #   arr = doc.get_text("my array")
+    #   arr << 1
+    #   arr << 2
+    #   arr << 3
+    #
+    #   arr.slice!(1)
+    #
+    #   arr.to_a == [1, 3] # true
+    #
+    # @overload slice!(n)
+    #   Removes nth element from array
+    #
+    # @overload slice!(start, length)
+    #   Removes a range of elements
+    #
+    # @overload slice!(range)
+    #   Removes a range of elements
+    #
+    # @return [void]
+    def slice!(*args)
+      if args.size.zero?
+        raise ArgumentError,
+              "Provide one of `index`, `range`, `start, length` as arguments"
+      end
+
+      if args.size == 1
+        arg = args.first
+
+        if arg.is_a?(Range)
+          if arg.exclude_end?
+            yarray_remove_range(transaction, arg.first,
+                                arg.last - arg.first)
+          end
+          unless arg.exclude_end?
+            yarray_remove_range(transaction, arg.first,
+                                arg.last + 1 - arg.first)
+          end
+          return nil
+        end
+
+        if arg.is_a?(Numeric)
+          yarray_remove(transaction, arg.to_int)
+          return nil
+        end
+      end
+
+      if args.size == 2
+        first, second = args
+
+        if first.is_a?(Numeric) && second.is_a?(Numeric)
+          yarray_remove_range(transaction, first, second)
+          return nil
+        end
+      end
+
+      raise ArgumentError, "Please check your arguments, can't slice."
+    end
+
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength, Metrics/PerceivedComplexity
+
+    # Convert this array to a Ruby Array
+    #
+    # @return [Array<Object>]
+    def to_a
+      yarray_to_a
+    end
+
+    # Adds an element to the beginning of the array
+    #
+    # @return [void]
+    def unshift(value)
+      yarray_push_front(transaction, value)
+    end
+
+    alias prepend unshift
+
+    private
+
+    # @!method yarray_each(proc)
+    #   Iterates over all elements in Array by calling the provided proc
+    #   with the value as argument.
+    #
+    # @param [Proc<Object>] proc A proc that is called for every element
+
+    # @!method yarray_get(index)
+    #   Retrieves content as specified index
+    #
+    # @param [Integer] index
+    # @return [Object]
+
+    # @!method yarray_insert(transaction, index, content)
+    #   Inserts content at specified index
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Boolean, Float, Integer, Array, Hash, Text] content
+    # @return [void]
+
+    # @!method yarray_insert_range(transaction, index, arr)
+    #   Inserts all elements of a given array at specified index
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Array<Boolean, Float, Integer, Array, Hash, Text>] arr
+    # @return [void]
+
+    # @!method yarray_length
+    #   Returns length of array
+    #
+    # @return [Integer] Length of array
+
+    # @!method yarray_push_back(transaction, value)
+    #   Adds an element to the end of the array
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Object] value
+    # @return [void]
+
+    # @!method yarray_push_front(transaction, value)
+    #   Adds an element to the front of the array
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Object] value
+    # @return [void]
+
+    # @!method yarray_observe(callback)
+    #
+    # @param [Proc] callback
+    # @return [Integer]
+
+    # @!method yarray_remove(transaction, index)
+    #   Removes a single element from array at index
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @return [void]
+
+    # @!method yarray_remove_range(transaction, index, length)
+    #   Removes a range of elements from array
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Integer] length
+    # @return [void]
+
+    # @!method yarray_to_a
+    #   Transforms the array into a Ruby array
+    #
+    # @return [Array]
+
+    # @!method yarray_unobserve(subscription_id)
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
+
+    # A reference to the current active transaction of the document this map
+    # belongs to.
+    #
+    # @return [Y::Transaction] A transaction object
+    def transaction
+      document.current_transaction
+    end
+  end
+end

data/lib/y/doc.rb

@@ -0,0 +1,217 @@
+# frozen_string_literal: true
+
+require_relative "transaction"
+
+module Y
+  # @example Create a local and remote doc and syncs the diff
+  #   local = Y::Doc.new
+  #   local_map = local.get_map("my map")
+  #   local_map[:hello] = "world"
+  #
+  #   remote = Y::Doc.new
+  #
+  #   diff = local.diff(remote.state)
+  #   remote.sync(diff)
+  #
+  #   remote_map = remote.get_map("my_map")
+  #   pp remote_map.to_h #=> {hello: "world"}
+  class Doc
+    # Commit current transaction
+    #
+    # This is a convenience method that invokes {Y::Transaction#commit} on the
+    # current transaction used by this document.
+    #
+    # @return [void]
+    def commit
+      current_transaction.commit
+    end
+
+    # The currently active transaction for this document
+    # @return [Y::Transaction]
+    def current_transaction
+      @current_transaction ||= begin
+        transaction = ydoc_transact
+        transaction.document = self
+        transaction
+      end
+    end
+
+    # Create a diff between this document and another document. The diff is
+    # created based on a state vector provided by the other document. It only
+    # returns the missing blocks, as binary encoded sequence.
+    #
+    # @param [::Array<Int>] state The state to create the diff against
+    # @return [::Array<Int>] Binary encoded diff
+    def diff(state)
+      ydoc_encode_diff_v1(state)
+    end
+
+    # Creates a full diff for the current document. It is similar to {#diff},
+    # but does not take a state. Instead it creates an empty state and passes it
+    # to the encode_diff function.
+    #
+    # @return [::Array<Int>] Binary encoded diff
+    def full_diff
+      empty_state = Y::Doc.new.state
+      ydoc_encode_diff_v1(empty_state)
+    end
+
+    # Gets or creates a new array by name
+    #
+    # If the optional values array is present, fills the array up with elements
+    # from the provided array. If the array already exists and isn't
+    # empty, elements are pushed to the end of the array.
+    #
+    # @param [String] name The name of the structure
+    # @param [::Array] values Optional initial values
+    # @return [Y::Array]
+    def get_array(name, values = nil)
+      array = current_transaction.get_array(name)
+      array.document = self
+      array.concat(values) unless values.nil?
+      array
+    end
+
+    # Gets or creates a new map by name
+    #
+    # If the optional input hash is present, fills the map up with key-value
+    # pairs from the provided input hash. If the map already exists and isn't
+    # empty, any existing keys are overridden and new keys are added.
+    #
+    # @param [String] name The name of the structure
+    # @param [Hash] input Optional initial map key-value pairs
+    # @return [Y::Map]
+    def get_map(name, input = nil)
+      map = current_transaction.get_map(name)
+      map.document = self
+      input&.each { |key, value| map[key] = value }
+      map
+    end
+
+    # Gets or creates a new text by name
+    #
+    # If the optional input string is provided, fills a new text with the string
+    # at creation time. If the text isn't new and not empty, appends the input
+    # to the end of the text.
+    #
+    # @param [String] name The name of the structure
+    # @param [String] input Optional initial text value
+    # @return [Y::Text]
+    def get_text(name, input = nil)
+      text = current_transaction.get_text(name)
+      text.document = self
+      text.push(input) unless input.nil?
+      text
+    end
+
+    # Gets or creates a new XMLElement by name
+    #
+    # @param [String] name The name of the structure
+    # @return [Y::XMLElement]
+    def get_xml_element(name)
+      xml_element = current_transaction.get_xml_element(name)
+      xml_element.document = self
+      xml_element
+    end
+
+    # Gets or creates a new XMLText by name
+    #
+    # @param [String] name The name of the structure
+    # @param [String] input Optional initial text value
+    # @return [Y::XMLText]
+    def get_xml_text(name, input = nil)
+      xml_text = current_transaction.get_xml_text(name)
+      xml_text.document = self
+      xml_text.push(input) unless input.nil?
+      xml_text
+    end
+
+    # Creates a state vector of this document. This can be used to compare the
+    # state of two documents with each other and to later on sync them.
+    #
+    # @return [::Array<Int>] Binary encoded state vector
+    def state
+      current_transaction.state
+    end
+
+    # Synchronizes this document with the diff from another document
+    #
+    # @param [::Array<Int>] diff Binary encoded update
+    # @return [void]
+    def sync(diff)
+      current_transaction.apply(diff)
+    end
+
+    # Restores a specific document from an update that contains full state
+    #
+    # This is doing the same as {#sync}, but it exists to be explicit about
+    # the intent. This is the companion to {#full_diff}.
+    #
+    # @param [::Array<Int>] full_diff Binary encoded update
+    # @return [void]
+    def restore(full_diff)
+      current_transaction.apply(full_diff)
+    end
+
+    # rubocop:disable Metrics/MethodLength
+
+    # Creates a new transaction and provides it to the given block
+    #
+    # @example Insert into text
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #
+    #   doc.transact do
+    #     text << "Hello, World!"
+    #   end
+    #
+    # @yield [transaction]
+    # @yieldparam [Y::Transaction] transaction
+    # @yieldreturn [void]
+    # @return [Y::Transaction]
+    def transact
+      current_transaction.commit
+
+      if block_given?
+        # create new transaction just for the lifetime of this block
+        tmp_transaction = ydoc_transact
+        tmp_transaction.document = self
+
+        # override transaction for the lifetime of the block
+        @current_transaction = tmp_transaction
+
+        yield tmp_transaction
+
+        tmp_transaction.commit
+      end
+
+      # create new transaction
+      @current_transaction = ydoc_transact
+      @current_transaction.document = self
+
+      current_transaction
+    end
+
+    # rubocop:enable Metrics/MethodLength
+
+    # @!method ydoc_encode_diff_v1
+    #   Encodes the diff of current document state vs provided state
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_encode_diff_v1(other_state)
+    #
+    # @return [Array<Integer>] Binary encoded update
+    # @!visibility private
+
+    # @!method ydoc_transact
+    #   Creates a new transaction for the document
+    #
+    #   @example Create transaction on doc
+    #     doc = Y::Doc.new
+    #     tx = doc.ydoc_transact
+    #
+    # @return [Y::Transaction] The transaction object
+    # @!visibility private
+  end
+end