rbbcode 0.1.2

data/README

@@ -0,0 +1,46 @@
+RbbCode is a customizable Ruby library for parsing BB Code.
+
+RbbCode validates and cleans input. It supports customizable schemas so you can set rules about what tags are allowed where. The default rules are designed to ensure valid HTML output.
+
+Example usage:
+
+require 'rubygems'
+require 'rbbcode'
+
+bb_code = 'This is [b]bold[/b] text'
+parser = RbbCode::Parser.new
+html = parser.parse(bb_code)
+# => '<p>This is <strong>bold</strong> text</p>'
+
+Customizing
+===========
+
+You can customize RbbCode by subclassing HtmlMaker and/or by passing configuration directives to a Schema object.
+
+HtmlMaker can be extended by adding methods like this:
+
+class MyHtmlMaker < RbbCode::HtmlMaker
+	def html_from_TAGNAME_tag(node)
+		# ...
+	end
+end
+
+...where TAGNAME should be replaced with the name of the tag. The method should accept an RbbCode::TagNode and return HTML as a string. (See tree_maker.rb for the definition of RbbCode::TagNode.) Anytime the parser encounters the specified tag, it will call your method and insert the returned HTML into the output.
+
+Now you just have to tell the Parser object to use an instance of your custom subclass instead of the default HtmlMaker:
+
+my_html_maker = MyHtmlMaker.new
+parser = RbbCode::Parser.new(:html_maker => my_html_maker)
+
+RbbCode removes invalid markup by comparing the input against a Schema object. The Schema is much like a DTD in XML. You can set your own rules and change the default ones by calling configuration methods on a Schema instance. Look at Schema#use_defaults in schema.rb for examples.
+
+Normally, RbbCode instantiates Schema behind the scenes, but if you want to customize it, you'll have to instantiate it yourself and pass the instance to the Parser object:
+
+schema = RbbCode::Schema.new
+schema.tag('quote').may_not_be_nested # Or whatever other configuration methods you want to call
+parser = RbbCode::Parser.new(:schema => schema)
+
+Unicode Support
+===============
+
+UTF-8 compatibility is a high priority for this project. RbbCode aims to be fully compatible with UTF-8, but not with other multibyte encodings. As of the most recent release, UTF-8 support has been tested to a limited extent. It is possible that there are some hidden gotchas. Please report any bugs you may find.

data/spec/html_maker_spec.rb

@@ -0,0 +1,70 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require File.expand_path(File.dirname(__FILE__) + '/node_spec_helper')
+
+describe RbbCode::HtmlMaker do
+	context '#make_html' do
+		def expect_html(expected_html, &block)
+			@html_maker.make_html(NodeBuilder.build(&block)).should == expected_html
+		end
+		
+		before :each do
+			@html_maker = RbbCode::HtmlMaker.new
+		end
+		
+		it 'should replace simple BB code tags with HTML tags' do
+			expect_html('<p>This is <strong>bold</strong> text</p>') do
+				tag('p') do
+					text 'This is '
+					tag('b') { text 'bold' }
+					text ' text'
+				end
+			end
+		end
+		
+		it 'should work for nested tags' do
+			expect_html('<p>This is <strong>bold and <u>underlined</u></strong> text</p>') do
+				tag('p') do
+					text 'This is '
+					tag('b') do
+						text 'bold and '
+						tag('u') { text 'underlined' }
+					end
+					text ' text'
+				end
+			end
+		end
+
+		it 'should not allow JavaScript in URLs' do
+			urls = {
+				'javascript:alert("foo");' => 'http://javascript%3Aalert("foo");',
+				'j a v a script:alert("foo");' => 'http://j+a+v+a+script%3Aalert("foo");',
+				' javascript:alert("foo");' => 'http://+javascript%3Aalert("foo");',
+				'JavaScript:alert("foo");' => 'http://JavaScript%3Aalert("foo");' ,
+				"java\nscript:alert(\"foo\");" => 'http://java%0Ascript%3Aalert("foo");',
+				"java\rscript:alert(\"foo\");" => 'http://java%0Dscript%3Aalert("foo");'
+			}
+			
+			# url tag
+			urls.each do |evil_url, clean_url|
+				expect_html("<p><a href=\"#{clean_url}\">foo</a></p>") do
+					tag('p') do
+						tag('url', evil_url) do
+							text 'foo'
+						end
+					end
+				end
+			end
+			
+			# img tag
+			urls.each do |evil_url, clean_url|
+				expect_html("<p><img src=\"#{clean_url}\" alt=\"\"/></p>") do
+					tag('p') do
+						tag('img') do
+							text evil_url
+						end
+					end
+				end
+			end
+		end
+	end
+end

