multisax 0.0.0.3 → 0.0.0.4

data/LICENSE.txt

@@ -1,6 +1,4 @@
-Copyright (c) 2013, cielavenir
-
-All rights reserved.
+- Copyright (c) 2013, T. Yamada
 
 Redistribution and use in source and binary forms, with or without
 modification, are permitted provided that the following conditions are met: 
@@ -22,9 +20,9 @@ ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
 (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS
 SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 
-A part of Nokogiri source code is cited to convert Nokogiri::XML::SAX::Document into module.
+- A part of Nokogiri source code is cited to convert Nokogiri::XML::SAX::Document into module.
 
-Copyright © 2008 - 2012: Aaron Patterson, Mike Dalessio, Charles Nutter, Sergio Arbeo, Patrick Mahoney, Yoko Harada
+- Copyright © 2008 - 2012: Aaron Patterson, Mike Dalessio, Charles Nutter, Sergio Arbeo, Patrick Mahoney, Yoko Harada
 
 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:
 
@@ -34,7 +32,7 @@ THE SOFTWARE IS PROVIDED ‘AS IS’, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR I
 
 Note: MultiSAX shouldn't load any copyleft libraries.
 
-Ruby (REXML): 2-clause BSD License (or Artistic License)
-Nokogiri: MIT License
-libxml-ruby: MIT License
-Ox: 3-clause BSD License
+- Ruby (REXML): 2-clause BSD License (or Artistic License)
+- Nokogiri: MIT License
+- libxml-ruby: MIT License
+- Ox: 3-clause BSD License

data/{README.md → README.rdoc}

@@ -2,33 +2,32 @@
 
 * Please check spec/multisax.spec as an example.
 * Complex usage:
-```ruby
-listener=MultiSAX::Sax.parse(xml,Class.new{
-	include MultiSAX::Callbacks
-	def initialize
-		@content=Hash.new{|h,k|h[k]=[]}
-		@current_tag=[]
-	end
-	attr_reader :content
+    require 'multisax'
+    listener=MultiSAX::Sax.parse(xml,Class.new{
+    	include MultiSAX::Callbacks
+    	def initialize
+    		@content=Hash.new{|h,k|h[k]=[]}
+    		@current_tag=[]
+    	end
+    	attr_reader :content
 
-	def sax_tag_start(tag,attrs)
-		@current_tag.push(tag)
-	end
-	def sax_tag_end(tag)
-		if (t=@current_tag.pop)!=tag then raise "xml is malformed /#{t}" end
-	end
-	def sax_cdata(text)
-		@content[@current_tag.last] << text
-	end
-	def sax_text(text)
-		text.strip!
-		@content[@current_tag.last] << text if text.size>0
-	end
-	def sax_comment(text)
-	end
-}.new)
-listener.content.each{...}
-```
+    	def sax_tag_start(tag,attrs)
+    		@current_tag.push(tag)
+    	end
+    	def sax_tag_end(tag)
+    		if (t=@current_tag.pop)!=tag then raise "xml is malformed /#{t}" end
+    	end
+    	def sax_cdata(text)
+    		@content[@current_tag.last] << text
+    	end
+    	def sax_text(text)
+    		text.strip!
+    		@content[@current_tag.last] << text if text.size>0
+    	end
+    	def sax_comment(text)
+    	end
+    }.new)
+    listener.content.each{...}
 
 * Optional XML libraries:
 * gem install ox
@@ -47,5 +46,5 @@ listener.content.each{...}
 
 == Copyright
 
-Copyright (c) 2013 cielavenir. See LICENSE.txt for
+Copyright (c) 2013 T. Yamada. See LICENSE.txt for
 further details.

data/Rakefile

@@ -44,6 +44,8 @@ Rake::RDocTask.new do |rdoc|
 
   rdoc.rdoc_dir = 'rdoc'
   rdoc.title = "multisax #{version}"
+  rdoc.main = 'README.rdoc'
   rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('LICENSE*')
   rdoc.rdoc_files.include('lib/**/*.rb')
 end

data/VERSION

@@ -1 +1 @@
-0.0.0.3
+0.0.0.4

data/lib/multisax.rb

@@ -1,14 +1,23 @@
-#MultiSAX: Ruby Gem to handle multiple SAX libraries
-#Copyright (c) 2013, T. Yamada All rights reserved under 2-clause BSDL.
-#Check LICENSE terms.
-#Note: MIT License is also applicable if that compresses LICENSE file.
+# MultiSAX: Ruby Gem to handle multiple SAX libraries
+#
+# Copyright (c) 2013, T. Yamada All rights reserved under 2-clause BSDL.
+#
+# Check LICENSE terms.
+#
+# Note: MIT License is also applicable if that compresses LICENSE file.
 
 module MultiSAX
 	#VERSION=''
 
+	# The class to handle XML libraries.
 	class Sax
 		@@parser=nil
 		@@saxmodule=nil
+		# Library loader.
+		# Arguments are list (or Array) of libraries.
+		#  Currently the following are supported (order by speed):
+		#  :ox, :libxml, :nokogiri, :rexmlstream, :rexmlsax2
+		#  If multiple selected, MultiSAX will try the libraries one by one and use the first usable one.
 		def self.open(*list)
 			return @@parser if @@parser
 			list=[:ox,:libxml,:nokogiri,:rexmlstream,:rexmlsax2] if list.size==0
@@ -61,10 +70,19 @@ module MultiSAX
 			}
 			return @@parser
 		end
+		# Reset MultiSAX state so that you can re-open() another library.
 		def self.reset() @@parser=nil;@@saxmodule=nil end
