yerba 0.3.0 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 477663fa314d01cbe3c98e8a5a8bdc08c0e26d287bff36d23ae1eea519e81609
-  data.tar.gz: 3a9ce13df82bbebd5cbbfc7590d0d334e841c4314bb059f31047ba707bd9bb1e
+  metadata.gz: 8e77d3cce1f16b9adf15e44b0dec51f2182ab12eeeacea0e0d6d1223d7a1f23b
+  data.tar.gz: 7abd1edd2196ce73d22dab4b05dbb2f2af47cb04e1cff756bd8df5a678dcbe9e
 SHA512:
-  metadata.gz: be2932fad743bdf806070d5898f73533e8225994dc8d6581b0f47c5ee79519a8cfc83fd4f88cae4607fe5e36ee85f2cc165f288bbeca0184a9756fe18e7b3b27
-  data.tar.gz: 6251a8c8d261c458781e48a2adc8364172bd999c4ecbcc8e38ba625cf9a2434285efabd96dbfb64eabf78791f5a6a187cb76114bfc37facce78d48aa782696cf
+  metadata.gz: 3d22690ae793eb147848050793e22eeeeb8614d942d258e685b4bbea3094d0c118ac72d93c4beb56044bad8d7a3ce9a37947fac8870c302755d4777075a191ca
+  data.tar.gz: 3c4d9c7159d665b55355c965f5f2a41b5962b17dde6f29aa5a57006e33fc9b64c987fe833872e102d5bf4882eb11673f67c1001d857011213b2012ce5648344a

data/README.md

@@ -47,13 +47,15 @@ Use `yerba` as a library in your Rust project:
 
 ```toml
 [dependencies]
-yerba = "0.3"
+yerba = "0.4"
 ```
 
 ```rust
 let mut document = yerba::parse_file("config.yml")?;
 document.set("database.host", "0.0.0.0")?;
-document.save()?;
+
+document.save()?;                  // saves to original path
+document.save_to("output.yml")?;   // saves to new path
 ```
 
 ### Ruby Gem
@@ -286,7 +288,7 @@ yerba sort-keys "data/**/videos.yml" "[]" "id,title,speakers"
 
 ### `quote-style`
 
-Enforce a consistent quote style across keys and/or values. Available styles are `plain`, `single`, and `double`:
+Enforce a consistent quote style across keys and/or values:
 
 ```bash
 yerba quote-style config.yml --values double
@@ -301,6 +303,36 @@ yerba quote-style config.yml "[].speakers" --values plain
 yerba quote-style "data/**/*.yml" --keys plain --values double
 ```
 
+Use block scalar styles to enforce multiline formatting on specific fields:
+
+```bash
+yerba quote-style videos.yml "[].description" --values literal
+```
+
+**Key styles** (`--keys`):
+
+| 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 |
+
+Block scalars are only converted when scoped to a specific selector. An unscoped `--values double` will not touch existing block scalars.
+
 ### `blank-lines`
 
 Enforce a consistent number of blank lines between sequence entries:
@@ -311,6 +343,16 @@ yerba blank-lines videos.yml "[]" 1
 yerba blank-lines config.yml "tags" 0
 ```
 
+### `directives`
+
+Add or remove the document start marker (`---`):
+
+```bash
+yerba directives config.yml --ensure
+yerba directives config.yml --remove
+yerba directives "data/**/*.yml" --ensure
+```
+
 ### `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:
@@ -425,6 +467,7 @@ Available pipeline steps:
 - `delete` Remove a key (supports conditions)
 - `rename` Rename a key
 - `remove` Remove an item from a sequence
+- `directives` Add or remove the document start marker (`---`)
 - `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:
@@ -514,7 +557,44 @@ tags = document["tags"]
 tags << "yaml"
 tags << { name: "Rust", version: "1.80" }
 tags.remove("obsolete")
-tags.sort(by: "name")
+```
+
+### Sorting
+
+Sort sequences in place. Works on both the document and sequence level:
+
+```ruby
+document.sort(by: :name)
+document.sort(by: :name, order: :desc)
+document.sort(by: :name, order: ["Charlie", "Bob", "Alice"])
+document.sort("tags")
+document.sort("tags", order: :desc)
+document.sort("tags", order: ["rust", "ruby", "go"])
+```
+
+The `by:` option accepts symbols, strings, or dot-prefixed strings (`:name`, `"name"`, `".name"`).
+
+### Querying
+
+Find and filter items in sequences with `find_by`, `where`, and `pluck`:
+
+```ruby
+document.find_by(name: "Alice")
+document.where(role: "admin")
+document.pluck(:name)
+
+document.find_by(speakers: { name: "Alice" })
+document.where(tags: ["ruby"])
+document.find_by("database.host": "localhost")
+```
+
+These methods work on `Document` (delegates to root), `Sequence`, and `Collection` (searches across files):
+
+```ruby
+collection = Yerba.files("data/**/*.yml")
+collection.find_by(name: "Alice")
+collection.where(kind: "talk")
+collection.pluck(:name)
 ```
 
 ### Quote Style Control
