ruby_tree_sitter 0.20.6.4-x86_64-darwin-20

data/ext/tree_sitter/query_predicate_step.c

@@ -0,0 +1,83 @@
+#include "tree_sitter.h"
+
+extern VALUE mTreeSitter;
+
+VALUE cQueryPredicateStep;
+
+const char *done = "Done";
+const char *capture = "capture";
+const char *string = "String";
+
+DATA_WRAP(QueryPredicateStep, query_predicate_step)
+
+VALUE new_query_predicate_step_type(TSQueryPredicateStepType type) {
+  switch (type) {
+  case TSQueryPredicateStepTypeDone:
+    return ID2SYM(rb_intern(done));
+  case TSQueryPredicateStepTypeCapture:
+    return ID2SYM(rb_intern(capture));
+  case TSQueryPredicateStepTypeString:
+    return ID2SYM(rb_intern(string));
+  default:
+    return Qnil;
+  }
+}
+
+static const char *query_predicate_type_string(TSQueryPredicateStepType type) {
+  switch (type) {
+  case TSQueryPredicateStepTypeDone:
+    return done;
+  case TSQueryPredicateStepTypeCapture:
+    return capture;
+  case TSQueryPredicateStepTypeString:
+    return string;
+  default:
+    return "???";
+  }
+}
+
+TSQueryPredicateStepType value_to_query_predicate_step_type(VALUE step_type) {
+  VALUE type = SYM2ID(step_type);
+  VALUE c = rb_const_get_at(cQueryPredicateStep, rb_intern(capture));
+  VALUE s = rb_const_get_at(cQueryPredicateStep, rb_intern(string));
+
+  // NOTE: should we emit a warning instead of defaulting to done?
+  if (type == c) {
+    return TSQueryPredicateStepTypeCapture;
+  } else if (type == s) {
+    return TSQueryPredicateStepTypeString;
+  } else {
+    return TSQueryPredicateStepTypeDone;
+  }
+}
+
+static VALUE query_predicate_step_inspect(VALUE self) {
+  query_predicate_step_t *step = unwrap(self);
+  return rb_sprintf("{value_id=%i, type=%s}", step->data.value_id,
+                    query_predicate_type_string(step->data.type));
+}
+
+DATA_DEFINE_ACCESSOR(query_predicate_step, type, new_query_predicate_step_type,
+                     value_to_query_predicate_step_type)
+DATA_DEFINE_ACCESSOR(query_predicate_step, value_id, UINT2NUM, NUM2UINT)
+
+void init_query_predicate_step(void) {
+  cQueryPredicateStep =
+      rb_define_class_under(mTreeSitter, "QueryPredicateStep", rb_cObject);
+
+  rb_define_alloc_func(cQueryPredicateStep, query_predicate_step_allocate);
+
+  /* Constants */
+  rb_define_const(cQueryPredicateStep, "DONE", ID2SYM(rb_intern(done)));
+  rb_define_const(cQueryPredicateStep, "CAPTURE", ID2SYM(rb_intern(capture)));
+  rb_define_const(cQueryPredicateStep, "STRING", ID2SYM(rb_intern(string)));
+
+  /* Class methods */
+  DECLARE_ACCESSOR(cQueryPredicateStep, query_predicate_step, type)
+  DECLARE_ACCESSOR(cQueryPredicateStep, query_predicate_step, value_id)
+
+  rb_define_method(cQueryPredicateStep, "inspect", query_predicate_step_inspect,
+                   0);
+  rb_define_method(cQueryPredicateStep, "to_s", query_predicate_step_inspect,
+                   0);
+}

data/ext/tree_sitter/range.c

