xeme 1.0 → 1.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 2dd9c9b62b1d0d2f4db4657ff6880cea68476a47ca4e366da77eab004d5ad71f
-  data.tar.gz: b15afd00d574e1382597d43df90f50668e0c8a651f2623ab5447af0d717bd404
+  metadata.gz: 6f0167b2bc464df9ea9f19613a320fdae68341e4da43fba5a85f4c5d0644c5e7
+  data.tar.gz: 9a74cb9a9026cc9f3877c4232301fb88d611634f38ac755007cb56e76ffde52c
 SHA512:
-  metadata.gz: 800b710d55a2745c7591a8c5867c5b97125750d525b9ed941f8826093c60efac36f03a135ca9104728ffe849351d176f257a0dc13382a25a87b5d2e9f553653f
-  data.tar.gz: 90c33ffa2e86e06895176ce1a16aa06fef19991fb0c7fbcadc8cb79f9480d6fc4ee1764e162d8b5e3e00993c07523926d38befb74c1a3b9ef22193b968eb64ff
+  metadata.gz: 2d563da48a8c9a49ba3b5e9cec5da9843e84bf32ca28032699cd9ee94f38e9d9a422fe27aa03b10d852a1ad00a22bcf3e4097620fd68bdcb617e6789401ff2a9
+  data.tar.gz: 732c7cf90ed366fefa4bc9c3ac5abf3128e83ac3da33c0819af172b6683993250e118d7407e0d7fafe9459f566d5b70e66d9b87271881ef7fb31263583f4217c

data/README.md

@@ -109,7 +109,7 @@ The usual:
 gem install xeme
 ```
 
-### Using the Xeme gem
+### Basic Xeme concepts
 
 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.)
@@ -138,7 +138,7 @@ xeme['errors'] = []
 xeme['errors'].push({'id'=>'my-error'})
 ```
 
-#### Success and failure
+### 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
@@ -188,7 +188,7 @@ xeme.try_succeed
 puts xeme.success? # => false
 ```
 
-#### Creating and using messages
+### 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
@@ -206,12 +206,12 @@ 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.
+`#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.
 
-`errors`, `warnings`, and `notes` return arrays for each type.
+`#errors`, `#warnings`, `#notes`, and `#promises` return arrays for each type.
 
 ```ruby
 xeme.errors.each do |e|
@@ -261,7 +261,39 @@ err['database-error'] = 'some database error'
 err['commands'] = ['a', 'b', 'c']
 ```
 
-#### Nesting xemes
+### 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
+```
+
+### 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:
@@ -332,7 +364,7 @@ puts xeme['errors']
 ```
 
 
-#### Resolving xemes
+### 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
@@ -376,4 +408,5 @@ mike@idocs.com
 | version | date         | notes                         |
 |---------|--------------|-------------------------------|
 | 0.1     | Jan 7, 2020  | Initial upload.               |
-| 1.0     | May 29, 2023 | Complete overhaul. Not backward compatible. |
+| 1.0     | May 29, 2023 | Complete overhaul. Not backward compatible. |
+| 1.1     | May 29, 2023 | Added and cleaned up documentation. No change to funcationality. |

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: xeme
 version: !ruby/object:Gem::Version
-  version: '1.0'
+  version: '1.1'
 platform: ruby
 authors:
 - Mike O'Sullivan