ruby-bbcode 0.0.3 → 1.0.0

data/CHANGELOG.md

@@ -0,0 +1,7 @@
+Version 1.0.0 - 11-Oct-2014
+---------------------------
+
+* Added 'self closing tags' option (enabled for [*])
+* Added [list], [*] and [code] tags
+* Removed deprecated method
+* Renamed check_bbcode_validity to bbcode_check_validity

data/README.textile

@@ -1,4 +1,6 @@
-h1. Ruby-BBcode
+h1. Ruby-BBCode
+
+!https://badge.fury.io/rb/ruby-bbcode.svg!:http://badge.fury.io/rb/ruby-bbcode
 
 This gem adds support for "BBCode":http:/www.bbcode.org/ to Ruby. The BBCode is parsed by a parser before converted to HTML, allowing to convert nested BBCode tags in strings to their correct HTML equivalent. The parser also checks whether the BBCode is valid and gives errors for incorrect BBCode texts.
 
@@ -11,21 +13,25 @@ h2. Example
 
 h2. Installing
 
-Add the folling line to the Gemfile in your Rails application:
+Add the folling line to the Gemfile of your application:
 <pre><code>gem 'ruby-bbcode'</code></pre>
-Or grab it directly from the repository:
+
+Or to use the source code from the repository:
 <pre><code>gem 'ruby-bbcode', :git => 'git://github.com/veger/ruby-bbcode.git'</code></pre>
+
 Run
 <pre><code>bundle install</code></pre>
 
-And the gem is available in you application
+And Ruby-BBCode is available in your application.
 
 _Note_: Do not forget to restart your server!
 
 h2. Acknowledgements
 
-Some of the ideas and the tests came from "bb-ruby":http://github.com/cpjolicoeur/bb-ruby of Craig P Jolicoeur
+A big thanks to "TheNotary":https://github.com/TheNotary for all contributions he made to this project!
+
+Some of the ideas and the tests came from "bb-ruby":http://github.com/cpjolicoeur/bb-ruby of Craig P Jolicoeur.
 
 h2. License
 
-MIT License. See the included MIT-LICENCE file.
+MIT License. See the included "MIT-LICENCE":https://github.com/veger/ruby-bbcode/blob/master/MIT-LICENSE file.

data/Rakefile

@@ -9,14 +9,16 @@ begin
 rescue LoadError
   require 'rdoc/rdoc'
   require 'rake/rdoctask'
+	require 'rdoc/task'
   RDoc::Task = Rake::RDocTask
 end
 
 RDoc::Task.new(:rdoc) do |rdoc|
   rdoc.rdoc_dir = 'rdoc'
-  rdoc.title    = 'RubyBbcode'
+  rdoc.title    = 'Ruby BBCode'
   rdoc.options << '--line-numbers'
-  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('README.textile')
+  rdoc.rdoc_files.include('CHANGELOG.md')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
@@ -33,5 +35,11 @@ Rake::TestTask.new(:test) do |t|
   t.verbose = true
 end
 
+Rake::TestTask.new(:current) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/current_test.rb'
+  t.verbose = true
+end
 
 task :default => :test

data/lib/ruby-bbcode.rb

@@ -1,200 +1,77 @@
 require 'tags/tags'
-
+require 'ruby-bbcode/tag_info'
+require 'ruby-bbcode/tag_sifter'
+require 'ruby-bbcode/tag_node'
+require 'ruby-bbcode/tag_collection'
+require 'ruby-bbcode/bbtree'
+
+# RubyBBCode adds support for BBCode to Ruby.
+# The BBCode is parsed by a parser before converted to HTML, allowing to convert nested BBCode tags in strings to their correct HTML equivalent.
+# THe used parser also checks whether the BBCode is valid and gives errors for incorrect BBCode texts.
 module RubyBBCode
-  include BBCode::Tags
-
-  @@to_sentence_bbcode_tags = {:words_connector => "], [", 
-    :two_words_connector => "] and [", 
-    :last_word_connector => "] and ["}
+  include ::RubyBBCode::Tags
 
+  # This method converts the given text (with BBCode tags) into a HTML representation
+  # The escape_html parameter (default: true) escapes HTML tags that were present in the given text and therefore blocking (mallicious) HTML in the original text
+  # The additional_tags parameter is used to add additional BBCode tags that should be accepted
+  # The method paramter determines whether the tags parameter needs to be used to blacklist (when set to :disable) or whitelist (when not set to :disable) the list of BBCode tags
   def self.to_html(text, escape_html = true, additional_tags = {}, method = :disable, *tags)
