ruby-ole 1.2.1 → 1.2.2

data/lib/ole/property_set.rb

@@ -0,0 +1,85 @@
+
+module Ole
+	module Types
+		# should have a list of the VT_* variant types, and have all the serialization related code
+		# here... implement dump & load functions like marshalling
+		class Guid
+			SIZE = 16
+
+			def self.load str
+				Types.load_guid str
+			end
+		end
+
+		# see http://poi.apache.org/hpsf/internals.html
+		class PropertySet
+			HEADER_SIZE = 28
+			HEADER_UNPACK = "vvVa#{Guid::SIZE}V"
+			OS_MAP = {
+				0 => :win16,
+				1 => :mac,
+				2 => :win32
+			}
+
+			class Section < Struct.new(:guid, :offset)
+				include Enumerable
+
+				SIZE = Guid::SIZE + 4
+				UNPACK_STR = "a#{Guid::SIZE}v"
+
+				attr_reader :length
+				def initialize str, property_set
+					@property_set = property_set
+					super(*str.unpack(UNPACK_STR))
+					self.guid = Guid.load guid
+					load_header
+				end
+
+				def io
+					@property_set.io
+				end
+
+				def load_header
+					io.seek offset
+					@byte_size, @length = io.read(8).unpack 'V2'
+				end
+
+				def each
+					io.seek offset + 8
+					io.read(length * 8).scan(/.{8}/m).each do |str|
+						id, property_offset = str.unpack 'V2'
+						io.seek offset + property_offset
+						type = io.read(4).unpack('V')[0]
+						yield id, type, io.read(10)
+					end
+					self
+				end
+
+				def properties
+					to_a
+				end
+			end
+
+			attr_reader :io, :signature, :unknown, :os, :guid, :sections
+			def initialize io
+				@io = io
+				load_header io.read(HEADER_SIZE)
+				load_section_list io.read(@num_sections * Section::SIZE)
+				# expect no gap between last section and start of data.
+				Log.warn "gap between section list and property data" unless io.pos == @sections.map(&:offset).min
+			end
+
+			def load_header str
+				@signature, @unknown, @os_id, @guid, @num_sections = str.unpack HEADER_UNPACK
+				# should i check that unknown == 0? it usually is. so is the guid actually
+				@guid = Guid.load @guid
+				@os = OS_MAP[@os_id] || Log.warn("unknown operating system id #{@os_id}")
+			end
+
+			def load_section_list str
+				@sections = str.scan(/.{#{Section::SIZE}}/m).map { |str| Section.new str, self }
+			end
+		end
+	end
+end
+

data/lib/ole/{io_helpers.rb → ranges_io.rb}

@@ -1,12 +1,35 @@
-
-# move to support?
-class IO # :nodoc:
-	def self.copy src, dst
-		until src.eof?
-			buf = src.read(4096)
-			dst.write buf
+class IOModeString
+	def initialize mode='r'
+		@mode = mode
+		if @mode['b']
+			@binary = true
+			@mode = @mode.sub 'b', ''
+		else
+			@binary = false
+		end
+		if @mode[/\+$/]
+			@plus = true
+			@mode = @mode.sub(/\+$/, '')
+		else
+			@plus = false
 		end
 	end
+
+	def explicit_binary?
+		@binary
+	end
+
+	def binary?
+		RUBY_PLATFORM !~ /win/ or @binary
+	end
+
+	def to_s
+		@mode
+	end
+
+	def inspect
+		"#<#{self.class}:#{to_s.inspect}>"
+	end
 end
 
 #
@@ -49,13 +72,14 @@ end
 # 
 class RangesIO
 	attr_reader :io, :ranges, :size, :pos
-	# +io+ is the parent io object that we are wrapping.
+	# +io+:: the parent io object that we are wrapping.
 	# 
-	# +ranges+ are byte offsets, either
+	# +ranges+:: byte offsets, either:
 	# 1. an array of ranges [1..2, 4..5, 6..8] or
 	# 2. an array of arrays, where the second is length [[1, 1], [4, 1], [6, 2]] for the above
 	#    (think the way String indexing works)
-	# The +ranges+ provide sequential slices of the file that will be read. they can overlap.
+	#
+	# NOTE: the +ranges+ can overlap.
 	def initialize io, ranges, opts={}
 		@opts = {:close_parent => false}.merge opts
 		@io = io
@@ -67,10 +91,28 @@ class RangesIO
 		@pos = 0
 	end
 
+	# add block form. TODO add test for this
+	def self.open(*args, &block)
+		ranges_io = new(*args)
+		if block_given?
+			begin;  yield ranges_io
+			ensure; ranges_io.close
+			end
+		else
+			ranges_io
+		end
+	end
+
 	def pos= pos, whence=IO::SEEK_SET
-		# FIXME support other whence values
-		raise NotImplementedError, "#{whence.inspect} not supported" unless whence == IO::SEEK_SET
-		# just a simple pos calculation. invalidate buffers if we had them
+		case whence
+		when IO::SEEK_SET
+		when IO::SEEK_CUR
+			pos += @pos
+		when IO::SEEK_END
+			pos = @size + pos
+		else raise Errno::EINVAL
+		end
+		raise Errno::EINVAL unless (0...@size) === pos
 		@pos = pos
 	end
 
@@ -81,19 +123,19 @@ class RangesIO
 		@io.close if @opts[:close_parent]
 	end
 
-	def range_and_offset pos
-		off = nil
-		r = ranges.inject(0) do |total, r|
-			to = total + r[1]
-			if pos <= to
-				off = pos - total
-				break r
+	# returns the [+offset+, +size+], pair inorder to read/write at +pos+
+	# (like a partial range), and its index.
+	def offset_and_size pos
+		total = 0
+		ranges.each_with_index do |(offset, size), i|
+			if pos <= total + size
+				diff = pos - total
+				return [offset + diff, size - diff], i
 			end
-			to
+			total += size
 		end
 		# should be impossible for any valid pos, (0...size) === pos
-		raise "unable to find range for pos #{pos.inspect}" unless off
-		[r, off]
+		raise ArgumentError, "no range for pos #{pos.inspect}"
 	end
 
 	def eof?
@@ -103,26 +145,25 @@ class RangesIO
 	# read bytes from file, to a maximum of +limit+, or all available if unspecified.
 	def read limit=nil
 		data = ''
-		limit ||= size
-		# special case eof
 		return data if eof?
-		r, off = range_and_offset @pos
-		i = ranges.index r
+		limit ||= size
+		partial_range, i = offset_and_size @pos
 		# this may be conceptually nice (create sub-range starting where we are), but
 		# for a large range array its pretty wasteful. even the previous way was. but
 		# i'm not trying to optimize this atm. it may even go to c later if necessary.
-		([[r[0] + off, r[1] - off]] + ranges[i+1..-1]).each do |pos, len|
+		([partial_range] + ranges[i+1..-1]).each do |pos, len|
 			@io.seek pos
 			if limit < len
-				# FIXME this += isn't correct if there is a read error
-				# or something.
-				@pos += limit
-				break data << @io.read(limit) 
+				# convoluted, to handle read errors. s may be nil
+				s = @io.read limit
+				@pos += s.length if s
+				break data << s
 			end
-			# this can also stuff up. if the ranges are beyond the size of the file, we can get
-			# nil here.
-			data << @io.read(len)
-			@pos += len
+			# convoluted, to handle ranges beyond the size of the file
+			s = @io.read len
+			@pos += s.length if s
+			data << s
+			break if s.length != len
 			limit -= len
 		end
 		data
@@ -133,12 +174,16 @@ class RangesIO
 	def truncate size
 		raise NotImplementedError, 'truncate not supported'
 	end
-	# why not? :)
-	alias size= :truncate
+
+	# using explicit forward instead of an alias now for overriding.
+	# should override truncate.
+	def size=	size
+		truncate size
+	end
 
 	def write data
 		# short cut. needed because truncate 0 may return no ranges, instead of empty range,
-		# thus range_and_offset fails.
+		# thus offset_and_size fails.
 		return 0 if data.empty?
 		data_pos = 0
 		# if we don't have room, we can use the truncate hook to make more space.
@@ -146,13 +191,11 @@ class RangesIO
 			begin
 				truncate @pos + data.length
 			rescue NotImplementedError
-				# FIXME maybe warn instead, then just truncate the data?
-				raise "unable to satisfy write of #{data.length} bytes" 
+				raise IOError, "unable to grow #{inspect} to write #{data.length} bytes" 
 			end
 		end
-		r, off = range_and_offset @pos
-		i = ranges.index r
-		([[r[0] + off, r[1] - off]] + ranges[i+1..-1]).each do |pos, len|
+		partial_range, i = offset_and_size @pos
+		([partial_range] + ranges[i+1..-1]).each do |pos, len|
 			@io.seek pos
 			if data_pos + len > data.length
 				chunk = data[data_pos..-1]
@@ -168,17 +211,24 @@ class RangesIO
 		data_pos
 	end
 
-	# this will be generalised to a module later
-	def each_read blocksize=4096
-		yield read(blocksize) until eof?
+	# i can wrap it in a buffered io stream that
+	# provides gets, and appropriately handle pos,
+	# truncate. mostly added just to past the tests.
+	# FIXME
+	def gets
+		s = read 1024
+		i = s.index "\n"
+		@pos -= s.length - (i+1)
+		s[0..i]
 	end
+	alias readline :gets
 
 	def inspect
 		# the rescue is for empty files
-		pos, len = *(range_and_offset(@pos)[0] rescue [nil, nil])
+		pos, len = (@ranges[offset_and_size(@pos).last] rescue [nil, nil])
 		range_str = pos ? "#{pos}..#{pos+len}" : 'nil'
-		"#<#{self.class} io=#{io.inspect} size=#@size pos=#@pos "\
-			"current_range=#{range_str}>"
+		"#<#{self.class} io=#{io.inspect}, size=#@size, pos=#@pos, "\
+			"range=#{range_str}>"
 	end
 end
 

data/lib/ole/storage.rb

@@ -2,13 +2,11 @@
 
 $: << File.dirname(__FILE__) + '/..'
 
-require 'stringio'
 require 'tempfile'
 
 require 'ole/base'
 require 'ole/types'
-# not strictly ole related
-require 'ole/io_helpers'
+require 'ole/ranges_io'
 
 module Ole # :nodoc:
 	# 
@@ -53,27 +51,22 @@ module Ole # :nodoc:
 	#
 	# = TODO
 	#
-	# 1. tests. lock down how things work at the moment - mostly good.
-	#    create from scratch works now, as does copying in a subtree of another doc, so
-	#    ole embedded attachment serialization works now. i can save embedded xls in an msg
-	#    into a separate file, and open it. this was a goal. now i would want to implemenet
-	#    to_mime conversion for embedded attachments, that serializes them to ole, but handles
-	#    some separately like various meta file types as plain .wmf attachments perhaps. this
-	#    will give pretty good .eml's from emails with embedded attachments.
-	#    the other todo is .rtf output, with full support for embedded ole objects...
-	# 2. lots of tidying up
-	#    - main FIXME's in this regard are:
-	#      * the custom header cruft for Header and Dirent needs some love.
-	#      * i have a number of classes doing load/save combos: Header, AllocationTable, Dirent,
-	#        and, in a manner of speaking, but arguably different, Storage itself.
-	#        they have differing api's which would be nice to clean.
-	#        AllocationTable::Big must be created aot now, as it is used for all subsequent reads.
-	#     * ole types need work, can't serialize datetime at the moment.
-	# 3. need to fix META_BAT support in #flush.
+	# * the custom header cruft for Header and Dirent needs some love.
+	# * i have a number of classes doing load/save combos: Header, AllocationTable, Dirent,
+	#   and, in a manner of speaking, but arguably different, Storage itself.
+	#   they have differing api's which would be nice to clean.
+	#   AllocationTable::Big must be created aot now, as it is used for all subsequent reads.
+	# * need to fix META_BAT support in #flush.
 	#
 	class Storage
-		VERSION = '1.2.1'
+		# thrown for any bogus OLE file errors.
+		class FormatError < StandardError # :nodoc:
+		end
+
+		VERSION = '1.2.2'
 
+		# options used at creation time
+		attr_reader :opts
 		# The top of the ole tree structure
 		attr_reader :root
 		# The tree structure in its original flattened form. only valid after #load, or #flush.
@@ -86,15 +79,20 @@ module Ole # :nodoc:
 
 		# maybe include an option hash, and allow :close_parent => true, to be more general.
 		# +arg+ should be either a file, or an +IO+ object, and needs to be seekable.
-		def initialize arg, mode=nil
+		def initialize arg, mode=nil, opts={}
+			opts, mode = mode, nil if Hash === mode
+			opts = {:update_timestamps => true}.merge(opts)
+			@opts = opts
+	
 			# get the io object
 			@close_parent, @io = if String === arg
 				[true, open(arg, mode || 'rb')]
 			else
-				raise 'unable to specify mode string with io object' if mode
+				raise ArgumentError, 'unable to specify mode string with io object' if mode
 				[false, arg]
 			end
 			# do we have this file opened for writing? don't know of a better way to tell
+			# (unless we parse the mode string in the open case)
 			@writeable = begin
 				@io.flush
 				true
@@ -104,11 +102,12 @@ module Ole # :nodoc:
 			# silence undefined warning in clear
 			@sb_file = nil
 			# if the io object has data, we should load it, otherwise start afresh
+			# this should be based on the mode string rather.
 			@io.size > 0 ? load : clear
 		end
 
-		def self.new arg, mode=nil
-			ole = super
+		def self.open arg, mode=nil, opts={}
+			ole = new arg, mode, opts
 			if block_given?
 				begin   yield ole
 				ensure; ole.close
@@ -117,24 +116,16 @@ module Ole # :nodoc:
 			end
 		end
 
-		class << self
-			# encouraged
-			alias open :new
-			# deprecated
-			alias load :new
-		end
-
 		# load document from file.
 		def load
 			# we always read 512 for the header block. if the block size ends up being different,
 			# what happens to the 109 fat entries. are there more/less entries?
 			@io.rewind
 			header_block = @io.read 512
-			@header = Header.load header_block
+			@header = Header.new header_block
 
-			# create an empty bbat
+			# create an empty bbat.
 			@bbat = AllocationTable::Big.new self
-			# extra mbat blocks
 			mbat_blocks = (0...@header.num_mbat).map { |i| i + @header.mbat_start }
 			bbat_chain = (header_block[Header::SIZE..-1] + @bbat.read(mbat_blocks)).unpack 'L*'
 			# am i using num_bat in the right way?
@@ -143,7 +134,7 @@ module Ole # :nodoc:
 			# get block chain for directories, read it, then split it into chunks and load the
 			# directory entries. semantics changed - used to cut at first dir where dir.type == 0
 			@dirents = @bbat.read(@header.dirent_start).scan(/.{#{Dirent::SIZE}}/mo).
-				map { |str| Dirent.load self, str }.reject { |d| d.type_id == 0 }
+				map { |str| Dirent.new self, str }.reject { |d| d.type_id == 0 }
 
 			# now reorder from flat into a tree
 			# links are stored in some kind of balanced binary tree
@@ -155,7 +146,7 @@ module Ole # :nodoc:
 					return [] if idx == Dirent::EOT
 					d = self[idx]
 					d.children = to_tree d.child
-					raise "directory #{d.inspect} used twice" if d.idx
+					raise FormatError, "directory #{d.inspect} used twice" if d.idx
 					d.idx = idx
 					to_tree(d.prev) + [d] + to_tree(d.next)
 				end
@@ -164,7 +155,7 @@ module Ole # :nodoc:
 			@root = @dirents.to_tree.first
 			Log.warn "root name was #{@root.name.inspect}" unless @root.name == 'Root Entry'
 			unused = @dirents.reject(&:idx).length
-			Log.warn "* #{unused} unused directories" if unused > 0
+			Log.warn "#{unused} unused directories" if unused > 0
 
 			# FIXME i don't currently use @header.num_sbat which i should
 			# hmm. nor do i write it. it means what exactly again?
@@ -174,8 +165,8 @@ module Ole # :nodoc:
 		end
 
 		def close
-			flush if @writeable
 			@sb_file.close
+			flush if @writeable
 			@io.close if @close_parent
 		end
 
@@ -193,48 +184,53 @@ this stuff will ensure reliability of input better. otherwise, its actually wort
 directly after read, to ensure the above is probably acounted for, before subsequent writes possibly
 destroy things.
 =end
+
+		# the flush method is the main "save" method. all file contents are always
+		# written directly to the file by the RangesIO objects, all this method does
+		# is write out all the file meta data - dirents, allocation tables, file header
+		# etc.
 		def flush
-			# recreate dirs from our tree, split into dirs and big and small files
-			@root.type = :root
+			# update root dirent, and flatten dirent tree
 			@root.name = 'Root Entry'
 			@root.first_block = @sb_file.first_block
 			@root.size = @sb_file.size
 			@dirents = @root.flatten
 
-			# maybe i should move the block form up to RangesIO, and get it for free at all levels.
-			# Dirent#open gets block form for free then
-			io = RangesIOResizeable.new @bbat, @header.dirent_start
-			io.truncate 0
-			@dirents.each { |dirent| io.write dirent.save }
-			padding = (io.size / @bbat.block_size.to_f).ceil * @bbat.block_size - io.size
-			io.write 0.chr * padding
-			@header.dirent_start = io.first_block
-			io.close
-
-			# similarly for the sbat data.
-			io = RangesIOResizeable.new @bbat, @header.sbat_start
-			io.truncate 0
-			io.write @sbat.save
-			@header.sbat_start = io.first_block
-			@header.num_sbat = @bbat.chain(@header.sbat_start).length
-			io.close
+			# serialize the dirents using the bbat
+			RangesIOResizeable.open @bbat, @header.dirent_start do |io|
+				io.truncate 0
+				@dirents.each { |dirent| io.write dirent.to_s }
+				padding = (io.size / @bbat.block_size.to_f).ceil * @bbat.block_size - io.size
+				io.write 0.chr * padding
+				@header.dirent_start = io.first_block
+			end
 
-			# what follows will be slightly more complex for the bat fiddling.
+			# serialize the sbat
+			# perhaps the blocks used by the sbat should be marked with BAT?
+			RangesIOResizeable.open @bbat, @header.sbat_start do |io|
+				io.truncate 0
+				io.write @sbat.to_s
+				@header.sbat_start = io.first_block
+				@header.num_sbat = @bbat.chain(@header.sbat_start).length
+			end
 
 			# create RangesIOResizeable hooked up to the bbat. use that to claim bbat blocks using
 			# truncate. then when its time to write, convert that chain and some chunk of blocks at
 			# the end, into META_BAT blocks. write out the chain, and those meta bat blocks, and its
 			# done.
-			@bbat.table.map! do |b|
+			# this is perhaps not good, as we reclaim all bat blocks here, which
+			# may include the sbat we just wrote. FIXME
+			@bbat.map! do |b|
 				b == AllocationTable::BAT || b == AllocationTable::META_BAT ?
 					AllocationTable::AVAIL : b
 			end
 			io = RangesIOResizeable.new @bbat, AllocationTable::EOC
 	
-			# use crappy loop for now:
+			# currently we use a loop. this could be better, but basically,
+			# the act of writing out the bat, itself requires blocks which get
+			# recorded in the bat.
 			while true
-				bbat_data = @bbat.save
-				#mbat_data = bbat_data.length / @bbat.block_size * 4
+				bbat_data = @bbat.to_s
 				mbat_chain = @bbat.chain io.first_block
 				raise NotImplementedError, "don't handle writing out extra META_BAT blocks yet" if mbat_chain.length > 109
 				# so we can ignore meta blocks in this calculation:
@@ -247,27 +243,18 @@ destroy things.
 			ranges = io.ranges
 			mbat_chain = @bbat.chain io.first_block
 			io.close
-			mbat_chain.each { |b| @bbat.table[b] = AllocationTable::BAT }
+			mbat_chain.each { |b| @bbat[b] = AllocationTable::BAT }
 			@header.num_bat = mbat_chain.length
-			#p @bbat.truncated_table
-			#p ranges
-			#p mbat_chain
-			# not resizeable!
-			io = RangesIO.new @io, ranges
-			io.write @bbat.save
-			io.close
+
+			# now finally write the bbat, using a not resizable io.
+			RangesIO.open(@io, ranges) { |io| io.write @bbat.to_s }
+
+			# this is the mbat
 			mbat_chain += [AllocationTable::AVAIL] * (109 - mbat_chain.length)
 			@header.mbat_start = AllocationTable::EOC
 			@header.num_mbat = 0
 
 =begin
-			# Old save code. remove shortly
-
-			bbat_data = new_bbat.save
-			# must exist as linear chain stored in header.
-			@header.num_bat = (bbat_data.length / new_bbat.block_size.to_f).ceil
-			base = io.pos / new_bbat.block_size - 1
-			io.write bbat_data
 			# now that spanned a number of blocks:
 			mbat = (0...@header.num_bat).map { |i| i + base }
 			mbat += [AllocationTable::AVAIL] * (109 - mbat.length) if mbat.length < 109
@@ -278,11 +265,9 @@ destroy things.
 			io.write other_mbat_data
 =end
 
-			@root.type = :dir
-
 			# now seek back and write the header out
 			@io.seek 0
-			@io.write @header.save + mbat_chain.pack('L*')
+			@io.write @header.to_s + mbat_chain.pack('L*')
 			@io.flush
 		end
 
@@ -291,13 +276,9 @@ destroy things.
 			Log.warn 'creating new ole storage object on non-writable io' unless @writeable
 			@header = Header.new
 			@bbat = AllocationTable::Big.new self
-			@root = Dirent.new self, :dir
-			@root.name = 'Root Entry'
+			@root = Dirent.new self, :type => :root, :name => 'Root Entry'
 			@dirents = [@root]
 			@root.idx = 0
-			@root.children = []
-			# size shouldn't display for non-files
-			@root.size = 0
 			@sb_file.close if @sb_file
 			@sb_file = RangesIOResizeable.new @bbat, AllocationTable::EOC
 			@sbat = AllocationTable::Small.new self
@@ -310,7 +291,7 @@ destroy things.
 			case temp
 			when :file; Tempfile.open 'w+', &method(:repack_using_io)
 			when :mem;  StringIO.open(&method(:repack_using_io))
-			else raise "unknown temp backing #{temp.inspect}"
+			else raise ArgumentError, "unknown temp backing #{temp.inspect}"
 			end
 		end
 
@@ -318,8 +299,8 @@ destroy things.
 			@io.rewind
 			IO.copy @io, temp_io
 			clear
-			Storage.open temp_io do |temp_ole|
-				temp_ole.root.type = :dir
+			Storage.open temp_io, nil, @opts do |temp_ole|
+				#temp_ole.root.type = :dir
 				Dirent.copy temp_ole.root, root
 			end
 		end
@@ -333,7 +314,12 @@ destroy things.
 			"#<#{self.class} io=#{@io.inspect} root=#{@root.inspect}>"
 		end
 
+		#
 		# A class which wraps the ole header
+		#
+		# Header.new can be both used to load from a string, or to create from
+		# defaults. Serialization is accomplished with the #to_s method.
+		#
 		class Header < Struct.new(
 				:magic, :clsid, :minor_ver, :major_ver, :byte_order, :b_shift, :s_shift,
 				:reserved, :csectdir, :num_bat, :dirent_start, :transacting_signature, :threshold,
@@ -353,23 +339,18 @@ destroy things.
 				4096, EOC, 0, EOC, 0
 			]
 
-			# 2 basic initializations, from scratch, or from a data string.
-			# from scratch will be geared towards creating a new ole object
-			def initialize *values
-				super(*(values.empty? ? DEFAULT : values))
+			def initialize values=DEFAULT
+				values = values.unpack(PACK) if String === values
+				super(*values)
 				validate!
 			end
 
-			def self.load str
-				Header.new(*str.unpack(PACK))
-			end
-
-			def save
+			def to_s
 				to_a.pack PACK
 			end
 
 			def validate!
-				raise "OLE2 signature is invalid" unless magic == MAGIC
+				raise FormatError, "OLE2 signature is invalid" unless magic == MAGIC
 				if num_bat == 0 or # is that valid for a completely empty file?
 					 # not sure about this one. basically to do max possible bat given size of mbat
 					 num_bat > 109 && num_bat > 109 + num_mbat * (1 << b_shift - 2) or
@@ -379,7 +360,7 @@ destroy things.
 					 s_shift > b_shift or b_shift <= 6 or b_shift >= 31 or
 					 # we only handle little endian
 					 byte_order != "\xfe\xff"
-					raise "not valid OLE2 structured storage file"
+					raise FormatError, "not valid OLE2 structured storage file"
 				end
 				# relaxed this, due to test-msg/qwerty_[1-3]*.msg they all had
 				# 3 for this value. 
@@ -414,38 +395,41 @@ destroy things.
 		# block, and in extra blocks throughout the file as referenced by the meta
 		# bat.  That chain is linear, as there is no higher level table.
 		#
-		class AllocationTable
+		# AllocationTable.new is used to create an empty table. It can parse a string
+		# with the #load method. Serialization is accomplished with the #to_s method.
+		#
+		class AllocationTable < Array
 			# a free block (I don't currently leave any blocks free), although I do pad out
 			# the allocation table with AVAIL to the block size.
 			AVAIL		 = 0xffffffff
 			EOC			 = 0xfffffffe # end of a chain
-			# these blocks correspond to the bat, and aren't part of a file, nor available.
-			# (I don't currently output these)
+			# these blocks are used for storing the allocation table chains
 			BAT			 = 0xfffffffd
 			META_BAT = 0xfffffffc
 
-			attr_reader :ole, :io, :table, :block_size
+			attr_reader :ole, :io, :block_size
 			def initialize ole
 				@ole = ole
-				@table = []
+				@sparse = true
+				super()
 			end
 
 			def load data
-				@table = data.unpack('L*')
+				replace data.unpack('L*')
 			end
 
-			def truncated_table
+			def truncate
 				# this strips trailing AVAILs. come to think of it, this has the potential to break
 				# bogus ole. if you terminate using AVAIL instead of EOC, like I did before. but that is
 				# very broken. however, if a chain ends with AVAIL, it should probably be fixed to EOC
 				# at load time.
-				temp = @table.reverse
+				temp = reverse
 				not_avail = temp.find { |b| b != AVAIL } and temp = temp[temp.index(not_avail)..-1]
 				temp.reverse
 			end
 
-			def save
-				table = truncated_table #@table
+			def to_s
+				table = truncate
 				# pad it out some
 				num = @ole.bbat.block_size / 4
 				# do you really use AVAIL? they probably extend past end of file, and may shortly
@@ -454,101 +438,99 @@ destroy things.
 				table.pack 'L*'
 			end
 
-			# rewriting this to be non-recursive. it broke on a large attachment
-			# building up the chain, causing a stack error. need tail-call elimination...
-			def chain start
+			# rewrote this to be non-recursive as it broke on a large attachment
+			# chain with a stack error
+			def chain idx
 				a = []
-				idx = start
 				until idx >= META_BAT
-					raise "broken allocationtable chain" if idx < 0 || idx > @table.length
+					raise FormatError, "broken allocationtable chain" if idx < 0 || idx > length
 					a << idx
-					idx = @table[idx]
+					idx = self[idx]
 				end
 				Log.warn "invalid chain terminator #{idx}" unless idx == EOC
 				a
 			end
 			
-			def ranges chain, size=nil
-				chain = self.chain(chain) unless Array === chain
-				blocks_to_ranges chain, size
-			end
-
-			# Turn a chain (an array given by +chain+) of big blocks, optionally
-			# truncated to +size+, into an array of arrays describing the stretches of
+			# Turn a chain (an array given by +chain+) of blocks (optionally
+			# truncated to +size+) into an array of arrays describing the stretches of
 			# bytes in the file that it belongs to.
 			#
-			# Big blocks are of size Ole::Storage::Header#b_size, and are stored
-			# directly in the parent file.
-			# truncate the chain if required
-			# convert chain to ranges of the block size
-			# truncate final range if required
-
+			# The blocks are Big or Small blocks depending on the table type.
 			def blocks_to_ranges chain, size=nil
+				# truncate the chain if required
 				chain = chain[0...(size.to_f / block_size).ceil] if size
+				# convert chain to ranges of the block size
 				ranges = chain.map { |i| [block_size * i, block_size] }
+				# truncate final range if required
 				ranges.last[1] -= (ranges.length * block_size - size) if ranges.last and size
 				ranges
 			end
 
+			def ranges chain, size=nil
+				chain = self.chain(chain) unless Array === chain
+				blocks_to_ranges chain, size
+			end
+
 			# quick shortcut. chain can be either a head (in which case the table is used to
 			# turn it into a chain), or a chain. it is converted to ranges, then to rangesio.
-			# its not resizeable or migrateable. it probably could be resizeable though, using
-			# self as the bat. but what would the first_block be?
-			def open chain, size=nil
-				io = RangesIO.new @io, ranges(chain, size)
-				if block_given?
-					begin   yield io
-					ensure; io.close
-					end
-				else io
-				end
+			def open chain, size=nil, &block
+				RangesIO.open @io, ranges(chain, size), &block
 			end
 
 			def read chain, size=nil
 				open chain, size, &:read
 			end
 
-			# ----------------------
+			# catch any method that may add an AVAIL somewhere in the middle, thus invalidating
+			# the @sparse speedup for free_block. annoying using eval, but define_method won't
+			# work for this.
+			# FIXME
+			[:map!, :collect!].each do |name|
+				eval <<-END
+					def #{name}(*args, &block)
+						@sparse = true
+						super
+					end
+				END
+			end
+
+			def []= idx, val
+				@sparse = true if val == AVAIL
+				super
+			end
 
-			def get_free_block
-				@table.each_index { |i| return i if @table[i] == AVAIL }
-				@table.push AVAIL
-				@table.length - 1
+			def free_block
+				if @sparse
+					i = index(AVAIL) and return i
+				end
+				@sparse = false
+				push AVAIL
+				length - 1
 			end
 
 			# must return first_block
-			def resize_chain first_block, size
+			def resize_chain blocks, size
 				new_num_blocks = (size / block_size.to_f).ceil
-				blocks = chain first_block
 				old_num_blocks = blocks.length
 				if new_num_blocks < old_num_blocks
 					# de-allocate some of our old blocks. TODO maybe zero them out in the file???
-					(new_num_blocks...old_num_blocks).each { |i| @table[blocks[i]] = AVAIL }
-					# if we have a chain, terminate it and return head, otherwise return EOC
-					if new_num_blocks > 0
-						@table[blocks[new_num_blocks-1]] = EOC
-						first_block
-					else EOC
-					end
+					(new_num_blocks...old_num_blocks).each { |i| self[blocks[i]] = AVAIL }
+					self[blocks[new_num_blocks-1]] = EOC if new_num_blocks > 0
+					blocks.slice! new_num_blocks..-1
 				elsif new_num_blocks > old_num_blocks
 					# need some more blocks.
 					last_block = blocks.last
 					(new_num_blocks - old_num_blocks).times do
-						block = get_free_block
+						block = free_block
 						# connect the chain. handle corner case of blocks being [] initially
-						if last_block
-							@table[last_block] = block
-						else
-							first_block = block
-						end
+						self[last_block] = block if last_block
+						blocks << block
 						last_block = block
-						# this is just to inhibit the problem where it gets picked as being a free block
-						# again next time around.
-						@table[last_block] = EOC
+						self[last_block] = EOC
 					end
-					first_block
-				else first_block
 				end
+				# update ranges, and return that also now
+				blocks
 			end
 
 			class Big < AllocationTable
@@ -587,15 +569,18 @@ destroy things.
 			def initialize bat, first_block, size=nil
 				@bat = bat
 				self.first_block = first_block
-				super @bat.io, @bat.ranges(first_block, size)
+				# we know cache the blocks chain, for faster resizing.
+				@blocks = @bat.chain first_block
+				super @bat.io, @bat.ranges(@blocks, size)
 			end
 
 			def truncate size
 				# note that old_blocks is != @ranges.length necessarily. i'm planning to write a
 				# merge_ranges function that merges sequential ranges into one as an optimization.
-				self.first_block = @bat.resize_chain first_block, size
-				@ranges = @bat.ranges first_block, size
+				@bat.resize_chain @blocks, size
+				@ranges = @bat.ranges @blocks, size
 				@pos = @size if @pos > size
+				self.first_block = @blocks.empty? ? AllocationTable::EOC : @blocks.first
 
 				# don't know if this is required, but we explicitly request our @io to grow if necessary
 				# we never shrink it though. maybe this belongs in allocationtable, where smarter decisions
@@ -609,8 +594,7 @@ destroy things.
 		end
 
 		# like RangesIOResizeable, but Ole::Storage::Dirent specific. provides for migration
-		# between bats based on size, and updating the dirent, instead of the ole copy back
-		# on close.
+		# between bats based on size, and updating the dirent.
 		class RangesIOMigrateable < RangesIOResizeable
 			attr_reader :dirent
 			def initialize dirent
@@ -620,7 +604,7 @@ destroy things.
 
 			def truncate size
 				bat = @dirent.ole.bat_for_size size
-				if bat != @bat
+				if bat.class != @bat.class
 					# bat migration needed! we need to backup some data. the amount of data
 					# should be <= @ole.header.threshold, so we can just hold it all in one buffer.
 					# backup this
@@ -667,16 +651,16 @@ destroy things.
 		# was considering separate classes for dirs and files. some methods/attrs only
 		# applicable to one or the other.
 		#
-		# Note that Dirent is still using a home grown Struct variant, with explicit
-		# MEMBERS etc. any reason for that still?
+		# As with the other classes, #to_s performs the serialization.
 		#
-		class Dirent
-			MEMBERS = [
+		class Dirent < Struct.new(
 				:name_utf16, :name_len, :type_id, :colour, :prev, :next, :child,
 				:clsid, :flags, # dirs only
 				:create_time_str, :modify_time_str, # files only
 				:first_block, :size, :reserved
-			]
+			)
+			include RecursivelyEnumerable
+
 			PACK = 'a64 S C C L3 a16 L a8 a8 L2 a4'
 			SIZE = 128
 			TYPE_MAP = {
@@ -686,6 +670,7 @@ destroy things.
 				2 => :file,
 				5 => :root
 			}
+			# something to do with the fact that the tree is supposed to be red-black
 			COLOUR_MAP = {
 				0 => :red,
 				1 => :black
@@ -693,63 +678,70 @@ destroy things.
 			# used in the next / prev / child stuff to show that the tree ends here.
 			# also used for first_block for directory.
 			EOT = 0xffffffff
+			DEFAULT = [
+				0.chr * 2, 2, 0, # will get overwritten
+				1, EOT, EOT, EOT,
+				0.chr * 16, 0, nil, nil,
+				AllocationTable::EOC, 0, 0.chr * 4
+			]
 
-			include Enumerable
-
-			# Dirent's should be created in 1 of 2 ways, either Dirent.new ole, [:dir/:file/:root],
-			# or Dirent.load '... dirent data ...'
-			# its a bit clunky, but thats how it is at the moment. you can assign to type, but
-			# shouldn't.
-
+			# i think its just used by the tree building
 			attr_accessor :idx
 			# This returns all the children of this +Dirent+. It is filled in
 			# when the tree structure is recreated.
 			attr_accessor :children
-			attr_reader :ole, :type, :create_time, :modify_time, :name
-			def initialize ole, type
-				@ole = ole
-				# this isn't really good enough. need default values put in there.
-				@values = [
-					0.chr * 2, 2, 0, # will get overwritten
-					1, EOT, EOT, EOT,
-					0.chr * 16, 0, nil, nil,
-					AllocationTable::EOC, 0, 0.chr * 4]
-				# maybe check types here. 
-				@type = type
-				@create_time = @modify_time = nil
-				@children = []
-				if file?
-					@create_time = Time.now
-					@modify_time = Time.now
+			attr_accessor :name
+			attr_reader :ole, :type, :create_time, :modify_time
+			def initialize ole, values=DEFAULT, opts={}
+				@ole = ole				
+				values, opts = DEFAULT, values if Hash === values
+				values = values.unpack(PACK) if String === values
+				super(*values)
+
+				# extra parsing from the actual struct values
+				@name = opts[:name] || Types::FROM_UTF16.iconv(name_utf16[0...name_len].sub(/\x00\x00$/, ''))
+				@type = if opts[:type]
+					unless TYPE_MAP.values.include?(opts[:type])
+						raise ArgumentError, "unknown type #{opts[:type].inspect}"
+					end
+					opts[:type]
+				else
+					TYPE_MAP[type_id] or raise FormatError, "unknown type_id #{type_id.inspect}"
 				end
-			end
-
-			def self.load ole, str
-				# load should function without the need for the initializer.
-				dirent = Dirent.allocate
-				dirent.load ole, str
-				dirent
-			end
 
-			def load ole, str
-				@ole = ole
-				@values = str.unpack PACK
-				@name = Types::FROM_UTF16.iconv name_utf16[0...name_len].sub(/\x00\x00$/, '')
-				@type = TYPE_MAP[type_id] or raise "unknown type #{type_id.inspect}"
+				# further extra type specific stuff
 				if file?
-					@create_time = Types.load_time create_time_str
-					@modify_time = Types.load_time modify_time_str
+					default_time = @ole.opts[:update_timestamps] ? Time.now : nil
+					@create_time ||= default_time
+					@modify_time ||= default_time
+					@create_time = Types.load_time(create_time_str) if create_time_str
+					@modify_time = Types.load_time(create_time_str) if modify_time_str
+					@children = nil
+				else
+					@create_time = nil
+					@modify_time = nil
+					self.size = 0 unless @type == :root
+					@children = []
 				end
 			end
 
-			# only defined for files really. and the above children stuff is only for children.
-			# maybe i should have some sort of File and Dir class, that subclass Dirents? a dirent
-			# is just a data holder. 
-			# this can be used for write support if the underlying io object was opened for writing.
-			# maybe take a mode string argument, and do truncation, append etc stuff.
-			def open
-				return nil unless file?
+			def open mode='r'
+				raise Errno::EISDIR unless file?
 				io = RangesIOMigrateable.new self
+				# TODO work on the mode string stuff a bit more.
+				# maybe let the io object know about the mode, so it can refuse
+				# to work for read/write appropriately. maybe redefine all unusable
+				# methods using singleton class to throw errors.
+				# for now, i just want to implement truncation on use of 'w'. later,
+				# i need to do 'a' etc.
+				case mode
+				when 'r', 'r+'
+					# as i don't enforce reading/writing, nothing changes here
+				when 'w'
+					io.truncate 0
+				else
+					raise NotImplementedError, "unsupported mode - #{mode.inspect}"
+				end
 				if block_given?
 					begin   yield io
 					ensure; io.close
@@ -762,71 +754,48 @@ destroy things.
 				open { |io| io.read limit }
 			end
 
-			def dir?
-				# to count root as a dir.
-				type != :file
-			end
-
 			def file?
 				type == :file
 			end
 
-			def time
-				# time is nil for streams, otherwise try to parse either of the time pairse (not
-				# sure of their meaning - created / modified?)
-				#@time ||= file? ? nil : (Dirent.parse_time(secs1, days1) || Dirent.parse_time(secs2, days2))
-				create_time || modify_time
+			def dir?
+				# to count root as a dir.
+				!file?
 			end
 
-			def each(&block)
-				@children.each(&block)
+			def / name
+				children.find { |child| name === child.name }
 			end
-			
+
 			def [] idx
-				return children[idx] if Integer === idx
-				# path style look up.
-				# maybe take another arg to allow creation? or leave that to the filesystem
-				# add on. 
-				# not sure if '/' is a valid char in an Dirent#name, so no splitting etc at
-				# this level.
-				# also what about warning about multiple hits for the same name?
-				children.find { |child| idx === child.name }
-			end
-
-			# solution for the above '/' thing for now.
-			def / path
-				self[path]
-			end
-
-			def to_tree
-				if children and !children.empty?
-					str = "- #{inspect}\n"
-					children.each_with_index do |child, i|
-						last = i == children.length - 1
-						child.to_tree.split(/\n/).each_with_index do |line, j|
-							str << "  #{last ? (j == 0 ? "\\" : ' ') : '|'}#{line}\n"
-						end
-					end
-					str
-				else "- #{inspect}\n"
+				if String === idx
+					warn 'String form of Dirent#[] is deprecated'
+					self / idx
+				else
+					super
 				end
 			end
 
-			MEMBERS.each_with_index do |sym, i|
-				define_method(sym) { @values[i] }
-				define_method(sym.to_s + '=') { |val| @values[i] = val }
+			# move to ruby-msg. and remove from here
+			def time
+				warn 'Dirent#time is deprecated'
+				create_time || modify_time
 			end
 
-			def to_a
-				@values
+			def each_child(&block)
+				@children.each(&block)
 			end
 
 			# flattens the tree starting from here into +dirents+. note it modifies its argument.
 			def flatten dirents=[]
 				@idx = dirents.length
 				dirents << self
-				children.each { |child| child.flatten dirents }
-				self.child = Dirent.flatten_helper children
+				if file?
+					self.prev = self.next = self.child = EOT
+				else
+					children.each { |child| child.flatten dirents } 
+					self.child = Dirent.flatten_helper children
+				end
 				dirents
 			end
 
@@ -843,29 +812,27 @@ destroy things.
 				this.idx
 			end
 
-			attr_accessor :name, :type
-			def save
+			def to_s
 				tmp = Types::TO_UTF16.iconv(name)
 				tmp = tmp[0, 62] if tmp.length > 62
 				tmp += 0.chr * 2
 				self.name_len = tmp.length
 				self.name_utf16 = tmp + 0.chr * (64 - tmp.length)
-				begin
-					self.type_id = TYPE_MAP.to_a.find { |id, name| @type == name }.first
-				rescue
-					raise "unknown type #{type.inspect}"
-				end
+				# type_id can perhaps be set in the initializer, as its read only now.
+				self.type_id = TYPE_MAP.to_a.find { |id, name| @type == name }.first
 				# for the case of files, it is assumed that that was handled already
 				# note not dir?, so as not to override root's first_block
 				self.first_block = Dirent::EOT if type == :dir
-				if 0 #file?
-					#self.create_time_str = ?? #Types.load_time create_time_str
-					#self.modify_time_str = ?? #Types.load_time modify_time_str
+				if file?
+					if @ole.opts[:update_timestamps]
+						self.create_time_str = Types.save_time @create_time
+						self.modify_time_str = Types.save_time Time.now
+					end
 				else
 					self.create_time_str = 0.chr * 8
 					self.modify_time_str = 0.chr * 8
 				end
-				@values.pack PACK
+				to_a.pack PACK
 			end
 
 			def inspect
@@ -875,7 +842,7 @@ destroy things.
 					tmp = read 9
 					data = tmp.length == 9 ? tmp[0, 5] + '...' : tmp
 					str << " size=#{size}" +
-						"#{time ? ' time=' + time.to_s.inspect : nil}" +
+						"#{modify_time ? ' modify_time=' + modify_time.to_s.inspect : nil}" +
 						" data=#{data.inspect}"
 				else
 					# there is some dir specific stuff. like clsid, flags.
@@ -887,7 +854,7 @@ destroy things.
 			# and for creation of a dirent. don't like the name. is it a file or a directory?
 			# assign to type later? io will be empty.
 			def new_child type
-				child = Dirent.new ole, type
+				child = Dirent.new ole, :type => type
 				children << child
 				yield child if block_given?
 				child
@@ -895,7 +862,7 @@ destroy things.
 
 			def delete child
 				# remove from our child array, so that on reflatten and re-creation of @dirents, it will be gone
-				raise "#{child.inspect} not a child of #{self.inspect}" unless @children.delete child
+				raise ArgumentError, "#{child.inspect} not a child of #{self.inspect}" unless @children.delete child
 				# free our blocks
 				child.open { |io| io.truncate 0 }
 			end
@@ -903,7 +870,7 @@ destroy things.
 			def self.copy src, dst
 				# copies the contents of src to dst. must be the same type. this will throw an
 				# error on copying to root. maybe this will recurse too much for big documents??
-				raise 'differing types' if src.type == :file and dst.type != :file
+				raise ArgumentError, 'differing types' if src.file? and !dst.file?
 				dst.name = src.name
 				if src.dir?
 					src.children.each do |src_child|
@@ -919,7 +886,3 @@ destroy things.
 	end
 end
 
-if $0 == __FILE__
-	puts Ole::Storage.open(ARGV[0]) { |ole| ole.root.to_tree }
-end
-