yerba 0.9.1-x86_64-linux-gnu → 0.10.0-x86_64-linux-gnu

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5cec887961387cdf44392234842745f51538df4bb563f3c896422aade6022387
-  data.tar.gz: 8275cc4c54bca41702a3dd83a351a4f1b2169c3f956844cd5f165ef42e40288c
+  metadata.gz: 3939b71826dbe4f1aa8d6223ecf7f1a492e616e6e51546c0a7907919bcf2a5a9
+  data.tar.gz: d1af424df9d4c9c68078e68cc1d58fc0c79ec66af776879d3794af2411bf1522
 SHA512:
-  metadata.gz: 7fb8433ec5ef02d4aec964897fceaf141708a2c0f2f0a0897888c24f8cea25122008fc530849f588c0d6017e9283945530c1c2fd966e9233a4afc7ffa2354bfa
-  data.tar.gz: 0ec6936095188c83cd21afc92b4324a225de14ad14ef37485fc19a6ad185f8f38c2fb0550c901b50a3a1d09640580ce747b64e6c722fc5ece7526ad3b2e4467c
+  metadata.gz: 59d3183aa703a0d4f7834199be0fea5f9560d9ab8aafe05f64ce5f0d74824b46ef4503470e1e2d3ec8d854ecdca8c329010ef6427a47151080ef873399c3cc6f
+  data.tar.gz: dd2dbe3833362fb40d51754f596d4f69ec29fd0014e5b8599b09117bab0a96b1c1c0f225738e566165345f96516e0793e39a1cfe314f3a95ff12110fd257f06a

data/README.md

@@ -47,7 +47,7 @@ Use `yerba` as a library in your Rust project:
 
 ```toml
 [dependencies]
-yerba = "0.9"
+yerba = "0.10"
 ```
 
 ```rust
@@ -93,9 +93,10 @@ 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"` |
+| `key.nested`      | Nested keys         | `"database.settings.pool"` |
 | `[]`              | All items in array  | `"[].title"`               |
 | `[N]`             | Item at index       | `"[0].title"`              |
+| `[-N]`            | Item from the end   | `"[-1].title"`             |
 | `*`               | All values in a map | `"database.*"`             |
 | `[].key[].nested` | Nested array access | `"[].speakers[].name"`     |
 
@@ -149,14 +150,14 @@ yerba get videos.yml "[]" --condition ".speakers contains Matz" --raw
 
 ### `set`
 
-Update an existing value at a path. The original quote style is preserved automatically, if a value was double-quoted before, it stays double-quoted after the edit.
+Update an existing value at a selector. The original quote style is preserved automatically, if a value was double-quoted before, it stays double-quoted after the edit.
 
 ```bash
 yerba set config.yml "database.host" "0.0.0.0"
 yerba set videos.yml "[0].title" "New Title"
 ```
 
-Use `--if-exists` to only set the value when the path already exists, or `--if-missing` to only set it when the path does not exist:
+Use `--if-exists` to only set the value when the selector already exists, or `--if-missing` to only set it when the selector does not exist:
 
 ```bash
 yerba set config.yml "database.host" "0.0.0.0" --if-exists
@@ -189,7 +190,7 @@ Use `--all` to update all nodes matching a wildcard selector:
 yerba set videos.yml "[].description" "" --all
 ```
 
-Values are written in the quote style already at the path, which keeps string edits tidy. A value is quoted anyway when writing it plain would not read back as the string you passed, so `yes` becomes `"yes"` and `12345` becomes `"12345"` — whatever the field held before. Use `--plain` to write a YAML literal instead:
+Values are written in the quote style already at the selector, which keeps string edits tidy. A value is quoted anyway when writing it plain would not read back as the string you passed, so `yes` becomes `"yes"` and `12345` becomes `"12345"` — whatever the field held before. Use `--plain` to write a YAML literal instead:
 
 ```bash
 yerba set config.yml "database.replica" null --plain
@@ -469,10 +470,14 @@ Output:
   "end_line": 2,
   "end_column": 19,
   "start_offset": 22,
-  "end_offset": 32
+  "end_offset": 32,
+  "start_character_column": 9,
+  "end_character_column": 19
 }
 ```
 
+Lines are 1-based and columns are 0-based, like Prism. `start_column` and `end_column` count bytes, `start_character_column` and `end_character_column` count characters, and offsets are byte offsets into the file.
+
 ### `schema`
 
 Validate YAML files against a JSON schema:
