soml-lang 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: 1da7419c0865c3f10d59dab2f4e5b8d638b814a11ed322a2885c7d6e3e3aecee
+  data.tar.gz: ed89f8ed61c0c624cf3023ec9f3199b76eec6e7f090992df90409f065e175937
+SHA512:
+  metadata.gz: de26c20a01ef8fa144bf98402e2ae7d145f9b1ba22dfbd7b8fa02c283a3e66efbdf0060a9d5718ace01f1240384af0090c19717a802e3563e8c1d9f4534f182a
+  data.tar.gz: 65dce6ea77612c06ab6b5d656f1aa4bd030306c590416013b508797b47dd03ebedd3faa7be0ab9deb83d79d246ebc8b448cd7b1ed4db86f4f39d9e600351009c

data/lib/soml/duration.rb

@@ -0,0 +1,167 @@
+# frozen_string_literal: true
+
+module SOML
+	# A length of time, exact to the nanosecond: what a SOML duration such as `1h30m` holds.
+	#
+	# It is immutable, comparable, and usable as a hash key. A duration is a signed count of nanoseconds in the 64-bit range, about 292 years either way.
+	#
+	# @!attribute [r] nanoseconds
+	#   @return [Integer] The length in nanoseconds.
+	#
+	# @example
+	#   timeout = SOML.parse('timeout: 1m30s')['timeout']
+	#   #=> #<SOML::Duration 1m30s>
+	#
+	#   timeout.to_f
+	#   #=> 90.0
+	#
+	#   SOML::Duration.parse('90s') == timeout
+	#   #=> true
+	#
+	#   SOML::Duration.new(nanoseconds: 1_500_000_000).to_s
+	#   #=> "1.5s"
+	Duration = Data.define(:nanoseconds) do
+		include Comparable
+
+		# Read a duration written as in a document, such as `1h30m`, `1.5s`, or `-250ms`.
+		#
+		# @param text [String]
+		# @return [Duration]
+		# @raise [ParseError] When `text` is not a valid duration.
+		# @raise [TypeError] When `text` is not a string.
+		def self.parse(text)
+			Parser.new(text).parse_duration_literal
+		end
+
+		# Make a duration from a number of seconds, the inverse of {#to_r}. The seconds are rounded to the nearest nanosecond, because a `Float` such as `0.1` is not exact.
+		#
+		# @param seconds [Numeric] An `Integer`, a `Float`, a `Rational`, or another real number.
+		# @return [Duration]
+		# @raise [TypeError] When `seconds` is not a number.
+		# @raise [RangeError] When `seconds` is not finite, not real, or outside the 64-bit range of nanoseconds.
+		#
+		# @example
+		#   SOML::Duration.from_seconds(90)
+		#   #=> #<SOML::Duration 1m30s>
+		#
+		#   SOML::Duration.from_seconds(0.1)
+		#   #=> #<SOML::Duration 0.1s>
+		def self.from_seconds(seconds)
+			# `Numeric ===` checks the class itself, so an `ActiveSupport::Duration`, which only claims to be a `Numeric`, must be converted with `to_r` first. Its months are an average length.
+			raise TypeError, "A duration is made from a number of seconds, got #{Parser.describe_argument(seconds)}" unless Numeric === seconds
+
+			new(nanoseconds: (seconds.to_r * 1_000_000_000).round)
+		end
+
+		# @param nanoseconds [Integer] The length in nanoseconds.
+		# @raise [TypeError] When `nanoseconds` is not an `Integer`.
+		# @raise [RangeError] When `nanoseconds` is outside the 64-bit range.
+		def initialize(nanoseconds:)
+			raise TypeError, "A duration is a whole number of nanoseconds, got #{Parser.describe_argument(nanoseconds)}" unless Integer === nanoseconds
+			raise RangeError, "A duration must be in the 64-bit range of nanoseconds, about 292 years either way, got #{nanoseconds}" unless nanoseconds.between?(INT64_MIN, INT64_MAX)
+
+			super
+		end
+
+		# @return [Integer, nil]
+		def <=>(other)
+			# `Module#===` rather than `is_a?`, which a `BasicObject` does not have.
+			nanoseconds <=> other.nanoseconds if Duration === other
+		end
+
+		# @return [Boolean]
+		def zero? = nanoseconds.zero?
+
+		# @return [Boolean]
+		def positive? = nanoseconds.positive?
+
+		# @return [Boolean]
+		def negative? = nanoseconds.negative?
+
+		# @return [Duration] The same length in the other direction.
+		# @raise [RangeError] For the most negative duration, whose opposite is outside the 64-bit range.
+		def -@
+			Duration.new(nanoseconds: -nanoseconds)
+		end
+
+		# @return [Duration]
+		# @raise [RangeError] For the most negative duration, whose length is outside the 64-bit range.
+		def abs
+			negative? ? -self : self
+		end
+
+		# A number has no unit, so only a duration can be added.
+		#
+		# @param other [Duration]
+		# @return [Duration]
+		# @raise [TypeError] When `other` is not a duration.
+		# @raise [RangeError] When the sum is outside the 64-bit range.
+		#
+		# @example
+		#   SOML::Duration.parse('1h') + SOML::Duration.parse('30m')
+		#   #=> #<SOML::Duration 1h30m>
+		def +(other)
+			Duration.new(nanoseconds: nanoseconds + nanoseconds_of(other))
+		end
+
+		# @param other [Duration]
+		# @return [Duration]
+		# @raise [TypeError] When `other` is not a duration.
+		# @raise [RangeError] When the difference is outside the 64-bit range.
+		def -(other)
+			Duration.new(nanoseconds: nanoseconds - nanoseconds_of(other))
+		end
+
+		# @return [Rational] The length in seconds, exactly.
+		def to_r
+			Rational(nanoseconds, 1_000_000_000)
+		end
+
+		# @return [Float] The length in seconds, for `sleep` and `Timeout.timeout`.
+		def to_f
+			nanoseconds.fdiv(1_000_000_000)
+		end
+
+		# @return [String] The canonical spelling, such as `1h30m`, `1.5s`, or `0s`.
+		def to_s
+			# Not frozen, as the text that is built below is not.
+			return +'0s' if nanoseconds.zero?
+
+			magnitude = nanoseconds.abs
+			hours, rest = magnitude.divmod(3_600_000_000_000)
+			minutes, rest = rest.divmod(60_000_000_000)
+			seconds, fraction = rest.divmod(1_000_000_000)
+			text = nanoseconds.negative? ? +'-' : +''
+			text << "#{hours}h" if hours.positive?
+			text << "#{minutes}m" if minutes.positive?
+
+			if seconds.positive? || fraction.positive?
+				text << seconds.to_s
+				# The fraction is written like an instant's: nine digits with the trailing zeros removed.
+				text << ".#{format('%09d', fraction).sub(/0+\z/, '')}" if fraction.positive?
+				text << 's'
+			end
+
+			text
+		end
+
+		# @return [String]
+		def inspect
+			"#<SOML::Duration #{self}>"
+		end
+
+		# @api private
+		def pretty_print(printer)
+			printer.text(inspect)
+		end
+
+		private
+
+		# The message is the one Ruby gives for `1 + nil`.
+		def nanoseconds_of(other)
+			return other.nanoseconds if Duration === other
+
+			raise TypeError, "#{Parser.conversion_name(other)} can't be coerced into SOML::Duration"
+		end
+	end
+end

