hrx 1.0.0

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 113be96953fad121bc702b9218c683c567fab09f
+  data.tar.gz: 57dd4863e7b7e74e59d652cccc033f7dec8b7356
+SHA512:
+  metadata.gz: 503935bd42061aca65943fca313eeefe893ff8f744753ca547200bde88d73760d2c7a24c49bc67c534b9b30a89868f0dd167d740b9bf7e9fa05e0603f94147b9
+  data.tar.gz: 0ecbd595c273f93e457d6c89ce417f9f8bf6e66df068f8e6e9e6a25e1a56779dde994c4fd2958cb991d980cfde99c21b44345ec8704e851eb60e67a6483467fd

data/.gitignore

@@ -0,0 +1,31 @@
+*.gem
+*.rbc
+/.config
+/coverage/
+/InstalledFiles
+/pkg/
+/spec/reports/
+/spec/examples.txt
+/test/tmp/
+/test/version_tmp/
+/tmp/
+
+## Documentation cache and generated files:
+/.yardoc/
+/_yardoc/
+/doc/
+/rdoc/
+
+## Environment normalization:
+/.bundle/
+/vendor/bundle
+/lib/bundler/man/
+
+# for a library or gem, you might want to ignore these files since the code is
+# intended to run in multiple environments; otherwise, check them in:
+Gemfile.lock
+.ruby-version
+.ruby-gemset
+
+# unless supporting rvm < 1.11.0 or doing something fancy, ignore this:
+.rvmrc

data/.rdoc_options

@@ -0,0 +1,23 @@
+--- !ruby/object:RDoc::Options
+encoding: UTF-8
+static_path: []
+rdoc_include:
+- "."
+- "/home/nweiz/goog/hrx-ruby"
+charset: UTF-8
+exclude: 
+hyperlink_all: false
+line_numbers: false
+locale: 
+locale_dir: locale
+locale_name: 
+main_page: 
+markup: markdown
+output_decoration: true
+page_dir: 
+show_hash: false
+tab_width: 8
+template_stylesheets: []
+title: 
+visibility: :protected
+webcvs: 

data/.rspec

@@ -0,0 +1 @@
+--require spec_helper

data/CONTRIBUTING.md

