richtext 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a41039f175ce7ee67d507040de2a1c84f58c9069
-  data.tar.gz: 60ae51774de4953ea1b5e59ef3ffb8afd2f520ac
+  metadata.gz: 1056b27569ae91520079931c9a5da0efc921467a
+  data.tar.gz: 7a58d34765134f7b85a3254de3e09a1c59cada8e
 SHA512:
-  metadata.gz: 86924ff26a091d4087245467c47e43aabd5499eb8fc785ac2ba8b2dbca596ab49d9ba79399ad6c51e65c6f629fb9ba38e6d02cd8725845f9a6c1d0ffe84f70a6
-  data.tar.gz: 8e08c49fcb57d006235eaa58258b9e0dc0b0e0e5a753594b15becda8b7715413ce6a9b0ef5f5bea8be0a1075e05902d6dad5194e87635b9d34a5dd51432dac42
+  metadata.gz: 64eac480d4354c710fc26e97888314b9e5143ea56e3ad4443530712d63168470fff018f71f768d5da6402892e58f7efd334fe07903042d78e1e605008ee25daa
+  data.tar.gz: 56c7742bfdeaac68dba853766e0214f98bbd6ab0436d1ba188a9a98ff151783d218885bcf28cb1852c21d7ce0fb429b6ab97c83eacb83ece8ab85ebee2c04df1

data/README.md

@@ -35,7 +35,7 @@ entry = rt.append('world', bold: true, my_attribute: '.')
 # Some common styling attributes are supported directly
 # This line is equivalent to entry[:italic] = true
 entry.italic = true
-# Under the covers the attributes are stored as 
+# Under the covers the attributes are stored as
 # key-value pairs, so any attribute is valid
 entry[:my_attribute] = '!'
 
@@ -43,12 +43,12 @@ entry[:my_attribute] = '!'
 puts rt.to_s # => 'hello world'
 
 # Or style the text yourself
-html = rt.to_s do |entry, string|
+html = rt.to_s do |e, string|
   # Access the attributes from the entry and format the
   # string accordingly
-  string += entry[:my_attribute] if entry[:my_attribute]
-  string = "<b>#{string}</b>" if entry.bold?
-  
+  string += e[:my_attribute] if e[:my_attribute]
+  string = "<b>#{string}</b>" if e.bold?
+
   # Return the formatted string at the end of the block
   string
 end
