yerba 0.3.0 → 0.4.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 477663fa314d01cbe3c98e8a5a8bdc08c0e26d287bff36d23ae1eea519e81609
-  data.tar.gz: 3a9ce13df82bbebd5cbbfc7590d0d334e841c4314bb059f31047ba707bd9bb1e
+  metadata.gz: 9f0b8b264602f7f31483cff42e8c1c17266e6caa3f5fd8d2c737e6bec285b034
+  data.tar.gz: a0b706d50c311af27a7f0b58f64323dbb9dd38849ff31d372184b5ec4e417793
 SHA512:
-  metadata.gz: be2932fad743bdf806070d5898f73533e8225994dc8d6581b0f47c5ee79519a8cfc83fd4f88cae4607fe5e36ee85f2cc165f288bbeca0184a9756fe18e7b3b27
-  data.tar.gz: 6251a8c8d261c458781e48a2adc8364172bd999c4ecbcc8e38ba625cf9a2434285efabd96dbfb64eabf78791f5a6a187cb76114bfc37facce78d48aa782696cf
+  metadata.gz: a246cdd95c9d1b41b3e79c49501b61edef83e390d6915e43a9350d26b2012d98f319770e993f15e73e6903a7c611745f681220d9eb7569a0cb478442fd2941f4
+  data.tar.gz: 93aef7a57eae55c8b66f3271e54a7eb6021afa7cb54005ea74accab405ad584a96d998886c1eae4af7ee56442be99c0c75583715c811b5298f89f9102a83561f

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:
@@ -371,7 +413,10 @@ Use `yerba init` to create one, then `yerba apply` to apply all rules, or `yerba
 ```bash
 yerba init
 yerba apply
+yerba apply path/to/file.yml
+
 yerba check
+yerba check path/to/file.yml
 ```
 
 Each rule specifies a file glob and a list of steps to run in order:
@@ -425,6 +470,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 +560,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 +606,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 +630,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 +659,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 +677,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,
@@ -121,6 +121,10 @@ struct YerbaResult yerba_document_insert_object(struct Document *document,
 
 struct YerbaResult yerba_document_delete(struct Document *document, const char *path);
 
+struct YerbaResult yerba_document_insert_objects(struct Document *document,
+                                                 const char *path,
+                                                 const char *json);
+
 struct YerbaResult yerba_document_remove(struct Document *document,
                                          const char *path,
                                          const char *value);
@@ -129,6 +133,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 +147,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);
@@ -151,6 +165,15 @@ struct YerbaResult yerba_document_blank_lines(struct Document *document,
                                               const char *path,
                                               uintptr_t count);
 
+/**
+ * Caller must free with yerba_string_free.
+ */
+char *yerba_yerbafile_find(const char *directory);
+
+struct YerbaResult yerba_document_apply_yerbafile(struct Document *document,
+                                                  const char *file_path,
+                                                  const char *yerbafile_path);
+
 char *yerba_document_to_string(const struct Document *document);
 
 void yerba_string_free(char *s);

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);
 
@@ -488,6 +488,17 @@ static VALUE document_insert_object(int argc, VALUE *argv, VALUE self) {
   return self;
 }
 
+/* document.insert_objects(path, array) */
+static VALUE document_insert_objects(VALUE self, VALUE path, VALUE array) {
+  struct Document *document = get_document(self);
+  VALUE json_string = rb_funcall(rb_path2class("JSON"), rb_intern("generate"), 1, array);
+
+  YerbaResult result = yerba_document_insert_objects(document, StringValueCStr(path), StringValueCStr(json_string));
+  check_result(result);
+
+  return self;
+}
+
 /* document.delete(path, condition: nil) */
 static VALUE document_delete(int argc, VALUE *argv, VALUE self) {
   VALUE path, opts;
@@ -533,24 +544,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);
 
@@ -612,6 +682,23 @@ static VALUE document_blank_lines(VALUE self, VALUE path, VALUE count) {
   return self;
 }
 
+/* document.apply_yerbafile(yerbafile_path = nil) */
+static VALUE document_apply_yerbafile(int argc, VALUE *argv, VALUE self) {
+  VALUE yerbafile_path;
+  rb_scan_args(argc, argv, "01", &yerbafile_path);
+
+  struct Document *document = get_document(self);
+  VALUE file_path = rb_iv_get(self, "@path");
+
+  const char *file_path_str = NIL_P(file_path) ? "" : StringValueCStr(file_path);
+  const char *yerbafile_path_str = NIL_P(yerbafile_path) ? NULL : StringValueCStr(yerbafile_path);
+
+  YerbaResult result = yerba_document_apply_yerbafile(document, file_path_str, yerbafile_path_str);
+  check_result(result);
+
+  return self;
+}
+
 /* document.to_s */
 static VALUE document_to_s(VALUE self) {
   struct Document *document = get_document(self);
@@ -714,6 +801,22 @@ static VALUE collection_s_find(int argc, VALUE *argv, VALUE self) {
   return rb_funcall(rb_path2class("JSON"), rb_intern("parse"), 1, json_string);
 }
 
+/* Yerbafile.locate(directory = nil) → path string or nil */
+static VALUE yerbafile_s_locate(int argc, VALUE *argv, VALUE klass) {
+  VALUE directory;
+  rb_scan_args(argc, argv, "01", &directory);
+
+  const char *dir = NIL_P(directory) ? NULL : StringValueCStr(directory);
+  char *result = yerba_yerbafile_find(dir);
+
+  if (!result) return Qnil;
+
+  VALUE path = make_utf8_string(result);
+  yerba_string_free(result);
+
+  return path;
+}
+
 void Init_yerba(void) {
   rb_require("json");
 
@@ -744,6 +847,7 @@ void Init_yerba(void) {
   rb_define_method(rb_cDocument, "set", document_set, -1);
   rb_define_method(rb_cDocument, "insert", document_insert, -1);
   rb_define_method(rb_cDocument, "insert_object", document_insert_object, -1);
+  rb_define_method(rb_cDocument, "insert_objects", document_insert_objects, 2);
   rb_define_method(rb_cDocument, "delete", document_delete, -1);
   rb_define_method(rb_cDocument, "remove", document_remove, 2);
   rb_define_method(rb_cDocument, "remove_at", document_remove_at, 2);
@@ -752,8 +856,12 @@ void Init_yerba(void) {
   rb_define_method(rb_cDocument, "sort_keys", document_sort_keys, 2);
   rb_define_method(rb_cDocument, "quote_style", document_quote_style, -1);
   rb_define_method(rb_cDocument, "blank_lines", document_blank_lines, 2);
+  rb_define_method(rb_cDocument, "apply_yerbafile", document_apply_yerbafile, -1);
   rb_define_method(rb_cDocument, "to_s", document_to_s, 0);
-  rb_define_method(rb_cDocument, "save!", document_save, 0);
+  rb_define_method(rb_cDocument, "write!", document_save, 0);
   rb_define_method(rb_cDocument, "changed?", document_changed_p, 0);
   rb_define_method(rb_cDocument, "path", document_path, 0);
+
+  VALUE rb_cYerbafile = rb_define_class_under(rb_mYerba, "Yerbafile", rb_cObject);
+  rb_define_singleton_method(rb_cYerbafile, "locate", yerbafile_s_locate, -1);
 }

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(...).to_a)
+      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