xeme 0.3.1 → 1.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 1413d7abd0e3cbfa5bebfad9dd795b007df52d93b177ab7233fbafc4bdd79c98
-  data.tar.gz: bad5d9f7de703c07d092a88f68ab97f5dbf01eae52ebdebc4632c611c5c3656d
+  metadata.gz: 2dd9c9b62b1d0d2f4db4657ff6880cea68476a47ca4e366da77eab004d5ad71f
+  data.tar.gz: b15afd00d574e1382597d43df90f50668e0c8a651f2623ab5447af0d717bd404
 SHA512:
-  metadata.gz: 03d58e05f1544a1b68400bfb76be1ae38e880b3e4bde7c4e0894591b83015d9eee26b81803b96910cc045e06045adc75943798a42a3ceeeaa9c3600dd6d8305a
-  data.tar.gz: 674de2ab9106711fef9c123e68ddba3cc4293f3d8a3f1c2c7032e361e0864005e4c2a047e41df1eba98419d92a6420095fcfc27f36d3bac6c88f2e7a0eb3dd1d
+  metadata.gz: 800b710d55a2745c7591a8c5867c5b97125750d525b9ed941f8826093c60efac36f03a135ca9104728ffe849351d176f257a0dc13382a25a87b5d2e9f553653f
+  data.tar.gz: 90c33ffa2e86e06895176ce1a16aa06fef19991fb0c7fbcadc8cb79f9480d6fc4ee1764e162d8b5e3e00993c07523926d38befb74c1a3b9ef22193b968eb64ff

data/README.md

@@ -1,263 +1,362 @@
 # 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 provides a common format for returning the results of a process. First
+we'll look at the Xeme format, which is language independent, then we'll look at
+how the Xeme gem implements the format.
+
 
 ## 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.