@@ -0,0 +1,35 @@
+#include "tree_sitter.h"
+
+extern VALUE mTreeSitter;
+
+VALUE cRange;
+
+DATA_WRAP(Range, range)
+DATA_DEFINE_ACCESSOR(range, start_point, new_point_by_val, value_to_point)
+DATA_DEFINE_ACCESSOR(range, end_point, new_point_by_val, value_to_point)
+DATA_DEFINE_ACCESSOR(range, start_byte, UINT2NUM, NUM2UINT)
+DATA_DEFINE_ACCESSOR(range, end_byte, UINT2NUM, NUM2UINT)
+
+static VALUE range_inspect(VALUE self) {
+  range_t *range = unwrap(self);
+  return rb_sprintf("{start_point= %+" PRIsVALUE ", end_point=%+" PRIsVALUE
+                    ", start_byte=%i, end_byte=%i}",
+                    new_point_by_val(range->data.start_point),
+                    new_point_by_val(range->data.end_point),
+                    range->data.start_byte, range->data.end_byte);
+}
+
+void init_range(void) {
+  cRange = rb_define_class_under(mTreeSitter, "Range", rb_cObject);
+
+  rb_define_alloc_func(cRange, range_allocate);
+
+  /* Class methods */
+  DECLARE_ACCESSOR(cRange, range, start_point)
+  DECLARE_ACCESSOR(cRange, range, end_point)
+  DECLARE_ACCESSOR(cRange, range, start_byte)
+  DECLARE_ACCESSOR(cRange, range, end_byte)
+
+  rb_define_method(cRange, "inspect", range_inspect, 0);
+  rb_define_method(cRange, "to_s", range_inspect, 0);
+}

data/ext/tree_sitter/symbol_type.c

@@ -0,0 +1,46 @@
+#include "tree_sitter.h"
+
+extern VALUE mTreeSitter;
+
+VALUE mSymbolType;
+
+const char *regular = "regular";
+const char *anonymous = "anonymous";
+const char *auxiliary = "auxiliary";
+
+TSSymbolType value_to_symbol_type(VALUE symbol_type) {
+  VALUE sym = SYM2ID(symbol_type);
+  VALUE anon = rb_const_get_at(mSymbolType, rb_intern(anonymous));
+  VALUE aux = rb_const_get_at(mSymbolType, rb_intern(auxiliary));
+
+  // NOTE: should we emit a warning instead of defaulting to regular?
+  if (sym == anon) {
+    return TSSymbolTypeAnonymous;
+  } else if (sym == aux) {
+    return TSSymbolTypeAuxiliary;
+  } else {
+    return TSSymbolTypeRegular;
+  }
+}
+
+VALUE new_symbol_type(TSSymbolType symbol_type) {
+  switch (symbol_type) {
+  case TSSymbolTypeRegular:
+    return ID2SYM(rb_intern(regular));
+  case TSSymbolTypeAnonymous:
+    return ID2SYM(rb_intern(anonymous));
+  case TSSymbolTypeAuxiliary:
+    return ID2SYM(rb_intern(auxiliary));
+  default:
+    return ID2SYM(rb_intern("this_should_never_get_reached"));
+  }
+}
+
+void init_symbol_type(void) {
+  mSymbolType = rb_define_module_under(mTreeSitter, "SymbolType");
+
+  /* Constants */
+  rb_define_const(mSymbolType, "REGULAR", ID2SYM(rb_intern(regular)));
+  rb_define_const(mSymbolType, "ANONYMOUS", ID2SYM(rb_intern(anonymous)));
+  rb_define_const(mSymbolType, "AUXILIARY", ID2SYM(rb_intern(auxiliary)));
+}

data/ext/tree_sitter/tree.c