@@ -0,0 +1,28 @@
+# How to Contribute
+
+We'd love to accept your patches and contributions to this project. There are
+just a few small guidelines you need to follow.
+
+## Contributor License Agreement
+
+Contributions to this project must be accompanied by a Contributor License
+Agreement. You (or your employer) retain the copyright to your contribution;
+this simply gives us permission to use and redistribute your contributions as
+part of the project. Head over to <https://cla.developers.google.com/> to see
+your current agreements on file or to sign a new one.
+
+You generally only need to submit a CLA once, so if you've already submitted one
+(even if it was for a different project), you probably don't need to do it
+again.
+
+## Code reviews
+
+All submissions, including submissions by project members, require review. We
+use GitHub pull requests for this purpose. Consult
+[GitHub Help](https://help.github.com/articles/about-pull-requests/) for more
+information on using pull requests.
+
+## Community Guidelines
+
+This project follows [Google's Open Source Community
+Guidelines](https://opensource.google.com/conduct/).

data/Gemfile

@@ -0,0 +1,6 @@
+source "https://rubygems.org"
+
+gemspec
+
+gem "rspec", "~> 3.0", group: :test
+gem "rspec-temp_dir", "~> 1.0", group: :test

data/LICENSE

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

data/README.md

@@ -0,0 +1,35 @@
+# HRX (Human Readable Archive)
+
+This gem is a parser and serializer for the [HRX format][].
+
+[HRX format]: https://github.com/google/hrx
+
+```ruby
+# Load an archive from a path on disk. You can also parse it directly from a
+# string using HRX::Archive.parse, or create an empty archive using
+# HRX::Archive.new.
+archive = HRX::Archive.load("path/to/archive.hrx")
+
+# You can read files directly from an archive as though it were a filesystem.
+puts archive.read("dir/file.txt")
+
+# You can also write to files. Writing to a file implicitly creates any
+# directories above it. You can also overwrite an existing file.
+archive.write("dir/new.txt", "New file contents!\n")
+
+# You can access HRX::File or HRX::Directory objects directly using
+# HRX::Archive#[]. Unlike HRX::Archive#read(), this will just return nil if the
+# entry isn't found.
+archive["dir/file.txt"] # => HRX::File
+
+# You can add files to the end of the archive using HRX::Archive#<< or
+# HRX::Archive#add. If you pass `before:` or `after:`, you can control where in
+# the archive they're added.
+archive << HRX::File.new("dir/newer.txt", "Newer file contents!\n")
+
+# Write the file back to disk. You can also use HRX::Archive#to_hrx to serialize
+# the archive to a string.
+archive.write!("path/to/archive.hrx")
+```
+
+This is not an officially supported Google product.

data/hrx.gemspec

@@ -0,0 +1,30 @@
+# Copyright 2018 Google Inc
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+Gem::Specification.new do |s|
+  s.name = "hrx"
+  s.version = "1.0.0"
+  s.license = "Apache-2.0"
+
+  s.homepage = "https://github.com/google/hrx-ruby"
+  s.summary = "An HRX parser and serializer"
+  s.description = "A parser and serializer for the HRX human-readable archive format."
+  s.authors = ["Natalie Weizenbaum"]
+  s.email = "nweiz@google.com"
+
+  s.files = `git ls-files -z`.split("\x0")
+
+  s.add_runtime_dependency "linked-list", "~> 0.0.13"
+  s.required_ruby_version = ">= 2.3.0"
+end

data/lib/hrx.rb

@@ -0,0 +1,22 @@
+# Copyright 2018 Google Inc
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+# The parent module for all HRX classes. See the README for more information and
+# usage examples.
+#
+# Parse an archive from a string with HRX::Archive.parse, load it from disk with
+# HRX::Archive.load, or create an empty archive with HRX::Archive.new.
+module HRX; end
+
+require_relative 'hrx/archive'

data/lib/hrx/archive.rb

@@ -0,0 +1,461 @@
+# Copyright 2018 Google Inc
+#
+#    Licensed under the Apache License, Version 2.0 (the "License");
+#    you may not use this file except in compliance with the License.
+#    You may obtain a copy of the License at
+#
+#        http://www.apache.org/licenses/LICENSE-2.0
+#
+#    Unless required by applicable law or agreed to in writing, software
+#    distributed under the License is distributed on an "AS IS" BASIS,
+#    WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#    See the License for the specific language governing permissions and
+#    limitations under the License.
+
+require 'linked-list'
+require 'set'
+require 'strscan'
+
+require_relative 'directory'
+require_relative 'error'
+require_relative 'file'
+require_relative 'ordered_node'
+require_relative 'parse_error'
+
+# An HRX archive.
+#
+# Parse an archive from a string with ::parse, load it from disk with ::load, or
+# create an empty archive with ::new.
+class HRX::Archive
+  class << self
+    # Parses an HRX file's text.
+    #
+    # If `file` is passed, it's used as the file name for error reporting.
+    #
+    # Throws an HRX::ParseError if `text` isn't valid HRX. Throws an
+    # EncodingError if `text` can't be converted to UTF-8.
+    def parse(text, file: nil)
+      text = text.encode("UTF-8")
+      return new if text.empty?
+
+      scanner = StringScanner.new(text)
+      unless boundary = scanner.scan(/<=+>/)
+        HRX::Util.parse_error(scanner, "Expected boundary", file: file)
+      end
+      boundary_length = boundary.length - 2
+      hrx = HRX::Archive.new(boundary_length: boundary_length)
+      boundary_regexp = /^<={#{boundary_length}}>/m
+
+      loop do
+        if scanner.scan(/\n/)
+          if comment_plus_boundary = scanner.scan_until(boundary_regexp)
+            comment = comment_plus_boundary[0...-boundary_length - 3]
+          else
+            hrx.last_comment = scanner.rest
+            return hrx
+          end
+        end
+
+        unless scanner.scan(/ /)
+          HRX::Util.parse_error(scanner, "Expected space", file: file)
+        end
+
+        before_path = scanner.pos
+        path = HRX::Util.scan_path(scanner, assert_done: false, file: file)
+        unless scanner.scan(/\n/)
+          HRX::Util.parse_error(scanner, "Expected newline", file: file)
+        end
+
+        begin
+          if path.end_with?("/")
+            hrx << HRX::Directory._new_without_checks(path, comment)
+            return hrx if scanner.eos?
+            next if scanner.scan(boundary_regexp)
+            HRX::Util.parse_error(scanner, "Expected boundary", file: file)
+          end
+
+          if content_plus_boundary = scanner.scan_until(boundary_regexp)
+            content = content_plus_boundary[0...-boundary_length - 3]
+            hrx << HRX::File._new_without_checks(path, content, comment)
+          else
+            hrx << HRX::File._new_without_checks(path, scanner.rest, comment)
+            return hrx
+          end
+        rescue HRX::ParseError => e
+          raise e
+        rescue HRX::Error => e
+          scanner.pos = before_path
+          HRX::Util.parse_error(scanner, e.message, file: file)
+        end
+      end
+    end
+
+    # Loads an HRX::Archive from the given `file`.
+    #
+    # Throws an HRX::ParseError if the file isn't valid HRX. Throws an
+    # EncodingError if the file isn't valid UTF-8.
+    def load(file)
+      text = File.read(file, mode: "rb", encoding: "UTF-8")
+
+      # If the encoding is invalid, force an InvalidByteSequenceError.
+      text.encode("UTF-16") unless text.valid_encoding?
+
+      parse(text, file: file)
+    end
+
+    # Creates an archive as a child of an existing archive.
+    #
+    # The `root` is the path to the root of this archive, relative to its
+    # outermost ancestor. The `entries` is the outermost ancestor's entries
+    # list. The `entries_by_path` is the subtree of the outermost ancestor's
+    # entries tree that corresponds to this child.
+    def _new_child(root, boundary_length, entries, entries_by_path) # :nodoc:
+      allocate.tap do |archive|
+        archive._initialize_child(root, boundary_length, entries, entries_by_path)
+      end
+    end
+  end
+
+  # The last comment in the document, or `nil` if it has no final comment.
+  #
+  # HRX comments are always encoded as UTF-8.
+  attr_reader :last_comment
+
+  # Creates a new, empty archive.
+  #
+  # The `boundary_length` is the number of `=` signs to include in the boundary
+  # when #to_hrx is called, unless a file already contains that boundary.
+  def initialize(boundary_length: 3)
+    if boundary_length && boundary_length < 1
+      raise ArgumentError.new("boundary_length must be 1 or greater")
+    end
+
+    @root = nil
+    @boundary_length = boundary_length
+    @entries = LinkedList::List.new
+    @entries_by_path = {}
+  end
+
+  # See _new_child.
+  def _initialize_child(root, boundary_length, entries, entries_by_path) # :nodoc:
+    @root = root.end_with?("/") ? root : root + "/"
+    @boundary_length = boundary_length
+    @entries = entries
+    @entries_by_path = entries_by_path
+  end
+
+  # A frozen array of the HRX::File and/or HRX::Directory objects that this
+  # archive contains.
+  #
+  # Note that a new array is created every time this method is called, so try to
+  # avoid calling this many times in a tight loop.
+  def entries
+    return @entries.to_a.freeze unless @root
+    @entries.
+      each.
+      select {|e| e.path.start_with?(@root) && e.path != @root}.
+      map {|e| e._relative(@root)}.
+      freeze
+  end
+
+  # Returns the HRX::File or HRX::Directory at the given `path` in this archive,
+  # or `nil` if there's no entry at that path.
+  #
+  # This doesn't verify that `path` is well-formed, but instead just returns
+  # `nil`.
+  #
+  # If `path` ends with `"/"`, returns `nil` if the entry at the given path is a
+  # file rather than a directory.
+  def [](path)
+    _find_node(path)&.data&._relative(@root)
+  end
+
+  # Returns all HRX::File or HRX::Directory objects in this archive that match
+  # `pattern`. See also Dir::glob. This always uses the option File::FNM_PATHNAME.
+  #
+  # This only returns HRX::Directory objects if `pattern` ends in `/` or
+  # includes `**`.
+  def glob(pattern, flags = 0)
+    entries.select {|e| File.fnmatch?(pattern, e.path, flags | File::FNM_PATHNAME)}
+  end
+
+  # Returns the contents of the file at `path` in the archive as a frozen
+  # string.
+  #
+  # Throws an HRX::Error if there is no file at `path`, or if `path` is invalid
+  # (including if it ends with `/`).
+  def read(path)
+    raise HRX::Error.new("There is no file at \"#{path}\"") unless node = _find_node(path)
+    unless node.data.is_a?(HRX::File)
+      raise HRX::Error.new("\"#{node.data._relative(@root).path}\" is a directory")
+    end
+    node.data.content
+  end
+
+  # Returns an HRX::Archive that provides access to the entries in `path` as
+  # though they were at the root of the archive.
+  #
+  # Any modifications to the child archive will be reflected in the parent as
+  # well. The HRX::File and HRX::Directory objects returned by the child archive
+  # will have their paths adjusted to be relative to the child's root.
+  def child_archive(path)
+    components = path.split("/")
+    raise HRX::Error.new('There is no directory at ""') if components.empty?
+    child_entries_by_path = @entries_by_path.dig(*components)
+    raise HRX::Error.new("There is no directory at \"#{path}\"") unless child_entries_by_path
+    if child_entries_by_path.is_a?(LinkedList::Node)
+      raise HRX::Error.new("\"#{child_entries_by_path.data._relative(@root).path}\" is a file")
+    end
+
+    HRX::Archive._new_child(_absolute(path), @boundary_length, @entries, child_entries_by_path)
+  end
+
+  # Writes `content` to the file at `path`.
+  #
+  # If there's already a file at `path`, overwrites it. Otherwise, creates a new
+  # file after the nearest file in the archive.
+  #
+  # If `comment` is passed, it's used as the comment for the new file. The
+  # special value `:copy` copies the existing comment for the file, if there is
+  # one.
+  #
+  # Throws an HRX::ParseError if `path` is invalid.
+  #
+  # Throws an HRX::Error if there's a directory at `path`.
+  def write(path, content, comment: nil)
+    components = path.split("/")
+    nearest_dir = nil
+    parent = components[0...-1].inject(@entries_by_path) do |hash, component|
+      entry = hash[component]
+      if entry.is_a?(LinkedList::Node)
+        raise HRX::Error.new("\"#{entry.data._relative(@root).path}\" is a file")
+      end
+
+      # Even though both branches of this if are assignments, their return
+      # values are used by #inject.
+      if entry
+        nearest_dir = entry
+      else
+        hash[component] = {}
+      end
+    end
+    nearest_dir = parent unless parent.empty?
+
+    previous = parent[components.last]
+    if previous.is_a?(Hash)
+      raise HRX::Error.new("\"#{path}/\" is a directory")
+    end
+
+    if previous.is_a?(LinkedList::Node)
+      comment = previous.data.comment if comment == :copy
+      previous.data = HRX::File.new(_absolute(path), content, comment: comment)
+      return
+    end
+
+    comment = nil if comment == :copy
+    node = HRX::OrderedNode.new(HRX::File.new(_absolute(path), content, comment: comment))
+    if nearest_dir.nil?
+      @entries << node
+    else
+      # Add the new file after its closest pre-existing cousin. Start looking
+      # for siblings in `nearest_dir`, and then work down through its children.
+      if last_cousin = _each_entry(nearest_dir).max_by {|n| n.order}
+        @entries.insert_after_node(node, last_cousin)
+      else
+        @entries << node
+      end
+    end
+
+    parent[components.last] = node
+    nil
+  end
+
+  # Deletes the file or directory at `path`.
+  #
+  # Throws an HRX::Error if there's no entry at `path`.
+  def delete(path, recursive: false)
+    # The outermost parent directory hash that contains only the entry at
+    # `path`, from which key_to_delete should be deleted
+    parent_to_delete_from = nil
+    key_to_delete = nil
+
+    components = path.split("/")
+    parent = components[0...-1].inject(@entries_by_path) do |hash, component|
+      entry = hash[component]
+      if entry.is_a?(LinkedList::Node)
+        raise HRX::Error.new("\"#{entry.data._relative(@root).path}\" is a file")
+      end
+
+      if entry.nil?
+        raise HRX::Error.new("\"#{path}\" doesn't exist")
+      elsif entry.size == 1
+        parent_to_delete_from ||= hash
+        key_to_delete ||= component
+      else
+        parent_to_delete_from = nil
+        key_to_delete = nil
+      end
+
+      hash[component] ||= {}
+    end
+    parent_to_delete_from ||= parent
+    key_to_delete ||= components.last
+
+    node = parent[components.last]
+    if node.nil?
+      raise HRX::Error.new("\"#{path}\" doesn't exist")
+    elsif node.is_a?(Hash)
+      if recursive
+        _each_entry(node) {|n| @entries.delete(n)}
+      else
+        unless node = node[:dir]
+          raise HRX::Error.new("\"#{path}\" is not an explicit directory and recursive isn't set")
+        end
+        @entries.delete(node)
+      end
+    elsif path.end_with?("/")
+      raise HRX::Error.new("\"#{path}\" is a file")
+    else
+      @entries.delete(node)
+    end
+
+    parent_to_delete_from.delete(key_to_delete)
+  end
+
+  # Sets the text of the last comment in the document.
+  #
+  # Throws an EncodingError if `comment` can't be converted to UTF-8.
+  def last_comment=(comment)
+    @last_comment = comment.encode("UTF-8")
+  end
+
+  # Adds an HRX::File or HRX::Directory to this archive.
+  #
+  # If `before` or `after` is passed, this adds `entry` before or after the
+  # entry with the given path in the archive. If the archive has no entry with
+  # the given path, this throws an HRX::Error. If `before` and `after` are
+  # *both* passed, this throws an ArgumentError.
+  #
+  # Throws an HRX::Error if the entry conflicts with an existing entry.
+  def add(entry, before: nil, after: nil)
+    raise ArgumentError.new("before and after may not both be passed") if before && after
+
+    node = HRX::OrderedNode.new(entry._absolute(@root))
+
+    path = entry.path.split("/")
+    parent = path[0...-1].inject(@entries_by_path) do |hash, component|
+      if hash[component].is_a?(LinkedList::Node)
+        raise HRX::Error.new("\"#{hash[component].data._relative(@root).path}\" defined twice")
+      end
+      hash[component] ||= {}
+    end
+
+    if parent[path.last].is_a?(LinkedList::Node)
+      raise HRX::Error.new("\"#{entry.path}\" defined twice")
+    end
+
+    if entry.is_a?(HRX::Directory)
+      dir = (parent[path.last] ||= {})
+      if dir.is_a?(LinkedList::Node) || dir[:dir]
+        raise HRX::Error.new("\"#{entry.path}\" defined twice")
+      end
+      dir[:dir] = node
+    else
+      raise HRX::Error.new("\"#{entry.path}\" defined twice") if parent.has_key?(path.last)
+      parent[path.last] = node
+    end
+
+    if before || after
+      reference = _find_node(before || after)
+      raise HRX::Error.new("There is no entry named \"#{before || after}\"") if reference.nil?
+
+      if before
+        @entries.insert_before_node(node, reference)
+      else
+        @entries.insert_after_node(node, reference)
+      end
+    else
+      @entries << node
+    end
+
+    nil
+  end
+  alias_method :<<, :add
+
+  # Returns this archive, serialized to text in HRX format.
+  def to_hrx
+    buffer = String.new.encode("UTF-8")
+    boundary = "<#{"=" * _choose_boundary_length}>"
+
+    entries.each_with_index do |e, i|
+      buffer << boundary << "\n" << e.comment << "\n" if e.comment
+      buffer << boundary << " " << e.path << "\n"
+      if e.respond_to?(:content) && !e.content.empty?
+        buffer << e.content
+        buffer << "\n" unless i == entries.length - 1
+      end
+    end
+    buffer << boundary << "\n" << last_comment if last_comment
+
+    buffer.freeze
+  end
+
+  # Writes this archive to disk at `file`.
+  def write!(file)
+    File.write(file, to_hrx, mode: "wb")
+  end
+
+  private
+
+  # Adds `@root` to the beginning of `path` if `@root` isn't `nil`.
+  def _absolute(path)
+    @root ? @root + path : path
+  end
+
+  # Returns the LinkedList::Node at the given `path`, or `nil` if there is no
+  # node at that path.
+  def _find_node(path)
+    components = path.split("/")
+    return if components.empty?
+    result = @entries_by_path.dig(*components)
+    return result[:dir] if result.is_a?(Hash)
+    return result unless path.end_with?("/")
+  end
+
+  # Returns each entry in or beneath the directory hash `dir`, in no particular
+  # order.
+  def _each_entry(dir)
+    return to_enum(__method__, dir) unless block_given?
+
+    dir.values.each do |entry|
+      if entry.is_a?(Hash)
+        _each_entry(entry) {|e| yield e}
+      else
+        yield entry
+      end
+    end
+  end
+
+  # Returns a boundary length for a serialized archive that doesn't conflict
+  # with any of the files that archive contains.
+  def _choose_boundary_length
+    forbidden_boundary_lengths = Set.new
+    entries.each do |e|
+      [
+        (e.content if e.respond_to?(:content)),
+        e.comment
+      ].each do |text|
+        next unless text
+        text.scan(/^<(=+)>/m).each do |(equals)|
+          forbidden_boundary_lengths << equals.length
+        end
+      end
+    end
+
+    boundary_length = @boundary_length
+    while forbidden_boundary_lengths.include?(boundary_length)
+      boundary_length += 1
+    end
+    boundary_length
+  end
+end