+include JSON and YAML. In these examples we'll use JSON.
+
+A xeme can be as simple as an empty hash:
+
+```json
+{}
+```
+
+That structure indicates no errors, and, in fact, no details at all. However, it
+also does not explicitly indicate success, so that xeme would be considered to
+have failed.
+
+To indicate a successful operation, a xeme must have an explicit `success`
+element:
+
+```json
+{"success":true}
+```
+
+A xeme can be marked as explicitly failed:
+
+```json
+{"success":false}
+```
+
+If a xeme does not have an explicit `success` element, or it is set to `nil`, it
+should be considered to have failed. However, depending on how you process the
+xeme, `nil` could be considered as having not finished the test. In that case,
+consider using [promises](#promises).
+
+### Messages
+
+A message is an error, a warning, a note, or a promise. Each type of message has
+an array. For example, this xeme has two errors:
+
+```json
+{ "errors":[{"id":"http-fault"}, {"id":"transaction-error"}] }
+```
+
+A message does not have to have any particular structure, but best practice is
+to give each message an identifier (`id`).
+
+If there are any errors then that indicates a failure, regardless of the value
+of `success`. Any implementation of Xeme should have a method for resolving
+conflicts between `success` and `errors`, always giving priority to the presence
+of errors over the value of `success`.
+
+If a xeme has any promises then that indicates not success, though not
+necessarily explicit failure. If a xeme is marked as successful, but there are
+promises, then `success` should be considered nil.
+
+Warnings indicate problems that don't outright cause a failure. Notes are
+messages that don't indicate a problem of any kind.
+
+### Metainformation
+
+Sometimes it's useful to store metainformation the xeme. For example, log files
+are more discoverable if each xeme has a unique id and timestamp. Generally a
+xeme will have at least to elements, `uuid` and `timestamp`:
+
+```json
+{
+   "meta":{
+      "uuid":"dae1cf26-e8fa-43fa-bedc-88fea10255f4",
+      "timestamp":"2023-05-25 03:46:19 -0400"
+   }
+}
+```
+
+### Nested xemes
+
+A xeme can have nested xemes within it. Those nested xemes go in the `nested`
+array:
+
+```json
+{
+   "nested": [
+      { "success": true },
+      { "errors": [{"id":"server-fault"}] },
+   ]
+}
+```
+
+For a xeme to be considered successful, all of its nested xemes must be marked
+as success. If any nested xemes have errors, then the outermost xeme is
+considered to be considered as failed. If any nested xemes has `success` as nil,
+then the outermost xeme cannot `success` as true, though it can be explicitly
+false.
+
+## Xeme gem
+
+### Install
+
+The usual:
+
+```sh
+gem install xeme
+```
+
+### Using the Xeme gem
+
+Xeme (the gem) is a thin layer over a hash that implements the Xeme format. (For
+the rest of this document "Xeme" refers to the Ruby class, not the format.)
+Create a new xeme by instantiating the Xeme class. Instantiation has no required
+parameters.
+
+```ruby
+require 'xeme'
+xeme = Xeme.new
+puts xeme # => #<Xeme:0x000055586f1340a8>
+```
+
+Sometimes it's handy to give a xeme an identifier. You can do that by passing in
+a string in `Xeme.new`.
+
+```ruby
+xeme = Xeme.new('my-xeme')
+puts xeme.id # => my-xeme
+```
+
+If you want to access the hash stored in the xeme object, you can use the object
+as if it were a hash.
+
+```ruby
+xeme['errors'] = []
+xeme['errors'].push({'id'=>'my-error'})
+```
+
+#### Success and failure
+
+Because a xeme isn't considered successful until it has been explicitly declared
+so, a new xeme is considered to indicate failure. However, because there are no
+errors and `success` has not been explicitly set, `success?` returns `nil`
+instead of `false`.
+
+```ruby
+xeme = Xeme.new
+puts xeme.success?.class # => NilClas
+```
+
+There are two ways to mark a xeme as successful, one of which usually the better
+choice. The not-so-good way to mark success is with the `succeed` method.
+
+```ruby
+xeme = Xeme.new
+xeme.succeed
+puts xeme.success?  # => true
+```
+
+The problem with `succeed` is that if there are errors, `succeed` will raise an
+exception.
+
+```ruby
+xeme = Xeme.new
+xeme.error 'my-error'
+xeme.succeed # => raises exception: `succeed': cannot-set-to-success: errors
+```
+
+A better option is `try_succeed`. If your script gets to a point, usually at the
+end of the function or script, that you want to set the xeme to success, but
+only if there are no errors, use `try_succeed`.
+
+```ruby
+xeme = Xeme.new
+xeme.try_succeed
+puts xeme.success? # => true
+```
+
+If there are errors, `try_succeed` won't raise an exception, but will not set
+the xeme to failure.
+
+```ruby
+xeme = Xeme.new
+xeme.error 'my-error'
+xeme.try_succeed
+puts xeme.success? # => false
+```
+
+#### Creating and using messages
+
+Messages in a xeme provide a way to indicate errors (i.e. fatal errors),
+warnings (non-fatal errors), notes (not an error at all), and promises (guides
+to getting the final success or failure of the process). A message is a hash
+with whatever arbitrary information you want to add. Each type of message has
+its own method for creating it, an array for storing them, and methods for
+checking if any exist. The following script creates an error, a warning, a
+note, and a promise.
+
+```ruby
+xeme = Xeme.new
+xeme.error 'my-error'
+xeme.warning 'my-warning'
+xeme.note 'my-note'
+xeme.promise 'my-promise'
+```
+
+`error`, `warning`, and `note` each create a message for their own type.
+Although it is not required, it's usually a good idea to give a string as the
+first parameter. That string will be set to the `id` element in the resulting
+hash, as seen in the example above.
+
+`errors`, `warnings`, and `notes` return arrays for each type.
+
+```ruby
+xeme.errors.each do |e|
+   puts e['id'] # => my-error
+end
+
+xeme.warnings.each do |w|
+   puts w['id'] # => my-warning
+end
+
+xeme.notes.each do |n|
+   puts n['id'] # => my-note
+end
+
+xeme.promises.each do |p|
+   puts p['id'] # => my-promise
+end
+```
+
+**Gotcha:** These methods return frozen arrays, *not* the arrays in the xeme.
+This is because these methods return not only the xeme's own message arrays, but
+also any nested messages. See [Nesting xemes](#nesting-xemes) below.
+
+There are several ways to create and populate a message. Choose whichever is
+preferable to you. One way is demonstrated in the example above. You simply call
+the appropriate method, passing in an identifier. If all you want to do is
+create a message with an `id` then that's probably the easiest choice.
+
+Another way to use a `do` block to add custom information to the message.
+
+```ruby
+xeme.error('my-error') do |error|
+   error['database-error'] = 'some database error'
+   error['commands'] = ['a', 'b', 'c']
+end
+```
+
+Remember a message is just a hash, so you can add any kind of structure to the
+hash you want such a strings, booleans, hashes, and arrays.
+
+Finally, the message command returns the new message. So, if you want, you can
+assign that return value to a variable and work with the message that way.
+
+```ruby
+err = xeme.error('my-error')
+err['database-error'] = 'some database error'
+err['commands'] = ['a', 'b', 'c']
+```
+
+#### Nesting xemes
+
+In complex testing situations it can be useful to nest results within other
+results. To nest a xeme within another xeme, use the `#nest` method:
+
+```ruby
+xeme = Xeme.new('results')
+xeme.nest 'child-xeme'
+```
+
+You probably want to do something more than just create a nested xeme, so you
+can use a `do` block to work with the nested xeme:
+
+```ruby
+xeme.nest('child-xeme') do |child|
+   child.error 'child-error'
+end
+```
+
+You can loop through all xemes, including the outermost xeme and all nested
+xemes, using the `#all` method.
+
+```ruby
+xeme.all.each do |x|
+   puts x.id
+end
+```
+
+**Nested messages**
+
+The `#errors`, `#warnings`, `#notes`, and `#promises` methods return arrays of
+all messages within the xeme, including the outermost xeme and nested xemes.
+
+```ruby
+xeme = Xeme.new
+xeme.error 'outer-error'
+
+xeme.nest do |child|
+   child.error 'child-error'
+end
+
+puts xeme.errors
+
+# => {"id"=>"outer-error"}
+# => {"id"=>"child-error"}
+```
+
+If you want to search for messages with a specific `id`, add that id to the
+messages method:
+
+```ruby
+puts xeme.errors('child-error') # => {"id"=>"child-error"}
+```
+
+**Flatten**
+
+Finally, if you want to slurp up all messages into the outermost xeme and delete
+the nested xemes, use `#flatten`.
+
+```ruby
+puts xeme['errors']
+# => {"id"=>"outer-error"}
+
+xeme.flatten
+
+puts xeme['errors']
+# => {"id"=>"outer-error"}
+# => {"id"=>"child-error"}
+```
+
+
+#### Resolving xemes
+
+A xeme can contain contradictory information. For example, if `success` is true
+but there are errors, then the xeme should be considered as failed. If there are
+promises, then the xeme should not be considered as failed, although `success`
+may be set as nil.
+
+The `#resolve` method resolves those contradictions. Generally you won't have to
+call `#resolve` yourself, but it's worth understanding the rules:
+
+* A xeme can always be explicitly set to false, regardless of any other
+considerations. Resolution never changes a `success` of false.
+
+* If any nested xemes have `success` explicitly set to false, then the outermost
+xeme will be set to false.
+
+* If a xeme has errors, or any of it's nested xemes has errors, then it is set
+to false.
+
+* If a xeme has promises, or any of its nested xemes do, then it cannot be set
+to true. If it is already false, then it stays false. Otherwise `success` is set
+to nil.
+
+* If any nested xemes have `success` set to nil, then the outermost xeme cannot
+be set to true.
 
 ## The name
 
@@ -267,12 +366,6 @@ 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
@@ -283,5 +376,4 @@ mike@idocs.com
 | version | date         | notes                         |
 |---------|--------------|-------------------------------|
 | 0.1     | Jan 7, 2020  | Initial upload.               |
-| 0.2     | Jan 8, 2020  | Fixed bug in exception()      |
-| 0.3     | Jan 19, 2020 | Fixed bug in Xeme.from_json() |
+| 1.0     | May 29, 2023 | Complete overhaul. Not backward compatible. |