xeme 0.3.1 → 1.0

data/lib/xeme.rb

@@ -1,37 +1,37 @@
-require 'date'
-require 'json'
 require 'forwardable'
+require 'declutter'
+
 
 #===============================================================================
 # Xeme
 #
-
-# Objects of this class represent a set of results. See the README file for
-# more details.
-
 class Xeme
-	# version 0.3.1
-	VERSION = '0.3.1'
+	# Returns the underlying hash that the xeme manages.
+	attr_reader :hsh
 	
-	# A Xeme::Messages object, which is basically just a hash containing arrays
-	# for errors, warnings, and notes.
-	attr_reader :messages
+	#---------------------------------------------------------------------------
+	# delegate
+	#
+	extend Forwardable
+	delegate %w([] []= each length clear delete to_json) => :hsh
+	#
+	# delegate
+	#---------------------------------------------------------------------------
 	
-	# A hash of any miscellaneous details you want to include.
-	attr_reader :misc
 	
 	#---------------------------------------------------------------------------
 	# initialize
 	#
 	
-	# new() does not take any parameters.
+	# Creates a new Xeme object. Optionally takes a single strin parameter which
+	# is set as the id for the xeme.
 	
-	def initialize
-		@messages = Xeme::Messages.new
-		@misc = {}
-		@prefixes = []
-		@auto_details_val = nil
-		@transaction = nil
+	def initialize(id=nil)
+		@hsh = {}
+		
+		if id
+			meta id
+		end
 	end
 	#
 	# initialize
@@ -39,627 +39,599 @@ class Xeme
 	
 	
 	#---------------------------------------------------------------------------
-	# errors, warnings, notes
+	# meta
 	#
 	
-	##
-	# Returns the array of errors.
-	def errors
-		return @messages['errors']
+	# Returns the meta hash, creating it if necessary. The meta hash
+	# contains at least a timestamp and a UUID.
+	
+	def meta(id=nil)
+		require 'securerandom'
+		
+		# initialize meta element if necessary
+		@hsh['meta'] ||= {}
+		
+		# populate meta
+		@hsh['meta']['uuid'] ||= SecureRandom.uuid().to_s
+		@hsh['meta']['timestamp'] ||= Time.now
+		
+		# give child id if given
+		if id
+			meta['id'] = id
+		end
+		
+		# return
+		return @hsh['meta']
+	end
+	
+	# Returns the UUID in the meta hash.
+	def uuid
+		return meta['uuid']
 	end
 	
-	##
-	# Returns the array of warnings.
-	def warnings
-		return @messages['warnings']
+	# Returns the timestamp in the meta hash.
+	def timestamp
+		return meta['timestamp']
+	end
+	
+	# Returns the id element of the meta hash if there is one.
+	def id
+		if @hsh['meta']
+			return @hsh['meta']['id']
+		else
+			return nil
+		end
 	end
 	
-	##
-	# Returns the array of notes.
-	def notes
-		return @messages['notes']
+	# Sets id element of the meta.
+	def id=(v)
+		return meta['id'] = v
 	end
 	#
-	# errors, warnings, notes
+	# meta
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# transaction
+	# flatten
 	#
 	
-	##
-	# Returns the transaction object, creating it if necessary. See
-	# Xeme::Transaction. If the transaction object is never created then it is
-	# not output with #to_json. The transaction object can be used to provide
-	# meta information about the request and response that produced the
-	# results. See Xeme::Transaction for more information.
+	# Folds all nested messages into the outermost xeme, and deletes nested
+	# xemes. Only the messages are folded in, not any metainformation or other
+	# information that might be in the nested xemes.
+	
+	def flatten
+		resolve()
+		
+		as_arr('nested').each do |child|
+			child.flatten
+			
+			%w{errors warnings notes promises}.each do |msg_key|
+				if child[msg_key]
+					@hsh[msg_key] ||= []
+					@hsh[msg_key] += child[msg_key]
+					child.delete(msg_key)
+				end
+			end
+		end
+		
+		@hsh.delete('nested')
+	end
 	#
-	# You can create the transaction object by simply calling this method:
+	# flatten
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_h
 	#
-	#	xeme.transaction
+	# def to_h
+	# 	rv = @hsh.to_h
+	# 	
+	# 	# loop through nested xemes
+	# 	if rv['nested']
+	# 		rv['nested'] = rv['nested'].map do |child|
+	# 			child.to_h
+	# 		end
+	# 	end
+	# 	
+	# 	# return
+	# 	return rv
+	# end
 	#
