soml-lang 0.0.1 → 0.0.2

data/lib/soml/tree.rb

@@ -1,16 +1,17 @@
 # frozen_string_literal: true
 
 module SOML
-	# The syntax tree of a valid document, for {SOML.format} and {SOML.edit}.
+	# A read-only syntax tree, returned by {SOML.parse_tree} and used by {SOML.format} and {SOML.edit}.
 	#
-	# It is a port of the JS reference's `tree.ts`, with only what the formatter and the editor read. Every offset is a byte offset into the UTF-8 source, and `finish` is the offset after the node. A node has no line and column, a scalar has no value, and there is no list of tokens. The document is checked by {Parser} first, so the builder can assume valid input, and the comments are collected in source order.
-	#
-	# @api private
+	# Every offset is a byte offset into the UTF-8 source, and `finish` is the offset after the node. Use {#position} for line and column. The document is checked by {Parser} first, so the builder can assume valid input. A tree from {SOML.parse_tree} is deeply frozen. Node constructors are internal. Tokens keep the source text of keys, scalar values, and punctuation, and comments are listed separately, in source order.
 	class Tree
 		# The nodes are structs rather than `Data`, whose `new` builds a hash of keywords for every node, which made building a tree several times as slow as parsing the document. Nothing changes a node once it is made.
 
-		# A `# ...` comment (`:line`) or a `/* ... */` comment (`:block`).
-		Comment = Struct.new(:type, :start, :finish)
+		# A `# ...` comment (`:line`) or a `/* ... */` comment (`:block`). `value` is its text without the delimiters.
+		Comment = Struct.new(:type, :start, :finish, :value)
+
+		# A lexical token with its original source text in `value`. `type` is `:punctuator`, `:bare_key`, `:string`, `:integer`, `:float`, `:keyword`, `:instant`, or `:duration`. Quoted keys are strings; booleans and null are keywords. Comments and whitespace are excluded.
+		Token = Struct.new(:type, :start, :finish, :value)
 
 		# An object, written with braces or, only at the top level, without them.
 		ObjectNode = Struct.new(:members, :braced, :start, :finish) do
@@ -26,18 +27,26 @@ module SOML
 			def type = :member
 		end
 
-		# A key, with its decoded `value`.
-		KeyNode = Struct.new(:value, :start, :finish)
+		# A key, with its decoded string `value` and `style` of `:bare`, `:literal`, or `:escaped`.
+		KeyNode = Struct.new(:value, :start, :finish, :style) do
+			def type = :key
+		end
 