@@ -523,7 +603,7 @@ Read and set the quote style on individual scalars:
 
 ```ruby
 scalar = document["database.host"]
-scalar.quote_style          # => :double
+scalar.quote_style # => :double
 scalar.quote_style = :single
 ```
 
@@ -547,6 +627,10 @@ collection.each do |document|
   puts document.get("[0].title")
 end
 
+collection.find_by(name: "Alice")
+collection.where(kind: "talk")
+collection.pluck(:name)
+
 collection.apply! do |document|
   document.set("status", "published")
 end
@@ -572,10 +656,9 @@ After checking out the repo, run `bundle install` to install Ruby dependencies,
 
 ### Building from source
 
-The Rust core is in the `rust/` directory:
+The Rust core is in the `rust/` directory, with a workspace `Cargo.toml` at the root so all cargo commands work from the project root:
 
 ```bash
-cd rust
 cargo build
 cargo test
 ```
@@ -591,7 +674,6 @@ cargo run -- get config.yml "database.host"
 Or build a release binary:
 
 ```bash
-cd rust
 cargo build --release
 ./target/release/yerba --help
 ```

data/ext/yerba/extconf.rb

@@ -44,22 +44,41 @@ if cross_compiling && target_platform.nil?
   end
 end
 
+workspace_target_dir = File.join(root_dir, "target")
+crate_target_dir = File.join(rust_dir, "target")
+
 if target_platform
   puts "yerba: Cross-compiling Rust for target: #{target_platform}"
   system("rustup target add #{target_platform}") || warn("yerba: Failed to add Rust target #{target_platform}")
 
   cargo_args = "--release --target #{target_platform}"
-  lib_dir = File.join(rust_dir, "target", target_platform, "release")
+  lib_dir = [workspace_target_dir, crate_target_dir]
+            .map { |dir| File.join(dir, target_platform, "release") }
+            .find { |dir| Dir.exist?(dir) } || File.join(crate_target_dir, target_platform, "release")
 else
   puts "yerba: Compiling Rust library for native platform..."
+
   cargo_args = "--release"
-  lib_dir = File.join(rust_dir, "target", "release")
+
+  lib_dir = [workspace_target_dir, crate_target_dir]
+            .map { |dir| File.join(dir, "release") }
+            .find { |dir| Dir.exist?(dir) } || File.join(crate_target_dir, "release")
 end
 
-unless system("cd #{rust_dir} && cargo build #{cargo_args}")
+unless system("cd #{root_dir} && cargo build #{cargo_args}")
   abort "ERROR: Failed to compile yerba from Rust source."
 end
 
+lib_dir = if target_platform
+            [workspace_target_dir, crate_target_dir]
+              .map { |dir| File.join(dir, target_platform, "release") }
+              .find { |dir| Dir.exist?(dir) } || lib_dir
+          else
+            [workspace_target_dir, crate_target_dir]
+              .map { |dir| File.join(dir, "release") }
+              .find { |dir| Dir.exist?(dir) } || lib_dir
+          end
+
 if target_platform
   platform_key = ENV.fetch("RCD_PLATFORM", "")
 else

data/ext/yerba/include/yerba.h

@@ -7,12 +7,12 @@
 #ifndef YERBA_H
 #define YERBA_H
 
