xeme 1.2 → 2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: cdf9cdb30bbab1fe3155496c778a01c83fb35c011bb9d00c63525fffa1c5cec8
-  data.tar.gz: aa5b17da3d91e1ab8940aa84ff38dd4fcbe5d274acebcb7483c4bf9221ed6dca
+  metadata.gz: ae47399bb72561b8d7d6efedeb37e43840269d5fb6ab686bdfc31499ee3595e8
+  data.tar.gz: 83c15744b30011cfd1cac0ee53771ee790f34a15b5983af1763b65000109bc64
 SHA512:
-  metadata.gz: 98eab45cddd377c4a3c81d1de8c800e169b360fbe0451402256e57c18e412c971f6eef059795ad54134297228757728561e730a33271e932574d198028976f99
-  data.tar.gz: 1200e1c8b64b5233c102e83414499fdc39db85df7d5cf071caee830a5e218a29c94f590b6d44b8ed2266d8c6fb5b34ee9112d2d7eeb97201a9d49fc57225bd0b
+  metadata.gz: 3486a1a926faea61cb880dba644cf8619c8615bdf22af79e37ab5a3777907eb0c20f81532f215d42be8cfb7dbaf0773f80cbf6b5f9f42c50a6d4bc781a1f26c8
+  data.tar.gz: 21e10be699393ea20c8e6bcd488f66d9f05647aa6f8c6c51a0b8ea6072ecea4f51a4920061fbd9b2f53d98766fd103048937dcb1386952486b8e505d3a21fec2

data/README.md

@@ -19,8 +19,8 @@ A xeme can be as simple as an empty hash:
 ```
 
 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.
+also does not explicitly indicate success. In the absence of a defined value of
+true or false, the result should be considered either undetermined or failed.
 
 To indicate a successful operation, a xeme must have an explicit `success`
 element:
@@ -35,69 +35,235 @@ A xeme can be marked as explicitly failed:
 {"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).
+Any truthy value for `success` is considered to indicate success. So, for
+example, the following xeme should be considered to indicate success.
 
-### Messages
+```json
+{"success":{}}
+```
 
-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:
+A xeme may contain other arbitrary information. This is useful if you need more
+information than just a success or failure.
 
 ```json
-{ "errors":[{"id":"http-fault"}, {"id":"transaction-error"}] }
+{"success":true, "tags":["a", "b"]}
 ```
 
-A message does not have to have any particular structure, but best practice is
-to give each message an identifier (`id`).
+### Metainformation
 
-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`.
+A xeme may contain a `meta` element. The `meta` element can contain a timestamp,
+UUID, description, or other meta information.
 
-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.
+```json
+{
+  "success":true,
+  "meta": {
+    "timestamp": "2023-06-21T08:57:56+00:00",
+    "uuid": "e11b668c-0823-4b70-aa28-5ac83757a37c",
+    "description": "directory tests"
+  }
+}
+```
 
-Warnings indicate problems that don't outright cause a failure. Notes are
-messages that don't indicate a problem of any kind.
+`meta` can contain any arbitrary information you want, but several elements, if
+present, should follow some standards.
 
-### Metainformation
+| key         | description                                  |
+|-------------|----------------------------------------------|
+| id          | A string, typically without spaces.          |
+| description | A short description of the xeme as a string. |
+| timestamp   | Timestamp in a standard ISO 8601 format.     |
+| UUID        | A UUID.                                      |
+
+### Nested xemes
+
+A xeme represents the results of a single process. However, a xeme can also
+contain nested xemes which provide information about sub-processes. In this
+sense, a xeme can be considered as the final results of the xemes nested within
+it.
 