-		# A value that is not a collection. `block` is whether it is a block string.
-		ScalarNode = Struct.new(:block, :start, :finish) do
+		# A value that is not a collection. `kind` is `:string`, `:integer`, `:float`, `:boolean`, `:null`, `:instant`, or `:duration`, and `value` is decoded as by SOML.parse. `block` is whether it is a block string. Strings have `style: :literal` or `:escaped`; integers have `radix: 2`, `8`, `10`, or `16`. In other kinds, `style` and `radix` are nil and `block` is false.
+		ScalarNode = Struct.new(:block, :start, :finish, :kind, :value, :style, :radix) do
 			def type = :scalar
 		end
 
 		# The characters that end the search for the closing quote of a `"..."` string.
 		ESCAPED_STRING_SPECIAL = /["\\]/
 
-		private_constant(*constants(false))
+		# The radix of an integer by the letter of its prefix, after its `0`.
+		RADIX_PREFIXES = {0x62 => 2, 0x6F => 8, 0x78 => 16}.freeze
+
+		# The distance in bytes between two of the character counts that {#position} starts from.
+		CHECKPOINT_BYTES = 1024
+
+		private_constant :ESCAPED_STRING_SPECIAL, :RADIX_PREFIXES, :CHECKPOINT_BYTES
 
 		# @return [String] The source, in UTF-8.
 		attr_reader :source
@@ -48,49 +57,135 @@ module SOML
 		# @return [Array<Comment>] Every comment, in source order.
 		attr_reader :comments
 
+		# @return [Array<Token>] Every lexical token, in source order, with exclusive UTF-8 byte spans. Comments are in {#comments}.
+		attr_reader :tokens
+
 		# @param source [String] The document, decoded as {SOML.parse} decodes it.
+		# @param lean [Boolean] Internal, for {SOML.format} and {SOML.edit}: whether to leave out the tokens and the line index, and not freeze the tree, because they read neither, and the tokens and the deep freeze each cost about as much as building the nodes. A lean tree has no {#tokens}, no comment text, and no {#position}.
 		# @raise [ParseError] When the document is not valid, the same as {SOML.parse}.
-		def initialize(source)
+		def initialize(source, lean: false)
 			# Validates the whole document, so the builder below can assume valid input.
 			parser = Parser.new(source)
-			parser.parse
-			@source = parser.source
+			value = parser.parse
+			@source = parser.source.dup.freeze
 			@length = @source.bytesize
 			@index = 0
 			@comments = []
+			@tokens = lean ? nil : []
 
 			skip_trivia
 
 			@body = case @source.getbyte(@index)
 			when 0x7B # {
-				parse_object
+				parse_object(value)
 			when 0x5B # [
-				parse_array
+				parse_array(value)
 			else
-				parse_bare_object
+				parse_bare_object(value)
 			end
 
 			skip_trivia
+			return if lean
+
+			# The start of each line, so that {#position} finds the line of an offset with a binary search, rather than by counting the line breaks before it, which is quadratic for a linter that asks for the position of every node.
+			@line_starts = [0]
+			line_break = -1
+			@line_starts << line_break + 1 while (line_break = @source.byteindex("\n", line_break + 1))
+
+			# The number of characters before every `CHECKPOINT_BYTES`th byte, so that {#position} counts the characters before an offset from the nearest one, rather than from the start of its line, which is quadratic for a linter on a long line. In an ASCII source, every character is one byte.
+			unless @source.ascii_only?
+				count = 0
+
+				@checkpoints = 0.step(@length, CHECKPOINT_BYTES).map do |offset|
+					before = count
+					count += character_count(offset, CHECKPOINT_BYTES)
+					before
+				end
+			end
+
+			# Only the builder reads it.
+			remove_instance_variable(:@index)
+
+			Ractor.make_shareable(self)
+		end
+
+		# Yield the body and all its descendants in source order, each node before its children and each member's key before its value. Comments are available separately through {#comments}.
+		#
+		# @return [Enumerator] When no block is given.
+		def each_node
+			return enum_for(__method__) unless block_given?
+
+			pending = [@body]
+
+			until pending.empty?
+				node = pending.pop
+				yield node
+
+				case node.type
+				when :object
+					node.members.reverse_each { pending << it }
+				when :array
+					node.elements.reverse_each { pending << it }
+				when :member
+					pending.push(node.value, node.key)
+				end
+			end
+
+			self
+		end
+
+		# The 1-based line and column of a byte offset in {#source}. Columns count Unicode characters, not bytes or display cells. EOF is accepted. Unlike tree spans, {ParseError#offset} counts characters.
+		#
+		# @param byte_offset [Integer] An offset at a UTF-8 character boundary.
+		# @return [Array<Integer>] The line and column.
+		# @raise [TypeError] When the offset is not an integer.
+		# @raise [ArgumentError] When the offset is out of bounds or inside a character.
+		def position(byte_offset)
+			raise TypeError, 'The byte offset must be an integer' unless Integer === byte_offset
+			raise ArgumentError, 'The byte offset must be within the source' unless byte_offset.between?(0, @length)
+
+			byte = @source.getbyte(byte_offset)
+			raise ArgumentError, 'The byte offset must be at a character boundary' if byte&.between?(0x80, 0xBF)
+
+			# The number of lines that start at or before the offset is its line.
+			line = @line_starts.bsearch_index { it > byte_offset } || @line_starts.length
+			line_start = @line_starts[line - 1]
+			[line, character_index(byte_offset) - character_index(line_start) + 1]
 		end
 
 		private
 
+		# The number of characters before `offset`, which is at a character boundary.
+		def character_index(offset)
+			return offset unless @checkpoints
+
+			checkpoint, rest = offset.divmod(CHECKPOINT_BYTES)
+			@checkpoints[checkpoint] + character_count(offset - rest, rest)
+		end
+
+		# The number of characters that start in the `length` bytes from `start`: the bytes that are not UTF-8 continuation bytes. The bytes may begin or end inside a character.
+		def character_count(start, length)
+			bytes = @source.byteslice(start, length).b
+			bytes.bytesize - bytes.count("\x80-\xBF".b)
+		end
+
 		def skip_trivia
 			source = @source
 			index = @index
 
+			# A lean tree, which has no tokens, has no comment text either, because {SOML.format} and {SOML.edit} copy comments from the source.
 			while (byte = source.getbyte(index))
 				case byte
 				when 0x20, 0x09, 0x0A
 					index += 1
 				when 0x23 # #
 					finish = source.byteindex("\n", index) || @length
-					@comments << Comment.new(:line, index, finish)
+					@comments << Comment.new(:line, index, finish, @tokens && source.byteslice(index + 1, finish - index - 1))
 					index = finish
 				when 0x2F # /
 					# The parser checked that every block comment ends, so the search finds its `*/`.
 					finish = source.byteindex('*/', index + 2) + 2
-					@comments << Comment.new(:block, index, finish)
+					@comments << Comment.new(:block, index, finish, @tokens && source.byteslice(index + 2, finish - index - 4))
 					index = finish
 				else
 					break
@@ -100,96 +195,97 @@ module SOML
 			@index = index
 		end
 
-		def parse_bare_object
-			members = []
-
-			loop do
-				members << parse_member
+		# The decoded collection supplies each value in source order. A block with two parameters reads a member of a hash without the array of its key and value that a block with one would get.
+		def parse_bare_object(value)
+			members = value.map do |name, decoded|
+				member = parse_member(name, decoded)
 				skip_trivia
-				break if @index >= @length
+				member
 			end
 
 			ObjectNode.new(members, false, members.first.start, members.last.finish)
 		end
 
-		def parse_object
+		def parse_object(value)
 			start = @index
-			members = parse_items(0x7D) { parse_member }
+			members = parse_items { value.map { |name, decoded| parse_item(parse_member(name, decoded)) } }
 			ObjectNode.new(members, true, start, @index)
 		end
 
-		def parse_array
+		def parse_array(value)
 			start = @index
-			elements = parse_items(0x5D) { parse_value }
+			elements = parse_items { value.map { parse_item(parse_value(it)) } }
 			ArrayNode.new(elements, start, @index)
 		end
 
-		# The items between an opening bracket and its `closing` bracket, which is consumed too. The parser has already checked the separators, including that a comma is on the line of the item before it.
-		def parse_items(closing)
-			items = []
-			@index += 1
+		# The items between an opening and a closing bracket, which are consumed too, from the block, which reads each with `parse_item`. The parser has already checked the separators, including that a comma is on the line of the item before it.
+		def parse_items
+			parse_punctuator
 			skip_trivia
+			items = yield
+			parse_punctuator
+			items
+		end
 
-			until @source.getbyte(@index) == closing
-				items << yield
-				skip_trivia
-				next unless @source.getbyte(@index) == 0x2C # ,
+		# Consumes the trivia and the comma after `item`, and returns it.
+		def parse_item(item)
+			skip_trivia
 
-				@index += 1
+			if @source.getbyte(@index) == 0x2C # ,
+				parse_punctuator
 				skip_trivia
 			end
 
-			@index += 1
-			items
+			item
 		end
 
-		def parse_member
-			key = parse_key
-			@index += 1 # :
+		def parse_member(name, decoded)
+			key = parse_key(name)
+			parse_punctuator # :
 			skip_trivia
-			value = parse_value
+			value = parse_value(decoded)
 			MemberNode.new(key, value, key.start, value.finish)
 		end
 
-		def parse_key
+		def parse_key(value)
 			source = @source
 			start = @index
 			byte = source.getbyte(start)
 
 			if byte == 0x27 || byte == 0x22 # ' "
 				finish = string_end(start)
-				@index = finish
-				text = source.byteslice(start + 1, finish - start - 2)
-
-				# A `"..."` key with an escape is decoded by the parser itself, so that the tree and `SOML.parse` cannot disagree.
-				return KeyNode.new(byte == 0x22 && text.include?('\\') ? read_scalar(start, finish) : text, start, finish)
+				style = byte == 0x22 ? :escaped : :literal
+			else
+				finish = start
+				finish += 1 while (byte = source.getbyte(finish)) && BARE_KEY_BYTE[byte]
+				style = :bare
 			end
 
-			finish = start
-			finish += 1 while (byte = source.getbyte(finish)) && BARE_KEY_BYTE[byte]
+			# Keys are decoded by the parser itself, so that the tree and `SOML.parse` cannot disagree.
 			@index = finish
-			KeyNode.new(source.byteslice(start, finish - start), start, finish)
+			add_token(style == :bare ? :bare_key : :string, start, finish)
+			KeyNode.new(value, start, finish, style)
 		end
 
-		def parse_value
+		def parse_value(value)
 			source = @source
 			start = @index
 
 			case (byte = source.getbyte(start))
 			when 0x7B # {
-				parse_object
+				parse_object(value)
 			when 0x5B # [
-				parse_array
+				parse_array(value)
 			when 0x27, 0x22 # ' "
-				return parse_block_string(byte) if source.getbyte(start + 1) == byte && source.getbyte(start + 2) == byte
+				return parse_block_string(byte, value) if source.getbyte(start + 1) == byte && source.getbyte(start + 2) == byte
 
 				@index = string_end(start)
-				ScalarNode.new(false, start, @index)
+				scalar_node(value, false, start, @index)
 			else
 				finish = start + 1
 				finish += 1 while (byte = source.getbyte(finish)) && NUMBER_BYTE[byte]
 				@index = finish
-				ScalarNode.new(false, start, finish)
+				scalar_node(value, false, start, finish)
 			end
 		end
 
@@ -209,7 +305,7 @@ module SOML
 		end
 
 		# The block ends at the first line whose first non-whitespace content is a run of exactly as many quotes as the opening delimiter.
-		def parse_block_string(quote)
+		def parse_block_string(quote, value)
 			source = @source
 			start = @index
 			delimiter_length = 0
@@ -224,16 +320,51 @@ module SOML
 
 				if run_length == delimiter_length
 					@index = delimiter_start + delimiter_length
-					return ScalarNode.new(true, start, @index)
+					return scalar_node(value, true, start, @index)
 				end
 
 				line_start = source.byteindex("\n", line_start) + 1
 			end
 		end
 
-		# The value of the scalar from `start` to `finish`, read by the parser. A scalar's validity does not depend on its context, so it parses on its own inside an array.
-		def read_scalar(start, finish)
-			Parser.new("[#{@source.byteslice(start, finish - start)}]").parse.first
+		# Consume one bracket, colon, or comma that the parser has already validated.
+		def parse_punctuator
+			add_token(:punctuator, @index, @index + 1)
+			@index += 1
+		end
+
+		# Record a token while scanning, so punctuation inside strings and comments never becomes a separate token. A lean tree has none.
+		def add_token(type, start, finish)
+			@tokens&.push(Token.new(type, start, finish, @source.byteslice(start, finish - start)))
+		end
+
+		# The value of the scalar from `start` to `finish`, already read by the parser as part of the document, with the spelling metadata that a lint rule needs.
+		def scalar_node(value, block, start, finish)
+			style = nil
+			radix = nil
+
+			kind = case value
+			when String
+				style = @source.getbyte(start) == 0x27 ? :literal : :escaped
+				:string
+			when Integer
+				# A radix integer has no sign, so its prefix is at the start.
+				radix = @source.getbyte(start) == 0x30 ? RADIX_PREFIXES.fetch(@source.getbyte(start + 1), 10) : 10
+				:integer
+			when Float
+				:float
+			when true, false
+				:boolean
+			when nil
+				:null
+			when Time
+				:instant
+			when Duration
+				:duration
+			end
+
+			add_token(kind == :boolean || kind == :null ? :keyword : kind, start, finish)
+			ScalarNode.new(block, start, finish, kind, value, style, radix)
 		end
 	end
 end

data/lib/soml/version.rb

@@ -2,5 +2,5 @@
 
 module SOML
 	# The version of this gem.
-	VERSION = '0.0.1'
+	VERSION = '0.0.2'
 end

data/lib/soml.rb

@@ -23,10 +23,10 @@ module SOML
 	}.freeze
 
 	# A byte that a bare key can hold, as a table of 256 booleans, for the {Parser} and the {Tree}.