@@ -482,7 +487,7 @@ 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):
+Use `--selector` 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 "[]"
@@ -579,11 +584,11 @@ rules:
   - files: "data/**/videos.yml"
     pipeline:
       - quote_style:
-          path: "[].speakers"
+          selector: "[].speakers"
           value_style: plain
 
       - sort_keys:
-          path: "[]"
+          selector: "[]"
           order:
             - id
             - title
@@ -592,7 +597,7 @@ rules:
   - files: "data/speakers.yml"
     pipeline:
       - sort_keys:
-          path: "[]"
+          selector: "[]"
           order:
             - name
             - slug
@@ -602,13 +607,15 @@ rules:
           by: name
 ```
 
+Rules and steps take a `selector` to scope them. `path` is still accepted as the older name for it.
+
 Available pipeline steps:
 
-- `quote_style` Enforce quote style on keys and/or values, optionally scoped by path
+- `quote_style` Enforce quote style on keys and/or values, optionally scoped by selector
 - `collection_style` Enforce flow or block style on collections
 - `sequence_indent` Enforce compact or indented sequence style
 - `sort_keys` Reorder keys to match a predefined list
-- `sort` Sort sequence items by field(s)
+- `sort` Sort sequence items by field(s), `by: ".date,.start_time"` or `by: ".date .start_time"` for tie-breakers
 - `blank_lines` Enforce blank lines between sequence entries, optionally limited to named map keys with `before` and to non-empty values with `skip_empty`
 - `set` Set a value (supports conditions, and `plain: true` for YAML literals)
 - `insert` Insert a new key or sequence item (`plain: true` for YAML literals and fragments)
@@ -617,8 +624,8 @@ Available pipeline steps:
 - `remove` Remove an item from a sequence
 - `directives` Add or remove the document start marker (`---`), with optional `max` validation
 - `unique` Find or remove duplicate items in a sequence
-- `schema` Validate against a JSON schema (with optional `path` for scoping)
-- `escapes` Spell escaped characters literally where the quote style can carry them (with optional `path` for scoping)
+- `schema` Validate against a JSON schema (with optional `selector` for scoping)
+- `escapes` Spell escaped characters literally where the quote style can carry them (with optional `selector` for scoping)
 - `final_newline` Enforce exact number of trailing newlines (`count: 1` by default, strips extras)
 
 This makes it easy to enforce project-wide YAML conventions in CI:
@@ -747,7 +754,7 @@ document["database"]["host"].value  # => "localhost"
 document["database.host"].value     # => "localhost" (same thing)
 ```
 
-The returned object type depends on what's at the path:
+The returned object type depends on what's at the selector:
 
 ```ruby
 document["database"]          # => Yerba::Map
@@ -900,9 +907,14 @@ document.sort(by: :name, order: ["Charlie", "Bob", "Alice"])
 document.sort("tags")
 document.sort("tags", order: :desc)
 document.sort("tags", order: ["rust", "ruby", "go"])
+document.sort("tags", order: "rust,ruby,go")
+document.sort(by: [:date, :start_time])
+document.sort(by: ".date .start_time")
 ```
 
-The `by:` option accepts symbols, strings, or dot-prefixed strings (`:name`, `"name"`, `".name"`).
+The `by:` option accepts symbols, strings, or dot-prefixed strings (`:name`, `"name"`, `".name"`). Several fields, separated by commas or spaces or given as an Array, sort by the first and break ties with the next.
+
+The `order:` option is `:asc`, `:desc`, or an explicit order of values as an Array or comma-separated String.
 
 ### Querying
 
@@ -1038,8 +1050,12 @@ loc.end_line      # => 2
 loc.end_column    # => 19
 loc.start_offset  # => 22
 loc.end_offset    # => 32
+loc.start_character_column  # => 9
+loc.end_character_column    # => 19
 ```
 
+Lines are 1-based and columns are 0-based, matching `Prism::Location`. `start_column` and `end_column` count bytes, `start_character_column` and `end_character_column` count characters, so they differ on lines with non-ASCII text before the value.
+
 You can also get a location by selector string:
 
 ```ruby