data/spec/node_spec_helper.rb

@@ -0,0 +1,114 @@
+module RbbCode
+	class RootNode
+		def == (other_node)
+			self.class == other_node.class and self.children == other_node.children
+		end
+		
+		def print_tree(indent = 0)
+			output = ''
+			indent.times { output << "  " }
+			output << 'ROOT'
+			children.each do |child|
+				output << "\n" << child.print_tree(indent + 1)
+			end
+			output << "\n/ROOT"
+			output
+		end
+	end
+	
+	class TagNode
+		def == (other_node)
+			self.class == other_node.class and self.tag_name == other_node.tag_name and self.value == other_node.value and self.children == other_node.children
+		end
+		
+		def print_tree(indent = 0)
+			output = ''
+			indent.times { output << "  " }
+			if value.nil?
+				output << "[#{tag_name}]"
+			else
+				output << "[#{tag_name}=#{value}]"
+			end
+			children.each do |child|
+				output << "\n" << child.print_tree(indent + 1)
+			end
+			output << "\n"
+			indent.times { output << "  " }
+			output << "[/#{tag_name}]"
+			output
+		end
+	end
+	
+	class TextNode
+		def == (other_node)
+			self.class == other_node.class and self.text == other_node.text
+		end
+		
+		def print_tree(indent = 0)
+			output = ''
+			indent.times { output << "  " }
+			output << '"' << text << '"'
+		end
+	end
+end
+
+class NodeBuilder
+	include RbbCode
+	
+	def self.build(&block)
+		builder = new
+		builder.instance_eval(&block)
+		builder.root
+	end
+	
+	attr_reader :root
+	
+	protected
+	
+	def << (node)
+		@current_parent.children << node
+	end
+	
+	def initialize
+		@root = RootNode.new
+		@current_parent = @root
+	end
+	
+	def text(contents, &block)
+		self << TextNode.new(@current_parent, contents)
+	end
+	
+	def tag(tag_name, value = nil, &block)
+		tag_node = TagNode.new(@current_parent, tag_name, value)
+		self << tag_node
+		original_parent = @current_parent
+		@current_parent = tag_node
+		instance_eval(&block)
+		@current_parent = original_parent
+	end
+end
+
+module NodeMatchers
+	class MatchNode
+		def initialize(expected_tree)
+			@expected_tree = expected_tree
+		end
+		
+		def matches?(target)
+			@target = target
+			@target == @expected_tree
+		end
+		
+		def failure_message
+			"Expected:\n\n#{@expected_tree.print_tree}\n\nbut got:\n\n#{@target.print_tree}"
+		end
+		
+		def negative_failure_message
+			"Expected anything other than:\n\n#{@expected_tree.print_tree}"
+		end
+	end
+	
+	def match_node(expected_node)
+		MatchNode.new(expected_node)
+	end
+end

data/spec/parser_spec.rb