@@ -0,0 +1,144 @@
+#include "tree_sitter.h"
+
+extern VALUE mTreeSitter;
+
+VALUE cTree;
+
+int tree_rc_free(const TSTree *tree) {
+  VALUE ptr = ULONG2NUM((uintptr_t)tree);
+  VALUE rc = rb_cv_get(cTree, "@@rc");
+  VALUE val = rb_hash_lookup(rc, ptr);
+
+  if (!NIL_P(val)) {
+    unsigned int count = NUM2UINT(val);
+    --count;
+    if (count < 1) {
+      rb_hash_delete(rc, ptr);
+      ts_tree_delete((TSTree *)tree);
+      return 1;
+    } else {
+      rb_hash_aset(rc, ptr, ULONG2NUM(count));
+      return 0;
+    }
+  } else {
+    return 1;
+  }
+}
+
+void tree_rc_new(const TSTree *tree) {
+  VALUE ptr = ULONG2NUM((uintptr_t)tree);
+  VALUE rc = rb_cv_get(cTree, "@@rc");
+  VALUE val = rb_hash_lookup(rc, ptr);
+
+  if (NIL_P(val)) {
+    rb_hash_aset(rc, ptr, UINT2NUM(1));
+  } else {
+    rb_hash_aset(rc, ptr, UINT2NUM(NUM2UINT(val) + 1));
+  }
+}
+
+DATA_TYPE(TSTree *, tree)
+static void tree_free(void *ptr) {
+  tree_t *type = (tree_t *)ptr;
+  if (tree_rc_free(type->data)) {
+    xfree(ptr);
+  }
+}
+
+DATA_MEMSIZE(tree)
+DATA_DECLARE_DATA_TYPE(tree)
+DATA_ALLOCATE(tree)
+DATA_UNWRAP(tree)
+
+VALUE new_tree(TSTree *ptr) {
+  if (ptr == NULL) {
+    return Qnil;
+  }
+  VALUE res = tree_allocate(cTree);
+  tree_t *type = unwrap(res);
+  type->data = ptr;
+  tree_rc_new(ptr);
+  return res;
+}
+
+DATA_FROM_VALUE(TSTree *, tree)
+
+static VALUE tree_copy(VALUE self) { return new_tree(ts_tree_copy(SELF)); }
+
+static VALUE tree_root_node(VALUE self) {
+  return new_node_by_val(ts_tree_root_node(SELF));
+}
+
+static VALUE tree_language(VALUE self) {
+  return new_language(ts_tree_language(SELF));
+}
+
+static VALUE tree_edit(VALUE self, VALUE edit) {
+  TSInputEdit in = value_to_input_edit(edit);
+  ts_tree_edit(SELF, &in);
+  return Qnil;
+}
+
+static VALUE tree_changed_ranges(VALUE _self, VALUE old_tree, VALUE new_tree) {
+  TSTree *old = unwrap(old_tree)->data;
+  TSTree *new = unwrap(new_tree)->data;
+  uint32_t length;
+  TSRange *ranges = ts_tree_get_changed_ranges(old, new, &length);
+  VALUE res = rb_ary_new_capa(length);
+
+  for (uint32_t i = 0; i < length; i++) {
+    rb_ary_push(res, new_range(&ranges[i]));
+  }
+
+  if (ranges) {
+    free(ranges);
+  }
+
+  return res;
+}
+
+static VALUE tree_print_dot_graph(VALUE self, VALUE file) {
+  Check_Type(file, T_STRING);
+  char *path = StringValueCStr(file);
+  FILE *fd = fopen(path, "w+");
+  ts_tree_print_dot_graph(SELF, fd);
+  fclose(fd);
+  return Qnil;
+}
+
+static VALUE tree_finalizer(VALUE _self) {
+  VALUE rc = rb_cv_get(cTree, "@@rc");
+  VALUE keys = rb_funcall(rc, rb_intern("keys"), 0);
+  long len = RARRAY_LEN(keys);
+
+  for (long i = 0; i < len; ++i) {
+    VALUE curr = RARRAY_AREF(keys, i);
+    unsigned int val = NUM2UINT(rb_hash_lookup(rc, curr));
+    if (val > 0) {
+      ts_tree_delete((TSTree *)NUM2ULONG(curr));
+    }
+
+    rb_hash_delete(rc, curr);
+  }
+
+  return Qnil;
+}
+
+void init_tree(void) {
+  cTree = rb_define_class_under(mTreeSitter, "Tree", rb_cObject);
+
+  rb_undef_alloc_func(cTree);
+
+  /* Class methods */
+  rb_define_method(cTree, "copy", tree_copy, 0);
+  rb_define_method(cTree, "root_node", tree_root_node, 0);
+  rb_define_method(cTree, "language", tree_language, 0);
+  rb_define_method(cTree, "edit", tree_edit, 1);
+  rb_define_module_function(cTree, "changed_ranges", tree_changed_ranges, 2);
+  rb_define_method(cTree, "print_dot_graph", tree_print_dot_graph, 1);
+  rb_define_module_function(cTree, "finalizer", tree_finalizer, 0);
+
+  // Reference-count created trees
+  VALUE rc = rb_hash_new();
+  rb_cv_set(cTree, "@@rc", rc);
+}

data/ext/tree_sitter/tree_cursor.c

