yerba 0.2.2 → 0.4.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 29db5a562148d3de23fa0a071d7e6c43481bc376e57a01fb68c90537119e3785
-  data.tar.gz: 6e7e32d7779acc555896c77a27c64b6231770e58951877ca36c1efb189539037
+  metadata.gz: 8e77d3cce1f16b9adf15e44b0dec51f2182ab12eeeacea0e0d6d1223d7a1f23b
+  data.tar.gz: 7abd1edd2196ce73d22dab4b05dbb2f2af47cb04e1cff756bd8df5a678dcbe9e
 SHA512:
-  metadata.gz: fcc7982270f2875ae541830e4a5343d92834a09bb8a425e3a11fff231a42555f55771359365d07bee692533ba2f1899792924fc5f9c1fab48d46a661d839b842
-  data.tar.gz: f67c13246c8ba1d462e015e117344d9d3d4e00163c8810bd46e36015672e5697e31fd2a457360cda924d38f6ac66c900907ec0bb8bd7a7782ff086cb8f16d8e0
+  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.2"
+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
@@ -162,6 +164,12 @@ Use `--condition` to only apply the change when a sibling field matches:
 yerba set config.yml "database.host" "0.0.0.0" --condition ".port == 5432"
 ```
 
+Use `--all` to update all nodes matching a wildcard selector:
+
+```bash
+yerba set videos.yml "[].description" "" --all
+```
+
 ### `insert`
 
 Insert a new key into a map or a new item into a sequence. By default, new items are appended at the end.
@@ -249,15 +257,25 @@ yerba move-key config.yml "database.pool" --after "database.name"
 
 ### `sort`
 
-Sort items in a sequence. For simple scalar sequences, no options are needed. For sequences of maps, use `--by` to specify sort fields. Append `:desc` for descending order:
+Sort items in a sequence. For simple scalar sequences, no options are needed. For sequences of maps, use `--by` to specify the sort field. Use `--order desc` for descending. Repeat `--by` and `--order` for tie-breakers:
 
 ```bash
 yerba sort config.yml "tags"
-yerba sort videos.yml --by "title"
-yerba sort videos.yml --by "date:desc,title"
-yerba sort videos.yml "[].speakers" --by "name"
+yerba sort videos.yml --by ".title"
+yerba sort videos.yml --by ".date" --order desc --by ".title"
+yerba sort videos.yml "[].speakers" --by ".name"
+```
+
+Use `--order` with a comma-separated list to specify an explicit custom order. All items must be listed:
+
+```bash
+yerba sort videos.yml "[]" --by ".id" --order "talk-c,talk-a,talk-b"
+yerba sort speakers.yml "[]" --by ".name" --order "Charlie,Alice,Bob"
+yerba sort config.yml "tags" --by "." --order "yaml,ruby,rust"
 ```
 
+This is useful for reordering items in a specific sequence (e.g., conference schedule order, priority lists) or when an LLM agent needs to rearrange items programmatically.
+
 ### `sort-keys`
 
 Reorder the keys in a map to match a predefined order. If any key in the document is not present in the order list, the command aborts with an error, this ensures you account for every field:
@@ -270,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
@@ -285,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:
@@ -295,6 +343,67 @@ 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:
+
+```bash
+yerba selectors config.yml
+```
+
+Output:
+```
+database
+database.host
+database.port
+tags
+tags[]
+```
+
+For sequences of objects:
+
+```bash
+yerba selectors videos.yml
+```
+
+Output:
+```
+[]
+[].id
+[].title
+[].speakers
+[].speakers[]
+[].speakers[].name
+[].speakers[].slug
+[].video_id
+[].video_provider
+```
+
+Pass a selector to scope the output to a specific subtree:
+
+```bash
+yerba selectors config.yml "database"
+yerba selectors videos.yml "[]"
+yerba selectors videos.yml "[].speakers"
+```
+
+Works with glob patterns to show the union of selectors across multiple files:
+
+```bash
+yerba selectors "data/**/videos.yml"
+yerba selectors "data/**/videos.yml" "[]"
+```
+
 ## `Yerbafile`
 
 A `Yerbafile` is a YAML configuration file that defines formatting and editing rules as pipelines of operations that are applied to your files across your project.
@@ -358,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:
@@ -428,6 +538,12 @@ document["database"]["host"].value = "0.0.0.0"
 document.set("database.port", 3306)
 ```
 
+Set all matching nodes at once with `all: true`:
+
+```ruby
+document.set("[].description", "", all: true)
+```
+
 Insert new keys with positional control:
 
 ```ruby
@@ -441,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
@@ -450,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
 ```
 
@@ -474,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
@@ -499,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
 ```
@@ -518,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
@@ -93,19 +112,27 @@ if target_platform
              end
 end
 
-lib_path = File.join(lib_dir, lib_name)
+static_lib = File.join(lib_dir, "libyerba.a")
 
-unless File.exist?(lib_path)
-  abort "ERROR: Shared library not found at #{lib_path}"
-end
+if File.exist?(static_lib)
+  puts "yerba: Static library found at #{static_lib}"
+  $LDFLAGS << " #{static_lib}"
+else
+  lib_path = File.join(lib_dir, lib_name)
 
-puts "yerba: Shared library found at #{lib_path}"
+  unless File.exist?(lib_path)
+    abort "ERROR: Shared library not found at #{lib_path}"
+  end
 
-$LDFLAGS << " -L#{lib_dir} -lyerba"
-$CFLAGS << " -I#{File.join(__dir__, "include")}"
+  puts "yerba: Shared library found at #{lib_path} (dynamic)"
+
+  $LDFLAGS << " -L#{lib_dir} -lyerba"
 
-if RbConfig::CONFIG["host_os"].match?(/darwin|linux/)
-  $LDFLAGS << " -Wl,-rpath,#{lib_dir}"
+  if RbConfig::CONFIG["host_os"].match?(/darwin|linux/)
+    $LDFLAGS << " -Wl,-rpath,#{lib_dir}"
+  end
 end
 
+$CFLAGS << " -I#{File.join(__dir__, "include")}"
+
 create_makefile("yerba/yerba")

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,
@@ -102,7 +102,8 @@ char *yerba_document_find(const struct Document *document,
 struct YerbaResult yerba_document_set(struct Document *document,
                                       const char *path,
                                       const char *value,
-                                      enum YerbaValueType value_type);
+                                      enum YerbaValueType value_type,
+                                      bool all);
 
 struct YerbaResult yerba_document_insert(struct Document *document,
                                          const char *path,
@@ -128,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);
@@ -137,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);
 
@@ -399,6 +399,7 @@ static VALUE document_set(int argc, VALUE *argv, VALUE self) {
   const char *c_value;
   YerbaValueType value_type;
   char number_buffer[64];
+  bool all = false;
 
   if (value == Qnil) {
     c_value = "null";
@@ -422,7 +423,13 @@ static VALUE document_set(int argc, VALUE *argv, VALUE self) {
     value_type = YERBA_VALUE_TYPE_STRING;
   }
 
-  YerbaResult result = yerba_document_set(document, StringValueCStr(path), c_value, value_type);
+  if (!NIL_P(opts)) {
+    VALUE v_all = rb_hash_aref(opts, ID2SYM(rb_intern("all")));
+
+    if (RTEST(v_all)) all = true;
+  }
+
+  YerbaResult result = yerba_document_set(document, StringValueCStr(path), c_value, value_type, all);
   check_result(result);
 
   return self;
@@ -526,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