-	BARE_KEY_BYTE = Array.new(256) { |byte| byte.chr.match?(/[A-Za-z0-9_-]/) }.freeze
+	BARE_KEY_BYTE = Array.new(256) { it.chr.match?(/[A-Za-z0-9_-]/) }.freeze
 
 	# A number, an instant, or a duration is one maximal run of these bytes, which the {Parser} then validates as a whole. A keyword ends at the first byte that is not one, too, because the parser checked that it is followed by whitespace, a separator, a closing bracket, a comment, or the end.
-	NUMBER_BYTE = Array.new(256) { |byte| byte.chr.match?(/[A-Za-z0-9_.:+-]/) }.freeze
+	NUMBER_BYTE = Array.new(256) { it.chr.match?(/[A-Za-z0-9_.:+-]/) }.freeze
 
 	# A line of a block string without one of these is blank. A search for one character, because a repeat over a long line needs memory for every character.
 	NOT_BLANK_CHARACTER = /[^\t ]/
@@ -35,13 +35,13 @@ module SOML
 	NO_VALUE = Object.new.freeze
 
 	# The indentation of each level, so that the {Generator} and the {Printer} make no string for each line they indent. The {Printer} indents a value after a comment one level deeper than its key, so each container can be two levels deeper than the one that holds it, and a value after a comment in the deepest container is at level 200.