+		# Returns which module is actually chosen.
 		def self.parser() @@parser end
 
+		#--
 		#def initialize(listener)
+		#++
+		# The main parsing method.
+		# Listener can be Class.new{include MultiSAX::Callbacks}.new. Returns the listener after SAX is applied.
+		# If you have not called open(), this will call it using default value (all libraries). 
+		#  SAX's listeners are usually modified destructively.
+		#  So instances shouldn't be provided.
 		def self.parse(body,listener)
 			#self.class.open if !@@parser
 			self.open if !@@parser
@@ -76,33 +94,40 @@ module MultiSAX
 				when :ox
 					@listener.instance_eval{
 						extend @@saxmodule
-						@saxwrapper_attr=[:xmldecl]
+						@saxwrapper_attr=[]
 						def start_element(tag)
+							# I hope provided Listener's sax_tag_start will NOT be used elsewhere.
+							alias :attrs_done :attrs_done_normal
 							@saxwrapper_tag=tag
 							@saxwrapper_attr=[]
 						end
+						# These "instance methods" are actually injected to listener class using instance_eval.
+						# i.e. not APIs. You cannot call these methods from outside.
 						def attr(name,str)
 							@saxwrapper_attr<<[name,str]
 						end
+						#--
 						#alias :attr_value :attr
-						def attrs_done
-							if @saxwrapper_attr.first==:xmldecl
-								@saxwrapper_attr.shift
-								version=@saxwrapper_attr.assoc(:version)
-								version&&=version[1]
-								encoding=@saxwrapper_attr.assoc(:encoding)
-								encoding&&=encoding[1]
-								standalone=@saxwrapper_attr.assoc(:standalone)
-								standalone&&=standalone[1]
-								sax_xmldecl(version,encoding,standalone)
-							else
-								sax_tag_start(@saxwrapper_tag.to_s,@saxwrapper_attr)
-							end
+						#++
+						def attrs_done_xmldecl
+							version=@saxwrapper_attr.assoc(:version)
+							version&&=version[1]
+							encoding=@saxwrapper_attr.assoc(:encoding)
+							encoding&&=encoding[1]
+							standalone=@saxwrapper_attr.assoc(:standalone)
+							standalone&&=standalone[1]
+							sax_xmldecl(version,encoding,standalone)
 						end
+						def attrs_done_normal
+							sax_tag_start(@saxwrapper_tag.to_s,@saxwrapper_attr)
+						end
+						alias :attrs_done :attrs_done_xmldecl
 						def end_element(tag) sax_tag_end(tag.to_s) end
 						alias :cdata :sax_cdata
 						alias :text :sax_text
+						#--
 						#alias :value :sax_text
+						#++
 						alias :comment :sax_comment
 					}
 				when :libxml
@@ -161,8 +186,13 @@ module MultiSAX
 			@listener
 		end
 	end
+
+	##
+	# MultiSAX callbacks.
+	# MultiSAX::Sax listener should include this module.
 	module Callbacks
-		# https://github.com/sparklemotion/nokogiri/blob/master/lib/nokogiri/xml/sax/document.rb
+		# Cited from Nokogiri to convert Nokogiri::XML::SAX::Document into module.
+		#  https://github.com/sparklemotion/nokogiri/blob/master/lib/nokogiri/xml/sax/document.rb
 		def sax_start_element_namespace name, attrs = [], prefix = nil, uri = nil, ns = []
 			# Deal with SAX v1 interface
 			name = [prefix, name].compact.join(':')

data/multisax.gemspec

@@ -5,7 +5,7 @@
 
 Gem::Specification.new do |s|
   s.name = "multisax"
-  s.version = "0.0.0.3"
+  s.version = "0.0.0.4"
 
   s.required_rubygems_version = Gem::Requirement.new(">= 0") if s.respond_to? :required_rubygems_version=
   s.authors = ["cielavenir"]
@@ -14,7 +14,7 @@ Gem::Specification.new do |s|
   s.email = "cielartisan@gmail.com"
   s.extra_rdoc_files = [
     "LICENSE.txt",
-    "README.md"
+    "README.rdoc"
   ]
   s.files = [
     ".document",
@@ -22,7 +22,7 @@ Gem::Specification.new do |s|
     "Gemfile",
     "Gemfile.lock",
     "LICENSE.txt",
-    "README.md",
+    "README.rdoc",
     "Rakefile",
     "VERSION",
     "lib/multisax.rb",

data/spec/multisax_spec.rb

@@ -15,6 +15,8 @@ class MultiSAXTester
 		text.strip!
 		@result<<text if text.size>0
 	end
+	#def sax_xmldecl(version,encoding,standalone)
+	#end
 	attr_reader :result
 end
 input_xml=<<"EOM"

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: multisax
 version: !ruby/object:Gem::Version
-  version: 0.0.0.3
+  version: 0.0.0.4
   prerelease: 
 platform: ruby
 authors:
@@ -81,14 +81,14 @@ executables: []
 extensions: []
 extra_rdoc_files:
 - LICENSE.txt
-- README.md
+- README.rdoc
 files:
 - .document
 - .rspec
 - Gemfile
 - Gemfile.lock
 - LICENSE.txt
-- README.md
+- README.rdoc
 - Rakefile
 - VERSION
 - lib/multisax.rb
@@ -110,7 +110,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
       version: '0'
       segments:
       - 0
-      hash: -2850175293617683642
+      hash: 4112567294364414967
 required_rubygems_version: !ruby/object:Gem::Requirement
   none: false
   requirements: