yerba 0.4.2-x86_64-linux-gnu → 0.5.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: c9c98c8c8ced00e63c9e1aa22754c6b8b7a64859666982c74c3518d7d4d43559
-  data.tar.gz: 0fb2a87c461cdeff6b769dbbec9c95778cd5c6a4f7ffe7ce8c8d8416b67fb264
+  metadata.gz: 497a769ee07b1e766ff7e0f991212be8268e475d1e5a9cc882e9f62845390401
+  data.tar.gz: d7e66c881d9547477d3ea8ebc232e52141a561a063179cf3534ad9c0090e1ad2
 SHA512:
-  metadata.gz: ed82268f7be7591d2a0cc848aad5b9a520acf539a651c77861946ffce30144b3725129234563ad904471fa933dfb09c9462e64c57b410dc435e066bb2f7cbedf
-  data.tar.gz: 601278dc7527866f5810b519f3f8fc3b0ec321694022ed7b880f4384492e00dcdf02ffb31abcb8983c08361a4ce691e704e9466dd0a8e34bd33bc00b229a59c1
+  metadata.gz: 5fc61b863455ba54bb41f63da74d32114e62cc54c2f467534ce6da158b3c8ef820defe227de73179f8b013b9ec4d1824ca8c850f7538f7d0305b215c944d2279
+  data.tar.gz: 6d6a96b09dc0536f5704e43da759b75c0404d60c89d7ec6691bc1d3313d7f9ac0cfa755836de18dfcf224a57ca42f0afdfb19303a661ee3fc3c8b0e19d20f3a1

data/README.md

@@ -90,24 +90,24 @@ Selectors use dot-notation for nested keys, brackets for array access, and suppo
 
 Selectors let you address any node in a YAML document:
 
-| Pattern | Meaning | Example |
-|---------|---------|---------|
-| `key` | A single key | `"database.host"` |
-| `key.nested` | Nested key path | `"database.settings.pool"` |
-| `[]` | All items in array | `"[].title"` |
-| `[N]` | Item at index | `"[0].title"` |
-| `[].key[].nested` | Nested array access | `"[].speakers[].name"` |
+| Pattern           | Meaning             | Example                    |
+|-------------------|---------------------|----------------------------|
+| `key`             | A single key        | `"database.host"`          |
+| `key.nested`      | Nested key path     | `"database.settings.pool"` |
+| `[]`              | All items in array  | `"[].title"`               |
+| `[N]`             | Item at index       | `"[0].title"`              |
+| `[].key[].nested` | Nested array access | `"[].speakers[].name"`     |
 
 ### Conditions
 
 Conditions filter which items a command operates on:
 
-| Syntax | Meaning | Example |
-|--------|---------|---------|
-| `.key == value` | Equality | `".kind == keynote"` |
-| `.key != value` | Inequality | `".status != draft"` |
-| `.key contains val` | Substring or member | `".title contains Ruby"` |
-| `.key not_contains val` | Negated contains | `".title not_contains test"` |
+| Syntax                  | Meaning             | Example                      |
+|-------------------------|---------------------|------------------------------|
+| `.key == value`         | Equality            | `".kind == keynote"`         |
+| `.key != value`         | Inequality          | `".status != draft"`         |
+| `.key contains val`     | Substring or member | `".title contains Ruby"`     |
+| `.key not_contains val` | Negated contains    | `".title not_contains test"` |
 
 ---
 
@@ -311,25 +311,25 @@ yerba quote-style videos.yml "[].description" --values literal
 
 **Key styles** (`--keys`):
 
-| Style | Symbol | Example |
-|-------|--------|---------|
-| `plain` | — | `host: value` |
-| `single` | `'` | `'host': value` |
-| `double` | `"` | `"host": value` |
+| Style    | Symbol | Example         |
+|----------|--------|-----------------|
+| `plain`  | —      | `host: value`   |
+| `single` | `'`    | `'host': value` |
+| `double` | `"`    | `"host": value` |
 
 **Value styles** (`--values`):
 
-| Style | Symbol | Example | Behavior |
-|-------|--------|---------|----------|
-| `plain` | — | `host: localhost` | Unquoted |
-| `single` | `'` | `host: 'localhost'` | Single-quoted |
-| `double` | `"` | `host: "localhost"` | Double-quoted, supports `\n` escapes |
-| `literal` | `\|-` | Preserves newlines | Strip trailing newline |
-| `literal-clip` | `\|` | Preserves newlines | Keep one trailing newline |
-| `literal-keep` | `\|+` | Preserves newlines | Keep all trailing newlines |
-| `folded` | `>-` | Folds newlines to spaces | Strip trailing newline |
-| `folded-clip` | `>` | Folds newlines to spaces | Keep one trailing newline |
-| `folded-keep` | `>+` | Folds newlines to spaces | Keep all trailing newlines |
+| Style          | Symbol | Example                  | Behavior                             |                            |
+|----------------|--------|--------------------------|--------------------------------------|----------------------------|
+| `plain`        | —      | `host: localhost`        | Unquoted                             |                            |
+| `single`       | `'`    | `host: 'localhost'`      | Single-quoted                        |                            |
+| `double`       | `"`    | `host: "localhost"`      | Double-quoted, supports `\n` escapes |                            |
+| `literal`      | `\     | -`                       | Preserves newlines                   | Strip trailing newline     |
+| `literal-clip` | `\     | `                        | Preserves newlines                   | Keep one trailing newline  |
+| `literal-keep` | `\     | +`                       | Preserves newlines                   | Keep all trailing newlines |
+| `folded`       | `>-`   | Folds newlines to spaces | Strip trailing newline               |                            |
+| `folded-clip`  | `>`    | Folds newlines to spaces | Keep one trailing newline            |                            |
+| `folded-keep`  | `>+`   | Folds newlines to spaces | Keep all trailing newlines           |                            |
 
 Block scalars are only converted when scoped to a specific selector. An unscoped `--values double` will not touch existing block scalars.
 
@@ -353,6 +353,63 @@ yerba directives config.yml --remove
 yerba directives "data/**/*.yml" --ensure
 ```
 
+### `unique`
+
+Find or remove duplicate items in a sequence. Use `--by` to specify which field determines uniqueness:
+
+```bash
+yerba unique videos.yml --by ".id"
+yerba unique speakers.yml --by ".name"
+yerba unique config.yml "tags" --by "."
+```
+
+By default, duplicates are reported but not removed. Use `--remove` to remove them (keeps the first occurrence):
+
+```bash
+yerba unique videos.yml --by ".id" --remove
+yerba unique speakers.yml --by ".name" --remove --dry-run
+```
+
+### `location`
+
+Show the location (line, column, byte offset) of a selector in a YAML file:
+
+```bash
+yerba location config.yml "database.host"
+yerba location videos.yml "[0].title"
+yerba location videos.yml "[0]"
+```
+
+Output:
+```json
+{
+  "selector": "[0].title",
+  "file": "videos.yml",
+  "start_line": 2,
+  "start_column": 9,
+  "end_line": 2,
+  "end_column": 19,
+  "start_offset": 22,
+  "end_offset": 32
+}
+```
+
+### `schema`
+
+Validate YAML files against a JSON schema:
+
+```bash
+yerba schema data/speakers.yml --schema lib/schemas/speaker_schema.json
+yerba schema "data/**/videos.yml" --schema lib/schemas/video_schema.json
+```
+
+Use `--path` to scope validation to a specific selector (e.g. validate each item in an array):
+
+```bash
+yerba schema data/speakers.yml --schema speaker_schema.json --selector "[]"
+yerba schema data/sponsors.yml --schema tier_schema.json --selector "tiers[]"
+```
+
 ### `selectors`
 
 Show all valid selectors for a YAML file. Useful for discovering the structure of a file and knowing which selectors you can use with other commands:
@@ -471,6 +528,8 @@ Available pipeline steps:
 - `rename` Rename a key
 - `remove` Remove an item from a sequence
 - `directives` Add or remove the document start marker (`---`)
+- `unique` Find or remove duplicate items in a sequence
+- `schema` Validate against a JSON schema (with optional `path` for scoping)
 - `get` Read a value and store it as a variable for subsequent steps
 
 This makes it easy to enforce project-wide YAML conventions in CI:
@@ -491,47 +550,74 @@ Create a document from a file path or from a string:
 require "yerba"
 
 document = Yerba.parse_file("config.yml")
-document = Yerba.parse("database:\n  host: localhost\n  port: 5432\n")
+
+document = Yerba.parse(<<~YAML)
+  database:
+    host: localhost
+    port: 5432
+YAML
 ```
 
 ### Reading Values
 
-Use `get` to retrieve the raw value at a path. Values are returned with their YAML types, strings, integers, booleans, and nil are all mapped to their Ruby equivalents:
+Use bracket notation (`[]`) to navigate the document. Returns typed node objects (`Scalar`, `Map`, or `Sequence`) that are live references — mutations flow back to the document.
+
+All access methods (`[]`, `fetch`, `dig`, `value_at`) accept full selector strings like `"database.host"`, `"[0].title"`, or `"[].speakers[].name"`. In the examples below we prefer the more idiomatic chained bracket style, but the two forms are equivalent:
 
 ```ruby
-document.get("database.host")   # => "localhost"
-document.get("database.port")   # => 5432
-document.get("database.ssl")    # => false
+document["database"]["host"].value  # => "localhost"
+document["database.host"].value     # => "localhost" (same thing)
 ```
 
-### Structured Navigation
+The returned object type depends on what's at the path:
 
-Use bracket notation to get typed wrapper objects (`Scalar`, `Map`, or `Sequence`) representing nodes in the document. These are live references, mutations flow back to the document.
+```ruby
+document["database"]          # => Yerba::Map
+document["database"]["host"]  # => Yerba::Scalar
+document["tags"]              # => Yerba::Sequence
+```
 
-You can use a full dot-path in a single bracket call, or chain brackets to navigate one level at a time:
+Scalars expose their value and quote style:
 
 ```ruby
-document["database.host"].value          # => "localhost"
-document["database"]["host"].value       # => "localhost"
-document["database"]["port"].value       # => 5432
+scalar = document["database"]["host"]
+scalar.value        # => "localhost"
+scalar.quote_style  # => :double
 ```
 
-The returned object type depends on what's at the path:
+Use `fetch` for strict access, it raises `Yerba::SelectorNotFoundError` with "did you mean?" suggestions if the selector doesn't exist:
 
 ```ruby
-document["database"]       # => Yerba::Map
-document["database.host"]  # => Yerba::Scalar
-document["tags"]           # => Yerba::Sequence
+document.fetch("database.host")  # => Yerba::Scalar
+document.fetch("databse.host")   # => raises SelectorNotFoundError: ... Did you mean: database.host?
 ```
 
-Scalars expose their value and quote style:
+Use `dig` to traverse multiple levels, returning `nil` for missing paths:
+
+```ruby
+document.dig("database", "host")     # => Yerba::Scalar
+document.dig("items", 0, "name")     # => Yerba::Scalar
+document.dig("database", "missing")  # => nil
+```
+
+Use `value_at` to get the plain Ruby value (String, Integer, Hash, Array, etc.) instead of a node object:
 
 ```ruby
-scalar = document["database.host"]
-scalar.value         # => "localhost"
-scalar.quote_style   # => :double
+document.value_at("database.host")  # => "localhost"
+document.value_at("database.port")  # => 5432
+document.value_at("database")       # => {"host" => "localhost", "port" => 5432}
+document.value_at("[].title")       # => ["First Talk", "Second Talk"]
 ```
 
+Summary of access methods:
+
+| Method     | Not found                      | Returns                            |
+|------------|--------------------------------|------------------------------------|
+| `[]`       | `nil`                          | `Scalar` / `Map` / `Sequence` node |
+| `fetch`    | raises `SelectorNotFoundError` | `Scalar` / `Map` / `Sequence` node |
+| `dig`      | `nil`                          | `Scalar` / `Map` / `Sequence` node |
+| `value_at` | `nil`                          | plain Ruby value                   |
+
 ### Mutations
 
 Modify values in place. The original formatting is preserved:
@@ -600,23 +686,99 @@ collection.where(kind: "talk")
 collection.pluck(:name)
 ```
 
+### Schema Validation
+
+Validate documents against JSON schemas from Ruby:
+
+```ruby
+schema = {
+  type: "object",
+  properties: { name: { type: "string" }, slug: { type: "string" } },
+  required: ["name", "slug"]
+}
+
+document.valid?(schema)                 # => true/false
+document.valid?(schema, selector: "[]") # validate each array item
+
+errors = document.validate(schema, selector: "[]")
+
+errors.each do |error|
+  puts "#{error["message"]} at #{error["path"]} (line #{error["line"]})"
+end
+```
+
+Also accepts a JSON string:
+
+```ruby
+document.valid?('{"type":"object","required":["name"]}')
+```
+
 ### Quote Style Control
 
 Read and set the quote style on individual scalars:
 
 ```ruby
-scalar = document["database.host"]
+scalar = document["database"]["host"]
 scalar.quote_style # => :double
 scalar.quote_style = :single
 ```
 
+### Location
+
+Get the precise location (line, column, byte offset) of any selector in a document:
+
+```ruby
+loc = document[0]["title"].location
+loc.start_line    # => 2
+loc.start_column  # => 9
+loc.end_line      # => 2
+loc.end_column    # => 19
+loc.start_offset  # => 22
+loc.end_offset    # => 32
+```
+
+You can also get a location by selector string:
+
+```ruby
+document.location("[0].title")
+```
+
+The above is the same as:
+
+```ruby
+document[0]["title"].location
+document["[0].title"].location
+```
+
+Omit the selector to get the whole document's location:
+
+```ruby
+document.location # => #<Yerba::Location start_line=1, ...>
+```
+
+Returns `nil` for non-existent selectors. Use `locations` for wildcard selectors that match multiple nodes:
+
+```ruby
+locs = document.locations("[].title")
+locs.each { |loc| puts "line #{loc.start_line}" }
+# line 2
+# line 4
+
+document.locations("[]")
+document.locations("[].speakers[]")
+```
+
 ### Wildcard Access
 
-Use `at_path` to access all items matching a wildcard selector:
+When `[]` receives a wildcard selector (containing `[]`), it returns an array of nodes instead of a single node:
 
 ```ruby
-titles = document.at_path("[].title")
-titles.each { |scalar| puts scalar.value }
+document["[].title"]       # => [Yerba::Scalar, Yerba::Scalar, ...]
+document["[].speakers[]"]  # => [Yerba::Scalar, Yerba::Scalar, ...]
+document["items[].name"]   # => [Yerba::Scalar, Yerba::Scalar, ...]
+
+document["[].title"].each { |scalar| puts scalar.value }
+document["[].title"].each { |scalar| scalar.value = "Updated" }
 ```
 
 ### Collections
@@ -627,7 +789,7 @@ Operate on multiple files matching a glob pattern:
 collection = Yerba.files("data/**/videos.yml")
 
 collection.each do |document|
-  puts document.get("[0].title")
+  puts document[0]["title"].value
 end
 
 collection.find_by(name: "Alice")
@@ -639,6 +801,32 @@ collection.apply! do |document|
 end
 ```
 
+Use `Collection.get` to retrieve nodes across all matching files in parallel. Returns `Scalar`, `Map`, or `Sequence` objects with `file_path`, `line`, and `selector`:
+
+```ruby
+speakers = Yerba::Collection.get("data/**/videos.yml", "[].speakers[]")
+
+speakers.each do |scalar|
+  puts "#{scalar.value} in #{scalar.file_path}:#{scalar.line}"
+end
+
+maps = Yerba::Collection.get("data/**/videos.yml", "[]")
+maps.first.class
+# => Yerba::Map
+
+sequences = Yerba::Collection.get("data/**/videos.yml", "[].speakers")
+sequences.first.class
+# => Yerba::Sequence
+```
+
+Nodes returned by `Collection.get` lazily load their `Document` on first mutation, so reads are fast and writes work transparently:
+
+```ruby
+scalars = Yerba::Collection.get("data/**/videos.yml", "[].title")
+scalars.first.value = "New Title"
+scalars.first.document.save!
+```
+
 ### Saving
 
 Write changes back to the original file:

data/ext/yerba/include/yerba.h

@@ -80,7 +80,9 @@ char *yerba_document_get_value(const struct Document *document, const char *path
 /**
  * Caller must free with yerba_string_free.
  */
-char *yerba_document_get_values(const struct Document *document, const char *path);
+char *yerba_document_selectors(const struct Document *document);
+
+char *yerba_document_resolve_selectors(const struct Document *document, const char *path);
 
 char *yerba_document_get_quote_style(const struct Document *document, const char *path);
 
@@ -94,6 +96,8 @@ bool yerba_document_evaluate_condition(const struct Document *document,
 
 bool yerba_document_exists(const struct Document *document, const char *path);
 
+bool yerba_document_valid_selector(const struct Document *document, const char *path);
+
 char *yerba_document_find(const struct Document *document,
                           const char *path,
                           const char *condition,
@@ -108,6 +112,7 @@ struct YerbaResult yerba_document_set(struct Document *document,
 struct YerbaResult yerba_document_insert(struct Document *document,
                                          const char *path,
                                          const char *value,
+                                         enum YerbaValueType value_type,
                                          const char *before,
                                          const char *after,
                                          int64_t at);
@@ -165,6 +170,13 @@ struct YerbaResult yerba_document_blank_lines(struct Document *document,
                                               const char *path,
                                               uintptr_t count);
 
+/**
+ * Caller must free with yerba_string_free.
+ */
+char *yerba_document_validate_schema(const struct Document *document,
+                                     const char *schema_json,
+                                     const char *selector);
+
 /**
  * Caller must free with yerba_string_free.
  */