xeme 1.0 → 1.2
Sign up to get free protection for your applications and to get access to all the features.
- checksums.yaml +4 -4
- data/README.md +46 -13
- metadata +1 -1
checksums.yaml
CHANGED
@@ -1,7 +1,7 @@
|
|
1
1
|
---
|
2
2
|
SHA256:
|
3
|
-
metadata.gz:
|
4
|
-
data.tar.gz:
|
3
|
+
metadata.gz: cdf9cdb30bbab1fe3155496c778a01c83fb35c011bb9d00c63525fffa1c5cec8
|
4
|
+
data.tar.gz: aa5b17da3d91e1ab8940aa84ff38dd4fcbe5d274acebcb7483c4bf9221ed6dca
|
5
5
|
SHA512:
|
6
|
-
metadata.gz:
|
7
|
-
data.tar.gz:
|
6
|
+
metadata.gz: 98eab45cddd377c4a3c81d1de8c800e169b360fbe0451402256e57c18e412c971f6eef059795ad54134297228757728561e730a33271e932574d198028976f99
|
7
|
+
data.tar.gz: 1200e1c8b64b5233c102e83414499fdc39db85df7d5cf071caee830a5e218a29c94f590b6d44b8ed2266d8c6fb5b34ee9112d2d7eeb97201a9d49fc57225bd0b
|
data/README.md
CHANGED
@@ -109,7 +109,7 @@ The usual:
|
|
109
109
|
gem install xeme
|
110
110
|
```
|
111
111
|
|
112
|
-
###
|
112
|
+
### Basic Xeme concepts
|
113
113
|
|
114
114
|
Xeme (the gem) is a thin layer over a hash that implements the Xeme format. (For
|
115
115
|
the rest of this document "Xeme" refers to the Ruby class, not the format.)
|
@@ -138,7 +138,7 @@ xeme['errors'] = []
|
|
138
138
|
xeme['errors'].push({'id'=>'my-error'})
|
139
139
|
```
|
140
140
|
|
141
|
-
|
141
|
+
### Success and failure
|
142
142
|
|
143
143
|
Because a xeme isn't considered successful until it has been explicitly declared
|
144
144
|
so, a new xeme is considered to indicate failure. However, because there are no
|
@@ -188,7 +188,7 @@ xeme.try_succeed
|
|
188
188
|
puts xeme.success? # => false
|
189
189
|
```
|
190
190
|
|
191
|
-
|
191
|
+
### Creating and using messages
|
192
192
|
|
193
193
|
Messages in a xeme provide a way to indicate errors (i.e. fatal errors),
|
194
194
|
warnings (non-fatal errors), notes (not an error at all), and promises (guides
|
@@ -206,12 +206,12 @@ xeme.note 'my-note'
|
|
206
206
|
xeme.promise 'my-promise'
|
207
207
|
```
|
208
208
|
|
209
|
-
|
210
|
-
Although it is not required, it's usually a good idea to give a string
|
211
|
-
first parameter. That string will be set to the `id` element in the
|
212
|
-
hash, as seen in the example above.
|
209
|
+
`#error`, `#warning`, `#note`, and `#promise` each create a message for their
|
210
|
+
own type. Although it is not required, it's usually a good idea to give a string
|
211
|
+
as the first parameter. That string will be set to the `id` element in the
|
212
|
+
resulting hash, as seen in the example above.
|
213
213
|
|
214
|
-
|
214
|
+
`#errors`, `#warnings`, `#notes`, and `#promises` return arrays for each type.
|
215
215
|
|
216
216
|
```ruby
|
217
217
|
xeme.errors.each do |e|
|
@@ -261,7 +261,39 @@ err['database-error'] = 'some database error'
|
|
261
261
|
err['commands'] = ['a', 'b', 'c']
|
262
262
|
```
|
263
263
|
|
264
|
-
|
264
|
+
### Creating metainformation
|
265
|
+
|
266
|
+
The `#meta` method returns the `meta` element in the xeme hash, creating it if
|
267
|
+
necessary. The hash will be automatically populated with a timestamp and a UUID.
|
268
|
+
If you gave the xeme an identifier when you created it, that id will stored in
|
269
|
+
the meta hash:
|
270
|
+
|
271
|
+
```ruby
|
272
|
+
xeme = Xeme.new('my-xeme')
|
273
|
+
puts xeme.meta
|
274
|
+
```
|
275
|
+
|
276
|
+
This produces a `meta` hash like this:
|
277
|
+
|
278
|
+
```ruby
|
279
|
+
{
|
280
|
+
"uuid"=>"4e736a8f-314e-470a-8209-6811a7b2d38c",
|
281
|
+
"timestamp"=>2023-05-29 19:22:37.26152866 -0400,
|
282
|
+
"id"=>"my-xeme"
|
283
|
+
}
|
284
|
+
```
|
285
|
+
|
286
|
+
If you don't pass in an id then the meta hash isn't created. However, you can
|
287
|
+
always create and use the meta hash by calling the `#meta` method. The timestamp
|
288
|
+
and UUID will be automatically created.
|
289
|
+
|
290
|
+
```ruby
|
291
|
+
xeme = Xeme.new
|
292
|
+
xeme.meta['foo'] = 'bar'
|
293
|
+
xeme.meta.class # => Hash
|
294
|
+
```
|
295
|
+
|
296
|
+
### Nesting xemes
|
265
297
|
|
266
298
|
In complex testing situations it can be useful to nest results within other
|
267
299
|
results. To nest a xeme within another xeme, use the `#nest` method:
|
@@ -332,7 +364,7 @@ puts xeme['errors']
|
|
332
364
|
```
|
333
365
|
|
334
366
|
|
335
|
-
|
367
|
+
### Resolving xemes
|
336
368
|
|
337
369
|
A xeme can contain contradictory information. For example, if `success` is true
|
338
370
|
but there are errors, then the xeme should be considered as failed. If there are
|
@@ -348,8 +380,8 @@ considerations. Resolution never changes a `success` of false.
|
|
348
380
|
* If any nested xemes have `success` explicitly set to false, then the outermost
|
349
381
|
xeme will be set to false.
|
350
382
|
|
351
|
-
* If a xeme has errors, or any of
|
352
|
-
|
383
|
+
* If a xeme has errors, or any of its nested xemes has errors, then it is set to
|
384
|
+
false.
|
353
385
|
|
354
386
|
* If a xeme has promises, or any of its nested xemes do, then it cannot be set
|
355
387
|
to true. If it is already false, then it stays false. Otherwise `success` is set
|
@@ -376,4 +408,5 @@ mike@idocs.com
|
|
376
408
|
| version | date | notes |
|
377
409
|
|---------|--------------|-------------------------------|
|
378
410
|
| 0.1 | Jan 7, 2020 | Initial upload. |
|
379
|
-
| 1.0 | May 29, 2023 | Complete overhaul. Not backward compatible. |
|
411
|
+
| 1.0 | May 29, 2023 | Complete overhaul. Not backward compatible. |
|
412
|
+
| 1.1 | May 29, 2023 | Added and cleaned up documentation. No change to funcationality. |
|