-    # We cannot convert to HTML if the BBCode is not valid!
     text = text.clone
-    use_tags = @@tags.merge(additional_tags)
 
-    if method == :disable then
-      tags.each { |t| use_tags.delete(t) }
-    else
-      new_use_tags = {}
-      tags.each { |t| new_use_tags[t] = use_tags[t] if use_tags.key?(t) }
-      use_tags = new_use_tags
-    end
+    use_tags = determine_applicable_tags(additional_tags, method, *tags)
 
-    if escape_html
-      text.gsub!('<', '&lt;')
-      text.gsub!('>', '&gt;')
-    end
+    @tag_sifter = TagSifter.new(text, use_tags, escape_html)
 
-    valid = parse(text, use_tags)
-    raise valid.join(', ') if valid != true
+    @tag_sifter.process_text
 
-    bbtree_to_html(@bbtree[:nodes], use_tags)
-  end
+    if @tag_sifter.invalid?
+      raise @tag_sifter.errors.join(', ')   # We cannot convert to HTML if the BBCode is not valid!
+    else
+      @tag_sifter.bbtree.to_html(use_tags)
+    end
 
-  def self.is_valid?(text, additional_tags = {})
-    parse(text, @@tags.merge(additional_tags));
   end
 
-  def self.tag_list
-    @@tags
+  # Returns true when valid, else returns array with error(s)
+  def self.validity_check(text, additional_tags = {})
+    @tag_sifter = TagSifter.new(text, @@tags.merge(additional_tags))
+
+    @tag_sifter.process_text
+    return @tag_sifter.errors if @tag_sifter.invalid?
+    true
   end
 
+
   protected
-  def self.parse(text, tags = {})
-    tags = @@tags if tags == {}
-    tags_list = []
-    @bbtree = {:nodes => []}
-    bbtree_depth = 0
-    bbtree_current_node = @bbtree
-    text.scan(/((\[ (\/)? (\w+) ((=[^\[\]]+) | (\s\w+=\w+)* | ([^\]]*))? \]) | ([^\[]+))/ix) do |tag_info|
-      ti = find_tag_info(tag_info)
-
-      if ti[:is_tag] and !tags.include?(ti[:tag].to_sym)
-        # Handle as text from now on!
-        ti[:is_tag] = false
-        ti[:text] = ti[:complete_match]
-      end
-     
-      if !ti[:is_tag] or !ti[:closing_tag]
-        if ti[:is_tag]
-          tag = tags[ti[:tag].to_sym]
-          unless tag[:only_in].nil? or (tags_list.length > 0 and tag[:only_in].include?(tags_list.last.to_sym))
-            # Tag does to be put in the last opened tag
-            err = "[#{ti[:tag]}] can only be used in [#{tag[:only_in].to_sentence(@@to_sentence_bbcode_tags)}]"
-            err += ", so using it in a [#{tags_list.last}] tag is not allowed" if tags_list.length > 0
-            return [err]
-          end
-
-          if tag[:allow_tag_param] and ti[:params][:tag_param] != nil
-            # Test if matches
-            return [tag[:tag_param_description].gsub('%param%', ti[:params][:tag_param])] if ti[:params][:tag_param].match(tag[:tag_param]).nil?
-          end
-        end
-
-        if tags_list.length > 0 and  tags[tags_list.last.to_sym][:only_allow] != nil
-          # Check if the found tag is allowed
-          last_tag = tags[tags_list.last.to_sym]
-          allowed_tags = last_tag[:only_allow]
-          if (!ti[:is_tag] and last_tag[:require_between] != true and ti[:text].lstrip != "") or (ti[:is_tag] and (allowed_tags.include?(ti[:tag].to_sym) == false))
-            # Last opened tag does not allow tag
-            err = "[#{tags_list.last}] can only contain [#{allowed_tags.to_sentence(@@to_sentence_bbcode_tags)}] tags, so "
-            err += "[#{ti[:tag]}]" if ti[:is_tag]
-            err += "\"#{ti[:text]}\"" unless ti[:is_tag]
-            err += ' is not allowed'
-            return [err]
-          end
-        end
-
-        # Validation of tag succeeded, add to tags_list and/or bbtree
-        if ti[:is_tag]
-          tag = tags[ti[:tag].to_sym]
-          tags_list.push ti[:tag]
-          element = {:is_tag => true, :tag => ti[:tag].to_sym, :nodes => [] }
-          element[:params] = {:tag_param => ti[:params][:tag_param]} if tag[:allow_tag_param] and ti[:params][:tag_param] != nil
-        else
-          text = ti[:text]
-          text.gsub!("\r\n", "\n")
-          text.gsub!("\n", "<br />\n")
-          element = {:is_tag => false, :text => text }
-          if bbtree_depth > 0
-            tag = tags[bbtree_current_node[:tag]]
-            if tag[:require_between] == true
-              bbtree_current_node[:between] = ti[:text]
-              if tag[:allow_tag_param] and tag[:allow_tag_param_between] and (bbtree_current_node[:params] == nil or bbtree_current_node[:params][:tag_param] == nil)
-                # Did not specify tag_param, so use between.
-                # Check if valid
-                return [tag[:tag_param_description].gsub('%param%', ti[:text])] if ti[:text].match(tag[:tag_param]).nil?
-                # Store as tag_param
-                bbtree_current_node[:params] = {:tag_param => ti[:text]} 
-              end
-              element = nil
-            end
-          end
-        end
-        bbtree_current_node[:nodes] << element unless element == nil
-        if ti[:is_tag]
-          # Advance to next level (the node we just added)
-          bbtree_current_node = element
-          bbtree_depth += 1
-        end
-      end
-
-      if  ti[:is_tag] and ti[:closing_tag]
-        if ti[:is_tag]
-          tag = tags[ti[:tag].to_sym]
-          return ["Closing tag [/#{ti[:tag]}] does match [#{tags_list.last}]"] if tags_list.last != ti[:tag]
-          return ["No text between [#{ti[:tag]}] and [/#{ti[:tag]}] tags."] if tag[:require_between] == true and bbtree_current_node[:between].blank?
-          tags_list.pop
-
-          # Find parent node (kinda hard since no link to parent node is available...)
-          bbtree_depth -= 1
-          bbtree_current_node = @bbtree
-          bbtree_depth.times { bbtree_current_node = bbtree_current_node[:nodes].last }
-        end
-      end
-    end
-    return ["[#{tags_list.to_sentence((@@to_sentence_bbcode_tags))}] not closed"] if tags_list.length > 0
 
