patchyaml 0.1.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: cfc5b7ca990f2b4e504bcc910faad8efd99467aef4d53b58115c04c626e3a0c3
+  data.tar.gz: 1d63195ee9f96395da68c3583d30249217db45c9add3c19a0435fd424b41f49f
+SHA512:
+  metadata.gz: 408cbf60cfbcb5a5003744d506dfbc6ff7aa090f09e2c57968e8469f665eae07091c922c7c65d6d94cd975cacb5a953b585090143f02ddecb53e3f5237c2cbdd
+  data.tar.gz: d9c9dad17bc67cad43748a63ca5f6e2125c50b17147974fbc5db65e21ccf7ed455b2e98be4736fa72677ec59a245efd2551e24ea454ff1fec4654a81da6d3f26

data/.rspec

@@ -0,0 +1,3 @@
+--format documentation
+--color
+--require spec_helper

data/.rubocop.yml

@@ -0,0 +1,65 @@
+AllCops:
+  TargetRubyVersion: 3.4
+  SuggestExtensions: false
+  NewCops: enable
+
+Style/StringLiterals:
+  EnforcedStyle: double_quotes
+
+Style/StringLiteralsInInterpolation:
+  EnforcedStyle: double_quotes
+
+Layout/LineLength:
+  Max: 120
+  Exclude:
+    - "**/spec/**/**"
+
+Layout/FirstHashElementIndentation:
+  EnforcedStyle: consistent
+
+Layout/EndAlignment:
+  EnforcedStyleAlignWith: start_of_line
+
+Layout/MultilineMethodCallIndentation:
+  EnforcedStyle: indented
+
+Style/Documentation:
+  Enabled: false
+
+Layout/CaseIndentation:
+  EnforcedStyle: end
+
+Layout/FirstArgumentIndentation:
+  EnforcedStyle: consistent_relative_to_receiver
+
+Layout/ArgumentAlignment:
+  EnforcedStyle: with_fixed_indentation
+
+Style/EmptyCaseCondition:
+  Enabled: false
+
+Metrics/BlockLength:
+  Exclude:
+    - "**/spec/**/**.rb"
+    - "**/**/**.gemspec"
+
+Metrics/ClassLength:
+  Enabled: false
+
+Metrics/ModuleLength:
+  Enabled: false
+
+Metrics/MethodLength:
+  Enabled: false
+
+Metrics/AbcSize:
+  Enabled: false
+
+Metrics/CyclomaticComplexity:
+  Enabled: false
+
+Metrics/PerceivedComplexity:
+  Enabled: false
+
+Lint/LiteralAsCondition:
+  Enabled: false

data/CODE_OF_CONDUCT.md