-	# If you want to assign a request ID, call this method and assign to its
-	# request property. For example, if there's a request object that provides
-	# an id, you could assign the transaction.request ID like this:
+	# to_h
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# succeed
 	#
-	#	xeme.transaction.request = request.id
 	
-	def transaction
-		@transaction ||= Xeme::Transaction.new()
-		return @transaction
+	# Attempt to set success to true. Raises an exception if there are any
+	# errors or promises in this or any nested Xeme.
+	
+	def succeed
+		# if any errors, don't succeed
+		if errors.any?
+			raise 'cannot-set-to-success: errors'
+		end
+		
+		# if any promises, don't succeed
+		if promises.any?
+			raise 'cannot-set-to-success: promises'
+		end
+		
+		# set to success
+		return @hsh['success'] = true
 	end
+	
 	#
-	# transaction
+	# succeed
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# to_h
+	# try_succeed
 	#
 	
-	##
-	# Returns a hash with all the results. This hash can be used to create a JSON
-	# object. Empty arrays, such as if there are no warnings, are not included.
+	# Attempt to set success to true. Does not raise an exception if there are
+	# errors or promises, but in those cases will not set success to true.
 	
-	def to_h
-		# $tm.hrm
-		
-		# initialize return value
-		rv = {}
+	def try_succeed(resolve_self=true)
+		enforce_nil = false
 		
-		# success
-		rv['success'] = success()
+		# resolve self and descendents
+		if resolve_self
+			resolve()
+		end
 		
-		# transaction
-		if @transaction
-			rv['transaction'] = @transaction.to_h
+		# if any promises
+		if as_arr('promises').any?
+			@hsh.delete 'success'
+			enforce_nil = true
 		end
 		
-		# if any messages
-		if @messages.any?
-			msgs = rv['messages'] = {}
+		# try_succeed for descendents
+		as_arr('nested').each do |child|
+			child.try_succeed false
 			
-			@messages.each do |key, arr|
-				if arr.any?
-					msgs[key] = []
-					
-					arr.each do |msg|
-						msgs[key].push msg.to_h
-					end
+			if @hsh['success'].nil?
+				if child['success'].nil?
+					enforce_nil = true
+				elsif not child['success']
+					@hsh['success'] = false
 				end
 			end
 		end
 		
-		# misc
-		if @misc.any?
-			rv['misc'] = @misc
+		# set to success if success is nil and no promises
+		if @hsh['success'].nil? and (! enforce_nil)
+			@hsh['success'] = true
 		end
 		
 		# return
-		return rv
+		return @hsh['success']
 	end
+	
 	#
-	# to_h
+	# try_succeed
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# to_json
+	# fail
 	#
 	
-	##
-	# Returns a JSON string containing all the result information.
-	def to_json(opts={})
-		if opts['pretty']
-			return JSON.pretty_generate(self.to_h)
-		else
-			return JSON.generate(self.to_h)
-		end
+	# Explicitly set success to false. Does not add an error.
+	
+	def fail
+		@hsh['success'] = false
+		resolve()
 	end
+	
 	#
-	# to_json
+	# fail
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# success
+	# success?
 	#
-	
-	##
-	# Returns false if there are any errors, true otherwise.
-	
-	def success		
-		return @messages['errors'].empty?
+	def success?
+		resolve()
+		return @hsh['success']
 	end
-	
-	##
-	# Returns the opposite of <tt>success()</tt>.
-	def failure
-		return success ? false : true
-	end
-	
 	#
-	# success
+	# success?
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# save_exception
+	# messages
 	#
 	
-	# Use this method to hold on to details about an exception. An error message
-	# object will be created, along with the exception's to_s and backtrace.
+	# Returns a locked array of all errors, including errors in nested xemes.
+	# If the optional id param is sent, returns only errors with that id.
+	def errors(id=nil)
+		return all_messages('errors', id)
+	end
+	
+	# Returns a locked array of all warnings, including warnings in nested xemes.
+	# If the optional id param is sent, returns only warnings with that id.
+	def warnings(id=nil)
+		return all_messages('warnings', id)
+	end
+	
+	# Returns a locked array of all notes, including notes in nested xemes.
+	# If the optional id param is sent, returns only notes with that id.
+	def notes(id=nil)
+		return all_messages('notes', id)
+	end
 	
