bb-ruby 0.8.2 → 0.8.3

data/History.txt

@@ -1,3 +1,7 @@
+== 0.8.3 2008-12-16
+
+* RDoc documentation updates
+
 == 0.8.2 2008-12-16
 
 * No major enhancements:

data/lib/bb-ruby.rb

@@ -2,9 +2,12 @@ $:.unshift(File.dirname(__FILE__)) unless
   $:.include?(File.dirname(__FILE__)) || $:.include?(File.expand_path(File.dirname(__FILE__)))
 
 module BBRuby
-  VERSION = '0.8.2'
+  VERSION = '0.8.3'
 
+  # allowable image formats
   @@imageformats = 'png|bmp|jpg|gif|jpeg'
+
+  # built-in BBCode tabs that will be processed
   @@tags = {
     # tag name => [regex, replace, description, example, enable/disable symbol]
     'Bold' => [
@@ -198,50 +201,128 @@ module BBRuby
       :email]
   }
 
-  def self.to_html(text, tags_alternative_definition = {}, escape_html=true, method=:disable, *tags)
-    text = text.clone
-    # escape < and > to remove any html
-    if escape_html 
-      text.gsub!( '<', '&lt;' )
-      text.gsub!( '>', '&gt;' )
-    end
-    
-    tags_definition = @@tags.merge(tags_alternative_definition)
+  class << self
+    # Convert a string with BBCode markup into its corresponding HTML markup
+    #
+    # === Basic Usage
+    #
+    # The first parameter is the string off BBCode markup to be processed
+    #
+    #   text = "[b]some bold text to markup[/b]"
+    #   output = BBRuby.to_html(text)
+    #   # output => "<strong>some bold text to markup</strong>"
+    #
+    # === Custom BBCode translations
+    #
+    # You can supply your own BBCode markup translations to create your own custom markup
+    # or override the default BBRuby translations (parameter is a hash of custom translations).
+    #
+    # The hash takes the following format: "name" => [regexp, replacement, description, example, enable_symbol]
+    #
+    #  custom_blockquote = {
+    #    'Quote' => [
+    #      /\[quote(:.*)?=(.*?)\](.*?)\[\/quote\1?\]/mi,
+    #      '<div class="quote"><p><cite>\2</cite></p><blockquote>\3</blockquote></div>',
+    #      'Quote with citation',
+    #      '[quote=mike]please quote me[/quote]',
+    #      :quote
+    #    ]
+    #  }
+    #
+    # === Enable and Disable specific tags
+    #
+    # BBRuby will allow you to only enable certain BBCode tags, or to explicitly disable certain tags.
+    # Pass in either :disable or :enable to set your method, followed by the comma-separated list of tags
+    # you wish to disable or enable
+    #
+    #   BBRuby.to_html(text, {}, true, :enable, :image, :bold, :quote)
+    #   BBRuby.to_html(text, {}, true, :disable, :image, :video, :color)
+    #
+    def to_html(text, tags_alternative_definition = {}, escape_html=true, method=:disable, *tags)
+      text = text.clone
+      # escape < and > to remove any html
+      if escape_html 
+        text.gsub!( '<', '&lt;' )
+        text.gsub!( '>', '&gt;' )
+      end
+      
+      tags_definition = @@tags.merge(tags_alternative_definition)
 
-    # parse bbcode tags
-    case method
-      when :enable
-        tags_definition.each_value { |t| text.gsub!(t[0], t[1]) if tags[0].include?(t[4]) }
-      when :disable
-        # this works nicely because the default is disable and the default set of tags is [] (so none disabled) :)
-        tags_definition.each_value { |t| text.gsub!(t[0], t[1]) unless tags[0].include?(t[4]) }
-    end
+      # parse bbcode tags
+      case method
+        when :enable
+          tags_definition.each_value { |t| text.gsub!(t[0], t[1]) if tags[0].include?(t[4]) }
+        when :disable
+          # this works nicely because the default is disable and the default set of tags is [] (so none disabled) :)
+          tags_definition.each_value { |t| text.gsub!(t[0], t[1]) unless tags[0].include?(t[4]) }
+      end
 
-    # parse spacing
-    text.gsub!( /\r\n?/, "\n" )
-    text.gsub!( /\n/, "<br />" )
+      # parse spacing
+      text.gsub!( /\r\n?/, "\n" )
+      text.gsub!( /\n/, "<br />" )
 
-    # return markup
-    text
-  end
+      # return markup
+      text
+    end
 
-  def self.tags
-    @@tags.each { |tn, ti|
-      # yields the tag name, a description of it and example
-      yield tn, ti[2], ti[3] if ti[2]
-    }
-  end
-  
-  def self.tag_list
-    @@tags
-  end
-end
+    # Returns the list of tags processed by BBRuby in a Hash object
+    def tag_list
+      @@tags
+    end
+  end # class << self
+
+end # class BBRuby
 
 class String
+  # Convert a string with BBCode markup into its corresponding HTML markup
+  #
+  # === Basic Usage
+  #
+  #   text = "[b]some bold text to markup[/b]"
+  #   output = text.bbcode_to_html
+  #   # output => "<strong>some bold text to markup</strong>"
+  #
+  # === Custom BBCode translations
+  #
+  # You can supply your own BBCode markup translations to create your own custom markup
+  # or override the default BBRuby translations (parameter is a hash of custom translations).
+  #
+  # The hash takes the following format: "name" => [regexp, replacement, description, example, enable_symbol]
+  #
+  #  custom_blockquote = {
+  #    'Quote' => [
+  #      /\[quote(:.*)?=(.*?)\](.*?)\[\/quote\1?\]/mi,
+  #      '<div class="quote"><p><cite>\2</cite></p><blockquote>\3</blockquote></div>',
+  #      'Quote with citation',
+  #      '[quote=mike]please quote me[/quote]',
+  #      :quote
+  #    ]
+  #  }
+  #
+  #  output = text.bbcode_to_html(custom_blockquote)
+  #
+  # === Enable and Disable specific tags
+  #
+  # BBRuby will allow you to only enable certain BBCode tags, or to explicitly disable certain tags.
+  # Pass in either :disable or :enable to set your method, followed by the comma-separated list of tags
+  # you wish to disable or enable
+  #
+  #   output = text.bbcode_to_html({}, true, :enable, :image, :bold, :quote)
+  #   output = text.bbcode_to_html({}, true, :disable, :image, :video, :color)
+  #
+  # === HTML auto-escaping
+  #
+  # By default, BBRuby will auto-escape HTML.  You can prevent this by passing in false as the second
+  # parameter
+  #
+  #   output = text.bbcode_to_html({}, false)
+  #
   def bbcode_to_html(tags_alternative_definition = {}, escape_html=true, method=:disable, *tags)
     BBRuby.to_html(self, tags_alternative_definition, escape_html, method, tags)
   end
+
+  # Replace the string contents with the HTML-converted markup
   def bbcode_to_html!(tags_alternative_definition = {}, escape_html=true, method=:disable, *tags)
     self.replace(BBRuby.to_html(self, tags_alternative_definition, escape_html, method, tags))
   end
-end
+end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: bb-ruby
 version: !ruby/object:Gem::Version 
-  version: 0.8.2
+  version: 0.8.3
 platform: ruby
 authors: 
 - Craig P Jolicoeur
@@ -20,7 +20,7 @@ dependencies:
     requirements: 
     - - ">="
       - !ruby/object:Gem::Version 
-        version: 1.1.0
+        version: 1.2.1
     version: 
 - !ruby/object:Gem::Dependency 
   name: hoe