@@ -0,0 +1,132 @@
+# Contributor Covenant Code of Conduct
+
+## Our Pledge
+
+We as members, contributors, and leaders pledge to make participation in our
+community a harassment-free experience for everyone, regardless of age, body
+size, visible or invisible disability, ethnicity, sex characteristics, gender
+identity and expression, level of experience, education, socio-economic status,
+nationality, personal appearance, race, caste, color, religion, or sexual
+identity and orientation.
+
+We pledge to act and interact in ways that contribute to an open, welcoming,
+diverse, inclusive, and healthy community.
+
+## Our Standards
+
+Examples of behavior that contributes to a positive environment for our
+community include:
+
+* Demonstrating empathy and kindness toward other people
+* Being respectful of differing opinions, viewpoints, and experiences
+* Giving and gracefully accepting constructive feedback
+* Accepting responsibility and apologizing to those affected by our mistakes,
+  and learning from the experience
+* Focusing on what is best not just for us as individuals, but for the overall
+  community
+
+Examples of unacceptable behavior include:
+
+* The use of sexualized language or imagery, and sexual attention or advances of
+  any kind
+* Trolling, insulting or derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or email address,
+  without their explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Enforcement Responsibilities
+
+Community leaders are responsible for clarifying and enforcing our standards of
+acceptable behavior and will take appropriate and fair corrective action in
+response to any behavior that they deem inappropriate, threatening, offensive,
+or harmful.
+
+Community leaders have the right and responsibility to remove, edit, or reject
+comments, commits, code, wiki edits, issues, and other contributions that are
+not aligned to this Code of Conduct, and will communicate reasons for moderation
+decisions when appropriate.
+
+## Scope
+
+This Code of Conduct applies within all community spaces, and also applies when
+an individual is officially representing the community in public spaces.
+Examples of representing our community include using an official email address,
+posting via an official social media account, or acting as an appointed
+representative at an online or offline event.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported to the community leaders responsible for enforcement at
+hey@vito.io.
+All complaints will be reviewed and investigated promptly and fairly.
+
+All community leaders are obligated to respect the privacy and security of the
+reporter of any incident.
+
+## Enforcement Guidelines
+
+Community leaders will follow these Community Impact Guidelines in determining
+the consequences for any action they deem in violation of this Code of Conduct:
+
+### 1. Correction
+
+**Community Impact**: Use of inappropriate language or other behavior deemed
+unprofessional or unwelcome in the community.
+
+**Consequence**: A private, written warning from community leaders, providing
+clarity around the nature of the violation and an explanation of why the
+behavior was inappropriate. A public apology may be requested.
+
+### 2. Warning
+
+**Community Impact**: A violation through a single incident or series of
+actions.
+
+**Consequence**: A warning with consequences for continued behavior. No
+interaction with the people involved, including unsolicited interaction with
+those enforcing the Code of Conduct, for a specified period of time. This
+includes avoiding interactions in community spaces as well as external channels
+like social media. Violating these terms may lead to a temporary or permanent
+ban.
+
+### 3. Temporary Ban
+
+**Community Impact**: A serious violation of community standards, including
+sustained inappropriate behavior.
+
+**Consequence**: A temporary ban from any sort of interaction or public
+communication with the community for a specified period of time. No public or
+private interaction with the people involved, including unsolicited interaction
+with those enforcing the Code of Conduct, is allowed during this period.
+Violating these terms may lead to a permanent ban.
+
+### 4. Permanent Ban
+
+**Community Impact**: Demonstrating a pattern of violation of community
+standards, including sustained inappropriate behavior, harassment of an
+individual, or aggression toward or disparagement of classes of individuals.
+
+**Consequence**: A permanent ban from any sort of public interaction within the
+community.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage],
+version 2.1, available at
+[https://www.contributor-covenant.org/version/2/1/code_of_conduct.html][v2.1].
+
+Community Impact Guidelines were inspired by
+[Mozilla's code of conduct enforcement ladder][Mozilla CoC].
+
+For answers to common questions about this code of conduct, see the FAQ at
+[https://www.contributor-covenant.org/faq][FAQ]. Translations are available at
+[https://www.contributor-covenant.org/translations][translations].
+
+[homepage]: https://www.contributor-covenant.org
+[v2.1]: https://www.contributor-covenant.org/version/2/1/code_of_conduct.html
+[Mozilla CoC]: https://github.com/mozilla/diversity
+[FAQ]: https://www.contributor-covenant.org/faq
+[translations]: https://www.contributor-covenant.org/translations

data/LICENSE.txt

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2025 Vito Sartori
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

data/README.md

@@ -0,0 +1,92 @@
+# PatchYAML
+
+PatchYAML is an utility library for patching YAML while optimistically keeping
+the original document formatting.
+
+## Installation
+
+Install the gem and add to the application's Gemfile by executing:
+
+```bash
+bundle add patchyaml
+```
+
+If bundler is not being used to manage dependencies, install the gem by executing:
+
+```bash
+gem install patchyaml
+```
+
+## Usage
+
+The exposed interface is intentionally minimal. The library provide the methods
+`delete`, `update`, `map_rename`, `map_add`, and `seq_add`, obtaining the
+resulting changes through the `yaml` method. For instance:
+
+```ruby
+require 'patchyaml'
+
+editor = PatchYAML.load(<<~YAML)
+    mapping:
+      a:
+        sequence:
+          - name: a
+          - name: b
+          - name: c
+          - name: d
+            otherValue: hello
+      b: foo
+      c: true
+      d: [1, 2, 3, 4, foo, bar, hello]
+    d: 1
+    empty:
+    e: { a: 1, b: 2, c: 3 }
+    f: [1, 2, 3, 4, hello]
+    g: {}
+    h: []
+YAML
+
+editor
+  .delete("mapping.a.sequence.1")
+  .update("mapping.a.sequence.3.otherValue", "henlo")
+  .map_rename("mapping.b", to: "test")
+  .map_add("mapping.a", "e", "some value")
+  .seq_add("f", 123)
+
+puts editor.yaml
+# mapping:
+#   a:
+#     sequence:
+#       - name: b
+#       - name: c
+#       - name: d
+#         otherValue: henlo
+#   b: test
+#   c: true
+#   d: [1, 2, 3, 4, foo, bar, hello]
+#   e: some value
+# d: 1
+# empty:
+# e: { a: 1, b: 2, c: 3 }
+# f: [1, 2, 3, 4, hello, 123]
+# g: {}
+# h: []
+```
+
+## Development
+
+After checking out the repo, run `bin/setup` to install dependencies. Then, run `rake spec` to run the tests. You can also run `bin/console` for an interactive prompt that will allow you to experiment.
+
+To install this gem onto your local machine, run `bundle exec rake install`. To release a new version, update the version number in `version.rb`, and then run `bundle exec rake release`, which will create a git tag for the version, push git commits and the created tag, and push the `.gem` file to [rubygems.org](https://rubygems.org).
+
+## Contributing
+
+Bug reports and pull requests are welcome on GitHub at https://github.com/heyvito/patchyaml. This project is intended to be a safe, welcoming space for collaboration, and contributors are expected to adhere to the [code of conduct](https://github.com/heyvito/patchyaml/blob/master/CODE_OF_CONDUCT.md).
+
+## License
+
+The gem is available as open source under the terms of the [MIT License](https://opensource.org/licenses/MIT).
+
+## Code of Conduct
+
+Everyone interacting in the Patchyaml project's codebases, issue trackers, chat rooms and mailing lists is expected to follow the [code of conduct](https://github.com/heyvito/patchyaml/blob/master/CODE_OF_CONDUCT.md).

data/Rakefile

@@ -0,0 +1,12 @@
+# frozen_string_literal: true
+
+require "bundler/gem_tasks"
+require "rspec/core/rake_task"
+
+RSpec::Core::RakeTask.new(:spec)
+
+require "rubocop/rake_task"
+
+RuboCop::RakeTask.new
+
+task default: %i[spec rubocop]

data/lib/patchyaml/anchors.rb

@@ -0,0 +1,28 @@
+# frozen_string_literal: true
+
+module PatchYAML
+  class Editor
+    def process_anchor(from)
+      @anchors[from.anchor] = from if !from.is_a?(Psych::Nodes::Alias) && from.respond_to?(:anchor) && !from.anchor.nil?
+
+      case from
+      when Psych::Nodes::Stream, Psych::Nodes::Document
+        process_anchor(from.children.first)
+      when Psych::Nodes::Mapping
+        process_anchor_map(from)
+      when Psych::Nodes::Sequence
+        from.children.each { process_anchor(it) }
+      when Psych::Nodes::Scalar, Psych::Nodes::Alias
+        # noop
+      else
+        raise "patchyaml: Unexpected node #{from.class} in #process_anchor"
+      end
+    end
+
+    def process_anchor_map(from)
+      from.children.each.with_index do |item, idx|
+        process_anchor(item) if idx.odd?
+      end
+    end
+  end
+end

data/lib/patchyaml/editor.rb

@@ -0,0 +1,77 @@
+# frozen_string_literal: true
+
+module PatchYAML
+  class Editor
+    def initialize(data)
+      @anchors = {}
+      @pipeline = []
+
+      reload(data)
+    end
+
+    # Deletes a given path from the yaml
+    #
+    # path - The path to the key to be deleted
+    #
+    # Returns the same Editor instance
+    def delete(path) = tap { @pipeline << [:delete, path] }
+
+    # Updates an existing path in the yaml to have the provided value
+    #
+    # path - The path to the key to be updated
+    # value - The value to be set in the key
+    #
+    # Returns the same Editor instance
+    def update(path, value) = tap { @pipeline << [:update, path, value] }
+
+    # Renames a given path
+    #
+    # path - The path to the key to be renamed
+    # to:  - The new name of the key
+    #
+    # Returns the same Editor instance
+    def map_rename(path, to:)
+      tap { @pipeline << [:rename, path, to] }
+    end
+
+    # Adds a new key to the yaml
+    #
+    # path  - The path to the mapping that will receive the new key
+    # key   - The new key name
+    # value - The new key value
+    #
+    # Returns the same Editor instance
+    def map_add(path, key, value)
+      tap { @pipeline << [:map_add, path, key, value] }
+    end
+
+    # Adds a new value to a sequence
+    #
+    # path   - The path to the sequence that will receive the new item
+    # value  - The value to be added to the sequence
+    # index: - The index to insert the value into. Defaults to nil, and
+    #          appends to the end of the sequence.
+    #
+    # Returns the same Editor instance
+    def seq_add(path, value, index: nil)
+      tap { @pipeline << [:seq_add, path, value, index] }
+    end
+
+    # Returns the processed YAML after edits have been applied.
+    def yaml = run_pipeline
+
+    private
+
+    def reload(data)
+      @data = data
+      @line_sizes = [0] + data.split("\n").map { it.length + 1 }
+      begin
+        @stream = Psych.parse_stream(data)
+      rescue Psych::SyntaxError
+        puts "Parsing failed. Input was:\n#{@data}"
+        raise
+      end
+      process_anchor(@stream)
+    end
+  end
+end

data/lib/patchyaml/find.rb

@@ -0,0 +1,75 @@
+# frozen_string_literal: true
+
+module PatchYAML
+  class Editor
+    def find(from, path)
+      path = QueryParser.parse(path)
+      # Pass through Psych::Nodes::Stream -> Psych::Nodes::Document
+      node = [from, nil]
+      path.each do |part|
+        node = find_node(node, part)
+        return [] if node.empty?
+      end
+      node
+    end
+
+    def find_node(from, part)
+      case part[:kind]
+      when :simple
+        case from.first
+        when Psych::Nodes::Stream, Psych::Nodes::Document
+          find_node([from.first.children.first, from], part)
+        when Psych::Nodes::Mapping
+          find_mapping_key(from.first, part[:value])
+        when Psych::Nodes::Sequence
+          [from.first.children.find { it.respond_to?(:value) && it.value == part[:value] }, from.first]
+        when Psych::Nodes::Alias
+          node = @anchors[from.first.anchor]
+          raise "patchyaml: Unknown anchor #{from.anchor} defined by #{from.first}" unless node
+
+          [find_node(node, part), node]
+        else
+          raise "patchyaml: Unexpected node #{from.first.class} in #find_node"
+        end
+      when :index
+        case from.first
+        when Psych::Nodes::Stream, Psych::Nodes::Document
+          [find_node(from.first.children.first, part[:value]), from.first]
+        when Psych::Nodes::Sequence
+          [from.first.children[part[:value]], from.first]
+        end
+      when :expression
+        case from.first
+        when Psych::Nodes::Stream, Psych::Nodes::Document
+          [find_node(from.first.children.first, part), from.first]
+        when Psych::Nodes::Sequence
+          v = from
+            .first
+            .children
+            .find { it.is_a?(Psych::Nodes::Mapping) && find_mapping_key(it, part[:key]).value == part[:value] }
+          [v, from]
+        end
+      end
+    end
+
+    def find_mapping_key(from, named)
+      # A mapping is basically an even-numbered array containing keys followed by their values.
+      # Keys are expressed as an scalar value.
+      i = 0
+      until i >= from.children.size - 1
+        if from.children[i].value == named
+          result = from.children[i + 1]
+          return [result, from] unless result.is_a?(Psych::Nodes::Alias)
+
+          item = @anchors[result.anchor]
+          raise "patchyaml: Unknown anchor #{result.anchor} defined by #{result}" unless item
+
+          return [item, from]
+        end
+
+        i += 2
+      end
+      [nil, from]
+    end
+  end
+end

data/lib/patchyaml/pipeline.rb

@@ -0,0 +1,304 @@
+# frozen_string_literal: true
+
+module PatchYAML
+  class Editor
+    def run_pipeline
+      run_pipeline_once until @pipeline.empty?
+      @data
+    end
+
+    private
+
+    def run_pipeline_once
+      op, *opts = @pipeline.shift
+      case op
+      when :delete
+        node_delete(opts[0])
+      when :rename
+        node_rename(opts[0], opts[1])
+      when :map_add
+        node_map_add(opts[0], opts[1], opts[2])
+      when :update
+        node_update(opts[0], opts[1])
+      when :seq_add
+        node_seq_add(opts[0], opts[1], opts[2])
+      else
+        raise Error, "patchyaml: Unknown pipeline operation #{op}"
+      end
+      reload(@data)
+    end
+
+    def start_offset(node)
+      @line_sizes[..node.start_line].sum + (node.start_column.positive? ? node.start_column : 0)
+    end
+
+    def end_offset(node)
+      @line_sizes[..node.end_line].sum + (node.end_column.positive? ? node.end_column : 0)
+    end
+
+    def node_delete(path)
+      value, parent = find(@stream, path)
+      case parent
+      when Psych::Nodes::Sequence
+        start_at = start_offset(value)
+        end_at = end_offset(value)
+        if parent.style == Psych::Nodes::Sequence::FLOW
+          # For flow-based sequences, like [1, 2, 3, 4], ensure we remove
+          # any leading spaces and trailing commas, as they are not part
+          # of the value itself. However, if the character before the space is
+          # a "[", keep the space.
+          start_at -= 1 if start_at >= 2 && @data[start_at - 1] == " " && @data[start_at - 2] != "["
+          end_at += 1 if @data[end_at] == ","
+        else
+          # For block-based sequences, we can remove the whole line
+          start_at = @line_sizes[..value.start_line].sum
+          end_at = @line_sizes[..value.end_line].sum
+        end
+        @data = @data[...start_at].concat(@data[end_at...])
+      when Psych::Nodes::Mapping
+        value_index = parent.children.index(value)
+        key_index = value_index - 1
+        key = parent.children[key_index]
+        value = parent.children[value_index]
+        start_at = start_offset(key)
+        end_at = end_offset(value)
+
+        if parent.style == Psych::Nodes::Mapping::FLOW
+          # For flow-based maps, like { a: 1, b: 2 }, ensure we remove
+          # any leading spaces and trailing commas, as they are not part
+          # of the k/v
+          start_at -= 1 if !start_at.zero? && @data[start_at - 1] == " "
+          end_at += 1 if @data[end_at] == ","
+        else
+          start_at = @line_sizes[..key.start_line].sum
+          end_at = if value.end_line == key.start_line
+            @line_sizes[..(value.end_line + 1)]
+          else
+            @line_sizes[..value.end_line]
+          end.sum
+        end
+
+        @data = @data[...start_at].concat(@data[end_at...])
+      else
+        raise Error, "patchyaml: BUG: cannot delete object from #{parent.class}"
+      end
+    end
+
+    def dump_yaml(value, indent: 0)
+      dump = Psych.dump(value, stringify_names: true).gsub(/---\s?\n?\s*/, "")
+      return dump if indent.zero?
+
+      arr = dump.split("\n")
+      ([arr[0]] + arr[1..].map { "#{" " * indent}#{it}" }).join("\n")
+    end
+
+    def node_update(path, new_value)
+      value, parent = find(@stream, path)
+      case parent
+      when Psych::Nodes::Mapping
+        update_mapping(value, parent, new_value)
+      when Psych::Nodes::Sequence
+        update_sequence(value, parent, new_value)
+      else
+        raise TypeError, "Cannot update value of type #{parent.class}, expected Mapping or Sequence"
+      end
+    end
+
+    # TODO: update_* does not take into consideration adding a complex, multiline
+    # value into an inline parent. This will certainly break things.
+    def update_mapping(value, parent, new_value)
+      key_index = parent.children.index(value) - 1
+      key = parent.children[key_index]
+      start_at = start_offset(value)
+      end_at = end_offset(value)
+      yaml_value = dump_yaml(new_value, indent: key.start_column + 2)
+      indent = if new_value.is_a?(Hash) || (new_value.is_a?(Array) && parent.style != Psych::Nodes::Mapping::FLOW)
+        start_at -= 1 while @data[start_at - 1] == " "
+        "\n#{" " * (key.start_column + 2)}"
+      else
+        ""
+      end
+      @data = @data[...start_at]
+        .concat(indent)
+        .concat(yaml_value)
+        .concat(@data[end_at...])
+    end
+
+    def update_sequence(value, parent, new_value)
+      start_at = start_offset(value)
+      end_at = end_offset(value)
+      end_at -= 1 if @data[end_at - 1] == "\n"
+
+      if parent.style == Psych::Nodes::Sequence::FLOW
+        if new_value.is_a?(Array) || new_value.is_a?(Hash)
+          raise Error, "Cannot update node as its parent is in flow-style."
+        end
+
+        yaml_value = dump_yaml(new_value)
+        yaml_value = yaml_value.strip
+      else
+        yaml_value = dump_yaml(new_value)
+        yaml_value = "#{yaml_value}\n" unless yaml_value.end_with?("\n")
+        yaml_value = "#{yaml_value}#{" " * value.end_column}"
+      end
+      @data = @data[...start_at]
+        .concat(yaml_value)
+        .concat(@data[end_at...])
+    end
+
+    def node_rename(path, new_name)
+      value, parent = find(@stream, path)
+      raise TypeError, "Cannot rename sequence" if parent.is_a? Psych::Nodes::Sequence
+
+      key_index = parent.children.index(value) - 1
+      key = parent.children[key_index]
+      start_at = start_offset(key)
+      end_at = end_offset(key)
+      @data = @data[...start_at].concat(new_name).concat(@data[end_at...])
+    end
+
+    def reindent(value, level:)
+      value
+        .split("\n")
+        .map { "#{" " * level}#{it}" }
+        .join("\n")
+    end
+
+    def node_map_add(path, key, value)
+      node, = find(@stream, path)
+      unless node.is_a?(Psych::Nodes::Mapping)
+        raise TypeError, "Cannot add key to non-mapping node of type #{node.class}"
+      end
+
+      encoded_value = dump_yaml(value)
+
+      # Adding an inline (flow) and block map differs a little. We are currently
+      # avoiding adding complex values to inline items, but adding simple
+      # values. For an empty node, we can add in our own style (space after
+      # and before curlies), otherwise, just add a comma, a space, the
+      # key/value, and a trailing space (if the node has a leading space after
+      # the curly)
+      @data = if node.style == Psych::Nodes::Mapping::FLOW
+        node_map_add_inline(node, key, value, encoded_value)
+      else
+        node_map_add_block(node, key, value, encoded_value)
+      end
+    end
+
+    def node_map_add_block(node, key, value, encoded_value)
+      indent_level, start_at = if node.children.length.positive?
+        [node.children.first.start_column, end_offset(node.children.last)]
+      else
+        [parent.first.start_column, end_offset(parent)]
+      end
+
+      if value.is_a?(Array) || value.is_a?(Hash)
+        encoded_value = reindent(encoded_value, level: indent_level + 2)
+        return @data[..start_at]
+            .concat("#{" " * indent_level}#{key}:\n#{encoded_value}")
+            .concat(@data[start_at...])
+      end
+
+      @data[..start_at]
+        .concat("#{" " * indent_level}#{key}: #{encoded_value.strip}")
+        .concat(@data[start_at...])
+    end
+
+    def node_map_add_inline(node, key, value, encoded_value)
+      raise Error, "Cannot add complex values to inline mapping" if value.is_a?(Hash) || value.is_a?(Array)
+
+      if node.children.length.positive?
+        end_off = end_offset(node.children.last)
+        start_at = start_offset(node.children.last)
+        start_at -= 1 if @data[start_at] == " "
+        return @data[..start_at]
+            .concat(", #{key}: #{encoded_value.strip}")
+            .concat(@data[end_off...])
+      end
+
+      end_off = end_offset(node)
+      start_at = start_offset(node)
+      start_at -= 1 if @data[start_at] == " "
+      @data[..start_at]
+        .concat(" #{key}: #{encoded_value.strip} ")
+        .concat(@data[(end_off - 1)...])
+    end
+
+    def node_seq_add(path, value, index)
+      node, = find(@stream, path)
+      unless node.is_a?(Psych::Nodes::Sequence)
+        raise TypeError, "Cannot add item to non-sequence node of type #{node.class}"
+      end
+
+      encoded_value = dump_yaml(value)
+
+      # Adding an inline (flow) and block map differs a little. We are currently
+      # avoiding adding complex values to inline items, but adding simple
+      # values. For an empty node, we can add in our own style (space after
+      # and before curlies), otherwise, just add a comma, a space, the
+      # key/value, and a trailing space (if the node has a leading space after
+      # the curly)
+      @data = if node.style == Psych::Nodes::Sequence::FLOW
+        node_seq_add_inline(node, value, encoded_value, index)
+      else
+        node_seq_add_block(node, value, encoded_value, index)
+      end
+    end
+
+    def node_seq_add_inline(node, value, encoded_value, index)
+      raise Error, "Cannot add complex values to inline mapping" if value.is_a?(Hash) || value.is_a?(Array)
+
+      if node.children.length.positive?
+        start_at, prefix, suffix = if index.nil?
+          [end_offset(node.children.last), ", ", ""]
+        else
+          item = node.children[index] || node.children.last
+          p, s = item == node.children.last ? [", ", ""] : ["", ", "]
+          [start_offset(item), p, s]
+        end
+        start_at -= 1 if @data[start_at] == " "
+        return @data[...start_at]
+            .concat(prefix)
+            .concat(encoded_value.strip)
+            .concat(suffix)
+            .concat(@data[start_at...])
+      end
+
+      end_off = end_offset(node)
+      start_at = start_offset(node)
+      start_at -= 1 if @data[start_at] == " "
+      @data[..start_at]
+        .concat(" #{encoded_value.strip} ")
+        .concat(@data[(end_off - 1)...])
+    end
+
+    def node_seq_add_block(node, value, encoded_value, index)
+      indent_level, start_at = if node.children.length.positive?
+        start = node.children.first.start_column
+        start_off = start_offset(node.children.first)
+        until @data[start_off] == "-"
+          start_off -= 1
+          start -= 1
+        end
+        ref = index.nil? ? end_offset(node.children.last) : start_offset(node.children[index])
+        [start, ref]
+      else
+        [parent.first.start_column, end_offset(parent)]
+      end
+      start_at -= 1 until @data[start_at - 1] == "\n" || @data[start_at].nil?
+
+      if value.is_a?(Array) || value.is_a?(Hash)
+        encoded_value = encoded_value.split("\n")
+        encoded_value = [encoded_value.first] + encoded_value[1...].map { (" " * (indent_level + 2)).concat(it) }
+        encoded_value = encoded_value.join("\n")
+        return @data[...start_at]
+            .concat("#{" " * indent_level}- #{encoded_value}\n")
+            .concat(@data[start_at...])
+      end
+
+      @data[...start_at]
+        .concat("#{" " * indent_level}- #{encoded_value.strip}")
+        .concat(@data[start_at...])
+    end
+  end
+end

data/lib/patchyaml/query_parser.rb

@@ -0,0 +1,147 @@
+# frozen_string_literal: true
+
+module PatchYAML
+  class QueryParser
+    def self.parse(query) = new(query).parse
+
+    def initialize(query)
+      @path = []
+      @pos = 0
+      @start = 0
+      @query = query.each_char.to_a
+      @current_path = nil
+    end
+
+    def peek = @query[@pos]
+    def advance = @query[@pos].tap { @pos += 1 }
+    def eof? = @pos >= @query.length
+    def matches?(char) = peek == char
+    def mark = @start = @pos
+    def value = @query[@start...@pos].join
+
+    def digit?(value = nil)
+      value = peek if value.nil?
+      !value.nil? && value >= "0" && value <= "9"
+    end
+
+    def non_separator?
+      peek != "[" && peek != "."
+    end
+
+    def push_path
+      if @current_path
+        @path << @current_path
+        @current_path = nil
+      end
+
+      advance if peek == "."
+      mark
+    end
+
+    def parse
+      until eof?
+        next parse_index if digit?
+
+        case peek
+        when "["
+          parse_expression_path
+        when "."
+          push_path
+        else
+          parse_simple_path
+        end
+      end
+
+      @path
+    end
+
+    def parse_index
+      mark
+      advance while digit?
+      @current_path = { kind: :index, value: value.to_i }
+      push_path
+    end
+
+    def parse_expression_path
+      raise ArgumentError, "Expected '[', found #{peek} at index #{@pos}" unless peek == "["
+
+      advance # Consume [
+      mark
+      advance until peek == "]" || eof?
+
+      raise ArgumentError, "Unterminated expression path at index #{@pos}" unless peek == "]"
+
+      v = value
+      advance # Consume ]
+
+      unless v.include? "="
+        raise ArgumentError, "Invalid expression path at index #{@start}: Expected expression to be in the format " \
+                             "key=value"
+      end
+
+      key, value = v.split("=", 2).map(&:strip)
+
+      value = case
+      when digit?(value[0])
+        value.to_i
+      when ['"', "'"].include?(value[0])
+        parse_quoted(value)
+      when "true"
+        true
+      when "false"
+        false
+      else
+        value
+      end
+
+      @current_path = { kind: :expression, key:, value: }
+      push_path
+    end
+
+    def parse_simple_path
+      mark
+      advance until !non_separator? || eof?
+      @current_path = { kind: :simple, value: value }
+      push_path
+    end
+
+    def parse_quoted(value)
+      quote = value[0]
+      escaping = false
+      v = []
+      chars = value[1...].each_char.to_a
+
+      until chars.empty?
+        ch = chars.shift
+
+        if ch == "\\"
+          escaping = true
+          next
+        end
+
+        if escaping
+          escaping = false
+
+          case ch
+          when quote
+            v << quote
+          else
+            v << "\\"
+            v << ch
+          end
+          next
+        end
+
+        break if ch == quote
+
+        v << ch
+      end
+
+      unless chars.empty?
+        raise ArgumentError, "Invalid expression #{value}: Stray #{chars.shift} after closing #{quote}"
+      end
+
+      v.join
+    end
+  end
+end

data/lib/patchyaml/version.rb

@@ -0,0 +1,5 @@
+# frozen_string_literal: true
+
+module Patchyaml
+  VERSION = "0.1.0"
+end

data/lib/patchyaml.rb

@@ -0,0 +1,22 @@
+# frozen_string_literal: true
+
+require "yaml"
+
+require_relative "patchyaml/version"
+require_relative "patchyaml/editor"
+require_relative "patchyaml/anchors"
+require_relative "patchyaml/find"
+require_relative "patchyaml/query_parser"
+require_relative "patchyaml/pipeline"
+
+module PatchYAML
+  class Error < StandardError; end
+
+  def self.load(data)
+    Editor.new(data)
+  end
+
+  def self.load_file(path)
+    Editor.new(File.read(path))
+  end
+end

metadata

@@ -0,0 +1,57 @@
+--- !ruby/object:Gem::Specification
+name: patchyaml
+version: !ruby/object:Gem::Version
+  version: 0.1.0
+platform: ruby
+authors:
+- Vito Sartori
+bindir: exe
+cert_chain: []
+date: 2025-08-05 00:00:00.000000000 Z
+dependencies: []
+description: YAML Editor Utility Library
+email:
+- hey@vito.io
+executables: []
+extensions: []
+extra_rdoc_files: []
+files:
+- ".rspec"
+- ".rubocop.yml"
+- CODE_OF_CONDUCT.md
+- LICENSE.txt
+- README.md
+- Rakefile
+- lib/patchyaml.rb
+- lib/patchyaml/anchors.rb
+- lib/patchyaml/editor.rb
+- lib/patchyaml/find.rb
+- lib/patchyaml/pipeline.rb
+- lib/patchyaml/query_parser.rb
+- lib/patchyaml/version.rb
+homepage: https://github.com/heyvito/patchyaml
+licenses:
+- MIT
+metadata:
+  allowed_push_host: https://rubygems.org
+  homepage_uri: https://github.com/heyvito/patchyaml
+  source_code_uri: https://github.com/heyvito/patchyaml
+  rubygems_mfa_required: 'true'
+rdoc_options: []
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '3.4'
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.6.2
+specification_version: 4
+summary: YAML Editor Utility Library
+test_files: []