-	def save_exception(id, e, details={})
-		message = self.error(id, details)
-		message['error'] = e.to_s
-		message['backtrace'] = e.backtrace
+	# Returns a locked array of all promises, including promises in nested xemes.
+	# If the optional id param is sent, returns only promises with that id.
+	def promises(id=nil)
+		return all_messages('promises', id)
 	end
+	
 	#
-	# save_exception
+	# messages
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# prefix
+	# message hashes
 	#
 	
-	##
-	# <tt>prefix</tt> allows you to automatically add prefixes to your message
-	# codes in situations where many messages will start with the same string.
-	# Consider the following situation.
-	#
-	# 	xeme.error '/virginia/slope'
-	# 	xeme.error '/virginia/angle'
-	# 	xeme.error '/virginia/departure'
-	#
-	# That works, but the redundancy can get confusing (and annoying). With
-	# <tt>prefix</tt> you can avoid the redundancy like this:
-	#
-	#	xeme.prefix('virginia') do
-	#	    xeme.error 'slope'
-	#	    xeme.error 'angle'
-	#	    xeme.error 'departure'
-	#	end
-	#
-	# 	puts xeme.errors[0].id # /virginia/slope
-	# 	puts xeme.errors[1].id # /virginia/angle
-	# 	puts xeme.errors[2].id # /virginia/departure
-	#
-	# Prefixes can also be nested, like this:
-	#
-	# 	xeme.prefix('virginia') do
-	#	    xeme.prefix('fairfax') do
-	#	        xeme.error 'slope'
-	#	    end
-	# 	end
-	#
-	# 	puts xeme.errors[0].id # /virginia/fairfax/slope
+	# Returns a hash of all errors, including nested errors. The key for each
+	# element is the id of the error(s). Does not return errors that don't have
+	# ids.
+	def errors_hash()
+		return messages_hash('errors')
+	end
 	
-	def prefix(p_prefix)
-		# $tm.hrm
-		hold_prefixes = @prefixes.clone
-		@prefixes = @prefixes.clone
-		@prefixes.push p_prefix
-			
-		begin
-			yield
-		ensure
-			@prefixes = hold_prefixes
-		end
+	# Returns a hash of all warnings, including nested warnings. The key for
+	# each element is the id of the warnings(s). Does not return warnings that
+	# don't have ids.
+	def warnings_hash(id=nil)
+		return messages_hash('warnings')
+	end
+	
+	# Returns a hash of all notes, including nested notes. The key for each
+	# element is the id of the notes(s). Does not return notes that don't have
+	# ids.
+	def notes_hash(id=nil)
+		return messages_hash('notes')
+	end
+	
+	# Returns a hash of all promises, including nested promises. The key for
+	# each element is the id of the promise(s). Does not return promises that
+	# don't have ids.
+	def promises_hash(id=nil)
+		return messages_hash('promises')
 	end
+	
 	#
-	# prefix
+	# message hashes
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# error, warning, note
+	# add message
 	#
 	
-	##
-	# Creates a message object and stores it in the errors array.
-	#
-	#	xeme.error('error-1').
-	#
-	# A hash of arbitrary details can be given. Those details will be stored
-	# with the message object in its Xeme::Message#details property.
-	#
-	#	xeme.error('error-0', 'choice'=>'a')
-	#
-	# This method returns the message object, which can be used as another
-	# way to store details.
-	#
-	#	msg = xeme.error('error-1').
-	#	msg['location'] = 1
-	#
-	# If a block is given, the block is called with the error object as the
-	# single param.
-	#
-	#	xeme.error('error-2') do |error|
-	#	    error['location'] = 2
-	#	end
-	def error(id, details={}, &block)
-		return add_comment(Xeme::Message, 'errors', id, details={}, &block)
+	# Creates and returns an error message. Accepts a do block which yields the
+	# new message. If given the opional id param, sets that value as the id for
+	# the message.
+	def error(id, &block)
+		@hsh['success'] = false
+		return message('errors', id, &block)
 	end
 	