-    true
+  # This method provides the final set of bbcode tags, it merges the default tags with the given additional_tags
+  # and blacklists(method = :disable) or whitelists the list of tags with the given tags parameter.
+  def self.determine_applicable_tags(additional_tags, method, *tags)
+    use_tags = @@tags.merge(additional_tags)
+    if method == :disable then               # if method is set to :disable
+      tags.each { |t| use_tags.delete(t) }   # blacklist (remove) the supplied tags
+    else  # method is not :disable, but has any other value
+      # Only use the supplied tags (whitelist)
+      new_use_tags = {}
+      tags.each { |t| new_use_tags[t] = use_tags[t] if use_tags.key?(t) }
+      use_tags = new_use_tags
+    end
+    use_tags
   end
 
-  def self.find_tag_info(tag_info)
-    ti = {}
-    ti[:complete_match] = tag_info[0]
-    ti[:is_tag] = (tag_info[0].start_with? '[')
-    if ti[:is_tag]
-      ti[:closing_tag] = (tag_info[2] == '/')
-      ti[:tag] = tag_info[3]
-      ti[:params] = {}
-      if tag_info[4][0] == ?=
-        ti[:params][:tag_param] = tag_info[4][1..-1]
-      elsif tag_info[4][0] == ?\s
-        #TODO: Find params
-      end
+  def self.parse(text, tags)
+    @tag_sifter = TagSifter.new(text, tags)
+
+    @tag_sifter.process_text
+
+    if @tag_sifter.invalid?
+      @tag_sifter.errors
     else
-      # Plain text
-      ti[:text] = tag_info[8]
+      true
     end
-    ti
-  end
 
