scxml 0.1.0

data/lib/scxml.rb

@@ -0,0 +1,86 @@
+require 'scxml/xpath'
+require 'scxml/document'
+require 'scxml/element'
+require 'strscan'
+
+# = SCXML 
+# Fast, lightweight access to simple xml data.
+#
+# == Introduction
+# REXML is a standard, pure-Ruby XML processing library.  It comes in the standard library and
+# as far as I can tell is quite complete.  It also is painfully slow when loading large XML documents
+# and produces enormous memory footprints.
+#
+# SCanningXML parses XML using a scanning approach that works very quickly and with a small memory
+# footprint.  SCXML can run in a lightweight mode that minimizes memory at the expense of access
+# time.
+#
+# Currently SCXML does not support insertion/removal of elements, although it may in the future.  
+# SCXML does allow elements to be re-written with new attributes and content.  For making XML
+# documents, I generally use the Builder[http://builder.rubyforge.com] gem.
+#
+# Elements can be accessed using XPath.  Currently XPath support is incomplete, as well as the type
+# of elements and content that can be parsed.  See the limitations section below.
+# 
+# Copyright (c) 2007 Simon Chiang
+# Version:	0.1
+# Licence:	MIT-Style
+#
+# == Usage
+#
+#   require 'scxml'
+#
+#    xml_string = %Q{
+#    <?xml version="1.0" encoding="UTF-8"?>
+#    <root>
+#     <elements>
+#       <element id="0">a</element>
+#       <element id="1">b</element>
+#       <element id="2">c</element>
+#     </elements>
+#    </root> }
+#
+#   # create a new xml document
+#   doc = SCXML::Document.new(xml_string)
+#
+#   # select all elements
+#   elements = doc.select('/root/elements/element')
+#
+#   # select element id = 1
+#   e = doc.select('/root/elements/element[@id='1']')		
+#   e.name					# -> 'element'
+#   e.attribute('key') 			# -> '1'
+#   e.atttributes				# -> {'id' => '1'}
+#   e.content					# -> 'a'
+#   e.rewrite(:attributes => {'id' => '10', 'new' => 'attr'}, :content => 'content')	# -> <element id='10' new='attr'>content</element>
+#
+#   # element creation sets the element to the first parsed node
+#   r = SCXML::Element.new(xml_string)
+#   r.name 					# -> 'root'
+#
+#   # elements select relative to themselves
+#   e = r.select('elements')
+#   e.name 					# -> 'elements'
+#   elements = e.select('element')
+#   elements.length				# -> 3
+#   elements.first.attribute('key')		# -> '1'
+#
+# == Limitations
+# SCXML does not support all types of xml nodes. At the moment only simple xml documents will be 
+# correctly parsed by SCXML.  The 'Usage' example is about SCXML can handle: elements with children 
+# or content, as well as attributes.
+#
+# Supported XPath expressions are likewise limited to simple paths and predicates:
+#
+#   doc.select('/')				# -> selects the document
+#   doc.select('/root')			# -> selects the root element
+#   e = doc.select('/root/elements')	# -> selects the elements node
+#   e.select('*')				# -> selects all children of the elements node
+#   e.select('element')			# -> selects all children of the elements node named element
+#   doc.select('//element')			# -> selects all element nodes wherever they occur
+#   doc.select('//element[@id='1']')	# -> selects all element nodes with attribute id='1' wherever they occur
+#
+# See the tests for specific expression support.
+#
+module SCXML    
+end

data/lib/scxml/document.rb

