y-rb 0.1.0

data/lib/y/map.rb

@@ -0,0 +1,200 @@
+# frozen_string_literal: true
+
+require "json"
+
+module Y
+  # A map can be used to store and retrieve key-value pairs.
+  #
+  # The map is the replicated counterpart to a Hash. It supports a subset
+  # of the Hash operations, like adding, getting and deleting values by key.
+  #
+  # Someone should not instantiate a map directly, but use {Y::Doc#get_map}
+  # instead.
+  #
+  # @example
+  #   doc = Y::Doc.new
+  #   map = doc.get_map("my map")
+  #
+  #   map[:hello] = "world"
+  #   puts map[:hello]
+  class Map
+    # @!attribute [r] document
+    #
+    # @return [Y::Doc] The document this map belongs to
+    attr_accessor :document
+
+    # Create a new map instance
+    #
+    # @param [Y::Doc] doc
+    def initialize(doc = nil)
+      @document = doc || Y::Doc.new
+
+      super()
+    end
+
+    # Attach a listener to get notified about any changes to the map
+    #
+    # @param [Proc] callback
+    # @param [Block] block
+    # @return [Integer]
+    def attach(callback, &block)
+      return ymap_observe(callback) unless callback.nil?
+
+      ymap_observe(block.to_proc) unless block.nil?
+    end
+
+    # Removes all map entries
+    #
+    # @return [Self]
+    def clear
+      ymap_clear(transaction)
+      self
+    end
+
+    # rubocop:disable Layout/LineLength
+
+    # Deletes the entry for the given key and returns its associated value.
+    #
+    # @example Deletes the entry and return associated value
+    #
+    #   m = doc.get_map("my map")
+    #   m[:bar] = 1
+    #   m.delete(:bar) # => 1
+    #   m # => {}
+    #
+    # @example Unknown key is handled in block
+    #
+    #   m = doc.get_map("my map")
+    #   m.delete(:nosuch) { |key| "Key #{key} not found" }# => "Key nosuch not found"
+    #   m # => {}
+    #
+    # @param [String, Symbol] key
+    # @return [void]
+    def delete(key)
+      value = ymap_remove(transaction, key)
+      if block_given? && key?(key)
+        yield key
+      else
+        value
+      end
+    end
+
+    # rubocop:enable Layout/LineLength
+
+    # Detach listener
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
+    def detach(subscription_id)
+      ymap_unobserve(subscription_id)
+    end
+
+    # @return [void]
+    def each(&block)
+      ymap_each(block)
+    end
+
+    # @return [true|false]
+    def key?(key)
+      ymap_contains(key)
+    end
+
+    alias has_key? key?
+
+    # @return [Object]
+    def [](key)
+      ymap_get(key)
+    end
+
+    # @return [void]
+    def []=(key, val)
+      ymap_insert(transaction, key, val)
+    end
+
+    # Returns size of map
+    #
+    # @return [Integer]
+    def size
+      ymap_size
+    end
+
+    # Returns a Hash representation of this map
+    #
+    # @return [Hash]
+    def to_h
+      ymap_to_h
+    end
+
+    # Returns a JSON representation of map
+    #
+    # @return [String] JSON string
+    def to_json(*_args)
+      to_h.to_json
+    end
+
+    private
+
+    # @!method ymap_clear()
+    #   Removes all key-value pairs from Map
+
+    # @!method ymap_contains(key)
+    #   Check if a certain key is in the Map
+    #
+    # @param [String|Symbol] key
+    # @return [Boolean] True, if and only if the key exists
+
+    # @!method ymap_each(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
+
+    # @!method ymap_get(key)
+    #   Returns stored value for key or nil if none is present
+    #
+    # @param [String|Symbol] key
+    # @return [Any|Nil] Value or nil
+
+    # @!method ymap_insert(transaction, 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
+
+    # @!method ymap_observe(callback)
+    #
+    # @param [Proc] callback
+    # @return [Integer]
+
+    # @!method ymap_remove(transaction, key)
+    #   Removes key-value pair from Map if key exists.
+    #
+    # @param [Y::Transaction] transaction
+    # @param [String|Symbol] key
+
+    # @!method ymap_size()
+    #   Returns number of key-value pairs stored in map
+    #
+    # @return [Integer] Number of key-value pairs
+
+    # @!method ymap_to_h()
+    #   Returns a Hash representation of the Map
+    #
+    # @return [Hash] Hash representation of Map
+
+    # @!method ymap_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/rb.rb