@@ -1165,6 +1181,34 @@ scalars.first.value = "New Title"
 scalars.first.document.save!
 ```
 
+### Parsing Selectors
+
+`Yerba::Selector` splits a selector into its segments, using the same parser as the rest of Yerba. Keys are Strings, indexes Integers (negative from the end), `[]` is `:all_items` and `*` is `:all_keys`:
+
+```ruby
+selector = Yerba::Selector.parse("[3].talks[1]")
+
+selector.segments   # => [3, "talks", 1]
+selector.parent     # => "[3].talks"
+selector.join("speakers", 0).to_s  # => "[3].talks[1].speakers[0]"
+
+Yerba::Selector.parse("[].speakers[]").segments  # => [:all_items, "speakers", :all_items]
+Yerba::Selector.parse(".title").relative?        # => true
+Yerba::Selector.parse("tags[-1]").segments       # => ["tags", -1]
+
+Yerba::Selector.build([3, "talks", 1]).to_s      # => "[3].talks[1]"
+```
+
+`dig` looks a concrete selector up in plain Ruby values, such as the cached `Document#values`, without calling into the native extension. Use it when reading many values from the same document:
+
+```ruby
+values = document.values
+
+Yerba::Selector.parse("[3].talks[1].title").dig(values)  # => same as document.value_at("[3].talks[1].title")
+```
+
+Parsed selectors are cached per string, so parsing the same selector again is free.
+
 ### Saving
 
 Write changes back to the original file:

data/ext/yerba/include/yerba.h