-	INDENTS = Array.new((MAX_DEPTH * 2) + 1) { |level| ("\t" * level).freeze }.freeze
+	INDENTS = Array.new((MAX_DEPTH * 2) + 1) { ("\t" * it).freeze }.freeze
 
 	private_constant :MAX_DEPTH, :INT64_MIN, :INT64_MAX, :DURATION_UNITS, :NO_VALUE, :BARE_KEY_BYTE, :NUMBER_BYTE, :NOT_BLANK_CHARACTER, :INDENTS
 
 	# Whether a key can be written without quotes, as a bare key: one or more ASCII letters, digits, `_`, or `-`, in any order, so `404` and `-x` are bare keys too. {SOML.generate} writes such a key bare and quotes every other key.
 	#
-	# @param key [String, Symbol] A key in UTF-8, or a symbol, which is read as its name. A key in an encoding that is not compatible with ASCII, such as UTF-16, is read as the UTF-8 string it converts to, as {SOML.generate} reads it. Any other object is not a key, so it gives false.
+	# @param key [String, Symbol] A key, or a symbol, which is read as its name. A key in an encoding that is not compatible with ASCII, such as UTF-16, is converted to UTF-8 first. Any other object gives false.
 	# @return [Boolean]
 	#
 	# @example
@@ -54,8 +54,8 @@ module SOML
 		# Only a String or a Symbol is a key. Anything else, such as a number or nil, could never be a bare key, so the answer is false rather than a crash on its missing `encoding`.
 		return false unless String === key || Symbol === key
 