@@ -0,0 +1,97 @@
+#include "tree_sitter.h"
+
+extern VALUE mTreeSitter;
+
+VALUE cTreeCursor;
+
+DATA_TYPE(TSTreeCursor, tree_cursor)
+static void tree_cursor_free(void *ptr) {
+  tree_cursor_t *type = (tree_cursor_t *)ptr;
+  ts_tree_cursor_delete(&type->data);
+  xfree(ptr);
+}
+DATA_MEMSIZE(tree_cursor)
+DATA_DECLARE_DATA_TYPE(tree_cursor)
+DATA_ALLOCATE(tree_cursor)
+DATA_UNWRAP(tree_cursor)
+DATA_NEW(cTreeCursor, TSTreeCursor, tree_cursor)
+DATA_FROM_VALUE(TSTreeCursor, tree_cursor)
+
+static VALUE tree_cursor_initialize(VALUE self, VALUE node) {
+  TSNode n = value_to_node(node);
+  tree_cursor_t *ptr = unwrap(self);
+  ptr->data = ts_tree_cursor_new(n);
+  return self;
+}
+
+static VALUE tree_cursor_reset(VALUE self, VALUE node) {
+  ts_tree_cursor_reset(&SELF, value_to_node(node));
+  return Qnil;
+}
+
+static VALUE tree_cursor_current_node(VALUE self) {
+  TSNode node = ts_tree_cursor_current_node(&SELF);
+  return new_node(&node);
+}
+
+static VALUE tree_cursor_current_field_name(VALUE self) {
+  return safe_str(ts_tree_cursor_current_field_name(&SELF));
+}
+
+static VALUE tree_cursor_current_field_id(VALUE self) {
+  return UINT2NUM(ts_tree_cursor_current_field_id(&SELF));
+}
+
+static VALUE tree_cursor_goto_parent(VALUE self) {
+  return ts_tree_cursor_goto_parent(&SELF) ? Qtrue : Qfalse;
+}
+
+static VALUE tree_cursor_goto_next_sibling(VALUE self) {
+  return ts_tree_cursor_goto_next_sibling(&SELF) ? Qtrue : Qfalse;
+}
+
+static VALUE tree_cursor_goto_first_child(VALUE self) {
+  return ts_tree_cursor_goto_first_child(&SELF) ? Qtrue : Qfalse;
+}
+
+static VALUE tree_cursor_goto_first_child_for_byte(VALUE self, VALUE byte) {
+  return LL2NUM(
+      ts_tree_cursor_goto_first_child_for_byte(&SELF, NUM2UINT(byte)));
+}
+
+static VALUE tree_cursor_goto_first_child_for_point(VALUE self, VALUE point) {
+  return LL2NUM(
+      ts_tree_cursor_goto_first_child_for_point(&SELF, value_to_point(point)));
+}
+
+static VALUE tree_cursor_copy(VALUE self) {
+  VALUE res = tree_cursor_allocate(cTreeCursor);
+  tree_cursor_t *ptr = unwrap(res);
+  ptr->data = ts_tree_cursor_copy(&SELF);
+  return res;
+}
+
+void init_tree_cursor(void) {
+  cTreeCursor = rb_define_class_under(mTreeSitter, "TreeCursor", rb_cObject);
+
+  rb_define_alloc_func(cTreeCursor, tree_cursor_allocate);
+
+  /* Class methods */
+  rb_define_method(cTreeCursor, "initialize", tree_cursor_initialize, 1);
+  rb_define_method(cTreeCursor, "reset", tree_cursor_reset, 1);
+  rb_define_method(cTreeCursor, "current_node", tree_cursor_current_node, 0);
+  rb_define_method(cTreeCursor, "current_field_name",
+                   tree_cursor_current_field_name, 0);
+  rb_define_method(cTreeCursor, "current_field_id",
+                   tree_cursor_current_field_id, 0);
+  rb_define_method(cTreeCursor, "goto_parent", tree_cursor_goto_parent, 0);
+  rb_define_method(cTreeCursor, "goto_next_sibling",
+                   tree_cursor_goto_next_sibling, 0);
+  rb_define_method(cTreeCursor, "goto_first_child",
+                   tree_cursor_goto_first_child, 0);
+  rb_define_method(cTreeCursor, "goto_first_child_for_byte",
+                   tree_cursor_goto_first_child_for_byte, 1);
+  rb_define_method(cTreeCursor, "goto_first_child_for_point",
+                   tree_cursor_goto_first_child_for_point, 1);
+  rb_define_method(cTreeCursor, "copy", tree_cursor_copy, 0);
+}

data/ext/tree_sitter/tree_sitter.c

@@ -0,0 +1,32 @@
+#include "tree_sitter.h"
+
+VALUE mTreeSitter;
+
+void Init_tree_sitter() {
+  mTreeSitter = rb_define_module("TreeSitter");
+
+  rb_define_const(mTreeSitter, "LANGUAGE_VERSION",
+                  INT2NUM(TREE_SITTER_LANGUAGE_VERSION));
+  rb_define_const(mTreeSitter, "MIN_COMPATIBLE_LANGUAGE_VERSION",
+                  TREE_SITTER_MIN_COMPATIBLE_LANGUAGE_VERSION);
+
+  init_encoding();
+  init_input();
+  init_input_edit();
+  init_language();
+  init_logger();
+  init_node();
+  init_parser();
+  init_point();
+  init_quantifier();
+  init_query();
+  init_query_capture();
+  init_query_cursor();
+  init_query_error();
+  init_query_match();
+  init_query_predicate_step();
+  init_range();
+  init_symbol_type();
+  init_tree();
+  init_tree_cursor();
+}

