rich-text 0.2.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 2ccc9aaba7e28826fd5559ee6a2fdf8bd358faa5d6cf55bf5f9b2b3819dc33ed
+  data.tar.gz: be7c87956e6e8c06f60b96f05c115b63430ce431eeba5faf4e9e15f66fa3e478
+SHA512:
+  metadata.gz: f3619d730230b49cb083f6866479848c0c2bdfb8a9b7c6095163f6d54eef6aca227052ffd0f64334800725e42410b0f04d27f2f52d588454a6b50cda636221fe
+  data.tar.gz: 57148b5ce1ffa60035391a8f7aeed6ba7bde5a6f9c4774f52b7375d72d2332ca25157b10e058edf2171971de76d2cc27e33e0c52d37bf61c1e10a88e4b0b5aba

data/.gitignore

@@ -0,0 +1,9 @@
+/.bundle/
+/.yardoc
+/Gemfile.lock
+/_yardoc/
+/coverage/
+/doc/
+/pkg/
+/spec/reports/
+/tmp/

data/.ruby-version

@@ -0,0 +1 @@
+2.2.5

data/.travis.yml

@@ -0,0 +1,5 @@
+sudo: false
+language: ruby
+rvm:
+  - 2.2.5
+before_install: gem install bundler -v 1.13.6

data/.yardopts

@@ -0,0 +1 @@
+--embed-mixins --markup=markdown

data/Gemfile

@@ -0,0 +1,4 @@
+source 'https://rubygems.org'
+
+# Specify your gem's dependencies in rich-text.gemspec
+gemspec

data/LICENSE.txt

