xeme 0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: d484d6f5c5b9cfdf0ae85dd4a1ca69c46b2b1c7eed711eae02352b59d3c929fe
+  data.tar.gz: e8d0a6527bafc7dff93ba1cd584a4527114e5dc3a40b165c3c86baf9ece744a2
+SHA512:
+  metadata.gz: 291925e898631853c7a64f49327954b0b1c309b73e330d511561dc5c017ae7b15ab51f0fc22264e5c800a80c59530733776eba813840c06e179fd7db221aa166
+  data.tar.gz: 13d3459ee59daf94a4bc2841ed308ec498b14f361ad8eb76abb0d919d44823ba2fdf4df19e3b93df89d54d3c0c9564fdaf408c6f7c60d352e22844a79746b4c1

data/README.md

@@ -0,0 +1,286 @@
+# Xeme
+
+Xeme provides a common format for returning the results of a process. In its
+simplest use, you create a Xeme object and add errors as necessary:
+
+    require 'xeme'
+    xeme = Xeme.new
+	xeme.error 'error-1'
+	
+If there are any errors, such as in this first example, <tt>success</tt> returns false:
+
+	puts xeme.success # false
+	
+A Xeme object without any errors returns true for <tt>success</tt>:
+	
+    xeme = Xeme.new
+	puts xeme.success # true
+
+Xeme is a good way to report results that are more complex than just success or
+failure. For example, consider the situation in which a record must have a name
+field and an email field. If the record does not meet these requirements, it is
+not sufficient to merely report success or failure, nor to just report that one
+field or the other is missing. With Xeme you can report all of that information
+in a single object:
+
+	xeme = Xeme.new
+	xeme.error 'name'
+	xeme.error 'email'
+
+You can return the Xeme object to another Ruby process, or you can output it to
+JSON for use in some other program:
+
+	puts xeme.to_json
+	
+    # outputs:
+	{"success":false,"messages":{"errors":[{"id":"name"},{"id":"email"}]}}
+	
+You might prefer to add the <tt>pretty</tt> option for more readable output:
+
+	puts xeme.to_json('pretty'=>true)
+	
+	# outputs:
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{
+					"id": "name"
+				},
+				{
+					"id": "email"
+				}
+			]
+		}
+	}
+
+In some situations, it's useful to give details about the error. For example,
+if the <tt>name</tt> field is too long, you can report not just that there is
+an error in that field, but specifics about that error:
+
+	xeme.error('name') do |msg|
+		msg['too-long'] = true
+		msg['max-length'] = 45
+	end
+
+That would produce a structure like this:
+
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{
+					"id": "name",
+					"details": {
+						"too-long": true,
+						"max-length": 45
+					}
+				}
+			]
+		}
+	}
+
+
+You can also add warnings and notes. A warning indicates a problem but not an
+actual failure. A note does not indicate any problem at all but just some
+information that should be passed along.
+
+	xeme.warning 'database-reset'
+	xeme.note 'database ok'
+
+It's often useful to add misc details to the results. For example, a database
+query might result in some rows from a table. You might add these rows to the
+<tt>misc</tt> property like this:
+
+	xeme = Xeme.new
+	xeme.misc['rows'] = []
+	xeme.misc['rows'].push 'a'
+	xeme.misc['rows'].push 'b'
+	xeme.misc['rows'].push 'c'
+	puts xeme.to_json('pretty'=>true)
+	
+	# outputs:
+	{
+		"success": true,
+		"misc": {
+			"rows": [
+				"a",
+				"b",
+				"c"
+			]
+		}
+	}
+
+Xeme can input a Xeme JSON structure to make a new Xeme object:
+
+	# json
+	json = <<~'JSON'
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{ "id": "location" }
+			]
+		}
+	}
+	JSON
+	
+	# xeme
+	xeme = Xeme.from_json(json)
+
+## Xeme structure
+
+The Xeme structure can be used by any software, Ruby or otherwise, as a standard
+way to report results. A Xeme structure can be stored in any format that
+recognizes hashes, arrays, strings, numbers, booleans, and null. Such formats
+include JSON and YAML. Xeme would be a good way for REST applications to
+provide results from a query. The Xeme#to_json method outputs such a structure.
+We'll use JSON for these examples. 
+
+An empty structure indicates success:
+
+	{}
+
+That structure indicates no messages such as errors, and no details. To make the
+structure easier to use by software that doesn't have a Xeme module, it is
+customary to also output an explicit indication of success or failure:
+
+	{"success":true}
+
+A Xeme structure can report any number of messages. A message is an error,
+warning, or note. An error indicates that the process failed, and gives a resaon
+why. If there are any errors, the process is considered a failure. A warning
+indicates a problem, but not an actual failure. A note reports useful
+information that does not indicate any kind of problem at all. Neither a warning
+nor a note cause failure.
+
+Messages, if any, are stored in a messages hash, which consists of arrays for
+errors, warnings, and notes. 
+
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{
+					"id": "missing-city"
+				}
+			],
+			"warnings": [
+				{
+					"id": "database-reset"
+				}
+			],
+			"notes": [
+				{
+					"id": "database-online"
+				}
+			]
+		}
+	}
+
+Any number of messages can be reported. So, for example, the following structure
+has two errors and no warnings or notes.
+
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{
+					"id": "missing-city"
+				}
+				],
+				"warnings": [
+				{
+					"id": "missing-zip-code"
+				}
+			]
+		}
+	}
+
+A message can have associated details. For example, the following error
+indicates that the problem with the name field is that it's too long, and the
+maximum length is 45:
+
+	{
+		"success": false,
+		"messages": {
+			"errors": [
+				{
+					"id": "name",
+					"details": {
+						"too-long": true,
+						"max-length": 45
+					}
+				}
+			]
+		}
+	}
+
+Sometimes it is useful to add arbitrary information to the results. For example,
+the results from a database query might return the rows that the query produced.
+In that situation, the misc element is handy.
+
+	{
+		"success": true,
+		"misc": {
+			"rows": [
+				"Fred",
+				"Mary",
+				"Jane"
+			]
+		}
+	}
+
+Sometimes it is useful to provide information about the specific transaction,
+e.g. the call to a REST server. The transaction element can be used to provide
+that information. If there is a transaction element, it should always provide a
+timestamp for the transaction and a unique ID for it.
+
+	{
+		"success": true,
+			"transaction": {
+				"response": "08214643960776591",
+				"timestamp": "2020-01-07T18:41:37+00:00"
+			}
+	}
+
+If the request includes an ID for that specific request, then that ID can be
+supplied as part of the transaction element:
+
+	{
+		"success": true,
+		"transaction": {
+			"request": "64e57c8a-bd3e-47b9-9221-e9e3e0263341",
+			"response": "3301315461336113",
+			"timestamp": "2020-01-07T18:42:01+00:00"
+		}
+	}
+
+The general adoption of the Xeme structure could simplify implementing
+interoperable applications such as REST APIs.
+
+## The name
+
+The word "xeme" has no particular association with the concept of results
+reporting. I got the word from a random word generator and I liked it. The xeme,
+also known as Sabine's gull, is a type of gull. See
+[the Wikipedia page](https://en.wikipedia.org/wiki/Sabine's_gull)
+if you'd like to know more.
+
+## Install
+
+```
+gem install xeme
+```
+
+## Author
+
+Mike O'Sullivan
+mike@idocs.com
+
+## History
+
+| version | date        | notes           |
+|---------|-------------|-----------------|
+| 0.1     | Jan 7, 2020 | Initial upload. |
+

data/lib/xeme.rb

@@ -0,0 +1,613 @@
+require 'date'
+require 'json'
+require 'forwardable'
+
+#===============================================================================
+# Xeme
+#
+
+##
+# Objects of this class represent a set of results. See the README file for
+# more details.
+
+class Xeme
+	# Version 0.1
+	VERSION = '0.1'
+	
+	# A Xeme::Messages object, which is basically just a hash containing arrays
+	# for errors, warnings, and notes.
+	attr_reader :messages
+	
+	# A hash of any miscellaneous details you want to include.
+	attr_reader :misc
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	##
+	# new() does not take any parameters.
+	
+	def initialize
+		# initialize errors, warnings, notes, misc
+		@messages = Xeme::Messages.new
+		@misc = {}
+		
+		# prefix and auto_misc
+		@prefixes = []
+		@auto_details_val = nil
+		
+		# transaction
+		@transaction = nil
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# errors, warnings, notes
+	#
+	
+	##
+	# Returns the array of errors.
+	def errors
+		return @messages['errors']
+	end
+	
+	##
+	# Returns the array of warnings.
+	def warnings
+		return @messages['warnings']
+	end
+	
+	##
+	# Returns the array of notes.
+	def notes
+		return @messages['notes']
+	end
+	#
+	# errors, warnings, notes
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# transaction
+	#
+	
+	##
+	# 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
+	
+	def transaction
+		@transaction ||= Xeme::Transaction.new()
+		return @transaction
+	end
+	#
+	# transaction
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_h
+	#
+	
+	##
+	# 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.
+	
+	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_h
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_json
+	#
+	
+	##
+	# 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
+	end
+	#
+	# to_json
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# success
+	#
+	
+	##
+	# Returns false if there are any errors, true otherwise.
+	
+	def success		
+		return @messages['errors'].empty?
+	end
+	
+	##
+	# Returns the opposite of <tt>success()</tt>.
+	def failure
+		return success ? false : true
+	end
+	
+	#
+	# success
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# exception
+	#
+	
+	##
+	# Use this method to hold on to details about an exception. An error object
+	# will be created, along with the exception's to_s backtrace.
+	
+	def exception(id, e, details={})
+		message = self.error(id, details)
+		message.details['error'] = e.to_s
+		message.details['backtrace'] = e.backtrace
+	end
+	#
+	# exception
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# prefix
+	#
+	
+	##
+	# <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
+	
+	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
+	#
+	# prefix
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# error, warning, note
+	#
+	
+	##
+	# 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)
+	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)
+	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)
+	end
+	#
+	# error, warning, note
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# from_json
+	#
+	
+	##
+	# Creates a new Xeme object from a JSON structure.
+	
+	def self.from_json(raw_json)
+		# $tm.hrm
+		hsh = JSON.parse(raw_json)
+		rv = self.new
+		
+		# explicit success or failure
+		if not hsh['success'].nil?
+			rv.success = hsh['success']
+		end
+		
+		# messages
+		if messages = hsh['messages']
+			messages.each do |msg_type, arr|
+				rv.messages[msg_type] ||= []
+				rv.messages[msg_type] += arr
+			end
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# from_json
+	#---------------------------------------------------------------------------
+	
+	
+	# private methods
+	private
+
+	
+	#---------------------------------------------------------------------------
+	# messages_to_h
+	#
+	def messages_to_h(arr)
+		rv = []
+		
+		# messages
+		arr.each do |msg|
+			rv.push msg.to_h
+		end
+		
+		# return
+		return rv
+	end
+	#
+	# messages_to_h
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# add_comment
+	#
+	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
+	#
+	# add_comment
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# prefix_id
+	#
+	def prefix_id(p_id)
+		if @prefixes.any?
+			return '/' + @prefixes.join('/') + '/' + p_id
+		else
+			return p_id
+		end
+	end
+	#
+	# prefix_id
+	#---------------------------------------------------------------------------
+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
+	
+	# delegate to hsh
+	extend Forwardable
+	delegate %w([] []= each length clear delete) => :@details
+	
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	# 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.
+	
+	def initialize(id, details={})
+		# $tm.hr __method__
+		
+		# set id
+		@id = id
+		
+		# initialize details
+		@details = details.clone
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_h
+	#
+	
+	##
+	# Returns a hash structure of the message. This structure is used by
+	# Xeme#to_h.
+	
+	def to_h
+		rv = {}
+		rv['id'] = @id
+		
+		if @details.any?
+			rv['details'] = @details
+		end
+		
+		return rv
+	end
+	#
+	# to_h
+	#---------------------------------------------------------------------------
+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
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	##
+	# new() takes no parameters.
+	
+	def initialize
+		@hsh = {}
+		@hsh['errors'] = []
+		@hsh['warnings'] = []
+		@hsh['notes'] = []
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# any?
+	#
+	
+	##
+	# Returns if there are any messages in any of the errors, warnings, or
+	# notes arrays.
+	
+	def any?
+		@hsh.values.each do |arr|
+			arr.any? and return true
+		end
+		
+		return false
+	end
+	#
+	# any?
+	#---------------------------------------------------------------------------
+end
+#
+# Xeme::Messages
+#===============================================================================
+
+
+#===============================================================================
+# Xeme::Transaction
+#
+
+##
+# An object of this class provdes meta information about the request and
+# results. It always provides a 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_reader :response
+	
+	# Gives a timestamp for when these results were generated.
+	attr_reader :timestamp
+	
+	#---------------------------------------------------------------------------
+	# initialize
+	#
+	
+	##
+	# Initialize does not take any parameters.
+	
+	def initialize
+		@timestamp = DateTime.now()
+		@response = rand().to_s.sub(/\A0\./mu, '')
+		@request = nil
+	end
+	#
+	# initialize
+	#---------------------------------------------------------------------------
+	
+	
+	#---------------------------------------------------------------------------
+	# to_h
+	#
+	def to_h
+		rv = {}
+		
+		# request
+		if @request
+			rv['request'] = @request
+		end
+		
+		# response and timestamp
+		rv['response'] = @response
+		rv['timestamp'] = @timestamp.to_s
+		
+		# return
+		return rv
+	end
+	#
+	# to_h
+	#---------------------------------------------------------------------------
+end
+#
+# Xeme::Transaction
+#===============================================================================

metadata

@@ -0,0 +1,45 @@
+--- !ruby/object:Gem::Specification
+name: xeme
+version: !ruby/object:Gem::Version
+  version: '0.1'
+platform: ruby
+authors:
+- Mike O'Sullivan
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-01-06 00:00:00.000000000 Z
+dependencies: []
+description: Provides a common means for reporting results between processes
+email: mike@idocs.com
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- README.md
+- lib/xeme.rb
+homepage: https://rubygems.org/gems/xeme
+licenses:
+- MIT
+metadata: {}
+post_install_message: 
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.7.6
+signing_key: 
+specification_version: 4
+summary: General purpose structure for reporting results
+test_files: []