ruby-bbcode 1.0.1 → 2.0.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: a10490262219dacfe057278e730b307e8c274c08
-  data.tar.gz: fc45b4491f2127baffe4d8c73e0a5480e858b9c0
+  metadata.gz: 81fc51b37a07ce293879a04f6c2e94d0888a5069
+  data.tar.gz: 7f35303b08f5a4f37c311b6aa70babe8e6918d04
 SHA512:
-  metadata.gz: e6e07a60e19708e13f1245a4a15874a00b138fb2af64a3d6ae494ea80d4eb90eee84587d3f6d65405b86b1d69100720b67b42af76b4bda81ae676279ae48df50
-  data.tar.gz: 3873a68c9f3e06de06ff07001507573513b7f219599c8b3d5be460127101eaf4735617d294dbb1cc3146f32d38d7b1378dbaab1f3b0c36093b417c21e2df8475
+  metadata.gz: dc09a68f466ee66a7a2591bff3fff64e48db3f2ea2e65f6226979ec5620e9bd0e2e084bfe85162d9c0d9beef5fb0781ffcd4b55d4e5bd5caf06dc9a2d4f836fd
+  data.tar.gz: c93e42b5f4b448f9589d105845a116f8d183aa2f66025c09ab07b518de01d85c5c7b0da5c7c92f43fef7233761ccfc5200d8f829331d0415ad9d3415775d4e59

data/CHANGELOG.md