@@ -0,0 +1,22 @@
+The MIT License (MIT)
+
+Copyright (c) 2014 Jason Chen
+Copyright (c) 2016 Blake Thomson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,99 @@
+# Rich Text
+
+Ported from https://github.com/quilljs/delta, this library provides an elegant way of creating, manipulating, iterating, and transforming rich-text deltas and documents with a ruby-native API.
+
+rich-text (aka Quill delta) is a format for representing attributed text. It aims to be intuitive and human readable with the ability to express any possible document or diff between documents.
+
+This format is suitable for [operational transformation](https://en.wikipedia.org/wiki/Operational_transformation) and defines several functions ([`compose`](#compose), [`transform`](#transform), [`transform_position`](#transform-position), and [`diff`](#diff)) to support this use case.
+
+For more information on the format itself, please consult the original README: https://github.com/quilljs/delta
+
+## Docs
+
+Please see the generated [API docs](https://www.rubydoc.info/gems/rich-text) for more details on all of the available classes and methods.
+
+## TODO
+
+- Implement `Delta#include?(other)`
+- Finish writing tests
+
+## Quick Example
+
+```ruby
+gandalf = RichText::Delta.new([
+  { insert: 'Gandalf', attributes: { bold: true } },
+  { insert: ' the ' },
+  { insert: 'Grey', attributes: { color: '#ccc' } }
+])
+# => #<RichText::Delta [insert="Gandalf" {"bold"=>true}, insert=" the ", insert="Grey" {"color"=>"#ccc"}]>
+
+# Keep the first 12 characters, delete the next 4, and insert a white 'White'
+death = RichText::Delta.new
+                       .retain(12)
+                       .delete(4)
+                       .insert('White', { color: '#fff' })
+# => #<RichText::Delta [retain=12, delete=4, insert="White" {:color=>"#fff"}]>
+
+gandalf.compose(death)
+# => #<RichText::Delta [insert="Gandalf" {"bold"=>true}, insert=" the ", insert="White" {:color=>"#fff"}]>
+```
+
+## Operations
+
+### Insert Operation
+
+Insert operations have an `insert` key defined. A String value represents inserting text. Any other type represents inserting an embed (however only one level of object comparison will be performed for equality).
+
+In both cases of text and embeds, an optional `attributes` key can be defined with an Hash to describe additonal formatting information. Formats can be changed by the [retain](#retain) operation.
+
+```ruby
+# Insert a bolded "Text"
+{ insert: "Text", attributes: { bold: true } }
+
+# Insert a link
+{ insert: "Google", attributes: { link: 'https://www.google.com' } }
+
+# Insert an embed
+{
+  insert: { image: 'https://octodex.github.com/images/labtocat.png' },
+  attributes: { alt: "Lab Octocat" }
+}
+
+# Insert another embed
+{
+  insert: { video: 'https://www.youtube.com/watch?v=dMH0bHeiRNg' },
+  attributes: {
+    width: 420,
+    height: 315
+  }
+}
+```
+
+### Delete Operation
+
+Delete operations have a Number `delete` key defined representing the number of characters to delete. All embeds have a length of 1.
+
+```ruby
+# Delete the next 10 characters
+{ delete: 10 }
+```
+
+### Retain Operation
+
+Retain operations have a Number `retain` key defined representing the number of characters to keep (other libraries might use the name keep or skip). An optional `attributes` key can be defined with an Hash to describe formatting changes to the character range. A value of `null` in the `attributes` Hash represents removal of that key.
+
+*Note: It is not necessary to retain the last characters of a document as this is implied.*
+
+```ruby
+# Keep the next 5 characters
+{ retain: 5 }
+
+# Keep and bold the next 5 characters
+{ retain: 5, attributes: { bold: true } }
+
+# Keep and unbold the next 5 characters
+# More specifically, remove the bold key in the attributes Hash
+# in the next 5 characters
+{ retain: 5, attributes: { bold: null } }
+```
+

data/Rakefile

@@ -0,0 +1,13 @@
+require "bundler/gem_tasks"
+require "rake/testtask"
+require "yard"
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << "test"
+  t.libs << "lib"
+  t.test_files = FileList['test/**/*_test.rb']
+end
+
+YARD::Rake::YardocTask.new(:doc)
+
+task :default => :test

data/bin/console

@@ -0,0 +1,14 @@
+#!/usr/bin/env ruby
+
+require "bundler/setup"
+require "rich-text"
+
+# You can add fixtures and/or initialization code here to make experimenting
+# with your gem easier. You can also use a different console, if you like.
+
+# (If you use this, don't forget to add pry to your Gemfile!)
+# require "pry"
+# Pry.start
+
+require "irb"
+IRB.start

data/bin/rake

@@ -0,0 +1,29 @@
+#!/usr/bin/env ruby
+# frozen_string_literal: true
+
+#
+# This file was generated by Bundler.
+#
+# The application 'rake' is installed as part of a gem, and
+# this file is here to facilitate running it.
+#
+
+require "pathname"
+ENV["BUNDLE_GEMFILE"] ||= File.expand_path("../../Gemfile",
+  Pathname.new(__FILE__).realpath)
+
+bundle_binstub = File.expand_path("../bundle", __FILE__)
+
+if File.file?(bundle_binstub)
+  if File.read(bundle_binstub, 150) =~ /This file was generated by Bundler/
+    load(bundle_binstub)
+  else
+    abort("Your `bin/bundle` was not generated by Bundler, so this binstub cannot run.
+Replace `bin/bundle` by running `bundle binstubs bundler --force`, then run this command again.")
+  end
+end
+
+require "rubygems"
+require "bundler/setup"
+
+load Gem.bin_path("rake", "rake")

data/bin/setup

@@ -0,0 +1,8 @@
+#!/usr/bin/env bash
+set -euo pipefail
+IFS=$'\n\t'
+set -vx
+
+bundle install
+
+# Do any other automated setup that you need to do here

data/lib/rich-text.rb

@@ -0,0 +1,31 @@
+module RichText
+  def self.config
+    @config ||= Config.new
+  end
+
+  def self.configure
+    yield config
+  end
+end
+
+require 'rich-text/version'
+require 'rich-text/config'
+require 'rich-text/delta'
+require 'rich-text/html'
+
+RichText.configure do |c|
+  c.safe_mode = true
+  c.html_default_block_tag = 'p'
+  c.html_block_tags = {
+    firstheader: 'h1',
+    secondheader: 'h2',
+    thirdheader: 'h3',
+    list: ->(content, value) { %(<ol><li>#{value}</li></ol>) },
+    bullet: ->(content, value) { %(<ul><li>#{value}</li></ul>) }
+  }
+  c.html_inline_tags = {
+    bold: 'strong',
+    italic: 'em',
+    link: ->(content, value) { %(<a href="#{value}">#{content}</a>) }
+  }
+end

data/lib/rich-text/attributes.rb

@@ -0,0 +1,29 @@
+module RichText
+  # @api private
+  module Attributes
+    class << self
+      def compose(a, b, keep_nil)
+        return b if a.nil?
+        return a if b.nil?
+        result = b.merge(a) { |k,vb,va| vb }
+        result.delete_if { |k,v| v.nil? } unless keep_nil
+        result
+      end
+
+      def diff(a, b)
+        return b if a.nil?
+        return a if b.nil?
+        (a.keys | b.keys).each_with_object({}) do |key, memo|
+          memo[key] = b[key] if a[key] != b[key]
+        end
+      end
+
+      def transform(a, b, priority)
+        return b if a.nil? || a.empty? || b.nil? || b.empty? || !priority
+        (b.keys - a.keys).each_with_object({}) do |key, memo|
+          memo[key] = b[key]
+        end
+      end
+    end
+  end
+end

data/lib/rich-text/config.rb

@@ -0,0 +1,6 @@
+module RichText
+  # @api private
+  class Config
+    attr_accessor :safe_mode, :html_default_block_tag, :html_block_tags, :html_inline_tags
+  end
+end

data/lib/rich-text/delta.rb

@@ -0,0 +1,490 @@
+require 'json'
+require 'rich-text/diff'
+require 'rich-text/iterator'
+require 'rich-text/op'
+require 'rich-text/attributes'
+
+module RichText
+  # A Delta is made up of an array of operations. All methods maintain the property that Deltas are represented in the most compact form. For example two consecutive insert operations with the same attributes will be merged into one. Thus a vanilla deep Hash/Array comparison can be used to determine Delta equality.
+  #
+  # A Delta with only insert operations can be used to represent a fully formed document. This can be thought of as a Delta applied to an empty document.
+  class Delta
+    # @return [Array<Op>]
+    attr_reader :ops
+
+    # Parses a new Delta object from incoming data.
+    # @param data [String, Array, Hash] String, Array of operations, or a Hash with an `:ops` or `'ops'` key set to an array of operations
+    # @raise [ArgumentError] if an argument other than a String, Array, or Hash is passed, or if any of the contained operations cannot be parsed by {Op.parse}
+    # @example
+    #   # All equivalent
+    #   RichText::Delta.new("abc")
+    #   RichText::Delta.new([{ insert: 'abc' }])
+    #   RichText::Delta.new({ ops: [{ insert: 'abc' }] })
+    def initialize(data = [])
+      if data.is_a?(String)
+        @ops = [Op.new(:insert, data)]
+      elsif data.is_a?(Array)
+        @ops = data.map { |h| Op.parse(h) }
+      elsif data.is_a?(Hash) && (data.key?('ops') || data.key?(:ops))
+        @ops = (data['ops'] || data[:ops]).map { |h| Op.parse(h) }
+      else
+        ArgumentError.new("Please provide either String, Array or Hash with an 'ops' key containing an Array")
+      end
+
+      @ops
+    end
+
+    # Appends an insert operation. A no-op if the provided value is the empty string.
+    # @param value [String|{ String => Object }] the value to insert, either a String or a Hash with a single String or Symbol key
+    # @param attributes [Hash]
+    # @return [Delta] `self` for chainability
+    # @example
+    #   delta.insert('abc').insert('xyz', { bold: true })
+    #   delta.insert({ image: 'http://i.imgur.com/FUCb95Y.gif' })
+    def insert(value, attributes = {})
+      return self if value.is_a?(String) && value.length == 0
+      push(Op.new(:insert, value, attributes))
+    end
+
+    # Appends a delete operation. A no-op if value <= 0.
+    # @param value [Integer] the number of characters to delete
+    # @return [Delta] `self` for chainability
+    # @example
+    #   delta.delete(5)
+    def delete(value)
+      return self if value <= 0
+      push(Op.new(:delete, value))
+    end
+
+    # Appends a retain operation. A no-op if value <= 0.
+    # @param value [Integer] the number of characters to skip or change attributes for
+    # @param attributes [Hash] leave blank to leave attributes unchanged
+    # @return [Delta] `self` for chainability
+    # @example
+    #   delta.retain(4).retain(5, { color: '#0c6' })
+    def retain(value, attributes = {})
+      return self if value <= 0
+      push(Op.new(:retain, value, attributes))
+    end
+
+    # Adds a new operation to the end of the delta, possibly merging it with the previously-last op if the types and attributes match, and ensuring that inserts always come before deletes.
+    # @param op [Op] the operation to add
+    # @return [Delta] `self` for chainability
+    def push(op)
+      index = @ops.length
+      last_op = @ops[index - 1]
+
+      if last_op
+        if last_op.delete? && op.delete?
+          @ops[index - 1] = Op.new(:delete, last_op.value + op.value)
+          return self
+        end
+
+        # Since it does not matter if we insert before or after deleting at the
+        # same index, always prefer to insert first
+        if last_op.delete? && op.insert?
+          index -= 1
+          last_op = @ops[index - 1]
+          if !last_op
+            @ops.unshift(op)
+            return self
+          end
+        end
+
+        if last_op.attributes == op.attributes
+          if last_op.insert?(String) && op.insert?(String)
+            @ops[index - 1] = Op.new(:insert, last_op.value + op.value, last_op.attributes)
+            return self
+          elsif last_op.retain? && op.retain?
+            @ops[index - 1] = Op.new(:retain, last_op.value + op.value, last_op.attributes)
+            return self
+          end
+        end
+      end
+
+      if index == @ops.length
+        @ops.push(op)
+      else
+        @ops[index, 0] = op
+      end
+
+      return self
+    end
+    alias :<< :push
+
+    # Modifies self by removing the last op if it was a retain without attributes.
+    # @return [Delta] `self` for chainability
+    def chop!
+      last_op = @ops.last
+      if last_op && last_op.retain? && !last_op.attributes?
+        @ops.pop
+      end
+      return self
+    end
+
+    # Returns true if all operations are inserts, i.e. a fully-composed document
+    # @return [Boolean]
+    def insert_only?
+      @ops.all?(&:insert?)
+    end
+    alias :document? :insert_only?
+
+    # Returns true if the last operation is a string insert that ends with a `\n` character.
+    # @return [Boolean]
+    def trailing_newline?
+      return false unless @ops.last && @ops.last.insert?(String)
+      @ops.last.value.end_with?("\n")
+    end
+
+    # Returns true if `other` is a substring of `self`
+    # @param other [Delta]
+    # @return [Boolean]
+    # @todo Not implemented yet
+    def include?(other)
+      raise NotImplementedError.new("TODO")
+    end
+
+    # Yields ops of at most `size` length to the block, or returns an enumerator which will do the same
+    # @param size [Integer]
+    # @yield [op] an {Op} object
+    # @return [Enumerator, Delta] if no block given, returns an {Enumerator}, else returns `self` for chainability
+    # @example
+    #   delta = RichText::Delta.new.insert('abc')
+    #   delta.each_slice(2).to_a # => [#<RichText::Op insert="ab">, #<RichText::Op insert="c">]
+    def each_slice(size = 1)
+      return enum_for(:each_slice, size) unless block_given?
+      Iterator.new(@ops).each(size) { |op| yield op }
+      self
+    end
+
+    # Yields char + attribute pairs of at most length = 1 to the block, or returns an enumerator which will do the same.
+    # Non-string inserts will result in that value being yielded instead of a string.
+    # The behavior is not defined with non-insert operations.
+    # @yield [char, attributes]
+    # @return [Enumerator, Delta] if no block given, returns an {Enumerator}, else returns `self` for chainability
+    # @example
+    #   delta = RichText::Delta.new.insert('a', { bold: true }).insert('b').insert({ image: 'http://i.imgur.com/YtQPTnw.gif' })
+    #   delta.each_char.to_a # => [["a", { bold: true }], ["b", {}], [{ image: "http://i.imgur.com/YtQPTnw.gif" }, {}]]
+    def each_char
+      return enum_for(:each_char) unless block_given?
+      each_slice(1) { |op| yield op.value, op.attributes }
+      self
+    end
+
+    # Yields {Delta} objects corresponding to each `\n`-separated line in the document, each including a trailing newline (except for the last if no trailing newline is present overall).
+    # The behavior is not defined with non-insert operations.
+    # @yield [delta]
+    # @return [Enumerator, Delta] if no block given, returns an {Enumerator}, else returns `self` for chainability
+    # @example
+    #   delta = RichText::Delta.new.insert("abc\n123\n")
+    #   delta.each_line.to_a # => [#<RichText::Delta [insert="abc\n"]>, #<RichText::Delta [insert="123\n"]>]
+    def each_line
+      return enum_for(:each_line) unless block_given?
+
+      iter = Iterator.new(@ops)
+      line = Delta.new
+
+      while iter.next?
+        op = iter.next
+        if !op.insert?(String)
+          line.push(op)
+          next
+        end
+
+        offset = 0
+        while idx = op.value.index("\n", offset)
+          line.push op.slice(offset, idx - offset + 1)
+          yield line
+          line = Delta.new
+          offset = idx + 1
+        end
+
+        if offset < op.value.length
+          line.push op.slice(offset)
+        end
+      end
+
+      yield line if line.length > 0
+    end
+
+    # Yields each operation in the delta, as-is.
+    # @yield [op] an {Op} object
+    # @return [Enumerator, Delta] if no block given, returns an {Enumerator}, else returns `self` for chainability
+    def each_op
+      return enum_for(:each_op) unless block_given?
+      @ops.each { |op| yield op }
+      self
+    end
+
+    # @return [Integer] the sum of the lengths of each operation.
+    # @example
+    #   RichText::Delta.new.insert('Hello').length # => 5
+    #   RichText::Delta.new.insert('A').retain(2).delete(1).length # => 4
+    def length
+      @ops.reduce(0) { |sum, op| sum + op.length }
+    end
+
+    # Returns a copy containing a subset of operations, measured in number of characters.
+    # An operation may be subdivided if needed to return just the requested length. Non-string inserts cannot be subdivided (naturally, as they have length 1).
+    # @param start [Integer] starting offset
+    # @param len [Integer] how many characters
+    # @return [Delta] whose length is at most `len`
+    # @example
+    #   delta = RichText::Delta.new.insert('Hello', { bold: true }).insert(' World')
+    #   copy = delta.slice() # => #<RichText::Delta [insert="Hello" {:bold=>true}, insert=" World"]>
+    #   world = delta.slice(6) # => #<RichText::Delta [insert="World"]>
+    #   space = delta.slice(5, 1) # => #<RichText::Delta [insert=" "]>
+    def slice(start = 0, len = length)
+      if start.is_a?(Range)
+        len = start.size
+        start = start.first
+      end
+
+      delta = Delta.new
+      start = [0, length + start].max if start < 0
+      finish = start + len
+      iter = Iterator.new(@ops)
+      idx = 0
+      while idx < finish && iter.next?
+        if idx < start
+          op = iter.next(start - idx)
+        else
+          op = iter.next(finish - idx)
+          delta.push(op)
+        end
+        idx += op.length
+      end
+      return delta
+    end
+    alias :[] :slice
+
+    # Returns a Delta that is equivalent to first applying the operations of `self`, then applying the operations of `other` on top of that.
+    # @param other [Delta]
+    # @return [Delta]
+    # @example
+    #   a = RichText::Delta.new.insert('abc')
+    #   b = RichText::Delta.new.retain(1).delete(1)
+    #   a.compose(b) # => #<RichText::Delta [insert="ac"]>
+    def compose(other)
+      iter_a = Iterator.new(@ops)
+      iter_b = Iterator.new(other.ops)
+      delta = Delta.new
+      while iter_a.next? || iter_b.next?
+        if iter_b.peek.insert?
+          delta.push(iter_b.next)
+        elsif iter_a.peek.delete?
+          delta.push(iter_a.next)
+        else
+          len = [iter_a.peek.length, iter_b.peek.length].min
+          op_a = iter_a.next(len)
+          op_b = iter_b.next(len)
+          if op_b.retain?
+            if op_a.retain?
+              attrs = Attributes.compose(op_a.attributes, op_b.attributes, true)
+              delta.push(Op.new(:retain, len, attrs))
+            else
+              attrs = Attributes.compose(op_a.attributes, op_b.attributes, false)
+              delta.push(Op.new(:insert, op_a.value, attrs))
+            end
+          elsif op_b.delete? && op_a.retain?
+            delta.push(op_b)
+          end
+        end
+      end
+      delta.chop!
+    end
+    alias :| :compose
+
+    # Modifies `self` by the concatenating this and another document Delta's operations.
+    # Correctly handles the case of merging the last operation of `self` with the first operation of `other`, if possible.
+    # The behavior is not defined when either `self` or `other` has non-insert operations.
+    # @param other [Delta]
+    # @return [Delta] `self`
+    # @example
+    #   a = RichText::Delta.new.insert('Hello')
+    #   b = RichText::Delta.new.insert(' World!')
+    #   a.concat(b) # => #<RichText::Delta [insert="Hello World!"]>
+    def concat(other)
+      if other.length > 0
+        push(other.ops.first)
+        @ops.concat(other.ops.slice(1..-1))
+      end
+      self
+    end
+
+    # The non-destructive version of {#concat}
+    # @see #concat
+    def +(other)
+      dup.concat(other)
+    end
+
+    # Returns a Delta representing the difference between two documents.
+    # The behavior is not defined when either `self` or `other` has non-insert operations.
+    # @param other [Delta]
+    # @return [Delta]
+    # @example
+    #   a = RichText::Delta.new.insert('Hello')
+    #   b = RichText::Delta.new.insert('Hello!')
+    #   a.diff(b) # => #<RichText::Delta [retain=5, insert="!"]>
+    #   a.compose(a.diff(b)) == b # => true
+    def diff(other)
+      delta = Delta.new
+      return delta if self == other
+
+      iter = Iterator.new(@ops)
+      other_iter = Iterator.new(other.ops)
+
+      Diff.new(self, other) do |kind, len|
+        while len > 0
+          case kind
+          when :insert
+            op_len = [len, other_iter.peek.length].min
+            delta.push(other_iter.next(op_len))
+          when :delete
+            op_len = [len, iter.peek.length].min
+            iter.next(op_len)
+            delta.delete(op_len)
+          when :retain
+            op_len = [iter.peek.length, other_iter.peek.length, len].min
+            this_op = iter.next(op_len)
+            other_op = other_iter.next(op_len)
+            if this_op.value == other_op.value
+              delta.retain(op_len, Attributes.diff(this_op.attributes, other_op.attributes))
+            else
+              delta.push(other_op).delete(op_len)
+            end
+          end
+          len -= op_len
+        end
+      end
+
+      delta.chop!
+    end
+    alias :- :diff
+
+    # Transform other Delta against own operations, such that [transformation property 1 (TP1)](https://en.wikipedia.org/wiki/Operational_transformation#Convergence_properties) holds:
+    #
+    #     self.compose(self.transform(other, true)) == other.compose(other.transform(self, false))
+    #
+    # If called with a number, then acts as an alias for {#transform_position}
+    # @param other [Delta, Integer] the Delta to be transformed, or a number to pass along to {#transform_position}
+    # @param priority [Boolean] used to break ties; if true, then operations from `self` are seen as having priority over operations from `other`:
+    #
+    #   - when inserts from `self` and `other` occur at the same index, `other`'s insert is shifted over in order for `self`'s to come first
+    #   - retained attributes from `other` can be obsoleted by retained attributes in `self`
+    # @example
+    #   a = RichText::Delta.new.insert('a')
+    #   b = RichText::Delta.new.insert('b')
+    #   a.transform(b, true) # => #<RichText::Delta [retain=1, insert="b"]>
+    #   a.transform(b, false) # => #<RichText::Delta [insert="b"]>
+    #
+    #   a = RichText::Delta.new.retain(1, { color: '#bbb' })
+    #   b = RichText::Delta.new.retain(1, { color: '#fff', bold: true })
+    #   a.transform(b, true) # => #<RichText::Delta [retain=1 {:bold=>true}]>
+    #   a.transform(b, false) # => #<RichText::Delta [retain=1 {:color=>"#fff", :bold=>true}]>
+    def transform(other, priority)
+      return transform_position(other, priority) if other.is_a?(Integer)
+      iter = Iterator.new(@ops)
+      other_iter = Iterator.new(other.ops)
+      delta = Delta.new
+      while iter.next? || other_iter.next?
+        if iter.peek.insert? && (priority || !other_iter.peek.insert?)
+          delta.retain iter.next.length
+        elsif other_iter.peek.insert?
+          delta.push other_iter.next
+        else
+          len = [iter.peek.length, other_iter.peek.length].min
+          op = iter.next(len)
+          other_op = other_iter.next(len)
+          if op.delete?
+            # Our delete makes their delete redundant, or removes their retain
+            next
+          elsif other_op.delete?
+            delta.push(other_op)
+          else
+            # We either retain their retain or insert
+            delta.retain(len, Attributes.transform(op.attributes, other_op.attributes, priority))
+          end
+        end
+      end
+      delta.chop!
+    end
+    alias :^ :transform
+
+    # Transform an index against the current delta. Useful for shifting cursor & selection positions in response to remote changes.
+    # @param index [Integer] an offset position that may be shifted by inserts and deletes happening beforehand
+    # @param priority [Boolean] used to break ties
+    #
+    #   - if true, then an insert happening exactly at `index` does not impact the return value
+    #   - if false, then an insert happening exactly at `index` results in the return value being incremented by that insert's length
+    # @return [Integer]
+    # @example
+    #   delta = RichText::Delta.new.retain(3).insert('def')
+    #   delta.transform_position(3, true) # => 3
+    #   delta.transform_position(3, false) # => 6
+    def transform_position(index, priority)
+      iter = Iterator.new(@ops)
+      offset = 0
+      while iter.next? && offset <= index
+        op = iter.next
+        if op.delete?
+          index -= [op.length, index - offset].min
+          next
+        elsif op.insert? && (offset < index || !priority)
+          index += op.length
+        end
+        offset += op.length
+      end
+      return index
+    end
+
+    # @return [Hash] the Hash representation of this object, by converting each contained op into a Hash
+    def to_h
+      { :ops => @ops.map(&:to_h) }
+    end
+
+    # @return [String] the JSON representation of this object, by delegating to {#to_h}
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # Returns a plain text representation of this delta (lossy).
+    # The behavior is not defined with non-insert operations.
+    # @param embed_str [String] the string to use in place of non-string insert operations
+    # @return [String]
+    def to_plaintext(embed_str: '!')
+      @ops.each_with_object('') do |op, str|
+        if op.insert?(String)
+          str << op.value
+        elsif embed_str
+          str << embed_str
+        end
+      end
+    end
+
+    # Returns an HTML representation of this delta.
+    # @see {HTML.render}
+    # @todo Support options that control how rich-text attributes are converted into HTML tags and attributes.
+    def to_html(options = {})
+      HTML.render(self, options)
+    end
+
+    # Returns a String useful for debugging that includes details of each contained operation.
+    # @return [String]
+    # @example
+    #   '#<RichText::Delta [retain=3, delete=1, insert="abc" {:bold=>true}, insert={:image=>"http://i.imgur.com/vwGN6.gif"}]>'
+    def inspect
+      str = "#<#{self.class.name} ["
+      str << @ops.map { |o| o.inspect(false) }.join(", ")
+      str << "]>"
+    end
+
+    # A Delta is equal to another if all the ops are equal.
+    # @param other [Delta]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(RichText::Delta) && @ops == other.ops
+    end
+    alias_method :eql?, :==
+  end
+end

data/lib/rich-text/diff.rb

@@ -0,0 +1,34 @@
+require 'diff-lcs'
+
+module RichText
+  # @api private
+  class Diff
+    attr_reader :chunks
+
+    def initialize(left, right)
+      @chunks = []
+      ::Diff::LCS.traverse_sequences(left.to_plaintext, right.to_plaintext, self)
+      @chunks.each { |c| yield c } if block_given?
+    end
+
+    def push(type)
+      if @chunks.any? && @chunks[-1][0] == type
+        @chunks[-1][1] += 1
+      else
+        @chunks.push [type, 1]
+      end
+    end
+
+    def match(args)
+      push :retain
+    end
+
+    def discard_a(args)
+      push :delete
+    end
+
+    def discard_b(args)
+      push :insert
+    end
+  end
+end

data/lib/rich-text/html.rb

@@ -0,0 +1,66 @@
+require 'delegate'
+require 'singleton'
+
+module RichText
+  # @todo Work in progress
+  class HTML
+    ConfigError = Class.new(StandardError)
+
+    attr_reader :config
+
+    def self.render(delta, options)
+      new(RichText.config).render(delta)
+    end
+
+    def initialize(config)
+      @default_block_tag = config.html_default_block_tag
+      @block_tags = config.html_block_tags
+      @inline_tags = config.html_inline_tags
+    end
+
+    def render(delta)
+      raise TypeError.new("cannot convert retain or delete ops to html") unless delta.insert_only?
+      html = delta.each_line.inject('') do |html, line|
+        html << render_line(line)
+      end
+      normalize(html)
+    end
+
+    private
+
+    def render_line(delta)
+      # TODO: handle a delta without a trailing "\n"
+      line = ''
+      delta.slice(0, delta.length - 1).each_op do |op|
+        line << apply_tags(@inline_tags, op.value, op.attributes)
+      end
+      delta.slice(delta.length - 1, 1).each_op do |op|
+        if op.attributes?
+          line = apply_tags(@block_tags, line, op.attributes)
+        else
+          line = apply_tag(@default_block_tag, line, true)
+        end
+      end
+      line
+    end
+
+    def apply_tags(tags, text, attributes)
+      attributes.inject(text) do |content, (key, value)|
+        apply_tag(tags[key], content, value)
+      end
+    end
+
+    def apply_tag(tag, content, value)
+      if tag.respond_to?(:call)
+        tag.call(content, value)
+      elsif tag
+        "<#{tag}>#{content}</#{tag}>"
+      end
+    end
+
+    def normalize(html)
+      # merge sibling tags
+      # standardize nesting order
+    end
+  end
+end

data/lib/rich-text/iterator.rb

@@ -0,0 +1,49 @@
+module RichText
+  # @api private
+  class Iterator
+    def initialize(ops)
+      @ops = ops
+      reset
+    end
+
+    def each(size = 1)
+      return enum_for(:each, size) unless block_given?
+      yield self.next(size) while next?
+    end
+
+    def peek
+      if op = @ops[@index]
+        op.slice(@offset)
+      else
+        Op.new(:retain, Float::INFINITY)
+      end
+    end
+
+    def next?
+      peek.length < Float::INFINITY
+    end
+
+    def next(length = Float::INFINITY)
+      next_op = @ops[@index]
+      offset = @offset
+      if next_op
+        if length >= next_op.length - offset
+          length = next_op.length - offset
+          @index += 1
+          @offset = 0
+        else
+          @offset += length
+        end
+
+        next_op.slice(offset, length)
+      else
+        return Op.new(:retain, Float::INFINITY)
+      end
+    end
+
+    def reset
+      @index = 0
+      @offset = 0
+    end
+  end
+end

data/lib/rich-text/op.rb

@@ -0,0 +1,153 @@
+require 'active_support/core_ext/hash/indifferent_access'
+
+module RichText
+  # Operations are the immutable units of rich-text deltas and documents. As such, we have a class that wraps these values and provides convenient methods for querying type and contents, and for subdividing as needed by {Delta#slice}.
+  class Op
+    TYPES = [:insert, :retain, :delete].freeze
+
+    # @return [Symbol] one of {TYPES}
+    attr_reader :type
+    # @return [String, Integer, Hash] value depends on type
+    attr_reader :value
+    # @return [Hash]
+    attr_reader :attributes
+
+    # Creates a new Op object from a Hash. Used by {Delta#initialize} to parse raw data into a convenient form.
+    # @param data [Hash] containing exactly one of {TYPES} as a key, and optionally an `:attributes` key. munged to provide indifferent access via String or Symbol keys
+    # @return [Op]
+    # @raise [ArgumentError] if `data` contains invalid keys, i.e. zero or more than one of {TYPES}
+    # @example
+    #   RichText::Op.parse({ insert: 'abc', attributes: { bold: true } })
+    #   # => #<RichText::Op insert="abc" {"bold"=>true}>
+    #
+    #   RichText::Op.parse({ insert: 'abc', retain: 3 })
+    #   # => ArgumentError: must be a Hash containing exactly one of the following keys: [:insert, :retain, :delete]
+    def self.parse(data)
+      data = data.to_h.with_indifferent_access
+      type_keys = (data.keys & TYPES.map(&:to_s))
+      if type_keys.length != 1
+        raise ArgumentError.new("must be a Hash containing exactly one of the following keys: #{TYPES.inspect}")
+      end
+
+      type = type_keys.first.to_sym
+      value = data[type]
+      if [:retain, :delete].include?(type) && !value.is_a?(Integer)
+        raise ArgumentError.new("value must be an Integer when type is #{type.inspect}")
+      end
+
+      attributes = data[:attributes]
+      if attributes && !attributes.is_a?(Hash)
+        raise ArgumentError.new("attributes must be a Hash")
+      end
+
+      self.new(type, value, attributes)
+    end
+
+    # Creates a new Op object, based on a type, value, and attributes. No sanity checking is performed on the arguments; please use {Op.parse} for dealing with untrusted user input.
+    # @param type [Symbol] one of {TYPES}
+    # @param value [Integer, String, Hash] various values corresponding to type
+    # @param attributes [Hash]
+    # @return [Op]
+    def initialize(type, value, attributes = nil)
+      @type = type.to_sym
+      @value = value.freeze
+      @attributes = (attributes || {}).freeze
+    end
+
+    # @return [Boolean] whether any attributes are present; `false` when attributes is empty, `true` otherwise.
+    # @example
+    #   RichText::Op.new(:insert, 'abc').attributes? # => false
+    #   RichText::Op.new(:insert, 'abc', {}).attributes? # => false
+    #   RichText::Op.new(:insert, 'abc', { bold: true }).attributes? # => true
+    def attributes?
+      !attributes.empty?
+    end
+
+    # Returns whether type is `:insert`, and value is an instance of `kind`
+    # @param kind [Class] pass a class to perform an additional `is_a?` check on {value}
+    # @return [Boolean]
+    # @example
+    #   RichText::Op.new(:insert, 'abc').insert? # => true
+    #   RichText::Op.new(:insert, 'abc').insert?(String) # => true
+    #   RichText::Op.new(:insert, { image: 'http://i.imgur.com/y6Eo48A.gif' }).insert?(String) # => false
+    def insert?(kind = Object)
+      type == :insert && value.is_a?(kind)
+    end
+
+    # Returns whether type is `:retain` or not
+    # @return [Boolean]
+    def retain?
+      type == :retain
+    end
+
+    # Returns whether type is `:delete` or not
+    # @returns [Boolean]
+    def delete?
+      type == :delete
+    end
+
+    # Returns a number indicating the length of this op, depending of the type:
+    #
+    # - for `:insert`, returns `value.length` if a String, 1 otherwise
+    # - for `:retain` and `:delete`, returns value
+    # @return [Integer]
+    def length
+      case type
+      when :insert
+        value.is_a?(String) ? value.length : 1
+      when :retain, :delete
+        value
+      end
+    end
+
+    # Returns a copy of the op with a subset of the value, measured in number of characters.
+    # An op may be subdivided if needed to return at most the requested length. Non-string inserts cannot be subdivided (naturally, as they have length 1).
+    # @param start [Integer] starting offset
+    # @param len [Integer] how many characters
+    # @return [Op] whose length is at most `len`
+    def slice(start = 0, len = length)
+      if insert?(String)
+        Op.new(:insert, value.slice(start, len), attributes)
+      elsif insert?
+        unless start == 0 && len == 1
+          raise ArgumentError.new("cannot subdivide a non-string insert")
+        end
+        dup
+      else
+        Op.new(type, [value - start, len].min, attributes)
+      end
+    end
+
+    # @return [Hash] the Hash representation of this object, the inverse of {Op.parse}
+    def to_h
+      { type => value }.tap do |json|
+        json[:attributes] = attributes if attributes?
+      end
+    end
+
+    # @return [String] the JSON representation of this object, by delegating to {#to_h}
+    def to_json(*args)
+      to_h.to_json(*args)
+    end
+
+    # A string useful for debugging, that includes type, value, and attributes.
+    # @param wrap [Boolean] pass false to avoid including the class name (used by {Delta#inspect})
+    # @return [String]
+    # @example
+    #   RichText::Op.new(:insert, 'abc', { bold: true }).inspect # => '#<RichText::Op insert="abc" {:bold=>true}>'
+    #   RichText::Op.new(:insert, 'abc', { bold: true }).inspect(false) => 'insert="abc" {:bold=>true}'
+    def inspect(wrap = true)
+      str = "#{type}=#{value.inspect}"
+      str << " #{attributes.inspect}" if attributes?
+      wrap ? "#<#{self.class.name} #{str}>" : str
+    end
+
+    # An Op is equal to another if type, value, and attributes all match
+    # @param other [Op]
+    # @return [Boolean]
+    def ==(other)
+      other.is_a?(Op) && type == other.type && value == other.value && attributes == other.attributes
+    end
+    alias :eql? :==
+  end
+end

data/lib/rich-text/version.rb

@@ -0,0 +1,3 @@
+module RichText
+  VERSION = "0.2.0"
+end

data/rich-text.gemspec

@@ -0,0 +1,30 @@
+# coding: utf-8
+lib = File.expand_path('../lib', __FILE__)
+$LOAD_PATH.unshift(lib) unless $LOAD_PATH.include?(lib)
+require 'rich-text/version'
+
+Gem::Specification.new do |spec|
+  spec.name          = "rich-text"
+  spec.version       = RichText::VERSION
+  spec.authors       = ["Blake Thomson"]
+  spec.email         = ["thomsbg@gmail.com"]
+
+  spec.summary       = %q{A ruby wrapper and utilities for rich text JSON documents.}
+  spec.homepage      = "https://github.com/voxmedia/rich-text-ruby"
+  spec.license       = "MIT"
+
+  spec.files         = `git ls-files -z`.split("\x0").reject do |f|
+    f.match(%r{^(test|spec|features)/})
+  end
+  spec.bindir        = "exe"
+  spec.executables   = spec.files.grep(%r{^exe/}) { |f| File.basename(f) }
+  spec.require_paths = ["lib"]
+
+  spec.add_dependency "diff-lcs", "~> 1.2.5"
+  spec.add_dependency "activesupport", ">= 3.0.0"
+  # spec.add_dependency "nokogiri", ">= 1.0.0"
+  spec.add_development_dependency "bundler", "~> 1.13"
+  spec.add_development_dependency "rake", "~> 10.0"
+  spec.add_development_dependency "minitest", "~> 5.0"
+  spec.add_development_dependency "yard"
+end

metadata

@@ -0,0 +1,150 @@
+--- !ruby/object:Gem::Specification
+name: rich-text
+version: !ruby/object:Gem::Version
+  version: 0.2.0
+platform: ruby
+authors:
+- Blake Thomson
+autorequire: 
+bindir: exe
+cert_chain: []
+date: 2018-06-13 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: diff-lcs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.5
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 1.2.5
+- !ruby/object:Gem::Dependency
+  name: activesupport
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 3.0.0
+- !ruby/object:Gem::Dependency
+  name: bundler
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '1.13'
+- !ruby/object:Gem::Dependency
+  name: rake
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '10.0'
+- !ruby/object:Gem::Dependency
+  name: minitest
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '5.0'
+- !ruby/object:Gem::Dependency
+  name: yard
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '0'
+description: 
+email:
+- thomsbg@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".gitignore"
+- ".ruby-version"
+- ".travis.yml"
+- ".yardopts"
+- CHANGELOG.md
+- Gemfile
+- LICENSE.txt
+- README.md
+- Rakefile
+- bin/console
+- bin/rake
+- bin/setup
+- lib/rich-text.rb
+- lib/rich-text/attributes.rb
+- lib/rich-text/config.rb
+- lib/rich-text/delta.rb
+- lib/rich-text/diff.rb
+- lib/rich-text/html.rb
+- lib/rich-text/iterator.rb
+- lib/rich-text/op.rb
+- lib/rich-text/version.rb
+- rich-text.gemspec
+homepage: https://github.com/voxmedia/rich-text-ruby
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: A ruby wrapper and utilities for rich text JSON documents.
+test_files: []