-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`:
+Child xemes are contained in the `nested` array.
 
 ```json
 {
-   "meta":{
-      "uuid":"dae1cf26-e8fa-43fa-bedc-88fea10255f4",
-      "timestamp":"2023-05-25 03:46:19 -0400"
-   }
+  "success":true,
+  "meta": {"id":"directory"},
+  "nested":[
+    {"success":true, "meta": {"id":"database-connection"}},
+    {"success":true, "meta": {"id":"update"}}
+  ]
 }
 ```
 
-### Nested xemes
+Nested xemes can themselves have nested xemes, forming a tree of process
+results.
+
+```json
+{
+  "success":true,
+  "meta": {"id":"database"},
+  "nested": [
+    {
+      "success":true,
+      "meta": {"id":"database-connection"},
+      "nested": [
+        {"success":true, "meta":{"id":"initialization"}},
+        {"success":true, "meta":{"id":"disconnection"}}
+      ]
+    }
+  ]
+}
+```
+
+### Resolution
+
+Xeme operates on the concept of "least successful outcome". A xeme cannot
+represent more success than its descendent xemes. So, for example, the following
+structure contains conflicts:
+
+```json
+{
+  "success":true,
+  "nested":[
+    {"success":false}
+  ]
+}
+```
+
+It is necessary to resolve these conflicts before the xeme can be considered
+valid. A conforming processor should implement the following rules:
+
+* If a xeme is marked as failure, all of its ancestor xemes should be marked
+as failed. So the example above would be resolved as follows:
+
+```json
+{
+  "success":false,
+  "nested":[
+    {"success":false}
+  ]
+}
+```
+
+A process can be marked as failed regardless of its nested xemes. So there is no
+conflict in the following structure.
+
+```json
+{
+  "success":false,
+  "nested":[
+    {"success":true}
+  ]
+}
+```
+
+* If a xeme's `success` is null, then all its ancestors' `success` values must
+be set to null if they are not already set to false. The following structure is
+invalid.
+
+```json
+{
+  "success":true,
+  "nested":[
+    {"success":null}
+  ]
+}
+```
+
+It should be resolved as follows:
+
+```json
+{
+  "success":null,
+  "nested":[
+    {"success":null}
+  ]
+}
+```
+
+### Advisory and promise xemes
+
+Three types of Xemes operate on a different ruleset than standard xemes. Those
+types are warnings, notes, and promises. They are indicated by the `type`
+property:
+
+```json
+{"type": "warning"}
+```
+
+#### Warnings and notes
+
+Warnings and notes provide advisory information about a process. They have no
+affect on the success/failure determination. Warnings provide information about
+non-fatal problems in a prosess. Notes do not indicate problems of any kind and
+simply provide whatever arbitrary information might be useful. Advisory xemes
+should not have `success` properties. So, for example, the following structure
+is valid, even though the nested advisory xemes do not have `success`
+properties.
+
+```json
+{
+  "success":true,
+  "nested":[
+    {"type":"warning", "id":"invalid-setting"},
+    {"type":"note", "id":"database-connected"}
+  ]
+}
+```
+
+Advisory xemes can have nested xemes. However, all descendents of an advisory
+xeme should themselves be advisory.
+
+#### Promises
+
+A promise xeme indicates that the success/failure of a process has yet to be
+determined. A promise should have a `success` value of null, unless it has also
+has a truthy value in `supplanted`. For example, the following xemes are valid:
+
+```json
+{ "type":"promise" }
+```
+
+```json
+{ "type":"promise", "supplanted":true, "success": true }
+```
+
+```json
+{ "type":"promise", "supplanted":"2023-06-22T06:28:43+0000", "success": true }
+```
 
-A xeme can have nested xemes within it. Those nested xemes go in the `nested`
-array:
+Typically, a promise should have an indication of how the promise can be
+resolved. For example, the following xeme is a promise, with further information
+to indicate a URI where the final result can be determined, and how soon to
+query that URI.
 
 ```json
 {
-   "nested": [
-      { "success": true },
-      { "errors": [{"id":"server-fault"}] },
-   ]
+  "type":"promise",
+  "uri": "https://example.com/20435t",
+  "delay": 6000
 }
 ```
 
-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.
+No standards are defined on how promises should provide such information. A
+substandard may be defined down the road.
+
+Best practice is that when a promise xeme is supplanted, it should have a nested
+xeme that provides the final success/failure of the process.
+
+```json
+{
+  "success": true,
+  "supplanted": true,
+  "type":"promise",
+  "uri": "https://example.com/20435t",
+  "delay": 6000,
+  
+  "nested": [
+    {"success":true}
+  ]
+}
+```
 
 ## Xeme gem
 
@@ -105,8 +271,8 @@ false.
 
 The usual:
 
-```sh
-gem install xeme
+```bash
+sudo gem install xeme
 ```
 
 ### Basic Xeme concepts