data/ext/tree_sitter/tree_sitter.h

@@ -0,0 +1,107 @@
+#ifndef _RB_TREE_SITTER_H
+#define _RB_TREE_SITTER_H
+
+#include "macros.h"
+#include <dlfcn.h>
+#include <fcntl.h>
+#include <ruby.h>
+#include <stdio.h>
+#include <string.h>
+#include <tree_sitter/api.h>
+
+static inline VALUE safe_str(const char *str) {
+  if (str == NULL) {
+    return Qnil;
+  } else {
+    return rb_utf8_str_new_cstr(str);
+  }
+}
+
+static inline VALUE safe_str2(const char *str, uint32_t len) {
+  if (str == NULL) {
+    return Qnil;
+  } else if (len == 0) {
+    return rb_utf8_str_new_cstr("");
+  } else {
+    return rb_utf8_str_new(str, len);
+  }
+}
+
+static inline VALUE safe_symbol(const char *str) {
+  if (str == NULL) {
+    return Qnil;
+  } else {
+    return ID2SYM(rb_intern(str));
+  }
+}
+
+// VALUE to TS* converters
+
+TSInput value_to_input(VALUE);
+TSInputEdit value_to_input_edit(VALUE);
+TSInputEncoding value_to_encoding(VALUE);
+TSLanguage *value_to_language(VALUE);
+TSLogger value_to_logger(VALUE);
+TSNode value_to_node(VALUE);
+TSPoint value_to_point(VALUE);
+TSQuantifier value_to_quantifier(VALUE);
+TSQuery *value_to_query(VALUE);
+TSQueryCursor *value_to_query_cursor(VALUE);
+TSQueryError value_to_query_error(VALUE);
+TSQueryMatch value_to_query_match(VALUE);
+TSQueryPredicateStep value_to_query_predicate_step(VALUE);
+TSQueryPredicateStepType value_to_query_predicate_step_type(VALUE);
+TSRange value_to_range(VALUE);
+TSSymbolType value_to_symbol_type(VALUE);
+TSTree *value_to_tree(VALUE);
+TSTreeCursor value_to_tree_cursor(VALUE);
+
+// TS* to VALUE converters
+VALUE new_input(const TSInput *);
+VALUE new_language(const TSLanguage *);
+VALUE new_logger(const TSLogger *);
+VALUE new_logger_by_val(TSLogger);
+VALUE new_node(const TSNode *);
+VALUE new_node_by_val(TSNode);
+VALUE new_point(const TSPoint *);
+VALUE new_point_by_val(TSPoint);
+VALUE new_query_capture(const TSQueryCapture *);
+VALUE new_query_match(const TSQueryMatch *);
+VALUE new_query_predicate_step(const TSQueryPredicateStep *);
+VALUE new_range(const TSRange *);
+VALUE new_symbol_type(TSSymbolType);
+VALUE new_tree(TSTree *);
+
+// All init_* functions are called from Init_tree_sitter
+void init_encoding(void);
+void init_input(void);
+void init_input_edit(void);
+void init_language(void);
+void init_logger(void);
+void init_node(void);
+void init_parser(void);
+void init_point(void);
+void init_quantifier(void);
+void init_query(void);
+void init_query_capture(void);
+void init_query_cursor(void);
+void init_query_error(void);
+void init_query_match(void);
+void init_query_predicate_step(void);
+void init_range(void);
+void init_symbol_type(void);
+void init_tree(void);
+void init_tree_cursor(void);
+
+// Other helpers
+const char *quantifier_str(TSQuantifier);
+const char *query_error_str(TSQueryError);
+
+// TSTree reference counting
+int tree_rc_free(const TSTree *);
+void tree_rc_new(const TSTree *);
+
+// This is a special entry-point for the extension
+void Init_tree_sitter(void);
+
+#endif

data/lib/tree_sitter/node.rb

