axml 0.0.4 → 0.0.5

data/README

@@ -1,53 +1,50 @@
-AXML
-====
+= {AXML}[http://axml.rubyforge.org]
 
 AXML - Provides a simple, minimalistic DOM for working with data stored in an
 XML document.  The API is very similar to LibXML, differing slightly in the
-handling of text nodes.  It is designed with very large documents in mind: nodes are represented in memory efficient Struct objects and it works with either XMLParser or LibXML!
+handling of text nodes.  It is designed with very large documents in mind:
+nodes are represented in memory efficient Struct objects and it works with
+either XMLParser or LibXML!
 
 'AXML' literally translates into 'ax XML' which succinctly describes the
 occasional feeling of a programmer towards XML or its myriad parsers.  AXML
 won't solve all your XML woes, but it does make working with XML much less
 painful.
 
-Features
---------
+== Overview
 
 * *fast*: runs on either XMLParser or LibXML
-* *lean*: as in 'lines of code' and as in 'memory consumption' (nodes implemented as Struct, children in Array)
-* *easy to extend*: code your Grandmother could read and understand (if she reads ruby)
-* PLOS: implements a useful subset of libxml methods for near drop in replacement.
+* *lean*: as in 'lines of code' and as in 'memory consumption'
 
-Examples
---------
+== Examples
 
     require 'axml'  
 
     # a little example xml string to use
-    string_or_io = "
+    string = "
     <n1>
       <n2 size='big'>
         <n3>words here</n3>
         <n3></n3>
       </n2>
-      <n2 size='small'>
-        <n3 id='3'></n3>
+      <n2 size='small' >
+        <n3 id='3' thinks='out loud'></n3>
       </n2>
     </n1>
     "
 
-### Read a string, io, or file
+=== Read a string, io, or file
 
-    n1_node = AXML.parse(string_or_io)   
-    # --or--
-    n1_node = AXML.parse('path/to/file')   
+    n1_node = AXML.parse(string)          # <- can read xml as string
+    n1_node = AXML.parse(io)              # <- can read an io object
+    n1_node = AXML.parse('path/to/file')  # <- can read a file 
 
-### Access children
+=== Access children
 
     n1_node.children # -> [array]
     n1_node.each {|child|  # do something with each child }
 
-### Traverse the whole tree structure
+=== Traverse the whole tree structure
 
     n1_node.traverse do |node|
       # pre traversal
@@ -55,20 +52,20 @@ Examples
 
     n1_node.traverse(:post) {|node| # post traversal }
 
-### Get attributes and text
+=== Get attributes and text
 
     n2_node['size'] == 'big'
     n3_node = n2_node.child
     n3_node.text    # -> 'words here'
-    n3_node.content # -> [same]
+    n3_node.content # -> 'words here'
 
-### Navigate nodes
+=== Navigate nodes
 
     n2_node = n1_node.child
     the_other_n2_node = n2_node.next
     the_other_n2_node.next = nil
 
-### Does a little xpath
+=== Does a little xpath
 
     # find_first (returns the first node)
     n3_node = n1_node.find_first('descendant::n3')
@@ -81,25 +78,49 @@ Examples
     n1_node.find('descendant::n3')     # -> [array of all 3 <n3> nodes]
     # also callable as find_child and find_descendant
 
+=== Manipulate tree structure
 
-See `specs/axml_spec.rb` for more examples and functionality
+    node.drop  # drop the node from its parents
+    ## (insert?)
 
-Detailed Description
---------------------
+=== Output
 
-Parses elements, attributes, and text(content), and nothing more.  Should be
-very easy to extend and modify for special cases.  It is roughly as fast as
-libxml, although it currently reads in the entire document first (however,
-this is memory efficient - nodes are implemented using Struct).
+XML Output is currently tested only with XMLParser.
 
-Installation
-------------
+    node.to_s             # -> formatted xml
+    node.to_doc           # -> with xml header line
+    node.to_doc(filename) # -> written to filename
+
+See `spec/` dir for more examples and functionality
+
+== Details
+
+If using XMLParser, builds nodes out of Struct objects (AXML::El).  Currently
+only parses elements, attributes, and text(content) (no CDATA right now).
+
+If using LibXML, it uses the underlying LibXML nodes already available.  It
+overrides some methods to treat the text in a text node as the parent node's
+text attribute.
+
+== Warnings
+
+Output of xml (i.e., node#to_s) under LibXML is untested (and probably buggy)
+since the node text behavor has been modified.  Will work it out in future
+release.
+
+Doesn't parse CDATA using XMLParser right now.
+
+== Installation
 
     gem install axml
 
-See Also
---------
+Can get instructions on installing XMLParser and LibXML by issuing this command:
+
+     ruby -rubygems -e 'require "axml"; puts AXML::Autoload.install_instructions(:all)'
+
+== See Also
 
-If you are parsing HTML or complex word processing documents this is not the parser for you.  Try something like hpricot or LibXML.
+If you are parsing HTML or complex word processing documents this is not the
+parser for you.  Try something like hpricot or LibXML.
 
 

data/Rakefile

@@ -17,10 +17,11 @@ FU = FileUtils
 
 readme = "README"
 
+rdoc_dir = 'rdoc'
 rdoc_extra_includes = [readme, "LICENSE"]
-rdoc_options = ['--main', readme, '--title', NAME]
+rdoc_options = ['--main', readme, '--title', NAME, '--line-numbers', '--inline-source']
 
-lib_files = FL["lib/**/*"]
+lib_files = FL["lib/**/*.rb"]
 dist_files = lib_files + FL[readme, "LICENSE", "Rakefile", "{specs}/**/*"]
 changelog = 'CHANGELOG'
 
@@ -40,37 +41,22 @@ end
 # DOC
 ###############################################
 Rake::RDocTask.new do |rd|
+  rd.rdoc_dir = rdoc_dir
   rd.main = readme
-  rd.rdoc_files.include rdoc_extra_includes
+  rd.rdoc_files.include( rdoc_extra_includes )
+  rd.rdoc_files.include( lib_files.uniq )
   rd.options.push( *rdoc_options )
-end
-
-task :html_docs do
-  css = 'doc/src/style.css'
-  FU.mkpath 'doc/output'
-  FU.cp css, 'doc/output/'
-  index = 'doc/output/index.html'
-  header = 'doc/src/header'
-  File.open(index, 'w') do |index|
-    index.puts '<html>'
-    index.puts IO.read(header)
-    index.puts '<html><body>'
-    index.puts `bluecloth --fragment #{readme}`
-
-    # add contact info:
-    index.puts '<h2>Contact</h2>'
-    index.puts 'jtprince@gmail.com'.email_encrypt
-
-    index.puts '</body></html>'
-  end
+  cmd = "rdoc -o #{rdoc_dir} #{(lib_files + rdoc_extra_includes).join(" ")} #{rdoc_options.join(" ")}"
+  puts cmd
 end
 
 desc "create and upload docs to server"
-task :upload_docs => :html_docs do
-  sh "scp -i ~/.ssh/rubyforge_key -r doc/output/* jtprince@rubyforge.org:/var/www/gforge-projects/axml/"
+task :upload_docs => [:rdoc] do
+  sh "scp -r #{rdoc_dir}/* jtprince@rubyforge.org:/var/www/gforge-projects/axml/"
 end
 
 
+
 ###############################################
 # TESTS
 ###############################################

data/lib/axml.rb

@@ -10,30 +10,53 @@ module AXML
   WARN = {:rexml => "Using REXML as parser!  This is very slow on large docs!\nCall the method AXML::Autoload.install_instructions for help installing\nsomething FASTER!",
   }
 
+  # returns the root node
   # opts:
-  #   :parser = 
+  #   :parser => :xmlparser || :libxml
+  #   :keep_blanks => false
+  #
+  # arg may be a string of xml, an io object, or a filename
+  # if the first non-blank character of the string is '<' then it is
+  # considered xml.  If you want to be sure, you can use parse_file or
+  # parse_string.
+  # Gets the parser with AXML::Autoload.parser!  Will set the default parser
+  # to the first one found unless a parser is provided.
   def parse(arg, opts={})
     opts = DEFAULTS.merge opts
     parser = AXML::Autoload.parser!(opts[:parser])
     method = 
-      if arg.is_a?(String) && File.exist?(arg)
-        :parse_file
+      if arg.is_a?(String)
+        if xml?(arg)
+          :parse_string
+        else
+          unless File.exist? arg
+            messg = "thinking this is a file: #{arg}\nbut file doesn't exist!"
+            raise RuntimeError, messg 
+          end
+          :parse_file
+        end
       elsif arg.is_a?(IO)
         :parse_io
-      elsif arg.is_a?(String)
-        :parse_string
       else
         raise ArgumentError, "can deal with filenames, Strings, and IO objects.\nDon't know how to work with object of class: #{arg.class}"
       end
     parser.send(method, arg, opts)
   end
 
+  # Returns the root node.
+  # Opens the filename given and calls parse_io on it
   def parse_file(file, opts={}) # :nodoc:
     opts = DEFAULTS.merge opts
     parser = AXML::Autoload.parser!(opts[:parser])
     File.open(file) {|fh| parser.parse_io(fh, opts) }
   end
 
+  # returns true if the first nonblank char is a '<'
+  def xml?(string)
+    first_real_char = string.match(/[^\s]/m)
+    !first_real_char.nil? && first_real_char[0] == '<'
+  end
+
   extend AXML
 
 end

data/lib/axml/autoload.rb

@@ -3,80 +3,79 @@ require 'axml'
 
 module AXML
   module Autoload
-    class << self
-      # if given a name, loads the parser class name if no arg (or nil) tries
-      # to load a parser from the AXML::PREFERRED list, returning the first
-      # one that works.  Sets AXML::DEFAULT[:parser] with the parser name if
-      # it is available and raises any warnings in AXML::WARN.  Raises a
-      # RuntimeError if no parser is found.
-      def parser!(name=nil)
-        parser_name_to_use = nil
-        parser_obj = nil
-        if name.nil?
-          PREFERRED.each do |nm|
-            parser_obj = load(nm)
-            if parser_obj 
-              parser_name_to_use = nm
-              break
-            end
+    # if given a name, loads the parser class name if no arg (or nil) tries
+    # to load a parser from the AXML::PREFERRED list, returning the first
+    # one that works.  Sets AXML::DEFAULT[:parser] with the parser name if
+    # it is available and raises any warnings in AXML::WARN.  Raises a
+    # RuntimeError if no parser is found.
+    def self.parser!(name=nil)
+      parser_name_to_use = nil
+      parser_obj = nil
+      if name.nil?
+        PREFERRED.each do |nm|
+          parser_obj = parser(nm)
+          if parser_obj 
+            parser_name_to_use = nm
+            break
           end
-        else
-          parser_name_to_use = name
-          parser_obj = parser(name)
-        end
-        if message = WARN[parser_obj]
-          warn message
-        end
-        if parser_obj
-          AXML::DEFAULTS[:parser] = parser_name_to_use
-        else
-          STDERR.puts "NO PARSERS CURRENTLY AVAILABLE!"
-          STDERR.puts "INSTALL INSTRUCTIONS:"
-          STDERR.puts "*****************************************************"
-          STDERR.puts install_instructions(:all)
-          STDERR.puts "*****************************************************"
-          raise RuntimeError, "no parser currently available!"
         end
-        parser_obj
+      else
+        parser_name_to_use = name
+        parser_obj = parser(name)
       end
+      if message = WARN[parser_obj]
+        warn message
+      end
+      if parser_obj
+        AXML::DEFAULTS[:parser] = parser_name_to_use
+      else
+        STDERR.puts "NO PARSERS CURRENTLY AVAILABLE!"
+        STDERR.puts "INSTALL INSTRUCTIONS:"
+        STDERR.puts "*****************************************************"
+        STDERR.puts install_instructions(:all)
+        STDERR.puts "*****************************************************"
+        raise RuntimeError, "no parser currently available!"
+      end
+      parser_obj
+    end
 
-      # loads the parser (if available) and returns an object ( that should
-      # respond_to parse_io and parse_string. If the parser is not available
-      # returns nil.
-      def parser(name)
-        req = 'axml/' << name.to_s.gsub('_', '/')
-        begin
-          require req
-          const_str = AXML::CLASS_MAPPINGS[name]
-          if AXML.const_defined?(const_str)
-            AXML.const_get(const_str)
-          else
-            nil
-          end
-        rescue LoadError
+    # loads the parser (if available) and returns an object ( that should
+    # respond_to parse_io and parse_string. If the parser is not available
+    # returns nil.
+    def self.parser(name)
+      req = 'axml/' << name.to_s.gsub('_', '/')
+      begin
+        require req
+        const_str = AXML::CLASS_MAPPINGS[name]
+        if AXML.const_defined?(const_str)
+          AXML.const_get(const_str)
+        else
           nil
         end
+      rescue LoadError
+        nil
       end
+    end
 
-      def install_instructions(name)
-        if name == :all
-          doublets = AXML::PREFERRED.map do |nm|
-            [nm, install_instructions(nm)]
-          end
-          string = ""
-          doublets.each do |k,v|
-            if v
-              string << '-' * k.to_s.size << "\n"
-              string << "#{k}\n"
-              string << '-' * k.to_s.size << "\n"
-              string << "#{v}"
-            end
+    def self.install_instructions(name)
+      if name == :all
+        doublets = AXML::PREFERRED.map do |nm|
+          [nm, install_instructions(nm)]
+        end
+        string = ""
+        doublets.each do |k,v|
+          if v
+            string << '-' * k.to_s.size << "\n"
+            string << "#{k}\n"
+            string << '-' * k.to_s.size << "\n"
+            string << "#{v}"
           end
-          string
-        else
-          case name
-          when :xmlparser
-            string = <<END
+        end
+        string
+      else
+        case name
+        when :xmlparser
+          string = <<END
 debian/ubuntu: sudo apt-get install libxml-parser-ruby1.8
 
 cygwin:
@@ -89,8 +88,8 @@ cygwin:
 
 windows: included in one-click-installer
 END
-          when :libxml
-            string = <<END 
+        when :libxml
+          string = <<END 
 deb/ubuntu: sudo apt-get install libxml-ruby
 
 install as gem:
@@ -98,7 +97,6 @@ install as gem:
 
 for more info: http://libxml.rubyforge.org/install.xml
 END
-          end
         end
       end
     end

data/lib/axml/el.rb

@@ -84,7 +84,22 @@ class AXML::El
     result
   end
 
+  # returns the xml string with the xml header in place
+  # if given a filename, writes it to the file
+  def to_doc(filename=nil)
+    output = '<?xml version="1.0" encoding="UTF-8"?>'
+    output << self.to_s
+    if filename
+      File.open(filename, 'w') do |out|
+        out.print output
+      end
+    end
+  end
+
   def to_s(indent=0)
+    if indent.is_a? Hash
+      to_doc
+    end
     attstring = ""
     if attrs.size > 0
       attstring = " " + attrs.collect { |k,v| "#{k}=\"#{escape(v)}\"" }.join(" ")

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification 
 name: axml
 version: !ruby/object:Gem::Version 
-  version: 0.0.4
+  version: 0.0.5
 platform: ruby
 authors: 
 - John Prince
@@ -23,7 +23,6 @@ extra_rdoc_files:
 - README
 - LICENSE
 files: 
-- lib/axml
 - lib/axml/el.rb
 - lib/axml/autoload.rb
 - lib/axml/libxml.rb
@@ -41,6 +40,8 @@ rdoc_options:
 - README
 - --title
 - axml
+- --line-numbers
+- --inline-source
 require_paths: 
 - lib
 required_ruby_version: !ruby/object:Gem::Requirement