yerba 0.9.2 → 0.10.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: bbff6da2b4fadf2758f9a9711d26bd3ac14c5b8c6ebc9d3630103550d3dfa22b
-  data.tar.gz: 46b35dc5a175e797edf19dbc24fe4961593e2ef4fc5c498c2bd5e5eeb9ca1f85
+  metadata.gz: fc77087eb847c22981cefa67955f831bf0764243ce53d9a81460fa94444b305d
+  data.tar.gz: 6f1cd3a0c356d1aa6bbf079a8f3e5684346865621f43adfd5126c9cf692dc8c5
 SHA512:
-  metadata.gz: '09afa4c8dc4f0f921496c3fd52b26b432fac7815ab0f3dfbfdd0a45e498dc821438eaa2ea0d69946ec284c7baccb173132907550ba591cc7c3001a9fd62f0ba3'
-  data.tar.gz: 1848eee956eb9c53c8a385b902a571052814c9ba997a0e133f7b2dedc168ddd19018864729f8e5811f08eea658feb1c605dbac2284a1c58e5b59d52af6f30205
+  metadata.gz: ac53fc548c14d63e51b931f86948cf4e651b13ba25c08b931e2756709d167af7b029c996737f68068a69dfc85a2585530dc861f0ba0e20cfbdf3d5282abc11ef
+  data.tar.gz: 65195d53f93a085112077b9a2833e35b92717b4d87dc5c3369989a2b1f53b187c9cec5b59ebf34f0ce10c5011e6516456e4dd9d682313558ac4c6563c32cc847

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
@@ -299,6 +300,17 @@ yerba sort videos.yml --by ".date" --order desc --by ".title"
 yerba sort videos.yml "[].speakers" --by ".name"
 ```
 
+Items without a value for a sort field sort as an empty value, so they come first. Use `--missing` to decide what happens to them instead:
+
+- `first` or `last` puts a missing value before or after the present ones, comparing one field at a time like SQL's `NULLS FIRST` and `NULLS LAST`. Sorted by `.date` and `.start_time`, a talk without a time goes first or last within its date.
+- `keep` leaves items with a missing value where they are and sorts the other items around them.
+- `skip` leaves the whole sequence unsorted if any item has a missing value.
+
+
+```bash
+yerba sort videos.yml --by ".date" --by ".start_time" --missing keep
+```
+
 Use `--order` with a comma-separated list to specify an explicit custom order. All items must be listed:
 
 ```bash
@@ -469,10 +481,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 +498,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 "[]"
@@ -577,13 +593,15 @@ pipeline:
 
 rules:
   - files: "data/**/videos.yml"
+    exclude:
+      - "data/archive/**/videos.yml"
     pipeline:
       - quote_style:
-          path: "[].speakers"
+          selector: "[].speakers"
           value_style: plain
 
       - sort_keys:
-          path: "[]"
+          selector: "[]"
           order:
             - id
             - title
@@ -592,7 +610,7 @@ rules:
   - files: "data/speakers.yml"
     pipeline:
       - sort_keys:
-          path: "[]"
+          selector: "[]"
           order:
             - name
             - slug
@@ -602,13 +620,15 @@ rules:
           by: name
 ```
 
+Rules and steps take a `selector` to scope them. `path` is still accepted as the older name for it. A rule's `exclude` takes a glob or a list of globs for files the rule skips.
+
 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, and `missing: first`, `last`, `keep` or `skip` for items without a value
 - `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 +637,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 +767,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 +920,20 @@ 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.
+
+The `missing:` option decides what happens to items without a value for a sort field: `:first` or `:last` put the missing value before or after the present ones for each field, `:keep` leaves those items in place and sorts the others into the remaining positions, and `:skip` leaves the sequence unsorted if any value is missing. Without it, a missing value sorts as an empty string.
+
+```ruby
+document.sort(by: [:date, :start_time], missing: :keep)
+```
 
 ### Querying
 
@@ -1038,8 +1069,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
@@ -1167,7 +1202,7 @@ 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, `[]` is `:all_items` and `*` is `:all_keys`:
+`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]")
@@ -1178,6 +1213,7 @@ 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]"
 ```

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,33 +90,33 @@ 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);
 
 /**
  * Parses a selector into JSON: `{"relative": bool, "segments": [...]}`.
  *
- * Keys are encoded as strings, indexes as integers, `[]` as `{"all": "items"}` and `*` as `{"all": "keys"}`.
+ * 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 *path);
+char *yerba_selector_parse(const char *selector);
 
 /**
  * Builds a selector string from a JSON array of segments, encoded like `yerba_selector_parse` returns them.
@@ -106,43 +124,43 @@ char *yerba_selector_parse(const char *path);
 char *yerba_selector_build(const char *segments_json,
                            bool relative);
 
-char *yerba_document_keys(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 *path);
+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,
@@ -150,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,
@@ -161,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);
 
@@ -191,26 +209,27 @@ 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);
+                                       bool case_sensitive,
+                                       const char *missing);
 
 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);
 
 /**
@@ -237,14 +256,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);