@@ -46,6 +46,8 @@ typedef struct YerbaLocation {
   uintptr_t start_column;
   uintptr_t end_line;
   uintptr_t end_column;
+  uintptr_t start_character_column;
+  uintptr_t end_character_column;
 } YerbaLocation;
 
 typedef struct YerbaGetResult {
@@ -64,6 +66,22 @@ typedef struct YerbaResult {
   char *error;
 } YerbaResult;
 
+typedef struct YerbaNodeRecord {
+  intptr_t parent;
+  enum NodeType node_type;
+  char *selector;
+  char *key_name;
+  struct YerbaTypedValue value;
+  bool has_value;
+  struct YerbaLocation location;
+  struct YerbaLocation key_location;
+} YerbaNodeRecord;
+
+typedef struct YerbaNodeList {
+  struct YerbaNodeRecord *records;
+  uintptr_t length;
+} YerbaNodeList;
+
 struct YerbaParseResult yerba_document_parse_file(const char *path);
 
 struct YerbaParseResult yerba_document_parse(const char *content);
@@ -72,64 +90,77 @@ uint64_t yerba_document_generation(const struct Document *document);
 
 void yerba_document_free(struct Document *document);
 
-struct YerbaGetResult yerba_document_get(const struct Document *document, const char *path);
+struct YerbaGetResult yerba_document_get(const struct Document *document, const char *selector);
 
 /**
  * Caller must free with yerba_string_free.
  */
-char *yerba_document_source(const struct Document *document, const char *path);
+char *yerba_document_source(const struct Document *document, const char *selector);
 
 /**
  * Caller must free with yerba_string_free.
  */
-char *yerba_document_get_value(const struct Document *document, const char *path);
+char *yerba_document_get_value(const struct Document *document, const char *selector);
 
 /**
  * Caller must free with yerba_string_free.
  */
 char *yerba_document_selectors(const struct Document *document);
 
-char *yerba_document_resolve_selectors(const struct Document *document, const char *path);
+char *yerba_document_resolve_selectors(const struct Document *document, const char *selector);
 
-bool yerba_selector_has_wildcard(const char *path);
+bool yerba_selector_has_wildcard(const char *selector);
 
-char *yerba_document_keys(const struct Document *document, const char *path);
+/**
+ * Parses a selector into JSON: `{"relative": bool, "segments": [...]}`.
+ *
+ * Keys are encoded as strings, indexes as integers (negative from the end), `[]` as `{"all": "items"}` and `*` as `{"all": "keys"}`.
+ */
+char *yerba_selector_parse(const char *selector);
+
+/**
+ * Builds a selector string from a JSON array of segments, encoded like `yerba_selector_parse` returns them.
+ */
+char *yerba_selector_build(const char *segments_json,
+                           bool relative);
 
-char *yerba_document_get_quote_style(const struct Document *document, const char *path);
+char *yerba_document_keys(const struct Document *document, const char *selector);
+
+char *yerba_document_get_quote_style(const struct Document *document, const char *selector);
 
 struct YerbaResult yerba_document_set_quote_style(struct Document *document,
-                                                  const char *path,
+                                                  const char *selector,
                                                   const char *style);
 
-char *yerba_document_get_collection_style(const struct Document *document, const char *path);
+char *yerba_document_get_collection_style(const struct Document *document, const char *selector);
 
 struct YerbaResult yerba_document_set_collection_style(struct Document *document,
-                                                       const char *path,
+                                                       const char *selector,
                                                        const char *style);
 
-char *yerba_document_get_sequence_indent(const struct Document *document, const char *path);
+char *yerba_document_get_sequence_indent(const struct Document *document, const char *selector);
 
 struct YerbaResult yerba_document_set_sequence_indent(struct Document *document,
-                                                      const char *path,
+                                                      const char *selector,
                                                       const char *style);
 
 char *yerba_validate_condition(const char *condition, bool item_context);
 
 bool yerba_document_evaluate_condition(const struct Document *document,
-                                       const char *parent_path,
+                                       const char *parent_selector,
                                        const char *condition);
 
-bool yerba_document_exists(const struct Document *document, const char *path);
+bool yerba_document_exists(const struct Document *document, const char *selector);
 
-bool yerba_document_valid_selector(const struct Document *document, const char *path);
+bool yerba_document_valid_selector(const struct Document *document, const char *selector);
 
 char *yerba_document_find(const struct Document *document,
-                          const char *path,
+                          const char *selector,
                           const char *condition,
                           const char *select);
 
 struct YerbaResult yerba_document_set(struct Document *document,
-                                      const char *path,
+                                      const char *selector,
                                       const char *value,
                                       uintptr_t value_length,
                                       enum YerbaValueType value_type,
@@ -137,7 +168,7 @@ struct YerbaResult yerba_document_set(struct Document *document,
                                       bool all);
 
 struct YerbaResult yerba_document_insert(struct Document *document,
-                                         const char *path,
+                                         const char *selector,
                                          const char *value,
                                          uintptr_t value_length,
                                          enum YerbaValueType value_type,
@@ -148,28 +179,28 @@ struct YerbaResult yerba_document_insert(struct Document *document,
                                          int64_t at);
 
 struct YerbaResult yerba_document_insert_object(struct Document *document,
-                                                const char *path,
+                                                const char *selector,
                                                 const char *json,
                                                 const char *before,
                                                 const char *after,
                                                 int64_t at);
 
-struct YerbaResult yerba_document_delete(struct Document *document, const char *path);
+struct YerbaResult yerba_document_delete(struct Document *document, const char *selector);
 
 struct YerbaResult yerba_document_insert_objects(struct Document *document,
-                                                 const char *path,
+                                                 const char *selector,
                                                  const char *json);
 
 struct YerbaResult yerba_document_remove(struct Document *document,
-                                         const char *path,
+                                         const char *selector,
                                          const char *value);
 
 struct YerbaResult yerba_document_remove_at(struct Document *document,
-                                            const char *path,
+                                            const char *selector,
                                             uintptr_t index);
 
 struct YerbaResult yerba_document_move_item(struct Document *document,
-                                            const char *path,
+                                            const char *selector,
                                             uintptr_t from,
                                             uintptr_t to);
 
@@ -178,26 +209,26 @@ struct YerbaResult yerba_document_rename(struct Document *document,
                                          const char *dest);
 
 struct YerbaResult yerba_document_sort(struct Document *document,
-                                       const char *path,
+                                       const char *selector,
                                        const char *by,
                                        bool case_sensitive);
 
 struct YerbaResult yerba_document_reorder(struct Document *document,
-                                          const char *path,
+                                          const char *selector,
                                           const char *by,
                                           const char *order_csv);
 
 struct YerbaResult yerba_document_sort_keys(struct Document *document,
-                                            const char *path,
+                                            const char *selector,
                                             const char *order);
 
 struct YerbaResult yerba_document_quote_style(struct Document *document,
-                                              const char *path,
+                                              const char *selector,
                                               const char *key_style,
                                               const char *value_style);
 
 struct YerbaResult yerba_document_blank_lines(struct Document *document,
-                                              const char *path,
+                                              const char *selector,
                                               uintptr_t count);
 
 /**
@@ -224,14 +255,18 @@ void yerba_string_free(char *s);
 
 void yerba_result_free(struct YerbaResult result);
 
+struct YerbaNodeList yerba_document_nodes(const struct Document *document);
+
+void yerba_node_list_free(struct YerbaNodeList list);
+
 void yerba_get_result_free(struct YerbaGetResult result);
 
-struct YerbaTypedList yerba_glob_get(const char *glob_pattern, const char *path);
+struct YerbaTypedList yerba_glob_get(const char *glob_pattern, const char *selector);
 
-struct YerbaTypedList yerba_document_get_all(const struct Document *document, const char *path);
+struct YerbaTypedList yerba_document_get_all(const struct Document *document, const char *selector);
 
 struct YerbaTypedList yerba_glob_find(const char *glob_pattern,
-                                      const char *path,
+                                      const char *selector,
                                       const char *condition,
                                       const char *select);