@@ -0,0 +1,164 @@
+# frozen_string_literal: true
+
+module TreeSitter
+  class Node
+    def fields
+      return @fields if @fields
+
+      @fields = Set.new
+      child_count.times do |i|
+        name = field_name_for_child(i)
+        @fields << name.to_sym if name
+      end
+
+      @fields
+    end
+
+    def field?(field)
+      fields.include?(field)
+    end
+
+    # Access node's named children.
+    #
+    # It's similar to {#fetch}, but differes in input type, return values, and
+    # the internal implementation.
+    #
+    # Both of these methods exist for separate use cases, but also because
+    # sometime tree-sitter does some monkey business and having both separate
+    # implementations can help.
+    #
+    # Comparison with {#fetch}:
+    #
+    #              []                            | fetch
+    #              ------------------------------+----------------------
+    # input types  Integer, String, Symbol       | Array<String, Symbol>
+    #              Array<Integer, String, Symbol>|
+    #              ------------------------------+----------------------
+    # returns      1-to-1 correspondance with    | unique nodes
+    #              input                         |
+    #              ------------------------------+----------------------
+    # uses         named_child                   | field_name_for_child
+    #              child_by_field_name           |   via each_node
+    #              ------------------------------+----------------------
+    #
+    # @param keys [Integer | String | Symbol | Array<Integer, String, Symbol>, #read]
+    #
+    # @return [Node | Array<Node>]
+    def [](*keys)
+      case keys.length
+      when 0 then raise "#{self.class.name}##{__method__} requires a key."
+      when 1
+        case k = keys.first
+        when Numeric        then named_child(k)
+        when String, Symbol
+          if fields.include?(k.to_sym)
+            child_by_field_name(k.to_s)
+          else
+            raise "Cannot find field #{k}"
+          end
+        else raise <<~ERR
+          #{self.class.name}##{__method__} accepts Integer and returns named child at given index,
+              or a (String | Symbol) and returns the child by given field name.
+        ERR
+        end
+      else
+        keys.map { |key| self[key] }
+      end
+    end
+
+    # Allows access to child_by_field_name without using [].
+    def method_missing(method_name, *_args, &_block)
+      if fields.include?(method_name)
+        child_by_field_name(method_name.to_s)
+      else
+        super
+      end
+    end
+
+    def respond_to_missing?(*args)
+      init_fields
+      args.length == 1 && fields.include?(args[0])
+    end
+
+    # Iterate over a node's children.
+    #
+    # @yieldparam child [Node] the child
+    def each
+      return enum_for __method__ if !block_given?
+
+      (0...(child_count)).each do |i|
+        yield child(i)
+      end
+    end
+
+    # Iterate over a node's children assigned to a field.
+    #
+    # @yieldparam name [NilClass | String] field name.
+    # @yieldparam child [Node] the child.
+    def each_field
+      return enum_for __method__ if !block_given?
+
+      each.with_index do |c, i|
+        f = field_name_for_child(i)
+        next if f.nil? || f.empty?
+
+        yield f, c
+      end
+    end
+
+    # Iterate over a node's named children
+    #
+    # @yieldparam child [Node] the child
+    def each_named
+      return enum_for __method__ if !block_given?
+
+      (0...(named_child_count)).each do |i|
+        yield named_child(i)
+      end
+    end
+
+    def to_a
+      each.to_a
+    end
+
+    # Access node's named children.
+    #
+    # It's similar to {#fetch}, but differes in input type, return values, and
+    # the internal implementation.
+    #
+    # Both of these methods exist for separate use cases, but also because
+    # sometime tree-sitter does some monkey business and having both separate
+    # implementations can help.
+    #
+    # Comparison with {#fetch}:
+    #
+    #              []                            | fetch
+    #              ------------------------------+----------------------
+    # input types  Integer, String, Symbol       | String, Symbol
+    #              Array<Integer, String, Symbol>| Array<String, Symbol>
+    #              ------------------------------+----------------------
+    # returns      1-to-1 correspondance with    | unique nodes
+    #              input                         |
+    #              ------------------------------+----------------------
+    # uses         named_child                   | field_name_for_child
+    #              child_by_field_name           |   via each_node
+    #              ------------------------------+----------------------
+    def fetch(*keys)
+      dict = {}
+      keys.each.with_index do |k, i|
+        dict[k.to_s] = i
+      end
+
+      res = {}
+      each_field do |f, c|
+        if dict.key?(f)
+          res[dict[f]] = c
+          dict.delete(f)
+        end
+        break if dict.empty?
+      end
+
+      res.sort.map { |_, v| v }
+    end
+  end
+end