@@ -0,0 +1,99 @@
+$KCODE = 'u'
+
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe RbbCode::Parser do
+	context '#parse' do
+		before :each do
+			@parser = RbbCode::Parser.new
+		end
+		
+		it 'should create paragraphs and line breaks' do
+			bb_code = "This is one paragraph.\n\nThis is another paragraph."
+			@parser.parse(bb_code).should == '<p>This is one paragraph.</p><p>This is another paragraph.</p>'
+			bb_code = "This is one line.\nThis is another line."
+			@parser.parse(bb_code).should == '<p>This is one line.<br/>This is another line.</p>'
+		end
+		
+		it 'should turn [b] to <strong>' do
+			@parser.parse('This is [b]bold[/b] text').should == '<p>This is <strong>bold</strong> text</p>'
+		end
+		
+		it 'should turn [i] to <em> by default' do
+			@parser.parse('This is [i]italic[/i] text').should == '<p>This is <em>italic</em> text</p>'
+		end
+		
+		it 'should turn [u] to <u>' do
+			@parser.parse('This is [u]underlined[/u] text').should == '<p>This is <u>underlined</u> text</p>'
+		end
+		
+		it 'should turn [url]http://google.com[/url] to a link' do
+			@parser.parse('Visit [url]http://google.com[/url] now').should == '<p>Visit <a href="http://google.com">http://google.com</a> now</p>'
+		end
+		
+		it 'should turn [url=http://google.com]Google[/url] to a link' do
+			@parser.parse('Visit [url=http://google.com]Google[/url] now').should == '<p>Visit <a href="http://google.com">Google</a> now</p>'
+		end
+		
+		it 'should turn [img] to <img>' do
+			@parser.parse('[img]http://example.com/image.jpg[/img]').should == '<p><img src="http://example.com/image.jpg" alt=""/></p>'
+		end
+		
+		it 'should turn [code] to <code>' do
+			@parser.parse('Too bad [code]method_missing[/code] is rarely useful').should == '<p>Too bad <code>method_missing</code> is rarely useful</p>'
+		end
+		
+		it 'should parse nested tags' do
+			@parser.parse('[b][i]This is bold-italic[/i][/b]').should == '<p><strong><em>This is bold-italic</em></strong></p>'
+		end
+		
+		it 'should not put <p> tags around <ul> tags' do
+			@parser.parse("Text.\n\n[list]\n[*]Foo[/*]\n[*]Bar[/*]\n[/list]\n\nMore text.").should == '<p>Text.</p><ul><li>Foo</li><li>Bar</li></ul><p>More text.</p>'
+		end
+		
+		it 'should ignore forbidden or unrecognized tags' do
+			@parser.parse('There is [foo]no such thing[/foo] as a foo tag').should == '<p>There is no such thing as a foo tag</p>'
+		end
+		
+		it 'should recover gracefully from malformed or improperly matched tags' do
+			@parser.parse('This [i/]tag[/i] is malformed').should == '<p>This [i/]tag is malformed</p>'
+			@parser.parse('This [i]]tag[/i] is malformed').should == '<p>This <em>]tag</em> is malformed</p>'
+			@parser.parse('This [i]tag[[/i] is malformed').should == '<p>This <em>tag[</em> is malformed</p>'
+			@parser.parse('This [i]tag[//i] is malformed').should == '<p>This <em>tag[//i] is malformed</em></p>'
+			@parser.parse('This [[i]tag[/i] is malformed').should == '<p>This [<em>tag</em> is malformed</p>'
+			@parser.parse('This [i]tag[/i]] is malformed').should == '<p>This <em>tag</em>] is malformed</p>'
+			@parser.parse('This [i]i tag[i] is not properly matched').should == '<p>This <em>i tag is not properly matched</em></p>'
+			@parser.parse('This i tag[/i] is not properly matched').should == '<p>This i tag is not properly matched</p>'
+		end
+		
+		it 'should escape < and >' do
+			@parser.parse('This is [i]italic[/i], but this it not <i>italic</i>.').should == '<p>This is <em>italic</em>, but this it not &lt;i&gt;italic&lt;/i&gt;.</p>'
+		end
+		
+		it 'should work when the string begins with a tag' do
+			@parser.parse('[b]This is bold[/b]').should == '<p><strong>This is bold</strong></p>'
+		end
+		
+		it 'should handle UTF8' do
+			@parser.parse("Here's some UTF-8: [i]א[/i]. And here's some ASCII text.").should == "<p>Here's some UTF-8: <em>א</em>. And here's some ASCII text.</p>"
+		end
+		
+		# Bugs reported and fixed:
+		
+		it 'should not leave an open <em> tag when parsing "foo [i][/i] bar"' do
+			# Thanks to Vizakenjack for finding this. It creates an empty <em> tag. Browsers don't like this, so we need to replace it.
+			@parser.parse('foo [i][/i] bar').should match(/<p>foo +bar<\/p>/)
+		end
+		
+		it 'should not raise when parsing "Are you a real phan yet?\r\n\r\n[ ] Yes\r\n[X] No"' do
+			# Thanks to sblackstone for finding this.
+			@parser.parse("Are you a real phan yet?\r\n\r\n[ ] Yes\r\n[X] No")
+		end
+		
+		it 'should support images inside links' do
+			# Thanks to Vizakenjack for finding this.
+			@parser.parse('[url=http://www.google.com][img]http://www.123.com/123.png[/img][/url]').should ==
+				'<p><a href="http://www.google.com"><img src="http://www.123.com/123.png" alt=""/></a></p>'
+		end
+	end
+end

