y-rb 0.3.2-x86_64-linux → 0.4.0-x86_64-linux

data/lib/y/doc.rb

@@ -26,37 +26,26 @@ module Y
     #
     # @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
+      current_transaction(&:commit)
     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
+    # @param state [::Array<Integer>] The state to create the diff against
+    # @return [::Array<Integer>] Binary encoded diff
     def diff(state = ZERO_STATE)
-      ydoc_encode_diff_v1(state)
+      current_transaction { |tx| ydoc_encode_diff_v1(tx, 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
+    # @return [::Array<Integer>] Binary encoded diff
     def full_diff
-      empty_state = Y::Doc.new.state
-      ydoc_encode_diff_v1(empty_state)
+      diff
     end
 
     # Gets or creates a new array by name
@@ -65,11 +54,11 @@ module Y
     # 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
+    # @param name [String] The name of the structure
+    # @param values [::Array] Optional initial values
     # @return [Y::Array]
     def get_array(name, values = nil)
-      array = current_transaction.get_array(name)
+      array = ydoc_get_or_insert_array(name)
       array.document = self
       array.concat(values) unless values.nil?
       array
@@ -81,11 +70,11 @@ module Y
     # 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
+    # @param name [String] The name of the structure
+    # @param input [Hash] Optional initial map key-value pairs
     # @return [Y::Map]
     def get_map(name, input = nil)
-      map = current_transaction.get_map(name)
+      map = ydoc_get_or_insert_map(name)
       map.document = self
       input&.each { |key, value| map[key] = value }
       map
@@ -97,11 +86,11 @@ module Y
     # 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
+    # @param name [String] The name of the structure
+    # @param input [String] Optional initial text value
     # @return [Y::Text]
     def get_text(name, input = nil)
-      text = current_transaction.get_text(name)
+      text = ydoc_get_or_insert_text(name)
       text.document = self
       text << input unless input.nil?
       text
@@ -109,21 +98,31 @@ module Y
 
     # Gets or creates a new XMLElement by name
     #
-    # @param [String] name The name of the structure
+    # @param name [String] 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 = ydoc_get_or_insert_xml_element(name)
+      xml_element.document = self
       xml_element
     end
 
+    # Gets or creates a new XMLFragment by name
+    #
+    # @param name [String] The name of the fragment
+    # @return [Y::XMLFragment]
+    def get_xml_fragment(name)
+      xml_fragment = ydoc_get_or_insert_xml_fragment(name)
+      xml_fragment.document = self
+      xml_fragment
+    end
+
     # Gets or creates a new XMLText by name
     #
-    # @param [String] name The name of the structure
-    # @param [String] input Optional initial text value
+    # @param name [String] The name of the structure
+    # @param input [String] Optional initial text value
     # @return [Y::XMLText]
     def get_xml_text(name, input = nil)
-      xml_text = current_transaction.get_xml_text(name)
+      xml_text = ydoc_get_or_insert_xml_text(name)
       xml_text.document = self
       xml_text << input unless input.nil?
       xml_text
@@ -132,17 +131,17 @@ module Y
     # 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
+    # @return [::Array<Integer>] Binary encoded state vector
     def state
-      current_transaction.state
+      current_transaction(&:state)
     end
 
     # Synchronizes this document with the diff from another document
     #
-    # @param [::Array<Int>] diff Binary encoded update
+    # @param diff [::Array<Integer>] Binary encoded update
     # @return [void]
     def sync(diff)
-      current_transaction.apply(diff)
+      current_transaction { |tx| tx.apply(diff) }
     end
 
     # Restores a specific document from an update that contains full state
@@ -150,54 +149,43 @@ module Y
     # 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
+    # @param full_diff [::Array<Integer>] Binary encoded update
     # @return [void]
     def restore(full_diff)
-      current_transaction.apply(full_diff)
+      current_transaction { |tx| tx.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]
+    # Creates a new 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
+      # 1. release potentially existing transaction
+      if @current_transaction
+        @current_transaction.free
+        @current_transaction = nil
       end
 
-      # create new transaction
+      # 2. store new transaction in instance variable
       @current_transaction = ydoc_transact
       @current_transaction.document = self
 
-      current_transaction
+      # 3. call block with reference to current_transaction
+      yield @current_transaction
+    ensure
+      @current_transaction&.free
+      @current_transaction = nil
     end
 
-    # rubocop:enable Metrics/MethodLength
+    # @!visibility private
+    def current_transaction(&block)
+      raise "provide a block" unless block
 
-    # @!method ydoc_encode_diff_v1
+      # 1. instance variable is set, just use it
+      return yield @current_transaction if @current_transaction
+
+      # 2. forward block to transact
+      transact(&block) unless @current_transaction
+    end
+
+    # @!method ydoc_encode_diff_v1(tx, state_vector)
     #   Encodes the diff of current document state vs provided state
     #
     #   @example Create transaction on doc
@@ -216,5 +204,23 @@ module Y
     #
     # @return [Y::Transaction] The transaction object
     # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_element(name)
+    #   Creates a new XMLText for the document
+    #
+    # @return [Y::XMLElement]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_fragment(name)
+    #   Creates a new XMLFragment for the document
+    #
+    # @return [Y::XMLFragment]
+    # @!visibility private
+
+    # @!method ydoc_get_or_insert_xml_text(name)
+    #   Creates a new XMLText for the document
+    #
+    # @return [Y::XMLText]
+    # @!visibility private
   end
 end

data/lib/y/map.rb

@@ -27,7 +27,7 @@ module Y
 
     # Create a new map instance
     #
-    # @param [Y::Doc] doc
+    # @param doc [Y::Doc]
     def initialize(doc = nil)
       @document = doc || Y::Doc.new
 
@@ -36,8 +36,8 @@ module Y
 
     # Attach a listener to get notified about any changes to the map
     #
-    # @param [Proc] callback
-    # @param [Block] block
+    # @param callback [Proc]
+    # @param block [Block]
     # @return [Integer]
     def attach(callback, &block)
       return ymap_observe(callback) unless callback.nil?
@@ -49,7 +49,7 @@ module Y
     #
     # @return [Self]
     def clear
-      ymap_clear(transaction)
+      document.current_transaction { |tx| ymap_clear(tx) }
       self
     end
 
@@ -70,10 +70,10 @@ module Y
     #   m.delete(:nosuch) { |key| "Key #{key} not found" }# => "Key nosuch not found"
     #   m # => {}
     #
-    # @param [String, Symbol] key
+    # @param key [String|Symbol]
     # @return [void]
     def delete(key)
-      value = ymap_remove(transaction, key)
+      value = document.current_transaction { |tx| ymap_remove(tx, key) }
       if block_given? && key?(key)
         yield key
       else
@@ -85,7 +85,7 @@ module Y
 
     # Detach listener
     #
-    # @param [Integer] subscription_id
+    # @param subscription_id [Integer]
     # @return [void]
     def detach(subscription_id)
       ymap_unobserve(subscription_id)
@@ -93,38 +93,38 @@ module Y
 
     # @return [void]
     def each(&block)
-      ymap_each(block)
+      document.current_transaction { |tx| ymap_each(tx, block) }
     end
 
     # @return [true|false]
     def key?(key)
-      ymap_contains(key)
+      document.current_transaction { |tx| ymap_contains(tx, key) }
     end
 
     alias has_key? key?
 
     # @return [Object]
     def [](key)
-      ymap_get(key)
+      document.current_transaction { |tx| ymap_get(tx, key) }
     end
 
     # @return [void]
     def []=(key, val)
-      ymap_insert(transaction, key, val)
+      document.current_transaction { |tx| ymap_insert(tx, key, val) }
     end
 
     # Returns size of map
     #
     # @return [Integer]
     def size
-      ymap_size
+      document.current_transaction { |tx| ymap_size(tx) }
     end
 
     # Returns a Hash representation of this map
     #
     # @return [Hash]
     def to_h
-      ymap_to_h
+      document.current_transaction { |tx| ymap_to_h(tx) }
     end
 
     # Returns a JSON representation of map
@@ -134,69 +134,66 @@ module Y
       to_h.to_json
     end
 
-    private
-
-    # @!method ymap_clear()
+    # @!method ymap_clear(tx)
     #   Removes all key-value pairs from Map
+    #
+    # @param tx [Y::Transaction]
 
-    # @!method ymap_contains(key)
+    # @!method ymap_contains(tx, key)
     #   Check if a certain key is in the Map
     #
-    # @param [String|Symbol] key
+    # @param tx [Y::Transaction]
+    # @param key [String|Symbol]
     # @return [Boolean] True, if and only if the key exists
 
-    # @!method ymap_each(proc)
+    # @!method ymap_each(tx, proc)
     #   Iterates over all key-value pairs in Map by calling the provided proc
     #   with the key and the value as arguments.
     #
-    # @param [Proc<String, Any>] proc A proc that is called for every element
+    # @param tx [Y::Transaction]
+    # @param proc [Proc<String|Any>] A proc that is called for every element
 
-    # @!method ymap_get(key)
+    # @!method ymap_get(tx, key)
     #   Returns stored value for key or nil if none is present
     #
-    # @param [String|Symbol] key
-    # @return [Any|Nil] Value or nil
+    # @param tx [Y::Transaction]
+    # @param key [String|Symbol]
+    # @return [Object|nil] Value or nil
 
-    # @!method ymap_insert(transaction, key, value)
+    # @!method ymap_insert(tx, key, value)
     #   Insert value for key. In case the key already exists, the previous value
     #   will be overwritten.
     #
-    # @param [Y::Transaction] transaction
-    # @param [String|Symbol] key
-    # @param [Any] value
+    # @param tx [Y::Transaction]
+    # @param key [String|Symbol]
+    # @param value [Object]
 
     # @!method ymap_observe(callback)
     #
-    # @param [Proc] callback
+    # @param callback [Proc]
     # @return [Integer]
 
-    # @!method ymap_remove(transaction, key)
+    # @!method ymap_remove(tx, key)
     #   Removes key-value pair from Map if key exists.
     #
-    # @param [Y::Transaction] transaction
-    # @param [String|Symbol] key
+    # @param tx [Y::Transaction]
+    # @param key [String|Symbol]
 
-    # @!method ymap_size()
+    # @!method ymap_size(tx)
     #   Returns number of key-value pairs stored in map
     #
+    # @param tx [Y::Transaction]
     # @return [Integer] Number of key-value pairs
 
-    # @!method ymap_to_h()
+    # @!method ymap_to_h(tx)
     #   Returns a Hash representation of the Map
     #
+    # @param tx [Y::Transaction]
     # @return [Hash] Hash representation of Map
 
     # @!method ymap_unobserve(subscription_id)
     #
-    # @param [Integer] subscription_id
+    # @param subscription_id [Integer]
     # @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