-  def self.bbtree_to_html(node_list, tags = {})
-    tags = @@tags if tags == {}
-    text = ""
-    node_list.each do |node|
-      if node[:is_tag]
-        tag = tags[node[:tag]]
-        t = tag[:html_open].dup
-        t.gsub!('%between%', node[:between]) if tag[:require_between]
-        if tag[:allow_tag_param]
-          if node[:params] and !node[:params][:tag_param].blank?
-            match_array = node[:params][:tag_param].scan(tag[:tag_param])[0]
-            index = 0
-            match_array.each do |match|
-              if index < tag[:tag_param_tokens].length
-                t.gsub!("%#{tag[:tag_param_tokens][index][:token].to_s}%", tag[:tag_param_tokens][index][:prefix].to_s+match+tag[:tag_param_tokens][index][:postfix].to_s)
-                index += 1
-              end
-            end
-          else
-            # Remove unused tokens
-            tag[:tag_param_tokens].each do |token|
-              t.gsub!("%#{token[:token]}%", '')
-            end
-          end
-        end
-
-        text += t
-        text += bbtree_to_html(node[:nodes], tags) if node[:nodes].length > 0
-        t = tag[:html_close]
-        t.gsub!('%between%', node[:between]) if tag[:require_between]
-        text += t
-      else
-        text += node[:text] unless node[:text].nil?
-      end
-    end
-    text
   end
+
 end
 
 String.class_eval do
@@ -202,14 +79,14 @@ String.class_eval do
   def bbcode_to_html(escape_html = true, additional_tags = {}, method = :disable, *tags)
     RubyBBCode.to_html(self, escape_html, additional_tags, method, *tags)
   end
-  
+
   # Replace the BBCode content of a string with its corresponding HTML markup
   def bbcode_to_html!(escape_html = true, additional_tags = {}, method = :disable, *tags)
     self.replace(RubyBBCode.to_html(self, escape_html, additional_tags, method, *tags))
   end
 
   # Check if string contains valid BBCode. Returns true when valid, else returns array with error(s)
-  def is_valid_bbcode?
-    RubyBBCode.is_valid?(self)
+  def bbcode_check_validity
+    RubyBBCode.validity_check(self)
   end
 end

data/lib/ruby-bbcode/bbtree.rb

@@ -0,0 +1,94 @@
+module RubyBBCode
+  # Tree of nodes containing the parsed BBCode information and the plain texts
+  #
+  # As you parse a string of text, say:
+  #     "[b]I'm bold and the next word is [i]ITALIC[/i][b]"
+  # ...you build up a tree of nodes (@bbtree).  The above string converts to 4 nodes when the parse has completed.
+  # * Node 1)  An opening tag node representing "[b]"
+  # * Node 2)  A text node         representing "I'm bold and the next word is "
+  # * Node 3)  An opening tag node representing "[i]"
+  # * Node 4)  A text node         representing "ITALIC"
+  #
+  # The closing of the nodes seems to be implied which is fine by me --less to keep track of.  
+  # 
+  class BBTree
+    attr_accessor :current_node, :tags_list
+    
+    def initialize(hash = { :nodes => TagCollection.new }, dictionary)
+      @bbtree = hash
+      @current_node = TagNode.new(@bbtree)
+      @tags_list = []
+      @dictionary = dictionary
+    end
+    
+    def [](key)
+      @bbtree[key]
+    end
+    
+    def []=(key, value)
+      @bbtree[key] = value
+    end
+    
+    def nodes
+      @bbtree[:nodes]
+    end
+    alias :children :nodes   # needed due to the similarities between BBTree[:nodes] and TagNode[:nodes]... they're walked through in debugging.rb right now
+    
+    def type
+      :bbtree
+    end
+    
+    def within_open_tag?
+      @tags_list.length > 0
+    end
+    alias :expecting_a_closing_tag? :within_open_tag?  # just giving this method multiple names for semantical purposes
+    
+    def parent_tag
+      return nil if !within_open_tag?
+      @tags_list.last.to_sym
+    end
+    
+    def parent_has_constraints_on_children?
+      @dictionary[parent_tag][:only_allow] != nil
+    end
+    
+    # Advance to next level (the node we just added)
+    def escalate_bbtree(element)
+      @tags_list.push element[:tag]
+      @current_node = TagNode.new(element)
+    end
+    
+    # Step down the bbtree a notch because we've reached a closing tag
+    def retrogress_bbtree
+      @tags_list.pop     # remove latest tag in tags_list since it's closed now... 
+      # The parsed data manifests in @bbtree.current_node.children << TagNode.new(element) which I think is more confusing than needed
+
+      if within_open_tag?
+        # Set the current node to be the node we've just parsed over which is infact within another node??...
+        @current_node = TagNode.new(self.nodes.last)
+      else # If we're still at the root of the BBTree or have returned back to the root via encountring closing tags...
+        @current_node = TagNode.new({:nodes => self.nodes})  # Note:  just passing in self works too...
+      end
+      
+      # OKOKOK!  
+      # Since @bbtree = @current_node, if we ever set @current_node to something, we're actually changing @bbtree...
+      # therefore... my brain is now numb
+    end
+    
+    def redefine_parent_tag_as_text
+      @tags_list.pop
+      @current_node[:is_tag] = false
+      @current_node[:closing_tag] = false
+      @current_node.element[:text] = "[#{@current_node[:tag].to_s}]"
+    end
+    
+    def build_up_new_tag(element)
+      @current_node.children << TagNode.new(element)
+    end
+    
+    def to_html(tags = {})
+      self.nodes.to_html(tags)
+    end
+    
+  end
+end