-		# The byte scan needs a String, so a Symbol is read as its name. A String, even a subclass, is left as it is, as the regex did.
-		key = key.to_s unless String === key
+		# The byte scan needs a String, so a Symbol is read as its name. A String, even a subclass, is left as it is.
+		key = key.name if Symbol === key
 		key = key.encode(Encoding::UTF_8) unless key.encoding.ascii_compatible?
 
 		# A scan of the bytes, which is faster than the regex it replaces and decides the same: a byte that is not an ASCII letter, digit, `_`, or `-` means the key needs quotes. A non-ASCII character is a run of bytes none of which a bare key can hold.
@@ -71,8 +71,8 @@ module SOML
 		end
 
 		true
-	rescue ArgumentError, EncodingError
-		# Invalid bytes, or a key that does not convert to UTF-8.
+	rescue EncodingError
+		# A key that does not convert to UTF-8.
 		false
 	end
 
@@ -94,13 +94,23 @@ module SOML
 	#     postgres: {host: 'db.internal'}
 	#   SOML
 	#   #=> {"name" => "api-gateway", "replicas" => 3, "timeout" => #<SOML::Duration 30s>, "postgres" => {"host" => "db.internal"}}
-	def self.parse(source, symbolize_names: false, freeze: false)
-		Parser.new(source, symbolize_names:, freeze:).parse
-	end
+	def self.parse(source, symbolize_names: false, freeze: false) = Parser.new(source, symbolize_names:, freeze:).parse
+
+	# Parse a document into a read-only syntax tree for linters and other tools. Nodes have decoded values, spelling, and UTF-8 byte spans. The tree holds a frozen copy of the source.
+	#
+	# @param source [String] The document, read as {SOML.parse} reads it.
+	# @return [Tree] The deeply frozen tree, including its source, tokens, and comments.
+	# @raise [ParseError, TypeError, EncodingError] As for {SOML.parse}.
+	# @example
+	#   tree = SOML.parse_tree('port: 0x1F90 # Default')
+	#   node = tree.body.members.first.value
+	#   [node.kind, node.value, node.radix, tree.position(node.start)]
+	#   #=> [:integer, 8080, 16, [1, 7]]
+	def self.parse_tree(source) = Tree.new(source)
 
 	# Read and parse a file.
 	#
