ruby-bbcode-to-md 0.0.1

data/MIT-LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2010 [name of plugin creator]
+
+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,41 @@
+# Ruby-BBcode-to-MD
+This gem converts BBcode to Markdown. BBcode is parsed before conversion, checking whether the BBcode is valid.
+
+The parser recognizes most "official tags":http://www.bbcode.org/reference.php and allows to easily extend this set with custom tags by editing tags.rb.
+
+## Example
+```ruby
+"This is [b]bold[/b] and this is [i]italic[/i].".bbcode_to_html
+```
+=>
+```markdown
+This is **bold** and this is *italic*.
+```
+
+## Installation
+Add this to your Rails app's Gemfile
+```
+gem 'ruby-bbcode-to-md'
+```
+or use the repo link
+```
+gem 'ruby-bbcode-to-md', :git => git://github.com/rikkit/ruby-bbcode-to-md.git
+```
+Then run
+```
+bundle install
+```
+
+And the gem is available in you application
+
+_Note: Do not forget to restart your server!_
+
+## Acknowledgements
+
+Code is based on BBcode to HTML gem by Maarten Bezemer: http://github.com/veger/ruby-bbcode.git 
+
+Some of the ideas and the tests came from "bb-ruby":http://github.com/cpjolicoeur/bb-ruby of Craig P Jolicoeur
+
+## Licence
+
+MIT Licence. See the included MIT-LICENCE file.

data/Rakefile

@@ -0,0 +1,44 @@
+#!/usr/bin/env rake
+begin
+  require 'bundler/setup'
+rescue LoadError
+  puts 'You must `gem install bundler` and `bundle install` to run rake tasks'
+end
+begin
+  require 'rdoc/task'
+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.options << '--line-numbers'
+  rdoc.rdoc_files.include('README.rdoc')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end
+
+
+
+Bundler::GemHelper.install_tasks
+
+require 'rake/testtask'
+
+Rake::TestTask.new(:test) do |t|
+  t.libs << 'lib'
+  t.libs << 'test'
+  t.pattern = 'test/**/*_test.rb'
+  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

@@ -0,0 +1,100 @@
+require 'active_support/core_ext/array/conversions'
+
+require 'tags/tags'
+require 'ruby-bbcode/debugging'
+require 'ruby-bbcode/tag_info'
+require 'ruby-bbcode/tag_sifter'
+require 'ruby-bbcode/tag_node'
+require 'ruby-bbcode/tag_collection'
+require 'ruby-bbcode/bbtree'
+
+
+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
+  def self.to_html(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?
+      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
+
+  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))
+
+    @tag_sifter.process_text
+    return @tag_sifter.errors if @tag_sifter.invalid?
+    true
+  end
+
+
+  protected
+
+  # 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.parse(text, tags)
+    @tag_sifter = TagSifter.new(text, tags)
+
+    @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
+  def bbcode_to_md(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_md!(escape_html = true, additional_tags = {}, method = :disable, *tags)
+    self.replace(RubyBBCode.to_html(self, escape_html, additional_tags, method, *tags))
+  end
+
+  # Deprecated!  Please use check_bbcode_validity (will be removed in version 0.1.0)
+  # Check if string contains valid BBCode. Returns true when valid, else returns array with error(s)
+  def is_valid_bbcode?
+    # TODO:  add a puts "Warning:  This method has been deprecated, please use check_bbcode_validity which does the same thing but is more syntactical." or something
+    check_bbcode_validity
+  end
+
+  # Check if string contains valid BBCode. Returns true when valid, else returns array with error(s)
+  def check_bbcode_validity
+    RubyBBCode.validity_check(self)
+  end
+end

data/lib/ruby-bbcode/bbtree.rb

@@ -0,0 +1,94 @@
+module RubyBBCode
+  # As you parse a string of text, say:
+  #     "[b]I'm bold and the next word is [i]ITALLICS[/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 "ITALLICS"
+  #
+  # The closing of the nodes seems to be implied which is fine by me --less to keep track of.  
+  # 
+  class BBTree
+    include ::RubyBBCode::DebugBBTree
+    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)
+      element[:parent_tag] = parent_tag
+      @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}) 
+      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/debugging.rb