@@ -0,0 +1,17 @@
+# frozen_string_literal: true
+
+require "rutie"
+require_relative "array"
+require_relative "doc"
+require_relative "map"
+require_relative "text"
+require_relative "transaction"
+require_relative "version"
+require_relative "xml"
+
+module Y
+  Rutie.new(:y_rb).init(
+    "Init_yrb",
+    File.join(__dir__, "..")
+  )
+end

data/lib/y/text.rb

@@ -0,0 +1,370 @@
+# frozen_string_literal: true
+
+module Y
+  # A text can be used insert and remove string fragments. It also supports
+  # formatting and the concept of embeds, which are supported data types that
+  # added as metadata.
+  #
+  # The text is the replicated counterpart to a String. It supports a subset
+  # of String operations, like appending, insert at position and slicing.
+  #
+  # Someone should not instantiate a text directly, but use {Y::Doc#get_text}
+  # instead.
+  #
+  # @example
+  #   doc = Y::Doc.new
+  #   text = doc.get_text("my text")
+  #
+  #   text << "Hello, World!"
+  #   puts text.to_s
+  class Text
+    # @!attribute [r] document
+    #
+    # @return [Y::Doc] The document this text belongs to
+    attr_accessor :document
+
+    # Create a new text instance
+    #
+    # @param [Y::Doc] doc
+    def initialize(doc = nil)
+      @document = doc || Y::Doc.new
+
+      super()
+    end
+
+    # Appends a string at the end of the text
+    #
+    # @return [void]
+    def <<(str)
+      ytext_push(transaction, str)
+    end
+
+    # Attach listener to text changes
+    #
+    # @example Listen to changes in text type
+    #   local = Y::Doc.new
+    #
+    #   text = local.get_text("my text")
+    #   text.attach(->(delta) { pp delta }) # { insert: "Hello, World!" }
+    #
+    #   local.transact do
+    #     text << "Hello, World!"
+    #   end
+    #
+    # @example Listen to changes in text type
+    #   local = Y::Doc.new
+    #
+    #   text = local.get_text("my text")
+    #   text.attach(->(delta) { pp delta }) # { insert: "Hello, World!" }
+    #
+    #   text << "Hello, World!"
+    #
+    #   # todo: required, otherwise segfault
+    #   local.commit
+    #
+    # @param [Proc] callback
+    # @param [Block] block
+    # @return [Integer]
+    def attach(callback, &block)
+      return ytext_observe(callback) unless callback.nil?
+
+      ytext_observe(block.to_proc) unless block.nil?
+    end
+
+    # Detach listener
+    #
+    # @param [Integer] subscription_id
+    # @return [void]
+    def detach(subscription_id)
+      ytext_unobserve(subscription_id)
+    end
+
+    # Checks if text is empty
+    #
+    # @example Check if text is empty
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #
+    #   text.empty? # true
+    #
+    # @return [true|false]
+    def empty?
+      length.zero?
+    end
+
+    # rubocop:disable Metrics/AbcSize, Metrics/MethodLength
+
+    # Insert a value at position and with optional attributes. This method is
+    # similar to [String#insert](https://ruby-doc.org/core-3.1.2/String.html),
+    # except for the optional third `attrs` argument.
+    #
+    # @example Insert a string at position
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #   text << "Hello, "
+    #
+    #   text.insert(7, "World!")
+    #
+    #   puts text.to_s == "Hello, World!" # true
+    #
+    # The value can be any of the supported types:
+    # - Boolean
+    # - String
+    # - Numeric
+    # - Array (where element types must be supported)
+    # - Hash (where the the types of key and values must be supported)
+    #
+    # @param [Integer] index
+    # @param [String, Float, Array, Hash] value
+    # @param [Hash|nil] attrs
+    # @return [void]
+    def insert(index, value, attrs = nil)
+      if value.is_a?(String)
+        ytext_insert(transaction, index, value) if attrs.nil?
+        unless attrs.nil?
+          ytext_insert_with_attrs(transaction, index, value,
+                                  attrs)
+        end
+        return nil
+      end
+
+      if can_insert?(value)
+        ytext_insert_embed(transaction, index, value) if attrs.nil?
+        unless attrs.nil?
+          ytext_insert_embed_with_attrs(transaction, index, value,
+                                        attrs)
+        end
+        return nil
+      end
+
+      raise ArgumentError,
+            "Can't insert value. `#{value.class.name}` isn't supported."
+    end
+
+    # rubocop:enable Metrics/AbcSize, Metrics/MethodLength
+
+    # Applies formatting to text
+    #
+    # @example Add formatting to first word
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #
+    #   attrs = {format: "bold"}
+    #   text.format(0, 2, attrs)
+    #
+    # @param [Integer] index
+    # @param [Integer] length
+    # @param [Hash] attrs
+    # @return [void]
+    def format(index, length, attrs)
+      ytext_format(transaction, index, length, attrs)
+    end
+
+    # Returns length of text
+    #
+    # @return [Integer] Length of text
+    def length
+      ytext_length
+    end
+
+    alias size length
+
+    # rubocop:disable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+    # Removes a part from text
+    #
+    # **Attention:** In comparison to String#slice, {Text#slice!} will not
+    # return the substring that gets removed. Even this being technically
+    # possible, it requires us to read the substring before removing it, which
+    # is not desirable in most situations.
+    #
+    # @example Removes a single character
+    #   doc = Y::Doc.new
+    #
+    #   text = doc.get_text("my text")
+    #   text << "Hello"
+    #
+    #   text.slice!(0)
+    #
+    #   text.to_s == "ello" # true
+    #
+    # @example Removes a range of characters
+    #   doc = Y::Doc.new
+    #
+    #   text = doc.get_text("my text")
+    #   text << "Hello"
+    #
+    #   text.slice!(1..2)
+    #   text.to_s == "Hlo" # true
+    #
+    #   text.slice!(1...2)
+    #   text.to_s == "Ho" # true
+    #
+    # @example Removes a range of chars from start and for given length
+    #   doc = Y::Doc.new
+    #
+    #   text = doc.get_text("my text")
+    #   text << "Hello"
+    #
+    #   text.slice!(0, 3)
+    #
+    #   text.to_s == "lo" # true
+    #
+    # @overload slice!(index)
+    #   Removes a single character at index
+    #
+    # @overload slice!(start, length)
+    #   Removes a range of characters
+    #
+    # @overload slice!(range)
+    #   Removes a range of characters
+    #
+    # @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)
+          ytext_remove_range(transaction, arg.first, arg.last - arg.first)
+          return nil
+        end
+
+        if arg.is_a?(Numeric)
+          ytext_remove_range(transaction, arg.to_int, 1)
+          return nil
+        end
+      end
+
+      if args.size == 2
+        start, length = args
+
+        if start.is_a?(Numeric) && length.is_a?(Numeric)
+          ytext_remove_range(transaction, start, length)
+          return nil
+        end
+      end
+
+      raise ArgumentError, "Please check your arguments, can't slice."
+    end
+
+    # rubocop:enable Metrics/AbcSize, Metrics/CyclomaticComplexity, Metrics/MethodLength
+
+    # Returns string representation of text
+    #
+    # @example
+    #   doc = Y::Doc.new
+    #   text = doc.get_text("my text")
+    #   text << "Hello"
+    #
+    #   puts text.to_s # "Hello"
+    #
+    # @return [String]
+    def to_s
+      ytext_to_s
+    end
+
+    private
+
+    def can_insert?(value)
+      value.is_a?(NilClass) ||
+        value.is_a?(Symbol) ||
+        [true, false].include?(value) ||
+        value.is_a?(Numeric) ||
+        value.is_a?(Enumerable) ||
+        value.is_a?(Hash)
+    end
+
+    # @!method ytext_insert(transaction, index, chunk)
+    #   Insert into text at position
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [String] chunk
+    # @return [nil]
+
+    # @!method ytext_insert_embed(transaction, index, content)
+    #   Insert into text at position
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Y::Text, Y::Array, Y::Map] content
+    # @return [nil]
+
+    # @!method ytext_insert_embed_with_attrs(transaction, index, embed, attrs)
+    #   Insert into text at position
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Y::Text, Y::Array, Y::Map] embed
+    # @param [Hash] attrs
+    # @return [nil]
+
+    # @!method ytext_insert_with_attrs(transaction, index, chunk, attrs)
+    #   Insert into text at position
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [String] chunk
+    # @param [Hash] attrs
+    # @return [nil]
+
+    # @!method ytext_push(transaction, value)
+    #   Returns length of text
+    #
+    # @param [Y::Transaction] transaction
+    # @param [String] value
+    # @return [nil]
+
+    # @!method ytext_remove_range(transaction, index, length)
+    #   Removes a range from text
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Integer] length
+    # @return [nil]
+
+    # @!method ytext_format(transaction, index, length, attrs)
+    #   Formats a text range
+    #
+    # @param [Y::Transaction] transaction
+    # @param [Integer] index
+    # @param [Integer] length
+    # @param [Hash] attrs
+    # @return [nil]
+
+    # @!method ytext_length()
+    #   Returns length of text
+    #
+    # @return [Integer]
+
+    # @!method ytext_observe(proc)
+    #   Observe text changes
+    #
+    # @param [Proc] proc
+    # @return [Integer]
+
+    # @!method ytext_to_s()
+    #   Returns string representation of text
+    #
+    # @return [String]
+
+    # @!method ytext_unobserve(subscription_id)
+    #   Detach listener
+    #
+    # @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/transaction.rb