-	# The file is read in binary mode, so that a carriage return, which a document may not contain, is not hidden by a text-mode conversion. An error names the file, as in `Duplicate key port at config.soml:3:1`.
+	# The file is read in binary mode, so that a text-mode conversion cannot hide a carriage return. An error names the file, as in `Duplicate key port at config.soml:3:1`.
 	#
 	# @param path [String, #to_path] The file, such as a `Pathname` or a `File`.
 	# @param symbolize_names [Boolean] See {SOML.parse}.
@@ -111,15 +121,13 @@ module SOML
 	#
 	# @example
 	#   config = SOML.load_file('config.soml', symbolize_names: true)
-	def self.load_file(path, symbolize_names: false, freeze: false)
-		Parser.new(File.binread(path), symbolize_names:, freeze:, path: File.path(path)).parse
-	end
+	def self.load_file(path, symbolize_names: false, freeze: false) = Parser.new(File.binread(path), symbolize_names:, freeze:, path: File.path(path)).parse
 
 	# Write a hash or an array as SOML.
 	#
-	# Members keep the order of their hash, nesting is written with braces and tabs, and the text ends with one line feed. Comments and block strings are never written. Everything but the order of members is canonical form, so the text is canonical form when the keys are already sorted.
+	# Members keep the order of their hash, nesting uses braces and tabs, and the text ends with one line feed. Everything but the member order follows canonical form.
 	#
-	# With `canonical: true`, members are sorted by key too, so the text is canonical form. Two equal values then give the same text, which can be hashed, signed, or compared.
+	# With `canonical: true`, members are sorted by key too, so two equal values give the same text, which can be hashed, signed, or compared.
 	#
 	# @param value [Hash, Array] The document.
 	# @param canonical [Boolean] Whether to write canonical form, with members sorted by key.
@@ -132,20 +140,18 @@ module SOML
 	#
 	#   SOML.generate({name: 'api-gateway', replicas: 3, ratio: 0.5}, canonical: true)
 	#   #=> "name: 'api-gateway'\nratio: 0.5\nreplicas: 3\n"
-	def self.generate(value, canonical: false)
-		Generator.new(canonical:).generate(value)
-	end
+	def self.generate(value, canonical: false) = Generator.new(canonical:).generate(value)
 
 	# Format a document. Returns the document with its layout normalized, ending with one line feed.
 	#
-	# The layout follows the formatter in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. An object or an array whose brackets are on one line stays on one line, as in `ports: [80, 443]`, with a comma and a space between its members or items. To give a one-line container one member or item per line, put a line break anywhere inside it. Comments, member order, block strings, and the spelling of every value stay as they are, so the value never changes. The one change inside a block comment is the same layout rule: trailing whitespace is removed, and runs of blank lines collapse to one.
+	# The layout follows the formatter in the specification: one tab per level, every member and item on its own line with no commas, and no trailing whitespace or runs of blank lines. A container on one line stays on one line, as in `ports: [80, 443]`. Put a line break anywhere inside it to split it. Comments, member order, block strings, and the spelling of every value stay as they are.
 	#
-	# In detail, as the specification states:
+	# In detail:
 	#