-	##
-	# Works just #error() except it stores the message in the warnings array.
-	def warning(id, details={}, &block)
-		return add_comment(Xeme::Message, 'warnings', id, details={}, &block)
+	# Creates and returns a warning message. Accepts a do block which yields
+	# the new message. If given the opional id param, sets that value as the id
+	# for the new message.
+	def warning(id, &block)
+		return message('warnings', id, &block)
 	end
 	
-	##
-	# Works just #error() except it stores the message in the notes array.
-	def note(id, details={}, &block)
-		return add_comment(Xeme::Message, 'notes', id, details={}, &block)
+	# Creates and returns a note message. Accepts a do block which yields
+	# the new message. If given the opional id param, sets that value as the id
+	# for the new message.
+	def note(id, &block)
+		return message('notes', id, &block)
 	end
+	
+	# Creates and returns a promise message. Accepts a do block which yields
+	# the new message. If given the opional id param, sets that value as the id
+	# for the new message.
+	def promise(id, &block)
+		unless @hsh['success'].is_a?(FalseClass)
+			@hsh.delete 'success'
+		end
+		
+		return message('promises', id, &block)
+	end
+	
 	#
-	# error, warning, note
+	# add message
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# from_json
+	# nest
 	#
 	
-	# Creates a new Xeme object from a JSON structure.
+	# Creates a new xeme and nests it in the current xeme. Yields to a do block
+	# if one is sent. Returns the new child xeme.
 	
-	def self.from_json(raw_json)
-		# $tm.hrm
-		hsh = JSON.parse(raw_json)
-		rv = self.new
+	def nest(id=nil)
+		@hsh['nested'] ||= []
+		child = self.class.new()
+		@hsh['nested'].push child
 		
-		# messages
-		if messages = hsh['messages']
-			messages.each do |msg_type, arr|
-				rv.messages[msg_type] ||= []
-				rv.messages[msg_type] += arr
-			end
-		end
-		
-		# misc
-		if misc = hsh['misc']
-			misc.each do |key, val|
-				rv.misc[key] = val
-			end
+		# give id
+		if id
+			child.meta['id'] = id
 		end
 		
-		# transaction
-		if transaction = hsh['transaction']
-			if transaction['timestamp']
-				rv.transaction.timestamp = DateTime.parse(transaction['timestamp'])
-			end
-			
-			if transaction['request']
-				rv.transaction.request = transaction['request']
-			end
-			
-			if transaction['response']
-				rv.transaction.response = transaction['response']
-			end
+		# yield in block
+		if block_given?
+			yield child
 		end
 		
 		# return
-		return rv
+		return child
 	end
+	
 	#
-	# from_json
+	# nest
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# new_exception
+	# nested
 	#
-	
-	# Creates and returns a Xeme::Exception object. The Xeme object is attached
-	# to the Xeme::Exception object.
-	
-	def new_exception(error_id)
-		return Xeme::Exception.new(error_id, self)
-	end
+	# def nested()
+	#	@hsh['nested'] ||= []
+	#	return @hsh['nested']
+	# end
 	#
-	# new_exception
+	# nested
 	#---------------------------------------------------------------------------
 	
 	
-	# private methods
-	private
-
-	
 	#---------------------------------------------------------------------------
-	# messages_to_h
+	# resolve
 	#
-	def messages_to_h(arr)
-		rv = []
-		
-		# messages
-		arr.each do |msg|
-			rv.push msg.to_h
-		end
-		
-		# return
-		return rv
-	end
-	#
-	# messages_to_h
-	#---------------------------------------------------------------------------
 	
+	# Resolves conflicts between errors, promises, and success. See README.md
+	# for details. You generally don't need to call this method yourself.
 	
-	#---------------------------------------------------------------------------
-	# add_comment
-	#
-	def add_comment(cls, type, id, details={}, &block)
-		# $tm.hrm
-		
-		# build message
-		msg = cls.new(prefix_id(id), details)
+	def resolve
+		# resolve descendents
+		as_arr('nested').each do |child|
+			child.resolve
+		end
 		
-		# ensure array
-		@messages[type] ||= []
+		# if own errors, fail
+		if as_arr('errors').any?
+			@hsh['success'] = false
+			return
+		end
 		
-		# add to errors array
-		@messages[type].push(msg)
+		# if explicitly set to false, return
+		if @hsh['success'].is_a?(FalseClass)
+			return
+		end
 		
-		# yield
-		if block_given?
-			yield msg
+		# if any promises, set success to nil
+		if as_arr('promises').any?
+			@hsh.delete 'success'
 		end
 		