@@ -122,14 +288,6 @@ 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.
 
@@ -141,36 +299,30 @@ 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`.
+so, a new xeme is considered to indicate failure or lack of determination of
+success/failure.
 
 ```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.
+To set a xeme to indicate failure, use the `fail` method.
 
 ```ruby
 xeme = Xeme.new
-xeme.succeed
-puts xeme.success?  # => true
+xeme.fail
+puts xeme.success? # => false
 ```
 
-The problem with `succeed` is that if there are errors, `succeed` will raise an
-exception.
+Perhaps counter-intuitively, there is no `succeed` method. That's because a xeme
+cannot be reliably marked as succeeding without checking nested xemes (see
+[resolution](#resolution)).
 
-```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`.
+Instead there is a `try_succeed` method. As its name implies, that method
+resolves the xeme and its descendents, only marking the xeme as successful if
+resolution allows. We'll get more into handling nested xemes later. The
+following example shows setting a single xeme to success using `try_succeed`.
 
 ```ruby
 xeme = Xeme.new
@@ -178,217 +330,144 @@ 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.
+`try_succeed` will only set a xeme to success if the current success is null or
+true. It will not override an explicit setting of false.
 
 ```ruby
 xeme = Xeme.new
-xeme.error 'my-error'
+xeme.fail
 xeme.try_succeed
 puts xeme.success? # => false
 ```
 
-### Creating and using messages
+### Nesting xemes
 
-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.
+Use `nest` to create nested xemes. If a block is sent, `nest` yields the new
+xeme.
 
 ```ruby
-xeme = Xeme.new
-xeme.error 'my-error'
-xeme.warning 'my-warning'
-xeme.note 'my-note'
-xeme.promise 'my-promise'
+xeme.nest() do |child|
+  # do stuff with nested xeme
+end
 ```
 
-`#error`, `#warning`, `#note`, and `#promise` 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.
+`nest` also returns the new xeme.
+
+```ruby
+child = xeme.nest()
+```
 
-`#errors`, `#warnings`, `#notes`, and `#promises` return arrays for each type.
+Several methods exist to provide shortcuts for creating nested xemes of various
+types: `success`, `error`, `warning`, `note`, and `promise`.
 
 ```ruby
-xeme.errors.each do |e|
-   puts e['id'] # => my-error
+xeme.success() do |child|
+  puts child.success? # => true
 end
 
-xeme.warnings.each do |w|
-   puts w['id'] # => my-warning
+xeme.error() do |child|
+  puts child.success? # => false
 end
 
-xeme.notes.each do |n|
-   puts n['id'] # => my-note
+# Xeme#failure does same thing as Xeme#error
+xeme.failure() do |child|
+  puts child.success? # => false
 end
 
-xeme.promises.each do |p|
-   puts p['id'] # => my-promise
+xeme.warning() do |child|
+  puts child.class # => Xeme::Warning
 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']
+xeme.note() do |child|
+  puts child.class # => Xeme::Note
 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']
-```
-
-### Creating metainformation
-
-The `#meta` method returns the `meta` element in the xeme hash, creating it if
-necessary. The hash will be automatically populated with a timestamp and a UUID.
-If you gave the xeme an identifier when you created it, that id will stored in
-the meta hash:
 
-```ruby
-xeme = Xeme.new('my-xeme')
-puts xeme.meta
-```
-
-This produces a `meta` hash like this:
-
-```ruby
-{
-   "uuid"=>"4e736a8f-314e-470a-8209-6811a7b2d38c",
-   "timestamp"=>2023-05-29 19:22:37.26152866 -0400,
-   "id"=>"my-xeme"
-}
-```
-
-If you don't pass in an id then the meta hash isn't created. However, you can
-always create and use the meta hash by calling the `#meta` method. The timestamp
-and UUID will be automatically created.
-
-```ruby
-xeme = Xeme.new
-xeme.meta['foo'] = 'bar'
-xeme.meta.class # => Hash
+xeme.promise() do |child|
+  puts child.class # => Xeme::Promise
+end
 ```
 
-### 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'
-```
+#### Querying nested xemes
 
-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:
+Xeme provides several methods for traversing through a stack of nested xemes. In
+the following examples, we'll use this structure:
 
 ```ruby
-xeme.nest('child-xeme') do |child|
-   child.error 'child-error'
+xeme = Xeme.new()
+xeme.id = 'top'
+
+xeme.nest() do |child|
+  child.id = 'foo'
+  
+  child.nest() do |grandchild|
+    grandchild.id = 'bar'
+    grandchild.warning.id = 'my-warning'
+    grandchild.promise.id = 'my-promise'
+    grandchild.success
+  end
+  
+  child.error.id = 'my-error'
+  child.note.id = 'my-note'
 end
 ```
 
-You can loop through all xemes, including the outermost xeme and all nested
-xemes, using the `#all` method.
+The simplest is the `all` method, which returns the xeme itself and all nested
+xemes as a locked array.
 
 ```ruby
 xeme.all.each do |x|
    puts x.id
 end
-```
 
-**Nested messages**
+# => top
+# => foo
+# => bar
+# => my-warning
+# => my-promise
+# => my-error
+# => my-note
+```
 
-The `#errors`, `#warnings`, `#notes`, and `#promises` methods return arrays of
-all messages within the xeme, including the outermost xeme and nested xemes.
+There are several methods for selecting xemes based on their success status.
 
 ```ruby
-xeme = Xeme.new
-xeme.error 'outer-error'
-
-xeme.nest do |child|
-   child.error 'child-error'
-end
+# xemes marked as success=false
+puts xeme.errors.length # => 3
 
-puts xeme.errors
+# xemes marked as success=true
+puts xeme.successes.length # => 1
 
-# => {"id"=>"outer-error"}
-# => {"id"=>"child-error"}
+# xemes marked as success=null
+# does not return advisory xemes
+puts xeme.nils.length # => 2
 ```
 
-If you want to search for messages with a specific `id`, add that id to the
-messages method:
+There are also several methods for selecting specific xemes based on their types.
 
 ```ruby
-puts xeme.errors('child-error') # => {"id"=>"child-error"}
+puts xeme.warnings.length # => 1
+puts xeme.notes.length # => 2
+puts xeme.promises.length # => 1
 ```
 
-**Flatten**
+### resolve() and try_succeed()
 
-Finally, if you want to slurp up all messages into the outermost xeme and delete
-the nested xemes, use `#flatten`.
+Xemes can be [resolved](#resolution) using the `resolve` method.
 
 ```ruby
-puts xeme['errors']
-# => {"id"=>"outer-error"}
-
-xeme.flatten
-
-puts xeme['errors']
-# => {"id"=>"outer-error"}
-# => {"id"=>"child-error"}
+xeme.resolve
 ```
 
+It's common that your process will get to a point, typically at the end of the
+script, where you want to mark the process as successful, but only if there were
+no errors. Use `try_succeed` for that. That method first resolves the xeme and
+its descendents, then marks the xeme (and descendents) as successful if there
+are no errors.
 
-### 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 its 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.
+```ruby
+xeme.try_succeed
+puts xeme.success? # => true, false, or nil
+```
 
 ## The name
 
@@ -409,4 +488,6 @@ mike@idocs.com
 |---------|--------------|-------------------------------|
 | 0.1     | Jan 7, 2020  | Initial upload.               |
 | 1.0     | May 29, 2023 | Complete overhaul. Not backward compatible. |
-| 1.1     | May 29, 2023 | Added and cleaned up documentation. No change to funcationality. |
+| 1.1     | May 29, 2023 | Added and cleaned up documentation. No change to functionality. |
+| 1.2     | May 29, 2023 | More cleanup to documentation. |
+| 2.0     | Jun 22, 2023 | Another complete overhaul. This should be the last non-backwards compatible revision. |