data/spec/schema_spec.rb

@@ -0,0 +1,98 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+
+describe RbbCode::Schema do
+	before :each do
+		@schema = RbbCode::Schema.new
+		@schema.clear
+		@schema.allow_tags(*RbbCode::DEFAULT_ALLOWED_TAGS)
+	end
+	
+	it 'should allow the default tags at the top level' do
+		schema = RbbCode::Schema.new
+		[
+			'b',
+			'i',
+			'u',
+			'url',
+			'img',
+			'code',
+			'quote',
+			'list'
+		].each do |tag|
+			schema.tag(tag).valid_in_context?().should == true
+		end
+	end
+	
+	it 'should not allow unknown tags' do
+		@schema.tag('foo').valid_in_context?().should == false
+	end
+	
+	it 'should return a new SchemaTag object when tag is called' do
+		@schema.tag('b').should be_a(RbbCode::SchemaTag)
+	end
+	
+	it 'should not allow nesting a tag when may_not_be_nested is called on it' do
+		@schema.tag('b').may_not_be_nested
+		@schema.tag('b').valid_in_context?('b').should == false
+	end
+	
+	it 'should allow nesting a tag when may_be_nested is called on it' do
+		@schema.tag('b').may_not_be_nested
+		@schema.tag('b').may_be_nested
+		@schema.tag('b').valid_in_context?('b').should == true
+	end
+	
+	it 'should not allow a tag to descend from another when forbidden by may_not_descend_from' do
+		@schema.tag('b').may_not_descend_from('u')
+		@schema.tag('b').valid_in_context?('u').should == false
+	end
+	
+	it 'should allow a tag to descend from another when permitted by may_descend_from' do
+		@schema.tag('b').may_not_descend_from('u')
+		@schema.tag('b').may_descend_from('u')
+		@schema.tag('b').valid_in_context?('u').should == true
+	end
+	
+	it 'should not allow a tag to descend from anything other than the tags specified in must_be_child_of' do
+		@schema.tag('b').must_be_child_of('u', 'quote')
+		@schema.tag('b').valid_in_context?('i').should == false
+		@schema.tag('b').valid_in_context?('u').should == true
+		@schema.tag('b').valid_in_context?('quote').should == true
+	end
+	
+	it 'should allow a tag to descend from the one specified in must_be_child_of' do
+		@schema.tag('b').may_not_descend_from('u')
+		@schema.tag('b').must_be_child_of('u')
+		@schema.tag('b').valid_in_context?('u').should == true
+	end
+	
+	it 'should not require a tag to be a child of another when need_not_be_child_of is called' do
+		@schema.tag('b').must_be_child_of('u')
+		@schema.tag('b').need_not_be_child_of('u')
+		@schema.tag('b').valid_in_context?('i').should == true
+	end
+	
+	it 'should allow only the specified tag as a child when may_only_be_parent_of is called' do
+		@schema.tag('list').may_only_be_parent_of('*')
+		@schema.tag('*').valid_in_context?('list').should == true
+		@schema.tag('u').valid_in_context?('list').should == false
+		@schema.tag('u').valid_in_context?('*', 'list').should == true
+	end
+	
+	it 'should not allow text inside a tag when may_not_contain_text is called' do
+		@schema.tag('list').may_not_contain_text
+		@schema.text.valid_in_context?('list').should == false
+	end
+	
+	it 'should allow text inside a tag when may_contain_text is called' do
+		@schema.tag('list').may_not_contain_text
+		@schema.tag('list').may_contain_text
+		@schema.text.valid_in_context?('list').should == true
+	end
+	
+	it 'should not allow text or children when must_be_empty is called' do
+		@schema.tag('br').must_be_empty
+		@schema.text.valid_in_context?('br').should == false
+		@schema.tag('b').valid_in_context?('br').should == false
+	end
+end

data/spec/spec_helper.rb

@@ -0,0 +1,9 @@
+require 'rubygems'
+require 'test/unit'
+require 'spec'
+
+def puts(foo)
+	raise 'puts called'
+end
+
+require File.expand_path(File.dirname(__FILE__) + '/../lib/rbbcode')