-		# return
-		return msg
+		# if any child is set to nil, set self to nil
+		# if any child set to false, set self to false and return
+		as_arr('nested').each do |child|
+			if child['success'].nil?
+				@hsh.delete 'success'
+			elsif not child['success']
+				@hsh['success'] = false
+				return
+			end
+		end
 	end
 	#
-	# add_comment
+	# resolve
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# prefix_id
+	# declutter
 	#
-	def prefix_id(p_id)
-		if @prefixes.any?
-			return '/' + @prefixes.join('/') + '/' + p_id
-		else
-			return p_id
-		end
+	
+	# Removes empty arrays and hahes.
+	
+	def declutter
+		resolve()
+		Declutter.process @hsh
+		return true
 	end
 	#
-	# prefix_id
+	# declutter
 	#---------------------------------------------------------------------------
-end
-#
-# Xeme
-#===============================================================================
-
-
-#===============================================================================
-# Xeme::Message
-#
-
-# A Xeme::Message object represents a single error, warning, or note.
-# It is the base class for Xeme::Message::Error,
-# Xeme::Message::Warning, and 
-# Xeme::Message::Note. Don't instantiate Xeme::Message
-# directly, use Xeme#error, Xeme#warning, or Xeme#note.
-#
-# Each message contains at least an id. It can also have an options details
-# hash which can be used to store misc information about the message.
-#
-# The message itself can be treated like a hash to give details:
-#
-#	msg = xeme.error('my-error')
-#	msg['location'] = 1
-
-class Xeme::Message
-	# The id of the message.
-	attr_reader :id
-	
-	# Details about the message.
-	attr_reader :details
-	
-	# delegate to hsh
-	extend Forwardable
-	delegate %w([] []= each length clear delete) => :@details
 	
 	
 	#---------------------------------------------------------------------------
-	# initialize
+	# all
 	#
 	
-	# Initialize a Xeme::Message object with the id of the message. The id can
-	# be any string. The optional <tt>details</tt> hash will be stored with the
-	# message.
+	# Returns an array consisting of the xeme and all nested xemes.
 	
-	def initialize(id, details={})
-		# $tm.hr __method__
+	def all(seek_id=nil)
+		rv = []
+		
+		# add self
+		if seek_id
+			if id == seek_id
+				rv.push self
+			end
+		else
+			rv.push self
+		end
+		
+		# loop through nested children
+		as_arr('nested').each do |child|
+			rv += child.all(seek_id)
+		end
 		
-		# set id
-		@id = id
+		# freeze return value
+		rv.freeze
 		
-		# initialize details
-		@details = details.clone
+		# return
+		return rv
 	end
 	#
-	# initialize
+	# all
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# to_h
+	# misc
 	#
 	
-	##
-	# Returns a hash structure of the message. This structure is used by
-	# Xeme#to_h.
+	# A handy place to puts miscellaneous information.
 	
-	def to_h
-		rv = {}
-		rv['id'] = @id
-		
-		if @details.any?
-			rv['details'] = @details
-		end
-		
-		return rv
+	def misc
+		@hsh['misc'] ||= {}
+		return @hsh['misc']
 	end
+	
 	#
-	# to_h
+	# misc
 	#---------------------------------------------------------------------------
-end
-#
-# Xeme::Message
-#===============================================================================
-
-
-#===============================================================================
-# Xeme::Messages
-#
-
-##
-# This object holds the arrays of errors, warnings, and notes. It can mostly be
-# treated like a hash. The main difference between a Xeme::Messages object and
-# a hash is that any? returns true or false based on if there are any messages,
-# not if there are any elements in the hash.
-
-class Xeme::Messages
-	# delegate to hsh
-	extend Forwardable
-	delegate %w([] []= each length keys has_key?) => :@hsh
+	
+	
+	# private
+	private
+	
 	
 	#---------------------------------------------------------------------------
-	# initialize
+	# as_arr
 	#
 	
-	##
-	# new() takes no parameters.
+	# Convenience function for reading messages as arrays even if they don't
+	# exist.
 	
-	def initialize
-		@hsh = {}
-		@hsh['errors'] = []
-		@hsh['warnings'] = []
-		@hsh['notes'] = []
+	def as_arr(key)
+		return @hsh[key] || []
 	end
 	#
-	# initialize
+	# as_arr
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# any?
+	# message
 	#
 	
