xmlcodec 0.1.3 → 0.3.0

data/README.rdoc

@@ -30,17 +30,21 @@ you would create the following classes:
 
   require 'xmlcodec'
 
-  class Root < XMLCodec::XMLElement
+  class Format < XMLCodec::XMLElement
+    xmlformat "Some XML Format Name"
+  end
+
+  class Root < Format
     elname 'root'
     xmlsubel :firstelement
   end
   
-  class FirstElement < XMLCodec::XMLElement
+  class FirstElement < Format
     elname 'firstelement'
     xmlsubel_mult :secondelement
   end
   
-  class SecondElement < XMLCodec::XMLElement
+  class SecondElement < Format
     elname 'secondelement'
     elwithvalue
     xmlattr :firstattr
@@ -69,21 +73,21 @@ format.
 To import XML just do:
 
   # From text
-  Root.import_xml_text(File.new('file.xml'))
+  Root.import_xml File.new('file.xml')
   
-  # From a REXML DOM
-  Root.import_xml(REXML::Document.new(File.new('file.xml')))
+  # From a Nokogiri DOM
+  Root.import_xml Nokogiri::XML::Document.parse(File.read('file.xml'))
   
 To export do:
 
   # To generate XML text
   string = some_element.xml_text
 
-  # To generate REXML DOM
-  doc = some_element.create_xml(REXML::Document.new)
+  # To generate Nokogiri DOM
+  doc = some_element.create_xml(Nokogiri::XML::Document.new)
   
 All these calls require keeping the whole contents of the document in memory.
-The ones that use the REXML DOM will have it twice. To handle large documents with constant memory usage another set of APIs is available.
+The ones that use the Nokogiri DOM will have it twice. To handle large documents with constant memory usage another set of APIs is available.
 
 To stream parse a large document you'd do something like:
 

data/Rakefile

@@ -1,64 +1,77 @@
-PKG_NAME = 'xmlcodec'
-PKG_VERSION = '0.1.3'
+# Based on the jekyll Rakefile (http://github.com/mojombo/jekyll)
 
+require 'rubygems'
 require 'rake'
+require 'date'
 require 'rake/testtask'
