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

messages[R]

A Xeme::Messages object, which is basically just a hash containing arrays for errors, warnings, and notes.

misc[R]

A hash of any miscellaneous details you want to include.

Public Class Methods

from_json(raw_json) click to toggle source

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() click to toggle source

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

error(id, details={}, &block) click to toggle source

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

errors() click to toggle source

Returns the array of errors.

# File lib/xeme.rb, line 47
def errors
        return @messages['errors']
end

failure() click to toggle source

Returns the opposite of success().

# File lib/xeme.rb, line 178
def failure
        return success ? false : true
end

new_exception(error_id) click to toggle source

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

note(id, details={}, &block) click to toggle source

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

notes() click to toggle source

Returns the array of notes.

# File lib/xeme.rb, line 59
def notes
        return @messages['notes']
end

prefix(p_prefix) { || ... } click to toggle source

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

save_exception(id, e, details={}) click to toggle source

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

success() click to toggle source

Returns false if there are any errors, true otherwise.

# File lib/xeme.rb, line 172
def success            
        return @messages['errors'].empty?
end

to_h() click to toggle source

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

to_json(opts={}) click to toggle source

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

transaction() click to toggle source

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

warning(id, details={}, &block) click to toggle source

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

warnings() click to toggle source

Returns the array of warnings.

# File lib/xeme.rb, line 53
def warnings
        return @messages['warnings']
end

Private Instance Methods

add_comment(cls, type, id, details={}) { |msg| ... } click to toggle source

# 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

messages_to_h(arr) click to toggle source

# 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

prefix_id(p_id) click to toggle source

# 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