@@ -60,30 +60,27 @@ Implementing new formats is easy. Just extend the `RichText::Document` class and
 
 ```ruby
 class MyFormat < RichText::Document
-  # Use this method to signal if the document needs to be
-  # parsed, or if its raw form will work.
   def should_parse?
     true
   end
 
-  def self.parse string
-    base = RichText::Document::Entry.new
+  def self.parse(base, string)
     # Format specific implementation to parse a string. Here
     # each word is represented by its own entry. Entries are
     # given a random visibility attribute.
     string.split(' ').each do |word|
-      entry = RichText::Document::Entry.new word, visible: (word.length > 6)
-      base.add entry
+      base.create_child word, visible: (word.length > 6)
     end
-    base
   end
 
-  def self.render base
+  def self.render(base)
     # Format specific implementation to render the document
-    base.to_s do |entry, string|
+    str = base.to_s do |entry, string|
       next string unless entry.leaf?
       entry[:visible] ? string + ' ' : ''
-    end.rstrip!
+    end
+
+    str.rstrip
   end
 end
 

data/lib/richtext/document/entry.rb

@@ -1,142 +1,126 @@
-# Entry
-#
-# The Entry class extends the basic Node class and adds methods that make 
-# handling text a little nicer. Essentially the :text attribute is given special
-# status by allowing it to a) be set during initialization, b) only visible in 
-# leaf nodes and c) copied over when adding children to leaf nodes.
-#
-# Some attributes are also supported explicitly by the inclusion of special 
-# accesser methods. The attributes are are bold, italic, underline, color and 
-# font.
-
 module RichText
   class Document
+    # Entry
+    #
+    # The Entry class extends the basic Node class and adds methods that make
+    # handling text a little nicer. Essentially the :text attribute is given
+    # special status by allowing it to a) be set during initialization, b) only
+    # visible in leaf nodes and c) copied over when adding children to leaf
+    # nodes.
+    #
+    # Some attributes are also supported explicitly by the inclusion of special
+    # accesser methods. The attributes are are bold, italic, underline, color
+    # and font.
+    #
     class Entry < Node
-      
       # Initialize
       #
-      # Extend the default Node initializer by also accepting a string. It will, 
+      # Extend the default Node initializer by also accepting a string. It will,
       # if given, be stored as a text attribute.
-      
-      def initialize text = nil, **attributes
+      def initialize(text = nil, **attributes)
         super attributes
         self[:text] = text if text
       end
-      
-      
+
       # Text
       #
-      # Read the text of the node. This will return nil unless the node is a 
-      # leaf node. Note that nodes that are not leafs can have the text entry, 
+      # Read the text of the node. This will return nil unless the node is a
+      # leaf node. Note that nodes that are not leafs can have the text entry,
       # but it is discouraged by dissalowing access using this method.
-      
       def text
-        if leaf?
-          self[:text] || ''
-        else
-          nil
-        end
+        self[:text] || '' if leaf?
       end
-      
-      
-      # Add child
+
+      # Append
       #
-      # A child is either another node or any object that respond to #to_s.
-      
-      def add *new_children
+      # Since the text attribute is treated differently, and only leaf nodes can
+      # expose it, it must be pushed to a new child if a) this node was a leaf
+      # prior to this method call and b) its text attribute is not empty.
+      def <<(child)
         if leaf?
-          # Remove the text entry from the node and put it in a new leaf node 
+          # Remove the text entry from the node and put it in a new leaf node
           # among the children, unless it is empty
-          if t = @attributes.delete(:text)
-            new_children.unshift self.class.new(t) unless t.empty?
+          if (t = @attributes.delete :text)
+            create_child(t) unless t.empty?
           end
         end
-        
+
         super
       end
-      
-      alias_method :<<, :add
-      
-      
+
+      def create_child(text = '', **attributes)
+        super attributes.merge(text: text)
+      end
+
       # To String
       #
-      # Combine the text from all the leaf nodes in the tree, from left to 
-      # right. If a block is given the node, along with its text will be passed 
-      # as arguments. The block will be called recursivly, starting at the leaf 
-      # nodes and propagating up until the entire tree has been "rendered" in 
+      # Combine the text from all the leaf nodes in the tree, from left to
+      # right. If a block is given the node, along with its text will be passed
+      # as arguments. The block will be called recursivly, starting at the leaf
+      # nodes and propagating up until the entire tree has been "rendered" in
       # this way.
-      
-      def to_s &block
-        string = leaf? ? 
-          text : 
-          @children.reduce('') {|str, child| str + child.to_s(&block) }
-          
+      def to_s(&block)
+        string =
+          if leaf?
+            text
+          else
+            @children.reduce('') { |a, e| a + e.to_s(&block) }
+          end
+
         block_given? ? yield(self, string) : string
       end
-      
-      
+
       # Supported Text Attributes
-      #
-      
-      
+
       # Bold
       #
-      
       def bold?
         self[:bold]
       end
-      
-      def bold= b
+
+      def bold=(b)
         self[:bold] = b ? true : false
       end
-      
-      
+
       # Italic
       #
-      
       def italic?
         self[:italic]
       end
-      
-      def italic= i
+
+      def italic=(i)
         self[:italic] = i ? true : false
       end
-      
-      
+
       # Underline
       #
-      
       def underline?
         self[:underline]
       end
-      
-      def underline= u
+
+      def underline=(u)
         self[:underline] = u ? true : false
       end
-      
-      
+
       # Color
       #
-      
       def color
         self[:color]
       end
-      
-      def color= c
+
+      def color=(c)
         self[:color] = c
       end
-      
-      
+
       # Font
       #
-      
       def font
         self[:font]
       end
-      
-      def font= f
+
+      def font=(f)
         self[:font] = f
       end
     end
   end
-end
+end

data/lib/richtext/document.rb

@@ -1,45 +1,46 @@
 module RichText
+  # Document
+  #
   class Document
+    attr_reader :raw
+    protected :raw
+
     # Initialize
     #
-    # Create a new RichText Document, either from a string or from an existing 
-    # ducument. That feature is particularly useful when converting between 
+    # Create a new RichText Document, either from a string or from an existing
+    # ducument. That feature is particularly useful when converting between
     # formats.
     #
-    # When given a string or a RichText Document of the same class no parsing is 
-    # performed. Only when given a document of a different subclass will the 
-    # parser need to be run parsed. Note that the document(s) may already be in  
-    # parsed form, in which case no further parsing is performed. See #base for 
+    # When given a string or a RichText Document of the same class no parsing is
+    # performed. Only when given a document of a different subclass will the
+    # parser need to be run parsed. Note that the document(s) may already be in
+    # parsed form, in which case no further parsing is performed. See #base for
     # more details.
-    
-    def initialize arg = ''
-      @base, @raw = if self.class == arg.class
-        arg.parsed? ?
-          [arg.base, nil] :
-          [nil, arg.raw]
-      elsif Document === arg
-        # For any other RichText object we take the base node
-        [arg.base, nil]
-      elsif Entry === arg
-        # Also accept an Entry which will be used as the
-        # document base
-        [arg, nil]
-      else
-        [nil, arg.to_s]
-      end
+    def initialize(arg = '')
+      @base, @raw =
+        if arg.class == self.class
+          arg.parsed? ? [arg.base, nil] : [nil, arg.raw]
+        elsif arg.is_a? Document
+          # For any other RichText object we take the base node
+          [arg.base, nil]
+        elsif arg.is_a? Entry
+          # Also accept an Entry which will be used as the
+          # document base
+          [arg, nil]
+        else
+          [nil, arg.to_s]
+        end
     end
-    
-    
+
     # To String
     #
     # Use the static implementation of .render to convert the document back into
-    # a string. If the document was never parsed (and is unchanged) the 
+    # a string. If the document was never parsed (and is unchanged) the
     # origninal string is just returned.
     #
-    # If a block is given it will be used in place of .render to format the node 
+    # If a block is given it will be used in place of .render to format the node
     # tree.
-    
-    def to_s &block
+    def to_s(&block)
       if block_given?
         base.to_s(&block)
       elsif parsed? || should_parse?
@@ -48,133 +49,115 @@ module RichText
         @raw
       end
     end
-    
-    
+
     # Add (+)
     #
-    # Add this RichText to another.
-    
-    def + other
+    # Add another Document to this one. If the two are of (exactly) the same
+    # class and neither one has been parsed, the two raw strings will be
+    # concatenated. If the other is a Document the two base nodes will be merged
+    # and the new root added to a new Document.
+    #
+    # Lastly, if other is a string it will first be wraped in a new Document and
+    # then added to this one.
+    def +(other)
       # If the other object is of the same class, and neither
       # one of the texts have been parsed, we can concatenate
       # the raw inputs together
       if other.class == self.class && !parsed? && !other.parsed?
-        return self.class.new (@raw + other.raw)
+        return self.class.new(@raw + other.raw)
       end
-      
+
       # Same root class
-      if Document === other
-        return self.class.new (base + other.base)
-      end
-      
-      unless other.respond_to?(:to_s)
+      return self.class.new(base + other.base) if other.is_a? Document
+
+      unless other.respond_to? :to_s
         raise TypeError,
-          "cannot add #{other.class.name} to #{self.class.name}"
+              "Cannot add #{other.class.name} to #{self.class.name}"
       end
-      
+
       # Assume that the input is a raw string of the same
       # class as the current RichText object and wrap it
       # before adding it
       self + self.class.new(other)
     end
-    
-    
-    def append string, **attributes
-      node = Entry.new(string, **attributes)
-      base.add node
-      node
+
+    # Append
+    #
+    #
+    def append(string, **attributes)
+      base.create_child string, **attributes
     end
-    
-    
+
     # Base
     #
-    # Getter for the base node. If the raw input has not yet been 
+    # Getter for the base node. If the raw input has not yet been
     # parsed that will happen first, before the base node is returned.
-    
     def base
       unless @base
         @base = Entry.new
         self.class.parse @base, @raw
-        @raw  = nil # Free the cached string
+        @raw = nil
       end
-      
+
       @base
     end
-    
-    alias_method :root, :base
-    
-    
-    # Raw
-    #
-    # Protected getter for the raw input.
-    
-    protected def raw
-      @raw
-    end
-    
-    
+
+    alias root base
+
     # Parsed?
     #
-    # Returns true if the raw input has been parsed and the internal 
+    # Returns true if the raw input has been parsed and the internal
     # representation is now a tree of nodes.
-    
     def parsed?
       @raw.nil?
     end
-    
-    
+
     protected def should_parse?
       false
     end
-    
-    
+
     # Each Node
     #
     # Iterate over all Entry nodes in the document tree.
-    
-    def each_node &block
+    def each_node(&block)
       base.each(&block)
     end
-    
-    alias_method :each_entry, :each_node
-    
-    
+
+    alias each_entry each_node
+
     # Parse
     #
-    # Document type specific method for parsing a string and turning it into a 
-    # tree of entry nodes. This method is intended to be overridden when the 
-    # Document is subclassed. The default implementation just creates a top 
+    # Document type specific method for parsing a string and turning it into a
+    # tree of entry nodes. This method is intended to be overridden when the
+    # Document is subclassed. The default implementation just creates a top
     # level Entry containing the given string.
-    
-    def self.parse base, string
+
+    def self.parse(base, string)
       base[:text] = string
     end
-    
-    
+
     # Render
     #
-    # Document type specific method for rendering a tree of entry nodes. This 
-    # method is intended to be overridden when the Document is subclassed. The 
+    # Document type specific method for rendering a tree of entry nodes. This
+    # method is intended to be overridden when the Document is subclassed. The
     # default implementation just concatenates the text entries into.
-    
-    def self.render base
+
+    def self.render(base)
       base.to_s
     end
-    
-    
+
     # From
     #
-    # Convenience method for instansiating one RichText object from another. The 
-    # methods only purpose is to make that intent more clear, and to make the 
+    # Convenience method for instansiating one RichText object from another. The
+    # methods only purpose is to make that intent more clear, and to make the
     # creation from another RichText object explicit.
-    
-    def self.from doc
-      unless Document === doc
-        raise TypeError, 
-            "Can only create a #{self.name} from other RichText objects"
+    def self.from(doc)
+      unless doc.is_a? Document
+        raise TypeError,
+              "Can only create a #{name} from other RichText Documents"
       end
-          
-      self.new doc
+
+      new doc
     end
   end
-end
+end

data/lib/richtext/node.rb

@@ -1,114 +1,105 @@
-# Node
-#
-# A Node can have  children, which themselvs can have children. A tree like 
-# structure can thus be formed by composing multiple Nodes. An example of such a 
-# tree structure can be seen below.
-#
-# The Node class implements some convenience methods for iterating, left to 
-# right, over either all
-#  - nodes in the tree
-#  - leafs in the tree
-#  - direct decendant of a node
-#
-# In addition to having children a Node can also have attributes, represented by # simple key => value pairs.
-#
-#                Example Tree
-#                                        +--------------------------+
-#                     A <- Root Node     | Left to right order: ABC |
-#                    / \                 +--------------------------+
-#      Leaf Node -> B   C <- Child to A
-#    (no children)     /|\
-#                      ...
-# 
-
 module RichText
+  # Node
+  #
+  # A Node can have  children, which themselvs can have children. A tree like
+  # structure can thus be formed by composing multiple Nodes. An example of such
+  # a tree structure can be seen below.
+  #
+  # The Node class implements some convenience methods for iterating, left to
+  # right, over either all
+  #  - nodes in the tree
+  #  - leafs in the tree
+  #  - direct decendant of a node
+  #
+  # In addition to having children a Node can also have attributes, represented
+  # by simple key => value pairs.
+  #
+  #                Example Tree
+  #                                        +--------------------------+
+  #                     A <- Root Node     | Left to right order: ABC |
+  #                    / \                 +--------------------------+
+  #      Leaf Node -> B   C <- Child to A
+  #    (no children)     /|\
+  #                      ...
+  #
   class Node
     include Enumerable
-    
-    attr_reader :attributes
-    
-    def initialize **attributes
+
+    attr_reader :attributes, :children
+    protected :children
+
+    def initialize(**attributes)
       @children   = []
       @attributes = attributes
-      #@attributes[:text] = text if text
     end
-    
-    
-    def initialize_copy original
+
+    def initialize_copy(original)
       @children   = original.children.map(&:dup)
       @attributes = original.attributes.dup
     end
-    
-    
+
     # Leaf?
     #
     # Returns true if this node a leaf (childless) node.
-    
     def leaf?
       @children.empty?
     end
-    
-    
-    # Children
-    #
-    # Protected accessor for the children array. This array should never be 
-    # mutated from the outside and is only protected rather than private to be
-    # accessable to ther Nodes.
-    
-    protected def children
-      @children
-    end
-    
-    
-    # Add child
+
+    # Append
     #
-    # A child is either another node or any object that respond to #to_s.
-    
-    def add *new_children
-      new_children.each do |c|
-        @children << ((Node === c) ? c : self.class.new(c))
+    # Add a child to the end of the node child list. The child must be of this
+    # class to be accepted. Note that subclasses of Node will not accept regular
+    # Nodes. The method returns self so that multiple children can be added via
+    # chaining:
+    #   root << child_a << child_b
+    def <<(child)
+      unless child.is_a? self.class
+        raise TypeError,
+              "Only objects of class #{self.class.name} can be appended"
       end
 
-      @children
+      @children << child
+      self
     end
-    
-    alias_method :<<, :add
-    
-    
+
+    # Create Child
+    #
+    # Create and append a new child, initialized with the given attributes.
+    def create_child(**attributes)
+      child = self.class.new(**attributes)
+      self << child
+      child
+    end
+
     # Add (+)
     #
     # Combines two nodes by creating a new root and adding the two as children.
-    
-    def + other
-      self.class.new.tap {|root| root.add self, other }
+    def +(other)
+      self.class.new.tap { |root| root << self << other }
     end
-    
-    
+
     # Each
     #
     # Iterate over each node in the tree, including self.
-    
-    def each &block
+    def each(&block)
       return to_enum(__callee__) unless block_given?
-      
+
       yield self
-            
+
       @children.each do |child|
         yield child
         child.each(&block) unless child.leaf?
       end
     end
-    
-    
+
     # Each Leaf
     #
-    # Iterate over each leaf in the tree. This method will yield the leaf nodes 
+    # Iterate over each leaf in the tree. This method will yield the leaf nodes
     # of the tree from left to right.
-    
-    def each_leaf &block
+    def each_leaf(&block)
       return to_enum(__callee__) unless block_given?
       return yield self if leaf?
-      
+
       @children.each do |child|
         if child.leaf?
           yield child
@@ -117,72 +108,60 @@ module RichText
         end
       end
     end
-    
-    
+
     # Each child
     #
     # Iterate over the children of this node.
-    
-    def each_child &block
+    def each_child(&block)
       @children.each(&block)
     end
-    
-    
+
     # Attribute accessor
     #
-    # Read and write an attribute of the node. Attributes are simply key-value 
+    # Read and write an attribute of the node. Attributes are simply key-value
     # pairs stored internally in a hash.
-    
-    def [] attribute
+    def [](attribute)
       @attributes[attribute]
     end
-    
-    def []= attribute, value
+
+    def []=(attribute, value)
       @attributes[attribute] = value
     end
-    
-    
+
     # Count
     #
     # Returns the child count of this node.
-    
     def count
       @children.size
     end
-    
-    
+
     # Size
     #
     # Returns the size of the tree where this node is the root.
-    
     def size
-      @children.reduce(1) {|total, child| total + child.size }
+      @children.reduce(1) { |a, e| a + e.size }
     end
-    
-    
+
     # Minimal?
     #
-    # Test if the tree under this node is minimal or not. A non minimal tree 
+    # Test if the tree under this node is minimal or not. A non minimal tree
     # contains children which themselvs only have one child.
-    
     def minimal?
-      all? {|node| node.count != 1 }
+      all? { |node| node.count != 1 }
     end
-    
-    
+
     # Optimize!
     #
-    # Go through each child and merge any node that a) is not a lead node and b) 
-    # only has one child, with its child. The attributes of the child will 
+    # Go through each child and merge any node that a) is not a lead node and b)
+    # only has one child, with its child. The attributes of the child will
     # override those of the parent.
-    
     def optimize!
       # If the node is a leaf it cannot be optimized further
       return if leaf?
-      
+
       # First optimize each of the children
       @children.map(&:optimize!)
-      
+
       # If we only have one child it is superfluous and
       # should be merged. That means this node will inherrit
       # the children of the single child as well as its
@@ -194,41 +173,40 @@ module RichText
         @attributes.merge! child.attributes
       end
     end
-    
-    
+
+    def optimize
+      dup.optimize!
+    end
+
     # Shallow equality (exclude children)
     #
     # Returns true if the other node has the exact same attributes.
-    
-    def === other
-      @attributes == other.attributes
+    def equal?(other)
+      count == other.count && @attributes == other.attributes
     end
-    
-    
+
     # Deep equality (include children)
     #
-    # Returns true if the other node has the same attributes and its children 
+    # Returns true if the other node has the same attributes and its children
     # are also identical.
-    
-    def == other
+    def ==(other)
       # First make sure the nodes child count matches
-      return false unless count == other.count
-      
-      # The nodes are not equal if their attributes do not
-      # match
-      return false unless self === other
-      
+      return false unless equal? other
+
       # Lastly make sure all of the children are equal
-      each_child.zip(other.each_child).all? {|c| c[0] == c[1] }
+      each_child.zip(other.each_child).all? { |c| c[0] == c[1] }
     end
-    
-    
+
     def inspect
-      children = @children.reduce(''){|s, c| 
-          s + "\n" + c.inspect.gsub(/(^)/) { $1 + '  ' }}
-          
-      "#<%{name} %<a>p:%<id>#x>%{children}" % {
-          name: self.class.name, id: self.object_id, a: @attributes, children: children}
+      children = @children.reduce('') do |s, c|
+        s + "\n" + c.inspect.gsub(/(^)/) { |m| m[1] + '  ' }
+      end
+
+      format '#<%{name} %<attrs>p:%<id>#x>%{children}',
+             name: self.class.name,
+             id: object_id,
+             attrs: @attributes,
+             children: children
     end
   end
-end
+end

data/lib/richtext/version.rb

@@ -1,3 +1,3 @@
 module RichText
-  VERSION = "0.1.0"
+  VERSION = '0.2.0'.freeze
 end

data/lib/richtext.rb

@@ -3,16 +3,13 @@ require 'richtext/node'
 require 'richtext/document/entry'
 require 'richtext/document'
 
-module RichText  
-  
+module RichText
 end
 
-
 # RichText
 #
-# Convenience method for creating RichText objects. Calling RichText(obj) is 
+# Convenience method for creating RichText objects. Calling RichText(obj) is
 # equivalent to RichText::Document.new(obj).
-
-def RichText string
+def RichText(string)
   RichText::Document.new string
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: richtext
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - Sebastian Lindberg
 autorequire: 
 bindir: exe
 cert_chain: []
-date: 2016-07-01 00:00:00.000000000 Z
+date: 2016-07-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: bundler