-require 'rake/rdoctask'
-require 'rake/gempackagetask'
-require 'rcov/rcovtask'
-require 'rubygems'
+require 'rdoc/task'
+
+#############################################################################
+#
+# Helper functions
+#
+#############################################################################
+
+def name
+  @name ||= Dir['*.gemspec'].first.split('.').first
+end
+
+def version
+  line = File.read("lib/#{name}.rb")[/^\s*VERSION\s*=\s*.*/]
+  line.match(/.*VERSION\s*=\s*['"](.*)['"]/)[1]
+end
+
+def date
+  Date.today.to_s
+end
+
+def rubyforge_project
+  name
+end
+
+def gemspec_file
+  "#{name}.gemspec"
+end
 
-task :default => ['test']
-
-TEST_FILES = 'test/**/*.rb'
-CODE_FILES = 'lib/**/*.rb'
-
-PKG_FILES = FileList[TEST_FILES,
-                     CODE_FILES,
-                     'README*',
-                     'LICENSE',
-                     'Rakefile']
-
-RDOC_OPTIONS = ['-S', '-w 2', '-N']
-RDOC_EXTRA_FILES = ['README.rdoc']
-
-spec = Gem::Specification.new do |s|
-  s.platform = Gem::Platform::RUBY
-  s.summary = "Generic Importer/Exporter of XML formats"
-  s.homepage = "http://github.com/pedrocr/xmlcodec" 
-  s.name = PKG_NAME
-  s.version = PKG_VERSION
-  s.author = 'Pedro Côrte-Real'
-  s.email = 'pedro@pedrocr.net'
-  s.requirements << 'none'
-  s.require_path = 'lib'
-  s.files = PKG_FILES
-  s.has_rdoc = true
-  s.rdoc_options = RDOC_OPTIONS
-  s.extra_rdoc_files = RDOC_EXTRA_FILES
-  s.description = <<EOF
-A library that eases the creation of XML importers and exporters for ruby.
-EOF
+def gem_file
+  "#{name}-#{version}.gem"
 end
 
-Rake::GemPackageTask.new(spec) do |pkg|
+def replace_header(head, header_name)
+  head.sub!(/(\.#{header_name}\s*= ').*'/) { "#{$1}#{send(header_name)}'"}
 end
 
-Rake::TestTask.new do |t|
-  t.test_files = FileList['test/*_test.rb']
-  t.verbose = true
+#############################################################################
+#
+# Standard tasks
+#
+#############################################################################
+
+task :default => [:test]
+
+Rake::TestTask.new(:test) do |test|
+  test.libs << 'lib' << 'test'
+  test.pattern = 'test/*_test.rb'
+  test.verbose = true
 end
 
-Rake::RDocTask.new do |rd|
-  rd.main = "README.rdoc"
-  rd.name = :docs
-  rd.rdoc_files.include(RDOC_EXTRA_FILES, CODE_FILES)
-  rd.rdoc_dir = 'doc'
-  rd.title = "#{PKG_NAME} API"
-  rd.options = RDOC_OPTIONS
+Rake::RDocTask.new do |rdoc|
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "#{name} #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
 end
 
+desc "Open an irb session preloaded with this library"
+task :console do
+  sh "irb -rubygems -r ./lib/#{name}.rb"
+end
+
+desc "Prints code to test ratio stats"
 task :stats do
+  CODE_FILES = "lib/**/*.rb"
+  TEST_FILES = "test/*_test.rb"
+
   code_code, code_comments = count_lines(FileList[CODE_FILES])
   test_code, test_comments = count_lines(FileList[TEST_FILES])
   
@@ -70,13 +83,6 @@ task :stats do
   puts "Code to test ratio: 1:%.2f" % ratio
 end
 
-Rcov::RcovTask.new do |t|
-  t.libs << "test"
-  t.test_files = FileList['test/*_test.rb']
-  t.output_dir = 'test/coverage'
-  t.verbose = true
-end
-
 def count_lines(files)
   code = 0
   comments = 0
@@ -91,3 +97,55 @@ def count_lines(files)
   end
   [code, comments]
 end
+
+#############################################################################
+#
+# Packaging tasks
+#
+#############################################################################
+
+desc "git tag, build and release gem"
+task :release => :build do
+  unless `git branch` =~ /^\* master$/
+    puts "You must be on the master branch to release!"
+    exit!
+  end
+  sh "git commit --allow-empty -a -m 'Release #{version}'"
+  sh "git tag v#{version}"
+  sh "git push origin master"
+  sh "git push origin v#{version}"
+  sh "gem push pkg/#{name}-#{version}.gem"
+end
+
+desc "Build gem"
+task :build => :gemspec do
+  sh "mkdir -p pkg"
+  sh "gem build #{gemspec_file}"
+  sh "mv #{gem_file} pkg"
+end
+
+task :gemspec do
+  # read spec file and split out manifest section
+  spec = File.read(gemspec_file)
+  head, manifest, tail = spec.split("  # = MANIFEST =\n")
+
+  # replace name version and date
+  replace_header(head, :name)
+  replace_header(head, :version)
+  replace_header(head, :date)
+
+  # determine file list from git ls-files
+  files = `git ls-files`.
+    split("\n").
+    sort.
+    reject { |file| file =~ /^\./ }.
+    reject { |file| file =~ /^(rdoc|pkg|coverage)/ }.
+    map { |file| "    #{file}" }.
+    join("\n")
+
+  # piece file back together and write
+  manifest = "  s.files = %w[\n#{files}\n  ]\n"
+  spec = [head, manifest, tail].join("  # = MANIFEST =\n")
+  File.open(gemspec_file, 'w') { |io| io.write(spec) }
+  puts "Updated #{gemspec_file}"
+end

data/lib/XMLUtils.rb

@@ -6,104 +6,46 @@ require 'stringio'
 # parser whose events are the text of whole elements instead of start and end 
 # tags.
 
-module XMLUtils
-  # Gets the REXML DOM for a given filename that must be a XML file.
-  def self.getdoc(filename)
-    file = File.new(filename, 'r')
-    REXML::Document.new file
-  end
+module XMLCodec
+  module XMLUtils
+    # Gets the Nokogiri DOM for a given filename that must be a XML file.
+    def self.getdoc(filename)
+      Nokogiri::XML::Document.parse File.new(filename, 'r')
+    end
 
-  # Count the number of elements that correspond to a given xpath in a file.
-  def self.count_elements(path, filename)
-    doc = getdoc(filename)
-    i = 0
-    REXML::XPath.each(doc, path) {|element| i+=1}
-    return i
-  end
+    # Count the number of elements that correspond to a given xpath in a file.
+    def self.count_elements(path, filename)
+      getdoc(filename).xpath(path).size
+    end
 
-  # Test if a given xpath exists in the file.
-  def self.element_exists(path, filename)
-    count_elements(path,filename)>0
-  end
+    # Test if a given xpath exists in the file.
+    def self.element_exists(path, filename)
+      count_elements(path,filename)>0
+    end
 
-  # Get a xpath from a REXML document.
-  def self.select_path_doc(path, doc)
-    element = REXML::XPath.first(doc, path)
-    return "" if not element
-    if element.respond_to?("value")
-      return element.value || ""
+    # Get a xpath from a Nokogiri::XML::Document.
+    def self.select_path_doc(path, doc)
+      els = doc.xpath(path)
+      return "" if !els[0]
+      els[0].children.to_s
     end
-    return element.text || ""
-  end
 
-  # Get a xpath from a file.
-  def self.select_path(path, filename)
-    XMLUtils::select_path_doc(path, getdoc(filename))
-  end
-  
-  # Create an open tag.
-  def self.create_open_tag(name, attrs)
-    str = "<"+name
-    attrs.each {|name, value| str << " #{name}='#{value}'"}
-    str << ">"
-    str
-  end
-  
-  # Escape a string so that it can be included in a XML document
-  def self.escape_xml(string)
-    t = REXML::Text.new('')
-    str = ''
-    t.write_with_substitution(str, string)
-    str
-  end
-  
-  # Gets the xpath inside a given document that can either be a string or a 
-  # REXML::Document
-  #
-  # Supported options (boolean):
-  # [:multiple] 
-  #   fetch all the occurences of the xpath
-  # [:with_attrs] 
-  #   include the attribute contents in the result
-  # [:recursive] 
-  #   recursively include all the subelements of the matches
-  def self.get_xpath(path, doc, opts={})
-    if doc.is_a? REXML::Document
-      doc = doc
-    else
-      doc = REXML::Document.new(doc)
+    # Get a xpath from a file.
+    def self.select_path(path, filename)
+      select_path_doc(path, getdoc(filename))
     end
     
-    if opts[:multiple]
-      strs = []
-      REXML::XPath.each(doc.root, path) do |e|
-        t = get_rexml_content(e, opts)
-        strs << t if t != ''
-      end
-      return strs.join(' ')
-    else
-      return get_rexml_content(REXML::XPath.first(doc, path), opts)
+    # Create an open tag.
+    def self.create_open_tag(name, attrs)
+      str = "<"+name
+      attrs.each {|name, value| str << " #{name}='#{value}'"}
+      str << ">"
+      str
     end
-  end
-  
-  def self.get_rexml_content(element, opts={})
-    return '' if not element
-    strs = []
-    if element.respond_to?('value')
-      return element.value || ''
-    else
-      if opts[:with_attrs]
-        element.attributes.each {|name, value| strs << value if value != ''}
-      end
-      if not opts[:recursive]
-        element.texts.each {|t| strs << t if t != ''}
-      else  
-        element.to_a.each do |e|
-          t = get_rexml_content(e, opts)
-          strs << t if t != ''
-        end
-      end
+    
+    # Escape a string so that it can be included in a XML document
+    def self.escape_xml(string)
+      Nokogiri::XML::Text.new(string, Nokogiri::XML::Document.new).to_s
     end
-    strs.join(' ')
   end
 end

data/lib/element.rb

@@ -2,6 +2,9 @@ module XMLCodec
   class ElementClassNotFound < RuntimeError
   end
 
+  class ElementAttributeNotFound < RuntimeError
+  end
+
   # This class should be inherited from to create classes that are able to
   # import and export XML elements and their children. It provides three main
   # functions: xmlattr, xmlsubel and xmlsubel_mult.
@@ -15,16 +18,13 @@ module XMLCodec
   # has no subelements and includes only text content.
   #
   # After the class is defined import_xml can be used to import the content from
-  # a REXML Element or Document and create_xml can be used to create the XML DOM
-  # of the element as a child to a REXML Element or Document. For big documents
+  # a Nokogiri Element or Document and create_xml can be used to create the XML DOM
+  # of the element as a child to a Nokogiri Element or Document. For big documents
   # these are usually too slow and memory hungry, using xml_text to export to 
   # XML and import_xml_text to import XML are probably better ideas. 
   # import_xml_text is just a utility function around XMLStreamObjectParser,
   # that allow more flexible stream parsing of XML files while still using the
   # same XMLElement objects.
-  #
-  # <b>WARNING</b>: This API is still very much a work in progress and very
-  # rough in certain places. Changes will surely be made.
   class XMLElement
     INDENT_STR = '  '
     CACHE = {}
@@ -48,7 +48,7 @@ module XMLCodec
     def self.xmlattrs
       @xmlattrs ||=[]
     end
-  
+
     # Add a name as being a subelement (mult or single)
     def self._xmlsubel(name)
       self.xmlsubels << name
@@ -74,7 +74,7 @@ module XMLCodec
       self._xmlsubel(name)
       self.xmlsubelmultiples << name
       define_method(name){
-        if not self.instance_variables.index("@#{name}")
+        if not self.instance_variables.index("@#{name}".to_sym)
           instance_variable_set "@#{name}", XMLSubElements.new(self)
         end
         instance_variable_get "@#{name}"
@@ -83,7 +83,7 @@ module XMLCodec
     
     # Iterates over the object's XML subelements
     def self.each_subel
-      if not self.instance_variables.index("@__subel_names")
+      if not self.instance_variables.index("@__subel_names".to_sym)
         names = []
         # Iterate all the superclasses that are still children of XMLElement
         # and iterate each of the subelements
@@ -100,7 +100,7 @@ module XMLCodec
     # Iterate all the superclasses that are still children of XMLElement
     # and check if any of them have the subelement mult defined
     def self.subel_mult?(element)
-      if not self.instance_variables.index("@__subel_mult_names")
+      if not self.instance_variables.index("@__subel_mult_names".to_sym)
         names = []
         c = self
         while c.ancestors.index(XMLCodec::XMLElement)
@@ -130,9 +130,13 @@ module XMLCodec
   
     # Iterates over the object's XML atributes
     def self.each_attr    
-      if not self.instance_variables.index("@__attr_names")
+      attr_names.each {|name| yield name}
+    end
+
+    def self.attr_names
+      if not self.instance_variables.index("@__attr_names".to_sym)
         names = []
-        # Iterate all the superclasses that are still children of EADElement
+        # Iterate all the superclasses that are still children of XMLElement
         # and iterate each of the attributes
         c = self
         while c.ancestors.index(XMLCodec::XMLElement)
@@ -142,7 +146,7 @@ module XMLCodec
         @__attr_names = names
       end
       
-      @__attr_names.each {|name| yield name}
+      @__attr_names
     end
 
     # Creates the XML for the atributes
@@ -150,7 +154,7 @@ module XMLCodec
       self.class.each_attr do |a|
         value = self.send(a)
         if value
-          parent.add_attribute(a.to_s, value)
+          parent.set_attribute(a.to_s, value)
         end
       end
     end
@@ -164,7 +168,7 @@ module XMLCodec
           attrs[a.to_s] = value
         end
       end
-      XMLUtils::create_open_tag(elname.to_s, attrs)
+      XMLCodec::XMLUtils::create_open_tag(elname.to_s, attrs)
     end
     
     # returns a string with the closing tag for the element
@@ -176,7 +180,7 @@ module XMLCodec
     # method called #subelements that will return an instance of XMLSubElements
     def self.xmlsubelements #:doc:
       define_method(:subelements) {
-        if not self.instance_variables.index("@subelements")
+        if not self.instance_variables.index("@subelements".to_sym)
           @subelements = XMLSubElements.new(self)
         end
         @subelements
@@ -198,7 +202,7 @@ module XMLCodec
   
     # Add a xmlattr type attribute (wrapper around attr_accessor)
     def self.xmlattr(name) #:doc:
-      self.xmlattrs << name
+      self.xmlattrs << name.to_sym
       attr_accessor name
     end
     
@@ -206,6 +210,11 @@ module XMLCodec
     # a class that's the super class of all the elements of a format
     def self.xmlformat(name=nil)
       class_variable_set('@@elclasses', {})
+      class_variable_set('@@strict_parsing', false)
+    end
+
+    def self.xml_strict_parsing
+      class_variable_set('@@strict_parsing', true)
     end
     
     def self.elclasses
@@ -258,22 +267,12 @@ module XMLCodec
       self.subelements.create_xml(parent)
     end
     
-    # Have we already started the partial export of this element?
-    def already_partial_exported?
-      (@already_partial_exported ||= false)
-    end
-    
-    # Have we already ended the partial export of this element?
-    def already_partial_export_ended?
-      (@already_partial_export_ended ||= false)
-    end
-    
     # Which level of indentation are we in?
     #
     # This is currently disabled until I get around to implementing proper and 
     # tested indent support.
     #def indent_level
-    #  if not self.instance_variables.index '@indent_level'
+    #  if not self.instance_variables.index '@indent_level'.to_sym
     #    curr = self
     #    level = 0
     #    while curr = curr.__parent
@@ -338,7 +337,7 @@ module XMLCodec
     # Gets the class for a certain element name.
     def self.get_element_class(name)
       cl = elclasses[name.to_sym]
-  	  if not cl
+  	  if not cl and class_variable_get('@@strict_parsing')
   		  raise ElementClassNotFound, "No class defined for element type: '" + name.to_s + "'"
   		end
   		cl
@@ -360,12 +359,12 @@ module XMLCodec
   
 
     # Creates the xml for the element inside the parent element. The parent
-    # passed should be a REXML element or document. This call is recursive
+    # passed should be a Nokogiri XML Node or Document. This call is recursive
     # creating the XML for any subelements. 
     def create_xml(parent)
-      xmlel = parent.add_element self.elname.to_s
+      xmlel = parent.add_child Nokogiri::XML::Element.new(self.elname.to_s, parent)
       if self.hasvalue?
-        xmlel.text = self.value
+        xmlel.add_child self.value
       end
       create_xml_attr(xmlel)
       create_xml_subel(xmlel)
@@ -377,34 +376,55 @@ module XMLCodec
       xmlel
     end
     
-    # Import the XML into an object from a REXML element. This call is recursive
-    # and imports any subelements found into the corresponding objects.
-    def self.import_xml(xmlel)
-      if xmlel.is_a? REXML::Document
+    # Import the XML into an object from a Nokogiri XML Node or Document or from
+    # a string.
+    def self.import_xml(obj)
+      if obj.instance_of? String
+        _import_xml_text(obj)
+      elsif obj.instance_of? Nokogiri::XML::Node or 
+            obj.instance_of? Nokogiri::XML::Document
+        _import_xml_dom(obj)
+      else
+        nil
+      end
+    end
+
+    # Import the XML into an object from a Nokogiri XML Node or Document. 
+    # This call is recursive and imports any subelements found into the 
+    # corresponding objects.
+    def self._import_xml_dom(xmlel)
+      if xmlel.is_a? Nokogiri::XML::Document
         xmlel = xmlel.root
       end
       
       elements = []
-      xmlel.to_a.each do |e|
-        if e.is_a? REXML::Text
-          elements << e.value
+      xmlel.children.each do |e|
+        if e.text?
+          elements << e.text
         else
           elclass = get_element_class(e.name)
-          elements << elclass.import_xml(e)
+          if not elclass
+            if class_variable_get('@@strict_parsing')
+  		        raise ElementClassNotFound, "No class defined for element type: '#{e.name}'"  
+            end
+  		    else
+            elements << elclass._import_xml_dom(e)
+          end
         end
       end
       
       attributes = {}
-      xmlel.attributes.each do |name, value|
-        attributes[name] = value
+      xmlel.attributes.each do |name, attr|
+        attributes[name] = attr.value
       end
       
-      new_with_content(attributes, elements)
+      elclass = get_element_class(xmlel.name)
+      return nil if not elclass
+      elclass.new_with_content(attributes, elements)
     end
     
-    # Import the XML directly from the text. This call receives the text and the
-    # classes that should be used to import the subelements.
-    def self.import_xml_text(text)
+    # Import the XML directly from the text.
+    def self._import_xml_text(text)
       parser = XMLStreamObjectParser.new(self)
       parser.parse(text)
       parser.top_element
@@ -436,7 +456,13 @@ module XMLCodec
     # add the attributes passed as a hash to the element
     def add_attr(attrs)
       attrs.each do |name, value|
-        self.send("#{name}=", value)
+        if not self.class.attr_names.include?(name.to_sym)
+          if self.class.class_variable_get('@@strict_parsing')
+            raise ElementAttributeNotFound, "No attribute '#{name}' defined for class '#{self.class}'" 
+          end
+        else
+          self.send("#{name}=", value)
+        end
       end
     end
     
@@ -467,12 +493,11 @@ module XMLCodec
     end
     
     
-    # create the XML text of the element. This does not use REXML so should be 
-    # pretty fast.
+    # create the XML text of the element
     def xml_text
       str = create_open_tag
       if self.hasvalue?
-        str << XMLUtils::escape_xml(self.value)
+        str << XMLCodec::XMLUtils::escape_xml(self.value)
       end
       
       each_subelement do |e|
@@ -483,6 +508,16 @@ module XMLCodec
       str
     end
     
+    # Have we already started the partial export of this element?
+    def already_partial_exported?
+      (@already_partial_exported ||= false)
+    end
+    
+    # Have we already ended the partial export of this element?
+    def already_partial_export_ended?
+      (@already_partial_export_ended ||= false)
+    end
+
     # Export this element into a file. Will also start to export the parents of
     # the element. It's equivalent to calling start_partial_export followed by
     # end_partial_export.
@@ -505,7 +540,7 @@ module XMLCodec
         
         file << create_open_tag
         if self.hasvalue?
-          file << XMLUtils::escape_xml(self.value)
+          file << XMLCodec::XMLUtils::escape_xml(self.value)
         end
         
         each_subelement do |e|