data/spec/tree_maker_spec.rb

@@ -0,0 +1,107 @@
+require File.expand_path(File.dirname(__FILE__) + '/spec_helper')
+require File.expand_path(File.dirname(__FILE__) + '/node_spec_helper')
+require 'pp'
+
+describe RbbCode::TreeMaker do
+	include NodeMatchers
+	
+	context '#make_tree' do
+		def expect_tree(str, &block)
+			expected = NodeBuilder.build(&block)
+			@tree_maker.make_tree(str).should match_node(expected)
+		end
+		
+		before :each do
+			@schema = RbbCode::Schema.new
+			@tree_maker = RbbCode::TreeMaker.new(@schema)
+		end		
+
+		it 'should make a tree from a string with one tag' do
+			str = 'This is [b]bold[/b] text'
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'This is '
+					tag('b') { text 'bold' }
+					text ' text'
+				end
+			end
+		end
+	
+		it 'should ignore tags that are invalid in their context' do
+			@schema.tag('u').may_not_descend_from('b')
+			
+			str = 'This is [b]bold and [u]underlined[/u][/b] text'
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'This is '
+					tag('b') do
+						text 'bold and '
+						text 'underlined'
+					end
+					text ' text'
+				end
+			end
+		end
+
+		it 'should create paragraph tags' do
+			str = "This is a paragraph.\n\nThis is another."
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'This is a paragraph.'
+				end
+				tag('p') do
+					text 'This is another.'
+				end
+			end
+		end
+
+		it 'should not put block-level elements inside paragraph tags' do
+			str = "This is a list:\n\n[list]\n\n[*]Foo[/i]\n\n[/list]\n\nwith some text after it"
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'This is a list:'
+				end
+				tag('list') do
+					tag('*') { text 'Foo' }
+				end
+				tag('p') do
+					text 'with some text after it'
+				end
+			end
+		end
+		
+		it 'should not insert br tags in the midst of block-level elements' do
+			str = "List:\n[list]\n[*]Foo[/*]\n[*]Bar[/*]\n[/list]\nText after list"
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'List:'
+				end
+				tag('list') do
+					tag('*') { text 'Foo' }
+					tag('*') { text 'Bar' }
+				end
+				tag('p') do
+					text 'Text after list'
+				end
+			end
+		end
+		
+		it 'should store tag values' do
+			str = 'This is a [url=http://google.com]link[/url]'
+			
+			expect_tree(str) do
+				tag('p') do
+					text 'This is a '
+					tag('url', 'http://google.com') do
+						text 'link'
+					end
+				end
+			end
+		end
+	end
+end

metadata

@@ -0,0 +1,60 @@
+--- !ruby/object:Gem::Specification 
+name: rbbcode
+version: !ruby/object:Gem::Version 
+  version: 0.1.2
+platform: ruby
+authors: 
+- Jarrett Colby
+autorequire: 
+bindir: bin
+cert_chain: []
+
+date: 2009-12-09 00:00:00 -06:00
+default_executable: 
+dependencies: []
+
+description: RbbCode is a customizable Ruby library for parsing BB Code. RbbCode validates and cleans input. It supports customizable schemas so you can set rules about what tags are allowed where. The default rules are designed to ensure valid HTML output.
+email: jarrett@jarrettcolby.com
+executables: []
+
+extensions: []
+
+extra_rdoc_files: 
+- README
+files: 
+- README
+has_rdoc: true
+homepage: http://github.com/jarrett/rbbcode
+licenses: []
+
+post_install_message: 
+rdoc_options: 
+- --charset=UTF-8
+require_paths: 
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+required_rubygems_version: !ruby/object:Gem::Requirement 
+  requirements: 
+  - - ">="
+    - !ruby/object:Gem::Version 
+      version: "0"
+  version: 
+requirements: []
+
+rubyforge_project: 
+rubygems_version: 1.3.5
+signing_key: 
+specification_version: 3
+summary: Ruby BB Code parser
+test_files: 
+- spec/html_maker_spec.rb
+- spec/node_spec_helper.rb
+- spec/parser_spec.rb
+- spec/schema_spec.rb
+- spec/spec_helper.rb
+- spec/tree_maker_spec.rb