-	# - A block comment that a value follows on the same line, as in `1, /* note */ 2`, stays in front of that value when each item goes on its own line.
-	# - One space follows each `:`, as in canonical form.
-	# - A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key, and the blank lines between them are removed.
-	# - A block string begins on the line after its key, and its delimiters and content have the indentation of that line. Its lines are not otherwise changed.
+	# - A block comment before a value on the same line, as in `1, /* note */ 2`, stays in front of that value.
+	# - One space follows each `:`.
+	# - A value on the line after its `key:` moves up to that line, unless a comment comes between them. Then it stays on its own line, one level deeper than the key.
+	# - A block string begins on the line after its key, indented to that line. Its lines are not otherwise changed.
 	# - There are no blank lines at the start of the file or directly inside brackets.
 	#
 	# @param source [String] The document, read as {SOML.parse} reads it.
@@ -160,41 +166,41 @@ module SOML
 	#
 	#   SOML.format("pool: {\nmin: 2, max: 16}")
 	#   #=> "pool: {\n\tmin: 2\n\tmax: 16\n}\n"
-	def self.format(source)
-		Printer.new(Tree.new(source)).print
-	end
+	def self.format(source) = Printer.new(Tree.new(source, lean: true)).print
 
-	# Change one value in a document, and keep everything else as it is written: comments, member order, layout, and the spelling of every other value. For tools that update a config file, such as a dependency bumper or a `set` command.
+	# Change one value in a document, and keep everything else as it is written: comments, member order, layout, and spelling. For tools that update a config file, such as a dependency bumper or a `set` command.
+	#
+	# Instead of a path, pass a member or a value node from {SOML.parse_tree} of the same source. A member selects its value for replacement and the whole member for deletion. Keys, comments, and the root collection cannot be edited this way. Reparse after each edit before selecting another node.
 	#
-	# The value at `path` is replaced, or added when it does not exist yet, and `delete: true` removes it. Only the changed part of the text is rewritten, and an edit to a formatted document leaves it formatted.
+	# The value at `path` is replaced, or added when it does not exist, and `delete: true` removes it. Only the changed part of the text is rewritten, so a formatted document stays formatted.
 	#
-	# - A new value is written as {SOML.generate} writes it, in canonical form except that its members keep their order, at the indentation of its line. So `0xFF` that is replaced by `255` is written `255`. In a container that is on one line, it is written on one line too, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`.
+	# - A new value is written as {SOML.generate} writes it (keeping member order), at the indentation of its line. So `0xFF` replaced by `255` is written `255`. In a one-line container, it is written on one line too, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`.
 	# - A new member goes after the last member of its object. Missing objects on the way are created.
-	# - A new item can be added at the end of an array, with the index that is its length.
-	# - A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below), and the commas of the other members and items stay as they are. When something follows the member or item before it on the same line, such as the closing bracket of the one-line container `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on a line of its own, unless that container is inside a container on one line, so `a: [1, []]` becomes `a: [1, [2]]`.
-	# - A removed member or item takes the comments it owns, which in a formatted document are the ones that {SOML.format} keeps with it: the comments after it on its line, also after its comma when nothing else follows there, and the block comments before it on its line, after the comma or bracket before it. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own belongs to no member or item, so it stays. A removed member or item also removes its lines when nothing else is on them. A line that a block comment after it continues onto counts as one of its lines. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
-	# - A removed member or item takes its comma with it. When the removed items are the last ones and have no comma after them, they take the comma directly before them instead, when only spaces, tabs, and the comments they own are between, so `[1, 2]` becomes `[1]`.
+	# - A new item can be added at the end of an array, at the index that is its length.
+	# - A new member or item goes on its own line without a comma, after the comments that the one before it owns (see below). The commas of the others stay as they are. When something follows the one before it on the same line, such as the `}` of `{a: 1}`, it goes on that line after a comma, as in `{a: 1, b: 2}`. In an empty `[]` or `{}`, it goes on its own line, unless that container is inside a one-line container, so `a: [1, []]` becomes `a: [1, [2]]`.
+	# - A removed member or item takes the comments it owns, which are the ones {SOML.format} keeps with it: the comments after it on its line (also after its comma), and the block comments before it on its line. So removing `2` from `[1, /* note */ 2]` gives `[1]`. A comment on a line of its own stays. Its lines are removed when nothing else is on them, including a line that a block comment after it continues onto. Removing every item of a container closes it up to `[]` or `{}`, unless a comment is left inside.
+	# - A removed member or item takes its comma with it. When it is the last one without a comma after it, it takes the comma directly before it instead, so `[1, 2]` becomes `[1]`.
 	# - Removing the only member of a document without braces leaves `{}`.
 	#
