class Xeme
Objects of this class represent a set of results. See the README file for more details.
Constants
- VERSION
version 0.3.1
Attributes
A Xeme::Messages
object, which is basically just a hash containing arrays for errors, warnings, and notes.
A hash of any miscellaneous details you want to include.
Public Class Methods
Creates a new Xeme
object from a JSON structure.
# File lib/xeme.rb, line 309 def self.from_json(raw_json) # $tm.hrm hsh = JSON.parse(raw_json) rv = self.new # 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 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 end # return return rv end
new() does not take any parameters.
# File lib/xeme.rb, line 29 def initialize @messages = Xeme::Messages.new @misc = {} @prefixes = [] @auto_details_val = nil @transaction = nil end
Public Instance Methods
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
# File lib/xeme.rb, line 283 def error(id, details={}, &block) return add_comment(Xeme::Message, 'errors', id, details={}, &block) end
Returns the array of errors.
# File lib/xeme.rb, line 47 def errors return @messages['errors'] end
Returns the opposite of success()
.
# File lib/xeme.rb, line 178 def failure return success ? false : true end
Creates and returns a Xeme::Exception
object. The Xeme
object is attached to the Xeme::Exception
object.
# File lib/xeme.rb, line 359 def new_exception(error_id) return Xeme::Exception.new(error_id, self) end
Works just error()
except it stores the message in the notes array.
# File lib/xeme.rb, line 295 def note(id, details={}, &block) return add_comment(Xeme::Message, 'notes', id, details={}, &block) end
Returns the array of notes.
# File lib/xeme.rb, line 59 def notes return @messages['notes'] end
prefix
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 prefix
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
# File lib/xeme.rb, line 240 def prefix(p_prefix) # $tm.hrm hold_prefixes = @prefixes.clone @prefixes = @prefixes.clone @prefixes.push p_prefix begin yield ensure @prefixes = hold_prefixes end end
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.
# File lib/xeme.rb, line 194 def save_exception(id, e, details={}) message = self.error(id, details) message['error'] = e.to_s message['backtrace'] = e.backtrace end
Returns false if there are any errors, true otherwise.
# File lib/xeme.rb, line 172 def success return @messages['errors'].empty? end
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.
# File lib/xeme.rb, line 105 def to_h # $tm.hrm # initialize return value rv = {} # success rv['success'] = success() # transaction if @transaction rv['transaction'] = @transaction.to_h end # if any messages if @messages.any? msgs = rv['messages'] = {} @messages.each do |key, arr| if arr.any? msgs[key] = [] arr.each do |msg| msgs[key].push msg.to_h end end end end # misc if @misc.any? rv['misc'] = @misc end # return return rv end
Returns a JSON string containing all the result information.
# File lib/xeme.rb, line 153 def to_json(opts={}) if opts['pretty'] return JSON.pretty_generate(self.to_h) else return JSON.generate(self.to_h) end end
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.
You can create the transaction object by simply calling this method:
xeme.transaction
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:
xeme.transaction.request = request.id
# File lib/xeme.rb, line 88 def transaction @transaction ||= Xeme::Transaction.new() return @transaction end
Works just error()
except it stores the message in the warnings array.
# File lib/xeme.rb, line 289 def warning(id, details={}, &block) return add_comment(Xeme::Message, 'warnings', id, details={}, &block) end
Returns the array of warnings.
# File lib/xeme.rb, line 53 def warnings return @messages['warnings'] end
Private Instance Methods
# File lib/xeme.rb, line 393 def add_comment(cls, type, id, details={}, &block) # $tm.hrm # build message msg = cls.new(prefix_id(id), details) # ensure array @messages[type] ||= [] # add to errors array @messages[type].push(msg) # yield if block_given? yield msg end # return return msg end
# File lib/xeme.rb, line 374 def messages_to_h(arr) rv = [] # messages arr.each do |msg| rv.push msg.to_h end # return return rv end
# File lib/xeme.rb, line 421 def prefix_id(p_id) if @prefixes.any? return '/' + @prefixes.join('/') + '/' + p_id else return p_id end end