-typedef enum YerbaNodeType {
-  YERBA_NODE_TYPE_SCALAR = 0,
-  YERBA_NODE_TYPE_MAP = 1,
-  YERBA_NODE_TYPE_SEQUENCE = 2,
-  YERBA_NODE_TYPE_NOT_FOUND = 3,
-} YerbaNodeType;
+typedef enum NodeType {
+  NODE_TYPE_SCALAR = 0,
+  NODE_TYPE_MAP = 1,
+  NODE_TYPE_SEQUENCE = 2,
+  NODE_TYPE_NOT_FOUND = 3,
+} NodeType;
 
 typedef enum YerbaValueType {
   YERBA_VALUE_TYPE_NULL = 0,
@@ -50,7 +50,7 @@ typedef struct YerbaLocation {
 
 typedef struct YerbaGetResult {
   bool is_list;
-  enum YerbaNodeType node_type;
+  enum NodeType node_type;
   struct YerbaTypedValue single;
   struct YerbaTypedList list;
   struct YerbaLocation location;
@@ -82,11 +82,11 @@ char *yerba_document_get_value(const struct Document *document, const char *path
  */
 char *yerba_document_get_values(const struct Document *document, const char *path);
 
-int32_t yerba_document_get_quote_style(const struct Document *document, const char *path);
+char *yerba_document_get_quote_style(const struct Document *document, const char *path);
 
 struct YerbaResult yerba_document_set_quote_style(struct Document *document,
                                                   const char *path,
-                                                  int32_t style);
+                                                  const char *style);
 
 bool yerba_document_evaluate_condition(const struct Document *document,
                                        const char *parent_path,
@@ -129,6 +129,11 @@ struct YerbaResult yerba_document_remove_at(struct Document *document,
                                             const char *path,
                                             uintptr_t index);
 
+struct YerbaResult yerba_document_move_item(struct Document *document,
+                                            const char *path,
+                                            uintptr_t from,
+                                            uintptr_t to);
+
 struct YerbaResult yerba_document_rename(struct Document *document,
                                          const char *source,
                                          const char *dest);
@@ -138,6 +143,11 @@ struct YerbaResult yerba_document_sort(struct Document *document,
                                        const char *by,
                                        bool case_sensitive);
 
+struct YerbaResult yerba_document_reorder(struct Document *document,
+                                          const char *path,
+                                          const char *by,
+                                          const char *order_csv);
+
 struct YerbaResult yerba_document_sort_keys(struct Document *document,
                                             const char *path,
                                             const char *order);

data/ext/yerba/yerba.c

@@ -230,7 +230,7 @@ static VALUE document_bracket(VALUE self, VALUE path) {
   }
 
   switch (result.node_type) {
-    case YERBA_NODE_TYPE_SCALAR: {
+    case NODE_TYPE_SCALAR: {
       VALUE klass = rb_path2class("Yerba::Scalar");
       VALUE value = typed_value_to_ruby(result.single);
       yerba_get_result_free(result);
@@ -240,7 +240,7 @@ static VALUE document_bracket(VALUE self, VALUE path) {
       return instance;
     }
 
-    case YERBA_NODE_TYPE_MAP: {
+    case NODE_TYPE_MAP: {
       yerba_get_result_free(result);
       VALUE klass = rb_path2class("Yerba::Map");
 
@@ -249,7 +249,7 @@ static VALUE document_bracket(VALUE self, VALUE path) {
       return instance;
     }
 
-    case YERBA_NODE_TYPE_SEQUENCE: {
+    case NODE_TYPE_SEQUENCE: {
       yerba_get_result_free(result);
       VALUE klass = rb_path2class("Yerba::Sequence");
 
@@ -298,35 +298,35 @@ static VALUE document_get_values(VALUE self, VALUE path) {
   return rb_funcall(rb_path2class("JSON"), rb_intern("parse"), 1, json_string);
 }
 
-/* document.get_quote_style(path) → :plain, :single, :double, or nil */
+/* document.get_quote_style(path) → :plain, :single, :double, :literal, etc. or nil */
 static VALUE document_get_quote_style(VALUE self, VALUE path) {
   struct Document *document = get_document(self);
-  int style = yerba_document_get_quote_style(document, StringValueCStr(path));
+  char *style = yerba_document_get_quote_style(document, StringValueCStr(path));
 
-  switch (style) {
-    case 0: return ID2SYM(rb_intern("plain"));
-    case 1: return ID2SYM(rb_intern("single"));
-    case 2: return ID2SYM(rb_intern("double"));
-    default: return Qnil;
-  }
+  if (style == NULL) return Qnil;
+
+  VALUE symbol = ID2SYM(rb_intern(style));
+
+  yerba_string_free(style);
+
+  return symbol;
 }
 
 /* document.set_quote_style(path, style) */
 static VALUE document_set_quote_style(VALUE self, VALUE path, VALUE style) {
   struct Document *document = get_document(self);
 
-  int style_int;
+  const char *style_string;
+
   if (RB_TYPE_P(style, T_SYMBOL)) {
-    ID style_id = SYM2ID(style);
-    if (style_id == rb_intern("plain")) style_int = 0;
-    else if (style_id == rb_intern("single")) style_int = 1;
-    else if (style_id == rb_intern("double")) style_int = 2;
-    else rb_raise(rb_eError, "Invalid quote style (use :plain, :single, or :double)");
+    style_string = rb_id2name(SYM2ID(style));
+  } else if (RB_TYPE_P(style, T_STRING)) {
+    style_string = StringValueCStr(style);
   } else {
-    style_int = NUM2INT(style);
+    rb_raise(rb_eError, "Invalid quote style (expected Symbol or String)");
   }
 
-  YerbaResult result = yerba_document_set_quote_style(document, StringValueCStr(path), style_int);
+  YerbaResult result = yerba_document_set_quote_style(document, StringValueCStr(path), style_string);
 
   check_result(result);
 
@@ -533,24 +533,83 @@ static VALUE document_rename(VALUE self, VALUE source, VALUE destination) {
   return self;
 }
 
-/* document.sort(path, by: nil, case_sensitive: false) */
+/* document.sort(path = "", by: nil, order: nil, case_sensitive: false) */
 static VALUE document_sort(int argc, VALUE *argv, VALUE self) {
   VALUE path, opts;
-  rb_scan_args(argc, argv, "1:", &path, &opts);
+  rb_scan_args(argc, argv, "01:", &path, &opts);
+
+  if (NIL_P(path)) path = rb_str_new_cstr("");
 
   const char *by = NULL;
   bool case_sensitive = false;
+  VALUE v_order = Qnil;
 
   if (!NIL_P(opts)) {
     VALUE v_by = rb_hash_aref(opts, ID2SYM(rb_intern("by")));
+    v_order = rb_hash_aref(opts, ID2SYM(rb_intern("order")));
     VALUE v_case_sensitive = rb_hash_aref(opts, ID2SYM(rb_intern("case_sensitive")));
 
-    if (!NIL_P(v_by)) by = StringValueCStr(v_by);
-    if (RTEST(v_case_sensitive)) case_sensitive = true;
+    if (SYMBOL_P(v_by)) {
+      VALUE by_string = rb_sym2str(v_by);
+      by = StringValueCStr(by_string);
+    } else if (!NIL_P(v_by)) {
+      by = StringValueCStr(v_by);
+    }
+
+    if (RTEST(v_case_sensitive)) {
+      case_sensitive = true;
+    }
   }
 
   struct Document *document = get_document(self);
-  YerbaResult result = yerba_document_sort(document, StringValueCStr(path), by, case_sensitive);
+  const char *path_string = StringValueCStr(path);
+
+  if (RB_TYPE_P(v_order, T_ARRAY)) {
+    VALUE order_csv = rb_ary_join(v_order, rb_str_new_cstr(","));
+    const char *order_string = StringValueCStr(order_csv);
+    const char *reorder_path = StringValueCStr(path);
+    const char *reorder_by;
+
+    if (by) {
+      VALUE reorder_by_value = rb_hash_aref(opts, ID2SYM(rb_intern("by")));
+
+      if (SYMBOL_P(reorder_by_value)) {
+        reorder_by_value = rb_sym2str(reorder_by_value);
+      }
+
+      reorder_by = StringValueCStr(reorder_by_value);
+    } else {
+      reorder_by = ".";
+    }
+
+    YerbaResult result = yerba_document_reorder(document, reorder_path, reorder_by, order_string);
+    check_result(result);
+
+    return self;
+  }
+
+  const char *order = NULL;
+
+  if (SYMBOL_P(v_order)) {
+    VALUE order_string = rb_sym2str(v_order);
+    order = StringValueCStr(order_string);
+  } else if (!NIL_P(v_order)) {
+    order = StringValueCStr(v_order);
+  }
+
+  VALUE by_with_order = Qnil;
+
+  if (order && strcmp(order, "desc") == 0) {
+    if (by) {
+      by_with_order = rb_sprintf("%s:desc", by);
+    } else {
+      by_with_order = rb_str_new_cstr(":desc");
+    }
+
+    by = StringValueCStr(by_with_order);
+  }
+
+  YerbaResult result = yerba_document_sort(document, path_string, by, case_sensitive);
 
   check_result(result);
 

data/lib/yerba/collection.rb

@@ -20,6 +20,41 @@ module Yerba
       self.class.find(@glob, path, condition: condition, select: select)
     end
 
+    def find_by(...)
+      each do |document|
+        next unless document.sequence?
+
+        result = document.root.find_by(...)
+        return result if result
+      end
+
+      nil
+    end
+
+    def where(...)
+      results = []
+
+      each do |document|
+        next unless document.sequence?
+
+        results.concat(document.root.where(...))
+      end
+
+      results
+    end
+
+    def pluck(...)
+      results = []
+
+      each do |document|
+        next unless document.sequence?
+
+        results.concat(document.root.pluck(...))
+      end
+
+      results
+    end
+
     def apply!
       each do |document|
         yield document

data/lib/yerba/document.rb

@@ -48,6 +48,22 @@ module Yerba
       end
     end
 
+    def find_by(...)
+      root.find_by(...)
+    end
+
+    def where(...)
+      root.where(...)
+    end
+
+    def pluck(...)
+      root.pluck(...)
+    end
+
+    def <<(item)
+      root << item
+    end
+
     def inspect
       if path
         "#<Yerba::Document path=#{path.inspect}>"