data/lib/soml/edit.rb

@@ -0,0 +1,468 @@
+# frozen_string_literal: true
+
+module SOML
+	# The editor behind {SOML.edit}. It is a close port of the JS reference's `edit.ts`: it finds the value at a path in the {Tree} of a document, and makes the change as replacements of parts of the source, so everything else keeps its text.
+	#
+	# @api private
+	class Editor
+		# What removing a member or an item takes out of the source. `is_whole_lines` is whether it takes whole lines, which may leave a blank line next to another one.
+		Removal = Struct.new(:start, :finish, :is_whole_lines)
+
+		Replacement = Data.define(:start, :finish, :text)
+
+		private_constant :Removal, :Replacement
+
+		# @param source [String] The document.
+		# @param path [Array<String, Symbol, Integer>]
+		# @param value [Object] The new value, unless `delete` is true.
+		# @param delete [Boolean] Whether to remove the value instead.
+		def initialize(source, path, value, delete:)
+			# `Array#all?` on something else than an array, such as a hash, would read it in another way.
+			unless Array === path && !path.empty? && path.all? { |segment| (Integer === segment && !segment.negative?) || String === segment || Symbol === segment }
+				raise TypeError, 'The path must be a non-empty array of keys and array indexes'
+			end
+
+			# A key is checked as `generate` checks one, and read as the UTF-8 string it names, so that a symbol finds its string. A key of a removal is not written, so a carriage return in it is no error: it finds nothing.
+			generator = Generator.new
+			names = []
+
+			path.each do |segment|
+				names << (Integer === segment ? segment : generator.member_name(segment, written: !delete))
+			rescue GenerateError => error
+				# A key that cannot be written is reported at the place of the object that holds it, as `generate` reports one.
+				error.path.unshift(*names)
+				raise
+			end
+
+			@path = names.freeze
+			@value = value
+			@delete = delete
+
+			tree = Tree.new(source)
+			@source = tree.source
+			# The same bytes, for the searches for a line break from an offset that may be inside a character, such as the last byte of a line that ends with `é`, which `String#byterindex` refuses in UTF-8.
+			@bytes = @source.b
+			@length = @source.bytesize
+			@body = tree.body
+			@comments = tree.comments
+			@replacements = []
+			# Whether the container being edited is inside one that stays on one line, so that it stays on one line too. An edit follows one path, so one flag is enough.
+			@is_inside_one_line = false
+
+			# The end of each comment, by its start, so that the trivia between tokens can be skipped.
+			@comment_ends = @comments.to_h { [it.start, it.finish] }
+			# The start of each block comment, by its end, so that the comments before a member or an item can be found.
+			@block_comment_starts = @comments.select { it.type == :block }.to_h { [it.finish, it.start] }
+		end
+
+		# @return [String] The changed document.
+		def edit
+			descend(@body, 0, 1)
+
+			# Replacements never overlap. A stable sort keeps the creation order of two insertions at the same offset.
+			result = +''
+			position = 0
+
+			@replacements.sort_by.with_index { |replacement, index| [replacement.start, index] }.each do |replacement|
+				result << @source.byteslice(position, replacement.start - position)
+				result << replacement.text
+				position = replacement.finish
+			end
+
+			result << @source.byteslice(position, @length - position)
+
+			# The result is checked, so that a mistake here raises rather than writing a broken document.
+			begin
+				Parser.new(result).parse
+			rescue ParseError
+				raise "SOML.edit made an invalid document for the path #{describe_path(@path)}. This is a bug in soml-lang"
+			end
+
+			result
+		end
+
+		private
+
+		def edit_in_array(array, index, depth)
+			position = @path[index]
+			raise TypeError, "Cannot edit #{describe_path(@path)}, because #{describe_parent(index)} is an array, so it needs an index, not a key" unless Integer === position
+
+			elements = array.elements
+
+			# An index past the end, which may be too large for `Array#[]`.
+			if position >= elements.length
+				# Removing an item that is not there changes nothing, at the end of the array or past it, and so does removing something below it.
+				return if @delete
+
+				count = elements.length
+
+				if position != count
+					items = count == 1 ? '1 item' : "#{count} items"
+					owner = index.zero? ? 'the document' : "the array at #{describe_parent(index)}"
+					raise IndexError, "Cannot edit #{describe_path(@path)}, because #{owner} has #{items}. Add an item at index #{count}"
+				end
+
+				new_value = nest(index + 1)
+				insert(array, elements.last) { |indentation| value_text(new_value, index + 1, depth + 1, indentation, array) }
+				return
+			end
+
+			element = elements[position]
+
+			if index < @path.length - 1
+				@is_inside_one_line = one_line?(array)
+				descend(element, index + 1, depth + 1)
+			elsif @delete
+				remove_node(array, element)
+			else
+				replace(element, depth + 1, array)
+			end
+		end
+
+		def edit_in_object(object, index, depth)
+			key = @path[index]
+			raise TypeError, "Cannot edit #{describe_path(@path)}, because #{describe_parent(index)} is an object, so it needs a key, not an index" unless String === key
+
+			member = object.members.find { it.key.value == key }
+
+			if member
+				if index < @path.length - 1
+					@is_inside_one_line = one_line?(object)
+					descend(member.value, index + 1, depth + 1)
+				elsif @delete
+					remove_member(object, member)
+				else
+					replace_member_value(member, depth + 1, object)
+				end
+
+				return
+			end
+
+			return if @delete
+
+			written_key = SOML.bare_key?(key) ? key : Generator.new.generate_value(key, 0)
+			new_value = nest(index + 1)
+			insert(object, object.members.last) { |indentation| "#{written_key}: #{value_text(new_value, index + 1, depth + 1, indentation, object)}" }
+		end
+
+		# Edits the path from `index` on, inside `node`, whose own depth is `depth`.
+		def descend(node, index, depth)
+			case node.type
+			when :array
+				edit_in_array(node, index, depth)
+			when :object
+				edit_in_object(node, index, depth)
+			else
+				raise TypeError, "Cannot edit #{describe_path(@path)}, because #{describe_parent(index)} is not an object or an array"
+			end
+		end
+
+		def replace(node, depth, container)
+			@replacements << Replacement.new(node.start, node.finish, value_text(@value, @path.length, depth, indentation(node.start), container))
+		end
+
+		# Replaces the value of `member`. A block string begins on the line after its key, and the new value is never a block string, so when only whitespace comes between the `:` and a block string, the new value goes on the key's line, as the formatter writes it.
+		def replace_member_value(member, depth, object)
+			value = member.value
+			colon_end = member.key.finish + 1
+
+			unless value.type == :scalar && value.block && skip_whitespace(colon_end) == value.start
+				replace(value, depth, object)
+				return
+			end
+
+			@replacements << Replacement.new(colon_end, value.finish, " #{value_text(@value, @path.length, depth, indentation(member.start), object)}")
+		end
+
+		# Removes `member`. Removing the only member of a document without braces leaves `{}` in its place, because a document is never empty, and the comments that the member owned stay.
+		def remove_member(object, member)
+			if object.braced || object.members.length > 1
+				remove_node(object, member)
+				return
+			end
+
+			@replacements << Replacement.new(member.start, member.finish, '{}')
+		end
+
+		# Removes `node` from `container`.
+		#
+		# The removal also takes a blank line that would be left next to another one or directly inside a bracket. When the only item of a braced container goes and no comment is left inside, its brackets close up, as `[]`.
+		def remove_node(container, node)
+			items = container.type == :array ? container.elements : container.members
+			# When the removed item is the last one and has no comma after it, it takes the comma before it, so that no trailing comma is left, as `[1, 2]` becomes `[1]`.
+			takes_comma_before = node.equal?(items.last) && @source.getbyte(skip_trivia(node.finish)) != 0x2C
+			removal = node_removal(node, takes_comma_before)
+			take_blank_line(removal, container, content_start(container)) if removal.is_whole_lines
+
+			if items.length == 1 && braced?(container) && !comment_left?(container, removal)
+				@replacements << Replacement.new(container.start + 1, container.finish - 1, '')
+				return
+			end
+
+			@replacements << Replacement.new(removal.start, removal.finish, '')
+		end
+
+		# Whether a comment inside `container` is outside `removal`.
+		def comment_left?(container, removal)
+			@comments.any? do |comment|
+				comment_start = comment.start
+				comment_start > container.start && comment_start < container.finish && (comment_start < removal.start || comment_start >= removal.finish)
+			end
+		end
+
+		# What removing a member or an item, with the comments it owns and its comma, takes out of the source. With `takes_comma_before`, a comma directly before it goes too.
+		def node_removal(node, takes_comma_before)
+			start = owned_start(node.start)
+			finish = owned_end(node.finish)
+			following = skip_spaces(finish)
+			# Only a braced container can have commas.
+			has_comma = @source.getbyte(following) == 0x2C
+
+			# The comma before it is only taken when spaces alone are between them and the comments it owns. The scan back only crosses spaces, so it stays short on a long line.
+			before = skip_spaces_back(start)
+			removal_start = takes_comma_before && before.positive? && @source.getbyte(before - 1) == 0x2C ? before - 1 : start
+			# The comments after its comma go with it when they end its line, as the formatter keeps them after it.
+			result = removal(removal_start, has_comma ? line_end_after_trivia(following + 1) || following + 1 : finish)
+
+			# When it takes the comma before it, the spaces before a comment after it stay, so that the comment does not join the item before the comma.
+			if removal_start != start && !result.is_whole_lines && @comment_ends.key?(result.finish)
+				result.finish = skip_spaces_back(result.finish)
+			end
+
+			result
+		end
+
+		# The start of the block comments that a member or an item at `offset` owns before it: those on its line after the comma or the opening bracket before it, as `/* note */` in `[1, /* note */ 2]`. The formatter keeps them in front of it. It is `offset` when there are none.
+		def owned_start(offset)
+			while (comment_start = @block_comment_starts[skip_spaces_back(offset)])
+				offset = comment_start
+			end
+
+			offset
+		end
+
+		# The end of the comments that a member or an item ending at `offset` owns after it: those on its line before its comma or the closing bracket, as `/* note */` in `[1 /* note */, 2]` and `[1, 2 /* note */]`, and a line comment at the end of its line. The formatter keeps them after it. It is `offset` when there are none.
+		def owned_end(offset)
+			while (comment_end = @comment_ends[skip_spaces(offset)])
+				offset = comment_end
+			end
+
+			offset
+		end
+
+		# The removal of the text from `start` to `finish`. When nothing else is on its lines, it takes the lines, including a comment at the end of the last one.
+		def removal(start, finish)
+			line_end = line_end_after_trivia(finish)
+
+			# The line start is only looked for when nothing follows on the line, because the scan back to it is long for an item in the middle of a long line, and doing it for every item would be quadratic.
+			if line_end
+				line_start = line_start(start)
+				return Removal.new(line_start, [line_end + 1, @length].min, true) if skip_spaces(line_start) == start
+			end
+
+			# The spaces after the text go too, and the spaces before it when nothing follows it on the line or in its container.
+			after = skip_spaces(finish)
+			byte = @source.getbyte(after)
+			is_last = byte.nil? || byte == 0x0A || byte == 0x7D || byte == 0x5D
+			Removal.new(is_last ? skip_spaces_back(start) : start, after, false)
+		end
+
+		# Widens a removal of whole lines by a blank line that would otherwise be left next to another blank line, or directly inside a bracket. `content_start` is the container's, from `content_start`.
+		def take_blank_line(removal, container, content_start)
+			is_blank_before = removal.start.positive? && blank_line?(line_start(removal.start - 1))
+			is_blank_after = removal.finish < @length && blank_line?(removal.finish)
+
+			if is_blank_before && (is_blank_after || at_closing?(removal.finish, container))
+				removal.start = line_start(removal.start - 1)
+			elsif is_blank_after && removal.start == content_start
+				removal.finish = @bytes.byteindex("\n", removal.finish) + 1
+			end
+		end
+
+		# The offset after the blank lines that start at `offset`.
+		def skip_blank_lines(offset)
+			offset = @bytes.byteindex("\n", offset) + 1 while offset < @length && blank_line?(offset)
+			offset
+		end
+
+		# Whether only blank lines come between the line at `offset` and the line that closes `container`, or the end of the source.
+		def at_closing?(offset, container)
+			offset = skip_blank_lines(offset)
+			offset == @length || (braced?(container) && skip_spaces(offset) == container.finish - 1)
+		end
+
+		# The start of the first line that is not blank after the line that opens `container`, or after the start of the source. The line that opens a container ends after the comments that follow its bracket, and when an item follows on it, this is `nil`.
+		def content_start(container)
+			return skip_blank_lines(0) unless braced?(container)
+
+			line_end = line_end_after_trivia(container.start + 1)
+			line_end && skip_blank_lines(line_end + 1)
+		end
+
+		def blank_line?(line_start)
+			@source.getbyte(skip_spaces(line_start)) == 0x0A
+		end
+
+		def line_start(offset)
+			return 0 if offset.zero?
+
+			(@bytes.byterindex("\n", offset - 1) || -1) + 1
+		end
+
+		# Adds an item after `previous`, or into the empty `container` when there is none. The block gets the indentation of the item's line, and returns the item.
+		#
+		# An item on its own line needs no comma, so only an item added on the line of the item before it gets one, as in a one-line container.
+		def insert(container, previous)
+			if previous.nil?
+				closing = container.finish - 1
+
+				# A container that stays on one line keeps the item on that line, so `[/* note */]` becomes `[/* note */ 1]`, and `[1, []]` becomes `[1, [2]]`.
+				if one_line?(container)
+					start = skip_spaces_back(closing)
+					@replacements << Replacement.new(start, closing, "#{start > container.start + 1 ? ' ' : ''}#{yield ''}")
+					return
+				end
+
+				outer = indentation(container.start)
+				inner = "#{outer}\t"
+				line_start = line_start(closing)
+
+				# A closing bracket on its own line keeps that line, and the item goes on a line before it.
+				@replacements << if line_start > container.start && skip_spaces(line_start) == closing
+					Replacement.new(line_start, line_start, "#{inner}#{yield inner}\n")
+				else
+					Replacement.new(skip_spaces_back(closing), closing, "\n#{inner}#{yield inner}\n#{outer}")
+				end
+
+				return
+			end
+
+			# The new item goes after the comments that the one before it owns, so that they stay with that one.
+			previous_end = owned_end(previous.finish)
+			following = skip_trivia(previous_end)
+			has_comma = @source.getbyte(following) == 0x2C
+			after_comma = has_comma ? following + 1 : previous_end
+			line_end = line_end_after_trivia(after_comma)
+
+			# Something follows on the same line, such as the closing bracket of a one-line object, so the item goes on that line too, and takes its indentation.
+			if line_end.nil?
+				item = yield indentation(after_comma)
+				@replacements << (has_comma ? Replacement.new(after_comma, after_comma, " #{item},") : Replacement.new(previous_end, previous_end, ", #{item}"))
+				return
+			end
+
+			indentation = indentation(previous.start)
+			@replacements << Replacement.new(line_end, line_end, "\n#{indentation}#{yield indentation}")
+		end
+
+		# Whether `container` stays on one line: its brackets are on one line and something is between them, which {SOML.format} keeps, or it is inside a container that stays on one line. An empty `[]` or `{}` on its own gets its new item on a line of its own.
+		def one_line?(container)
+			return true if @is_inside_one_line
+
+			start = container.start
+			finish = container.finish
+			braced?(container) && skip_spaces(start + 1) < finish - 1 && !@source.byteslice(start, finish - start).include?("\n")
+		end
+
+		# `value` as {SOML.generate} writes it, written inside `container` where the value at the first `path_length` segments of the path goes, as a container of depth `depth` whose lines after the first are indented by `indentation`. In a container on one line, the value is on one line too.
+		def value_text(value, path_length, depth, indentation, container)
+			text = Generator.new(one_line: one_line?(container)).generate_value(value, depth)
+
+			# Every line break that {Generator} writes is between two lines of a container, because a string writes its line feeds as `\n`.
+			indentation.empty? ? text : text.gsub("\n", "\n#{indentation}")
+		rescue GenerateError => error
+			# The error names the value's place in the document, as `generate` would name it in the whole document.
+			error.path.unshift(*@path.first(path_length))
+			raise
+		end
+
+		# The spaces and tabs at the start of the line that holds `offset`.
+		def indentation(offset)
+			line_start = line_start(offset)
+
+			# A line that a block comment from an earlier line runs into, as in `/* a\n b */ x: 1`, is indented as the line where that comment starts.
+			while (comment = comment_across(line_start))
+				line_start = line_start(comment.start)
+			end
+
+			@source.byteslice(line_start, skip_spaces(line_start) - line_start)
+		end
+
+		# The comment that starts before `offset` and ends after it, if any. The comments are in source order, so a binary search finds the last one that starts before `offset`.
+		def comment_across(offset)
+			index = @comments.bsearch_index { it.start >= offset } || @comments.length
+			comment = index.positive? ? @comments[index - 1] : nil
+			comment if comment && comment.finish > offset
+		end
+
+		# Skips whitespace, line breaks, and comments.
+		def skip_trivia(offset)
+			offset = skip_line_trivia(offset)
+			offset = skip_line_trivia(offset + 1) while @source.getbyte(offset) == 0x0A
+			offset
+		end
+
+		# Skips spaces, tabs, and comments, but not a line break outside a comment.
+		def skip_line_trivia(offset)
+			loop do
+				offset = skip_spaces(offset)
+				comment_end = @comment_ends[offset]
+				return offset if comment_end.nil?
+
+				offset = comment_end
+			end
+		end
+
+		# The offset of the line break that ends the line at `offset`, or the end of the source, when only whitespace and comments come before it. Otherwise `nil`.
+		def line_end_after_trivia(offset)
+			offset = skip_line_trivia(offset)
+			offset if offset == @length || @source.getbyte(offset) == 0x0A
+		end
+
+		# Skips spaces, tabs, and line feeds, but not comments.
+		def skip_whitespace(offset)
+			offset += 1 while space?(byte = @source.getbyte(offset)) || byte == 0x0A
+			offset
+		end
+
+		def skip_spaces(offset)
+			offset += 1 while space?(@source.getbyte(offset))
+			offset
+		end
+
+		def skip_spaces_back(offset)
+			offset -= 1 while offset.positive? && space?(@source.getbyte(offset - 1))
+			offset
+		end
+
+		def space?(byte)
+			byte == 0x20 || byte == 0x09
+		end
+
+		def braced?(container)
+			container.type == :array || container.braced
+		end
+
+		# `@value` inside new objects for the keys of the path from `index` on. An index there names an item of an array that does not exist yet, so it raises an `IndexError`.
+		def nest(index)
+			nested = @value
+
+			(@path.length - 1).downto(index) do |position|
+				segment = @path[position]
+				raise IndexError, "Cannot edit #{describe_path(@path)}, because #{describe_parent(position)} does not exist, so it has no index #{segment}" if Integer === segment
+
+				nested = {segment => nested}
+			end
+
+			nested
+		end
+
+		# The path comes from the caller, perhaps from user input, so it is cut short, and the characters that are invisible or that a terminal acts on become escapes.
+		def describe_path(path) = Parser.describe_path(path)
+
+		# The value that holds `@path[index]`.
+		def describe_parent(index)
+			index.zero? ? 'the document' : describe_path(@path.first(index))
+		end
+	end
+end