@@ -0,0 +1,143 @@
+# frozen_string_literal: true
+
+module Y
+  class Transaction
+    # @!attribute [r] document
+    #
+    # @return [Y::Doc] The document this array belongs to
+    attr_accessor :document
+
+    def initialize(doc = nil)
+      @document = doc
+
+      super()
+    end
+
+    # Applies the binary encoded update for this document. This will bring the
+    # the document to the same state as the one the update is from.
+    #
+    # @param [::Array<Integer>] update
+    # @return [void]
+    def apply(update)
+      ytransaction_apply_update(update)
+    end
+
+    # Commits transaction
+    #
+    # @return [void]
+    def commit
+      ytransaction_commit
+    end
+
+    # Create or get array type
+    #
+    # @param [String] name
+    # @return [Y::Array]
+    def get_array(name)
+      array = ytransaction_get_array(name)
+      array.document = document
+      array
+    end
+
+    # Create or get map type
+    #
+    # @param [String] name
+    # @return [Y::Map]
+    def get_map(name)
+      map = ytransaction_get_map(name)
+      map.document = document
+      map
+    end
+
+    # Create or get text type
+    #
+    # @param [String] name
+    # @return [Y::Text]
+    def get_text(name)
+      text = ytransaction_get_text(name)
+      text.document = document
+      text
+    end
+
+    # Create or get XMLElement type
+    #
+    # @param [String] name
+    # @return [Y::XMLElement]
+    def get_xml_element(name)
+      xml_element = ytransaction_get_xml_element(name)
+      xml_element.document = document
+      xml_element
+    end
+
+    # Create or get XMLText type
+    #
+    # @param [String] name
+    # @return [Y::XMLText]
+    def get_xml_text(name)
+      xml_text = ytransaction_get_xml_text(name)
+      xml_text.document = document
+      xml_text
+    end
+
+    # Return state vector for transaction
+    #
+    # @return [::Array<Integer>]
+    def state
+      ytransaction_state_vector
+    end
+
+    # @!method ytransaction_apply_update(update)
+    #   Returns or creates an array by name
+    #
+    # @param [::Array<Integer>] update
+    # @return [void]
+    # @!visibility private
+
+    # @!method ytransaction_commit()
+    #
+    # @return [void]
+    # @!visibility private
+
+    # @!method ytransaction_get_array(name)
+    #   Returns or creates an array by name
+    #
+    # @param [String] name Name of the array structure to retrieve or create
+    # @return [Y::Array] Array structure
+    # @!visibility private
+
+    # @!method ytransaction_get_map(name)
+    #   Returns or creates a map structure by name
+    #
+    # @param [String] name Name of the map structure to retrieve or create
+    # @return [Y::Map] Map structure
+    # @!visibility private
+
+    # @!method ytransaction_get_text(name)
+    #   Returns or creates a text structure by name
+    #
+    # @param [String] name Name of the text structure to retrieve or create
+    # @return [Y::Text] Text structure
+    # @!visibility private
+
+    # @!method ytransaction_get_xml_element(name)
+    #   Returns or creates a XML structure by name
+    #
+    # @param [String] name Name of the XML element structure to retrieve or
+    #     create
+    # @return [Y::XMLElement] XMLElement structure
+    # @!visibility private
+
+    # @!method ytransaction_get_xml_text(name)
+    #   Returns or creates a XML structure by name
+    #
+    # @param [String] name Name of the XML element structure to retrieve or
+    #     create
+    # @return [Y::XMLElement] XMLElement structure
+    # @!visibility private
+
+    # @!method ytransaction_state_vector
+    #
+    # @return [Array<Integer>]
+    # @!visibility private
+  end
+end