-	# Comments inside a value that is replaced or removed are removed with it. In a layout that {SOML.format} never writes, such as an item after a closing block string delimiter on its line, a new item can be indented differently from its neighbors, but the document is always valid and has the right value. Removing a value that does not exist changes nothing and is not an error: a missing member, a missing object or array on the way, or an index at or past the end of its array. So removing the same path twice is safe. The result has the same bytes as `source` exactly when nothing was removed, so `SOML.edit(source, path, delete: true).b == source.b` tells whether something was removed. The `.b` compares the bytes, because a source read in binary mode is not `==` to the UTF-8 result when it has a character that is not ASCII. This holds for a source in UTF-8, binary, or US-ASCII, because one in another encoding is converted to UTF-8.
+	# Comments inside a replaced or removed value are removed with it. In a layout that {SOML.format} never writes, such as an item after a closing block string delimiter on its line, a new item can be indented differently from its neighbors, but the document is always valid. Removing a value that does not exist (a missing member, a missing object or array on the way, or an index at or past the end of its array) changes nothing, so it is safe to remove the same path twice. Use `SOML.edit(source, path, delete: true).b == source.b` to tell whether something was removed. The `.b` is needed because a source read in binary mode is not `==` to the UTF-8 result when it has non-ASCII characters.
 	#
 	# The result is parsed before it is returned, so a bug in `edit` raises a `RuntimeError` rather than returning a broken document.
 	#
 	# @overload edit(source, path, value)
 	#   @param source [String] The document, read as {SOML.parse} reads it.
-	#   @param path [Array<String, Symbol, Integer>] The keys and array indexes that lead to the value, such as `['servers', 0, 'port']`.
+	#   @param path [Array<String, Symbol, Integer>, Tree::MemberNode, Tree::ObjectNode, Tree::ArrayNode, Tree::ScalarNode] A node from the same source, or the keys and array indexes that lead to the value, such as `['servers', 0, 'port']`.
 	#   @param value [Object] The new value, of the types that {SOML.generate} accepts. Write a `Hash` with braces, because without them Ruby passes its members as keyword arguments.
 	#   @return [String] The changed document, in UTF-8.
 	# @overload edit(source, path, delete: true)
 	#   @param source [String] The document, read as {SOML.parse} reads it.
-	#   @param path [Array<String, Symbol, Integer>] The keys and array indexes that lead to the value.
+	#   @param path [Array<String, Symbol, Integer>, Tree::MemberNode, Tree::ObjectNode, Tree::ArrayNode, Tree::ScalarNode] A node from the same source, or the keys and array indexes that lead to the value.
 	#   @param delete [true] Remove the value.
 	#   @return [String] The changed document, in UTF-8.
 	# @raise [ParseError] When the document is not valid, the same as {SOML.parse}.
-	# @raise [ArgumentError] When both a value and `delete: true` are given, or neither.
-	# @raise [TypeError] When `source` is not a string, when `path` is not a non-empty array of keys and array indexes, when it leads through a value that is not an object or an array, or when it has a key where an array is or an index where an object is.
-	# @raise [IndexError] When a value is set at an index past the end of its array, or at an index under a value that does not exist.
-	# @raise [GenerateError] For a value or a key that {SOML.generate} cannot write, and when the change would nest the document more than 100 levels deep.
+	# @raise [ArgumentError] When both a value and `delete: true` are given, or neither, or when the selected node is the root or cannot be found in the source.
+	# @raise [TypeError] When `source` is not a string, when `path` is not a supported node or a non-empty array of keys and indexes, when it leads through a scalar, or when it has a key where an array is or an index where an object is.
+	# @raise [IndexError] When a value is set at an index past the end of its array, or at an index under a missing value.
+	# @raise [GenerateError] For a value or a key that {SOML.generate} cannot write, and when the change would nest more than 100 levels deep.
 	# @raise [EncodingError] When `source` is in an encoding other than UTF-8, binary, or US-ASCII, and does not convert to UTF-8.
 	#
 	# @example