@@ -0,0 +1,165 @@
+
+module SCXML
+
+  # SCXML Documents keep one central instance of an XML string.  All elements
+  # in a document are tracked using ranges.  For example:
+  #
+  #   <?xml version="1.0"?> 
+  #   <doc>
+  #     <a>1</a>
+  #   </doc>
+  #
+  # Is tracked as:
+  #   doc.string_range = 0...45
+  #   doc.string = "<?xml version="1.0"?>\n<doc>\n  <a>1</a>\n</doc>"
+  #   doc.content_range = 24...45
+  #   doc.content = "<doc>\n  <a>1</a>\n</doc>"
+  #
+  #   a.string_range = 30...-7 
+  #   a.string = "<a>1</a>"
+  #   a.content_range = 3...-4
+  #   a.content = "1"
+  #
+  # In lightweight mode, the string and content of elements is not stored internally but rather 
+  # computed from the ranges and extracted from document.  Access is therefore slower, but 
+  # the memory footprint significantly less, especially in large documents.  Content for the document
+  # is always computed, and never stored internally.
+  #
+  # Attributes are parsed into a hash on their first access.  In lightweight mode, the hash is not 
+  # stored internally.  These attribute hashes account for most of the access/footprint difference.
+  #
+  # Note that ranges are exclusive of the last indexed character (ie '...' is used in the range rather than '..'),
+  # and that range end will ONLY be positive if the range extends to the end of the document.   
+  #
+  # String ranges encompass the entire tag and are relative to the full document.  Content ranges are relative 
+  # to the string range, and indicate all content within the tag.  Ergo:
+  #    doc.string == doc.string
+  #    doc.content == doc.string[doc.content_range]
+  #    a.string == doc.string[a.string_range]
+  #    a.content == a.string[a.content_range]
+  class Document
+	include XPath
+	
+	attr_reader :root, :scanner
+	
+	# Creates a new Document from the input string.  Options:
+	#
+	# +lightweight+:: In lightweight mode the string, content, and attributes of elements is recalculated on
+	#                       every access.  This results in slower access, but a much smaller memory footprint.  default => true
+	def initialize(string, options={})
+		@options = {:lightweight => true, :remove_whitespace => false}.merge(options)
+		
+		@string = options[:remove_whitespace] ? string.gsub(/\s*\r?\n\s*/, '') : string
+		
+		@scanner = StringScanner.new(@string)
+		s, range = scan_node(@scanner)	
+		range = range.nil? ? 0...@string.length : range.begin...(range.end == 0 ? @string.length : range.end)
+
+		@content_range = range
+		@root = Element.new(self, range, s)
+	end	
+	
+	# Returns true if the document is set to lightweight mode.
+	def lightweight?
+		@options[:lightweight]
+	end
+	
+	# The full range of the document (ie 0...length)
+	def string_range
+		0...string.length
+	end
+	
+	# The range from the beginning of the first element tag to the end of the corresponding end tag.
+	def content_range
+		@content_range #||= string_range
+	end
+	
+	# Select elements using XPath statements.  Not all statements are supported.  See the introduction
+	# or tests for allowed statements.
+	def select(xpath)
+		return [] if xpath.nil?
+		return [self] if xpath == '/'
+	
+		paths = xpath.scan(/\/*[^\/]+/)
+		select_by_paths(paths)
+	end
+	
+	# Returns an array of all node names present in the document.
+	def node_names
+		return @nodes if @nodes
+		
+		nodes = string.scan(/<(\w+)/m).flatten.uniq
+		@nodes = nodes unless lightweight?
+		nodes
+	end
+	
+	# Returns a table of element contents as configured.  Options:
+	#
+	# +target+:: 	Specify the output target of the tableize operation.  By default a string, but any object
+	#                	responding to '<<' can be provided.  The target is returned by +tableize+
+	# +row+::	The xpath expression used to select rows of the table.  default => '*'
+	# +col+::	The xpath expression used to select columns relative to the row elements.  default => '*'
+	# +header_row+::	These should currently select the header row and cols, but should be replaced in favor
+	#                            of a more intutive interface
+	# +header_col+::	
+	# +row_delimit+::	The row delimiter.  default => '\n'
+	# +col_delimit+::	The column delimiter.  default => '\t'
+	# +index+::		If true, the output rows will be prefixed by an index corresponding to the row.
+	# +col_width+::	Specifies the width of the columns.  Content will be trimmed if it exceeds this width,
+	#   			and will be justified left if width > 0 and justified right if width < 0.
+	#
+	# Selected elements are passed to the block.  The content for each table cell will be the return 
+	# value of the block, or the element contents if no block is given.
+	def tableize(options={}, &block)
+		options = {
+			:target => "",
+			:row_delimit => "\n",
+			:col_delimit => "\t",
+			:row => "*",
+			:col => "*",
+			:header_row => nil,
+			:header_col => "*",
+			:index => false,
+			:col_width => nil
+		}.merge(options)
+
+		target = options[:target]
+		col_delimit = options[:col_delimit]
+		row_delimit = options[:row_delimit]
+		index = options[:index]
+		col_width = options[:col_width]
+		
+		['header_', ''].each do |prefix|
+			row_xpath = options[ "#{prefix}row".to_sym ]
+			col_xpath = options[ "#{prefix}col".to_sym ]
+			
+			rows = select(row_xpath)
+			rows.each_index do |i|
+				row = rows[i]
+				cols = row.select(col_xpath)
+				cols = block_given? ? 
+					yield(row, cols) : 
+					cols.collect {|col| col.content}
+				
+				cols.unshift i if index
+				unless col_width.nil?
+					cols = cols.collect do |c| 
+						col_width < 0 ? c.to_s.rjust(-col_width) : c.to_s.ljust(col_width) 
+					end 
+				end
+				
+				target << cols.join(col_delimit)
+				target << row_delimit
+			end
+		end
+		
+		target
+	end
+	
+	protected
+	
+	def children
+		[root]
+	end
+  end
+end

data/lib/scxml/element.rb

@@ -0,0 +1,219 @@
+
+module SCXML
+  class Element
+	class << self
+		def new(*args)
+			obj = super
+			(obj.string_range == obj.doc.content_range && !obj.doc.root.nil?)  ? obj.doc.root : obj
+		end
+	end
+	
+	include XPath
+	
+	attr_reader :doc, :name, :parent
+	
+	def initialize(arg, range=nil, string=nil)
+		case arg
+		when String
+			@doc = Document.new(arg)
+			@string_range = @doc.content_range			
+		when Document
+			@doc = arg
+			@string_range = arg.content_range				
+		when Element
+			@parent = arg
+			@doc = arg.doc
+			@string_range = join_range(arg.string_range, range)
+		else
+			raise ArgumentError, "Cannot initialize using: #{arg.class}"
+		end
+		
+		@string = string unless doc.lightweight?
+		@name, @content_range = parse(self.string)
+	end
+	
+	def string
+		if doc.lightweight?
+			doc.string[string_range]
+		else
+			@string ||= doc.string[string_range]
+		end
+	end
+	
+	def string_range
+		@string_range ||= doc.content_range
+	end
+	
+	def content(objectify=false)
+		content_str = doc.lightweight? ? super() : (@content_str ||= super())
+		return content_str unless objectify
+		
+		stripped = content_str.strip
+		
+		case stripped
+		when /^\d+$/ then stripped.to_i
+		when /^\d*\.?\d+$/ then stripped.to_f
+		when /^true$/i then true
+		when /^false$/i then false
+		else
+			content_str
+		end
+	end
+	
+	def attribute(key)
+		return @attributes[key] unless @attributes.nil?
+		
+		attr_range_begin = string_range.begin + name.length + 1
+		attr_range_end = string_range.begin + content_range.begin - 1
+		
+		scanner = doc.scanner
+		scanner.pos = attr_range_begin
+		scanner.skip_until(Regexp.new("#{key}="))
+		
+		return nil if scanner.pos > attr_range_end
+		
+		result = scanner.scan(/'[^']*'|\"[^\"]*\"/)
+		result ? result[1...-1] : nil
+		
+		#attr_range = (string_range.begin + name.length + 1)...(string_range.begin + content_range.begin - 1)
+		#doc.string[attr_range] =~ Regexp.new("#{key}=('[^']*'|\"[^\"]*\")", Regexp::MULTILINE)
+		
+		#$1 ? $1[1...-1] : nil
+	end
+ 	
+	def attributes
+		return @attributes unless @attributes.nil?
+		
+		attrs = {}
+		
+		# indexing and selection is vs the doc.string rather than element.string
+		# because in lightweight mode this will require an additional string selection 
+		# to get element.string.  Better to go straight to the source
+		attr_range = (string_range.begin + name.length + 1)...(string_range.begin + content_range.begin - 1)
+		doc.string[attr_range].scan(/(\w+)=('[^']*'|\"[^\"]*\")/m).each do |attr|
+			key, value = attr
+			attrs[key] = value[1...-1]
+		end
+			
+		@attributes = attrs unless doc.lightweight?
+		attrs
+	end
+	
+	def children
+		unless @children
+			@children = []
+
+			scanner = StringScanner.new(content)
+			while node = content_node(scanner)
+				@children << node
+			end	
+		end
+		
+		@children
+	end
+	
+	def select(xpath)
+		return [] if xpath.nil?
+		
+		if xpath =~ /^\//
+			doc.select(xpath)
+		else
+			paths = xpath.scan(/\/*[^\/]+/)
+			select_by_paths(paths)
+		end
+	end
+	
+	def hashify(xpath='*', &block)
+		hash = {}
+		select(xpath).each do |element|
+			key = block_given? ? yield(element) : element.name
+			hash[key] = element.content
+		end
+		hash
+	end
+	
+	def to_s
+		string
+	end
+	
+	def rewrite(options={})
+		n = options[:indent] || 0
+		
+		attributes = options[:attributes] || self.attributes
+		attributes.merge!(options[:merge_attributes]) if options[:merge_attributes]
+			
+		content = options[:content] || self.content
+		content += options[:add_content] if options[:add_content]
+		
+		attr_string = attributes_to_s(attributes)
+		attr_string.insert(0, ' ') unless attr_string.strip.empty? 
+		
+		if content.empty?
+			closed = (string[-2..-1] == '/>')
+			closed ?
+				"#{indentation(n)}<#{name}#{attr_string}/>" :
+				"#{indentation(n)}<#{name}#{attr_string}></#{name}>"
+		else
+			content_str = reindent(content, n)
+			content_str = "#{content_str}#{indentation(n, true)}" unless content_str.strip.empty? || content_str == content
+			
+			"#{indentation(n)}<#{name}#{attr_string}>#{content_str}</#{name}>"
+		end
+	end
+	
+	protected
+
+	def attributes_to_s(attributes)
+		array = []
+		attributes.each_pair do |key, value|
+			array << "#{key}='#{value}'"
+		end
+		array.join(' ')
+	end
+	
+	def indentation(n, newline=false)
+		%Q{#{newline ? "\n" : '' }#{' ' * n}}
+	end
+	
+	def reindent(string, n)
+		scanner = StringScanner.new(string.strip)
+		output = []
+		while tag = scanner.scan_until(/>/)
+			closed_tag = (tag[-2..-1] == '/>')
+			end_tag = (closed_tag || tag.index('/'))
+			
+			n += 2 if closed_tag || !end_tag
+			output << "#{indentation(n, true)}#{tag.strip}"
+			n -= 2 if closed_tag || end_tag
+			
+			# checks to see if a tag end occurs before the next newline
+			# ie '<a>\n  <b>some content</b>\n<a>
+			# and assures that this content is NOT reindented
+			if scanner.check(/[^\n<]*<\//)
+				output << scanner.scan_until(/>/)
+				n -= 2
+			end
+		end
+		
+		# if no tags are present, simply return the input
+		output << string if output.empty?
+		
+		output.join('')
+	end
+	
+	def parse(str)
+		scanner = StringScanner.new(str)
+	
+		scanner.scan_until(/<(\w+)[^>]*>/m)
+		start = scanner.pos
+		name = scanner[1]
+		
+		end_tag = "</#{name}>"
+		scanner.skip_until(Regexp.new(end_tag, Regexp::MULTILINE))
+		finish = -scanner.restsize - end_tag.length
+	
+		content_range = start...(finish) 
+		[name, content_range]
+	end
+  end
+end