@@ -0,0 +1,93 @@
+module RubyBBCode
+  def self.log(string, clear_file = true)
+    clear_log_file_at_beginning_of_execution clear_file
+    
+    File.open('/tmp/ruby-bbcode.log', 'a') do |f|
+      f.puts string
+    end
+  end
+  
+  def self.clear_log_file_at_beginning_of_execution(clear_file)
+    return if !clear_file
+    if defined?(@@cleared_file).nil?
+      @@cleared_file = true
+      File.open('/tmp/ruby-bbcode.log', 'w+') do |f|
+        puts ''
+      end
+    end
+  end
+  
+  
+  # This module can be included in the BBTree and TagNode to give them debugging features
+  module DebugBBTree
+    # For Debugging/ visualization purposes.
+    # This can be used to render the #nodes array in a pretty manor, showing the hirarchy.  
+    def to_v
+      tree = self
+      visual_string = ''
+      
+      walk_tree(tree) do |node, depth|
+        indentation = '  ' * depth
+        case node[:is_tag]
+        when true
+          visual_string += "#{indentation}" + node[:tag].to_s + "\n"
+        when false
+          visual_string += "#{indentation}\"#{node[:text]}\"\n"
+        end
+      end
+      
+      visual_string
+    end
+    
+    
+    # this blocky method counts how many children are
+    # in the TagNode.children, recursively walking the tree
+    def count_child_nodes(hash = self)
+      count = 0
+      walk_tree(hash) do
+        count += 1
+      end
+      count
+    end
+
+    # For BBTree, teh to_s method shows the count of the children plus a graphical
+    # depiction of the tree, and the relation of the nodes.  
+    # For TagNodes, the root-most tag is displayed, and the children are counted.  
+    def to_s
+      object_identifier = "#<#{self.class.to_s}:0x#{'%x' % (self.object_id << 1)}\n"
+      close_object = ">\n"
+      
+      case self
+      when RubyBBCode::BBTree
+        object_identifier + "Children: #{count_child_nodes}\n" + self.to_v + close_object
+      when RubyBBCode::TagNode   # when inspecting TagNodes, it's better not to show the tree display
+        if self[:is_tag]
+          object_identifier + "Tag:  #{self[:tag].to_s}, Children: #{count_child_nodes}\n" + close_object
+        else
+          object_identifier + '"' + self[:text].to_s + "\"\n" + close_object
+        end
+      end
+    end
+    
+    private
+    
+    # This function is used by to_v and anything else that needs to iterate through the 
+    # @bbtree
+    def walk_tree(tree, depth = -1, &blk)
+      return enum_for(:walk_tree) unless blk  # ignore me for now, I'm a convention for being versatile
+      
+      # Perform the block action specified at top level!!!
+      yield tree, depth unless depth == -1
+      
+      # next if we're a text node
+      return if tree.type == :text
+      
+      # Enter into recursion (including block action) for each child node in this node
+      tree.children.each do |node|
+        walk_tree(node, depth + 1, &blk)
+      end
+    end
+    
+  end
+  
+end

data/lib/ruby-bbcode/tag_collection.rb

@@ -0,0 +1,116 @@
+module RubyBBCode
+  # This class holds TagNodes and helps build them into html when the time comes.  It's really just a simple array, with the addition of the #to_html method
+  class TagCollection < Array
+    
+    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?
+          
+          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 = ""
+        @closing_html = ""
+
+        # if this is a nested tag, then don't prefix first_html_open
+        if !node.definition[:first_html_open].nil? && node.type != node.parent_type then
+          @opening_html << node.definition[:first_html_open]
+        end
+
+        if node.definition[:html_open].is_a?(Hash) then
+          @opening_html << node.definition[:html_open][node.parent_type].dup
+        else
+          @opening_html << node.definition[:html_open].dup
+        end
+
+        if node.definition[:html_close].is_a?(Hash) then
+          @closing_html << node.definition[:html_close][node.parent_type].dup
+        else
+          @closing_html << node.definition[:html_close].dup
+        end
+
+        if !node.definition[:last_html_close].nil? && node.type != node.parent_type then
+          @closing_html << node.definition[:last_html_close]
+        end
+      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