-	##
-	# Returns if there are any messages in any of the errors, warnings, or
-	# notes arrays.
+	# Creates a message object of the given type.
 	
-	def any?
-		@hsh.values.each do |arr|
-			arr.any? and return true
+	def message(type, id, &block)
+		# build message
+		msg = {}
+		id and msg['id'] = id
+		
+		# add to array
+		@hsh[type] ||= []
+		@hsh[type].push msg
+		
+		# yield if necessary
+		if block_given?
+			yield msg
 		end
 		
-		return false
+		# return
+		return msg
 	end
 	#
-	# any?
+	# message
 	#---------------------------------------------------------------------------
-end
-#
-# Xeme::Messages
-#===============================================================================
-
-
-#===============================================================================
-# Xeme::Transaction
-#
-
-# An object of this class provides meta information about the request and
-# results. It always provides a timestamp and a unique ID for the results. It
-# may also optionally include a request ID that was provided by the process
-# that made the request, such as a call to a REST application. Do not directly
-# instantiate this class; use Xeme#transaction.
-
-class Xeme::Transaction
-	
-	# Optional. An ID for the request that was sent by the calling process. Do
-	# not generate this value yourself; use the ID that was sent with the
-	# request (if one was sent).
-	attr_accessor :request
 	
-	# Gives a unique ID for these results.
-	attr_accessor :response
-	
-	# Gives a timestamp for when these results were generated.
-	attr_accessor :timestamp
 	
 	#---------------------------------------------------------------------------
-	# initialize
+	# all_messages
 	#
 	
-	# Initialize does not take any parameters.
+	# Returns a locked array of all messages (including nested) or the given
+	# type.
 	
-	def initialize
-		@timestamp = DateTime.now()
-		@response = rand().to_s.sub(/\A0\./mu, '')
-		@request = nil
+	def all_messages(plural, id)
+		rv = []
+		
+		# add own messages
+		if @hsh[plural]
+			if id
+				@hsh[plural].each do |m|
+					if m['id'] == id
+						rv.push m
+					end
+				end
+			else
+				rv += @hsh[plural]
+			end
+		end
+		
+		# recurse
+		as_arr('nested').each do |child|
+			rv += child.send(plural, id)
+		end
+		
+		# freeze return value
+		rv.freeze
+		
+		# return
+		return rv
 	end
 	#
-	# initialize
+	# all_messages
 	#---------------------------------------------------------------------------
 	
 	
 	#---------------------------------------------------------------------------
-	# to_h
+	# messages_hash
 	#
-	def to_h
+	
+	# Returns a hash of the messages (including nested) of the given type. The
+	# keys to the hash are the message ids. Does not return messages that don't
+	# have ids.
+	
+	def messages_hash(type)
 		rv = {}
 		
-		# request
-		if @request
-			rv['request'] = @request
+		# add own messages
+		as_arr(type).each do |msg|
+			if msg['id']
+				rv[msg['id']] ||= []
+				rv[msg['id']].push msg
+			end
 		end
 		
-		# response and timestamp
-		rv['response'] = @response
-		rv['timestamp'] = @timestamp.to_s
+		# loop through nested children
+		as_arr('nested').each do |child|
+			child.send("#{type}_hash").each do |k, msgs|
+				rv[k] ||= []
+				rv[k] += msgs
+			end
+		end
 		
 		# return
 		return rv
 	end
 	#
-	# to_h
+	# messages_hash
 	#---------------------------------------------------------------------------
 end
 #
-# Xeme::Transaction
-#===============================================================================
-
-
-#===============================================================================
-# Xeme::Exception
-#
-
-# Xeme::Exception is a subclass of StandardError and can be used exactly like a
-# StandardError object. The one addition to StandardError is the `xeme` property
-# which holds a Xeme object. Don't instantiate this class directly; use
-# Xeme#new_exception.
-
-class Xeme::Exception < StandardError
-	attr_reader :xeme # a xeme object
-	
-	#---------------------------------------------------------------------------
-	# initialize
-	#
-	def initialize(error_code, xeme)
-		@error_code = error_code
-		@xeme = xeme
-		super @error_code
-	end
-	#
-	# initialize
-	#---------------------------------------------------------------------------
-end
-#
-# Xeme::Exception
-#===============================================================================
+# Xeme
+#===============================================================================