@@ -1,4 +1,22 @@
+Upcoming
+--------
+
+Version 2.0.0 - 09-Apr-2015
+---------------------------
+
+* Support multiple errors within a text
+* Add parameters to #bbcode_check_validity to add/remove tags
+* Support regular tag parameters (`[tag param=value][/tag]`) instead of 'quick parameters' (`[tag=value][/tag]`)
+* Changed tag description symbols (to become descriptive), **breaks existing custom tag additions!**
+* Add support to show the BBCode annotated with errors (when there are any)
+* Add support to escape token value using :uri_escape.
+* Recognize uppercase tags (issue #27)
+* Support [iframe-API](https://developers.google.com/youtube/iframe_api_reference) for YouTube videos (#18)
+* Support difference between optional and required parameters
+* Add optional parameters to youtube and vimeo tags to specify the dimensions of the video
+
 Version 1.0.1 - 04-Jan-2015
+---------------------------
 
 * Allow any version of activesupport since 3.2.3
 

data/README.textile

@@ -1,16 +1,35 @@
 h1. Ruby-BBCode
 
-!https://badge.fury.io/rb/ruby-bbcode.svg!:http://badge.fury.io/rb/ruby-bbcode
+!https://badge.fury.io/rb/ruby-bbcode.svg!:http://badge.fury.io/rb/ruby-bbcode !https://travis-ci.org/veger/ruby-bbcode.svg?branch=master!:https://travis-ci.org/veger/ruby-bbcode !https://coveralls.io/repos/veger/ruby-bbcode/badge.svg?branch=master(Coverage Status)!:https://coveralls.io/r/veger/ruby-bbcode?branch=master
 
 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.
+Additionally, annotations can be added to the BBCode string the showing errors that are present, assuming there are any errors.
 
 The parser recognizes all "official tags":http://www.bbcode.org/reference.php and allows to easily extend this set with custom tags.
 
-h2. Example
+See "changelog":CHANGELOG.md for the (recent) notable changes of this gem.
+
+h2. Examples
+
+<code>bbcode_to_html</code> can be used to convert a BBCode string to HTML:
 
 <pre><code>'This is [b]bold[/b] and this is [i]italic[/i].'.bbcode_to_html
  => 'This is <strong>bold</strong> and this is <em>italic</em>.'</code></pre>
 
+<code>bbcode_show_errors</code> can be used to convert a BBCode to BBCode annotated with errors (assuming the original BBCode did contain errors):
+
+<pre><code>'[img=no_dimensions_here]image.png[/img]'.bbcode_show_errors
+ => '<span class=\'bbcode_error\' data-bbcode-errors=\'["The image parameters \'no_dimensions_here\' are incorrect, \'<width>x<height>\' excepted"]\'>[img]</span>image.png[/img]'</code></pre>
+
+These HTML attributes containing the JSON representation of the errors can be used to inform the user about the problems.
+The following JavaScript/jQuery example makes use of the "Bootstrap tooltips plugin":http://getbootstrap.com/javascript/#tooltips to show the errors in tooltip popups:
+<pre><code>$(".bbcode_error").tooltip({
+  title: function() { 
+    var errors = JSON.parse($(this).attr('data-bbcode-errors'));
+    return errors.join("\n");
+  }
+});</code></pre>
+
 h2. Installing
 
 Add the following line to the Gemfile of your application:
@@ -34,4 +53,4 @@ Some of the ideas and the tests came from "bb-ruby":http://github.com/cpjolicoeu
 
 h2. License
 
-MIT License. See the included "MIT-LICENCE":https://github.com/veger/ruby-bbcode/blob/master/MIT-LICENSE file.
+MIT License. See the included "MIT-LICENCE":MIT-LICENSE file.

data/lib/ruby-bbcode.rb

@@ -7,37 +7,42 @@ 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.
+# The used parser also checks whether the BBCode is valid and gives errors for incorrect BBCode texts.
 module RubyBBCode
   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
+  # The method parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
   def self.to_html(text, escape_html = true, additional_tags = {}, method = :disable, *tags)
-    text = text.clone
-
+    parse(text, escape_html, additional_tags, method, *tags)
     use_tags = determine_applicable_tags(additional_tags, method, *tags)
 
-    @tag_sifter = TagSifter.new(text, use_tags, escape_html)
+    # We cannot convert to HTML if the BBCode is not valid!
+    raise @tag_sifter.errors.join(', ') unless @tag_sifter.valid?
 
-    @tag_sifter.process_text
-
-    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
+    @tag_sifter.bbtree.to_html(use_tags)
+  end
 
+  # This method converts the given text (with BBCode tags) into a HTML representation
+  # The additional_tags parameter is used to add additional BBCode tags that should be accepted
+  # The method parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
+  def self.to_bbcode(text, additional_tags = {}, method = :disable, *tags)
+    parse(text, true, additional_tags, method, *tags)
+    use_tags = determine_applicable_tags(additional_tags, method, *tags)
+    @tag_sifter.bbtree.to_bbcode(use_tags)
   end
 
   # 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))
+  def self.validity_check(text, additional_tags = {}, method = :disable, *tags)
+    use_tags = determine_applicable_tags(additional_tags, method, *tags)
+    @tag_sifter = TagSifter.new(text, use_tags)
 
     @tag_sifter.process_text
-    return @tag_sifter.errors if @tag_sifter.invalid?
+    return @tag_sifter.errors unless @tag_sifter.valid?
     true
   end
 
@@ -59,34 +64,50 @@ module RubyBBCode
     use_tags
   end
 
-  def self.parse(text, tags)
-    @tag_sifter = TagSifter.new(text, tags)
+  # This method parses the given text (with BBCode tags) into a BBTree 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 parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
+  def self.parse(text, escape_html = true, additional_tags = {}, method = :disable, *tags)
+    text = text.clone
+    use_tags = determine_applicable_tags(additional_tags, method, *tags)
 
+    @tag_sifter = TagSifter.new(text, use_tags, escape_html)
     @tag_sifter.process_text
-
-    if @tag_sifter.invalid?
-      @tag_sifter.errors
-    else
-      true
-    end
-
   end
-
 end
 
 String.class_eval do
   # Convert a string with BBCode markup into its corresponding HTML markup
+  # 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 parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
   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
+  # 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 parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
   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
 
+  # Convert a string with BBCode markup into its corresponding HTML markup
+  # Note that the returned bbocde, might differ than the original bbcode, as the original gets parsed and molded into something workable. For example, by adding closing tags (when they are optional), or by converting generic tags into specific ones.
+  def bbcode_show_errors(additional_tags = {}, method = :disable, *tags)
+    RubyBBCode.to_bbcode(self, additional_tags, method, *tags)
+  end
+
   # Check if string contains valid BBCode. Returns true when valid, else returns array with error(s)
-  def bbcode_check_validity
-    RubyBBCode.validity_check(self)
+  # The additional_tags parameter is used to add additional BBCode tags that should be accepted
+  # The method parameter 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
+  # The method raises an exception when the text could not be parsed due to errors
+  def bbcode_check_validity(additional_tags = {}, method = :disable, *tags)
+    RubyBBCode.validity_check(self, additional_tags, method, *tags)
   end
 end

data/lib/ruby-bbcode/bbtree.rb

@@ -3,64 +3,50 @@ module RubyBBCode
   #
   # 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.
+  # ...you build up a tree of nodes (@bbtree).  The above string is represented by 4 nodes when parsing 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)
+
+    def initialize(hash = { :nodes => TagCollection.new })
       @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
-    
+
+    # Returns the parent tag, if suitable/available
     def parent_tag
-      return nil if !within_open_tag?
-      @tags_list.last.to_sym
+      return nil unless within_open_tag?
+      @tags_list.last
     end
-    
+
+    # Return true if the parent tag only allows certain child tags
     def parent_has_constraints_on_children?
-      @dictionary[parent_tag][:only_allow] != nil
+      parent_tag[:definition][: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)
+      @tags_list.push @current_node
     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... 
+      @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?
@@ -69,26 +55,19 @@ module RubyBBCode
       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
-    
+
+    # Create a new node and adds it to the current node as a child node
     def build_up_new_tag(element)
       @current_node.children << TagNode.new(element)
     end
-    
+
     def to_html(tags = {})
       self.nodes.to_html(tags)
     end
-    
+
+    def to_bbcode(tags = {})
+      self.nodes.to_bbcode(tags)
+    end
   end
-end
+end

data/lib/ruby-bbcode/tag_collection.rb

@@ -1,99 +1,49 @@
+require 'ruby-bbcode/templates/html_template'
+require 'ruby-bbcode/templates/bbcode_errors_template'
+
 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
+  # This class holds TagNode instances and helps converting them into code (using the provided template) when the time comes.
   class TagCollection < Array
-    
-    # This method is vulnerable to stack-level-too-deep scenarios where >=1,200 tags are being parsed.  
+    # Convert nodes to HTML
+    def to_html(tags)
+      to_code(tags, RubyBBCode::Templates::HtmlTemplate)
+    end
+
+    # Convert nodes to BBCode (with error information)
+    def to_bbcode(tags)
+      to_code(tags, RubyBBCode::Templates::BBCodeErrorsTemplate)
+    end
+
+    # 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)
+    def to_code(tags, template)
       html_string = ""
       self.each do |node|
         if node.type == :tag
-          t = HtmlTemplate.new node
-          
+          t = template.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?
+
+          if node.allow_params?
+            t.inlay_params!
             t.remove_unused_tokens!
           end
-          
-          html_string << t.opening_html
-          
+
+          html_string << t.opening_part
+
           # 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
+          html_string << node.children.to_code(tags, template) if node.has_children?      # FIXME:  Don't use recursion, it can lead to stack-level-too-deep errors for large volumes?
+
+          t.inlay_closing_part!
+
+          html_string << t.closing_part
         elsif node.type == :text
-          html_string << node[:text] unless node[:text].nil?
+          html_string << template.convert_text(node)
         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
 end