data/lib/ruby-bbcode/tag_collection.rb

@@ -0,0 +1,99 @@
+module RubyBBCode
+  # This class holds TagNode instances and helps build them into html when the time comes.
+  #
+  # It is really just a simple array, with the addition of the #to_html method
+  class TagCollection < Array
+    
+    # This method is vulnerable to stack-level-too-deep scenarios where >=1,200 tags are being parsed.  
+    # But that scenario can be mitigated by splitting up the tags.  bbtree = { :nodes => [900tags, 1000tags] }, the work
+    # for that bbtree can be split up into two passes, do the each node one at a time.  I'm not coding that though, it's pointless, just a thought though
+    def to_html(tags)
+      html_string = ""
+      self.each do |node|
+        if node.type == :tag
+          t = HtmlTemplate.new node
+          
+          t.inlay_between_text!
+          
+          if node.allow_tag_param? and node.param_set?
+            t.inlay_inline_params!
+          elsif node.allow_tag_param? and node.param_not_set?
+            t.remove_unused_tokens!
+          end
+          
+          html_string << t.opening_html
+          
+          # invoke "recursive" call if this node contains child nodes
+          html_string << node.children.to_html(tags) if node.has_children?      # FIXME:  Don't use recursion, it can lead to stack-level-too-deep errors for large volumes?
+          
+          t.inlay_closing_html!
+          
+          html_string << t.closing_html
+        elsif node.type == :text
+          html_string << node[:text] unless node[:text].nil?
+        end
+      end
+      
+      html_string
+    end
+    
+    
+    
+    # This class is designed to help us build up the HTML data.  It starts out as a template such as...
+    #   @opening_html = '<a href="%url%">%between%'
+    #   @closing_html = '</a>'
+    # and then slowly turns into...
+    #   @opening_html = '<a href="http://www.blah.com">cool beans'
+    #   @closing_html = '</a>'
+    # TODO: Think about creating a separate file for this or something... maybe look into folder structures cause this project
+    # got huge when I showed up.  
+    class HtmlTemplate
+      attr_accessor :opening_html, :closing_html
+      
+      def initialize(node)
+        @node = node
+        @tag_definition = node.definition # tag_definition
+        @opening_html = node.definition[:html_open].dup
+        @closing_html = node.definition[:html_close].dup
+      end
+      
+      def inlay_between_text!
+        @opening_html.gsub!('%between%',@node[:between]) if between_text_goes_into_html_output_as_param?  # set the between text to where it goes if required to do so...
+      end
+      
+      def inlay_inline_params!
+        # Get list of paramaters to feed
+        match_array = @node[:params][:tag_param].scan(@tag_definition[:tag_param])[0]
+        
+        # for each parameter to feed
+        match_array.each.with_index do |match, i|
+          if i < @tag_definition[:tag_param_tokens].length
+            
+            # Substitute the %param% keyword for the appropriate data specified
+            @opening_html.gsub!("%#{@tag_definition[:tag_param_tokens][i][:token].to_s}%", 
+                      @tag_definition[:tag_param_tokens][i][:prefix].to_s + 
+                        match + 
+                        @tag_definition[:tag_param_tokens][i][:postfix].to_s)
+          end
+        end
+      end
+      
+      def inlay_closing_html!
+        @closing_html.gsub!('%between%',@node[:between]) if @tag_definition[:require_between]
+      end
+      
+      def remove_unused_tokens!
+        @tag_definition[:tag_param_tokens].each do |token|
+          @opening_html.gsub!("%#{token[:token]}%", '')
+        end
+      end
+      
+      private
+      
+      def between_text_goes_into_html_output_as_param?
+        @tag_definition[:require_between]
+      end
+    end
+    
+  end 
+end