Skip to main content

soml/
document.rs

1use crate::parse::MAX_DEPTH;
2use crate::tree::{self, Comment, Decor, Entries, Entry, Item, Key, Member, Node, Object, Printer};
3use crate::{Error, Value};
4use std::borrow::Cow;
5use std::fmt::{self, Display, Write as _};
6use std::str::FromStr;
7
8/**
9A SOML document as a lossless syntax tree, to read with positions, change, and print.
10
11An unchanged document prints the exact text it was parsed from. A changed one keeps the comments, blank lines, indentation, member order, and the author's spelling of every value outside the change. New values are written in canonical style, and on one line in a container that is on one line.
12
13```rust
14let mut document: soml::Document = "
15## The edge service.
16name: 'api-gateway'
17port: 0x1F90 # The default.
18".parse()?;
19
20document.set(["port"], 8080)?;
21document.set(["replicas"], 3)?;
22document.remove(["name"])?;
23
24assert_eq!(document.to_string(), "
25## The edge service.
26port: 8080 # The default.
27replicas: 3
28");
29# Ok::<(), soml::Error>(())
30```
31
32See [`tree`](crate::tree) for the nodes and how whitespace and comments are kept.
33*/
34#[derive(Debug, Clone, PartialEq)]
35pub struct Document {
36	/**
37	The text before and after a top-level collection written with braces.
38	*/
39	outer: Decor,
40	root: Node,
41	source: String,
42}
43
44/**
45One step of a path into a document: a key of an object, or a position in an array.
46*/
47#[derive(Debug, Clone, Copy, PartialEq, Eq)]
48pub enum PathSegment<'a> {
49	/**
50	A key of an object.
51	*/
52	Key(&'a str),
53	/**
54	A position in an array.
55	*/
56	Index(usize),
57}
58
59impl<'a> From<&'a str> for PathSegment<'a> {
60	fn from(key: &'a str) -> Self {
61		Self::Key(key)
62	}
63}
64
65impl<'a> From<&'a String> for PathSegment<'a> {
66	fn from(key: &'a String) -> Self {
67		Self::Key(key)
68	}
69}
70
71impl From<usize> for PathSegment<'_> {
72	fn from(index: usize) -> Self {
73		Self::Index(index)
74	}
75}
76
77impl Display for PathSegment<'_> {
78	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
79		match self {
80			Self::Key(key) => crate::write::write_key(formatter, key),
81			Self::Index(index) => write!(formatter, "[{index}]"),
82		}
83	}
84}
85
86/**
87The segments of a path given to `set` or `remove`, which must have at least one.
88*/
89fn path_segments<'a>(
90	path: impl IntoIterator<Item = impl Into<PathSegment<'a>>>,
91) -> Result<Vec<PathSegment<'a>>, Error> {
92	let path: Vec<PathSegment<'a>> = path.into_iter().map(Into::into).collect();
93
94	if path.is_empty() {
95		return Err(Error::data(
96			"The path must be a non-empty array of keys and array indexes",
97		));
98	}
99
100	Ok(path)
101}
102
103/**
104The error for a path that does not fit the document, in the words of the JS reference implementation, such as `Cannot edit a.b, because a is not an object or an array`, where `reason` is about the value that holds `path[index]`.
105*/
106#[cold]
107fn path_error(path: &[PathSegment<'_>], index: usize, reason: &str) -> Error {
108	Error::data(format!(
109		"Cannot edit {}, because {} {reason}",
110		describe_path(path),
111		describe_parent(path, index)
112	))
113}
114
115/**
116A path for an error message, as the JS reference implementation writes it, such as `servers[0]."the name"`: each key bare when it can be and otherwise as a JSON string, and each index in brackets. The path may come from user input, so it is cut to 200 characters, and the invisible characters and those that a terminal acts on are written as escapes, such as `\u{202e}`.
117*/
118fn describe_path(path: &[PathSegment<'_>]) -> String {
119	let mut text = String::with_capacity(256);
120	let mut length = 0;
121
122	for (position, segment) in path.iter().enumerate() {
123		let start = text.len();
124		match segment {
125			PathSegment::Key(key) => {
126				if position > 0 {
127					text.push('.');
128				}
129
130				crate::parse::write_described_key(&mut text, key);
131			}
132			PathSegment::Index(index) => {
133				write!(text, "[{index}]").expect("writing to a String does not fail");
134			}
135		}
136		length += text[start..].encode_utf16().count();
137		if length > 200 {
138			break;
139		}
140	}
141
142	let needs_escape = |character: char| {
143		character.is_control()
144			|| matches!(character, '\u{2028}' | '\u{2029}')
145			|| is_format_character(character)
146	};
147	let shortened = crate::abbreviate(&text, 200);
148	let Some((start, _)) = shortened
149		.char_indices()
150		.find(|&(_, character)| needs_escape(character))
151	else {
152		// Note: Not using Cow::into_owned because a borrowed result would copy text that is already owned here.
153		return match shortened {
154			Cow::Owned(text) => text,
155			Cow::Borrowed(_) => text,
156		};
157	};
158	let mut description = String::with_capacity(shortened.len());
159	description.push_str(&shortened[..start]);
160
161	for character in shortened[start..].chars() {
162		// The control, format, line separator, and paragraph separator characters, which a JSON string leaves as they are.
163		if needs_escape(character) {
164			description.extend(character.escape_unicode());
165		} else {
166			description.push(character);
167		}
168	}
169
170	description
171}
172
173/**
174The value that holds `path[index]`, for an error message.
175*/
176fn describe_parent(path: &[PathSegment<'_>], index: usize) -> String {
177	if index == 0 {
178		"the document".to_owned()
179	} else {
180		describe_path(&path[..index])
181	}
182}
183
184/**
185Whether a character is in the Unicode general category Format, as of Unicode 17.0, the version of Node.js 26, which the JS reference implementation escapes in a path.
186*/
187const fn is_format_character(character: char) -> bool {
188	matches!(
189		character,
190		'\u{AD}'
191			| '\u{600}'..='\u{605}'
192			| '\u{61C}'
193			| '\u{6DD}'
194			| '\u{70F}'
195			| '\u{890}'..='\u{891}'
196			| '\u{8E2}'
197			| '\u{180E}'
198			| '\u{200B}'..='\u{200F}'
199			| '\u{202A}'..='\u{202E}'
200			| '\u{2060}'..='\u{2064}'
201			| '\u{2066}'..='\u{206F}'
202			| '\u{FEFF}'
203			| '\u{FFF9}'..='\u{FFFB}'
204			| '\u{110BD}'
205			| '\u{110CD}'
206			| '\u{13430}'..='\u{1343F}'
207			| '\u{1BCA0}'..='\u{1BCA3}'
208			| '\u{1D173}'..='\u{1D17A}'
209			| '\u{E0001}'
210			| '\u{E0020}'..='\u{E007F}'
211	)
212}
213
214/**
215The indentation of the line an item starts on: the spaces and tabs after the last line break before it, or the indentation of its container's line when there is no line break.
216*/
217fn line_indentation(separator: &str, inherited: &str) -> String {
218	last_line_start(separator)
219		.map_or(inherited, |start| tree::indentation_of(&separator[start..]))
220		.to_owned()
221}
222
223/**
224The comment lines and blank lines of leading decor, without the indentation of the item's own line.
225*/
226fn comment_lines(leading: &str) -> &str {
227	last_line_start(leading).map_or("", |start| &leading[..start])
228}
229
230/**
231The indentation of the item's own line in leading decor.
232*/
233fn own_line(leading: &str) -> &str {
234	last_line_start(leading).map_or(leading, |start| &leading[start..])
235}
236
237/**
238The index after the last line feed in decor that is not inside a block comment, which is where the last line starts. A block comment that spans lines is part of the line it ends on.
239*/
240fn last_line_start(decor: &str) -> Option<usize> {
241	// Note: Not using rfind because decor_parts is forward-only.
242	tree::decor_parts(decor)
243		.filter(|(part, _)| *part == tree::DecorPart::LineFeed)
244		.last()
245		.map(|(_, range)| range.end)
246}
247
248/**
249The error for a path segment at `offset` in `path` that does not fit `node`: an index for an object, a key for an array, or any segment for a scalar.
250*/
251#[cold]
252fn segment_error(node: &Node, path: &[PathSegment<'_>], offset: usize) -> Error {
253	let reason = match node {
254		Node::Object(_) => "is an object, so it needs a key, not an index",
255		Node::Array(_) => "is an array, so it needs an index, not a key",
256		Node::Scalar(_) => "is not an object or an array",
257	};
258
259	path_error(path, offset, reason)
260}
261
262/**
263The position of the member or item that a path segment names in a node.
264*/
265fn step(node: &Node, segment: PathSegment<'_>) -> Option<usize> {
266	match (node, segment) {
267		(Node::Object(object), PathSegment::Key(key)) => object.position(key),
268		(Node::Array(array), PathSegment::Index(index)) if index < array.items().len() => {
269			Some(index)
270		}
271		_ => None,
272	}
273}
274
275impl Document {
276	/**
277	Prints into one owned buffer for internal consumers that do not need formatting machinery.
278	*/
279	fn printed_text(&self) -> String {
280		let mut printer = Printer::new(false);
281		printer.output.reserve(self.source.len());
282		printer.document(&self.outer, &self.root);
283		printer.output
284	}
285
286	/**
287	The top-level object or array.
288	*/
289	#[must_use]
290	pub const fn root(&self) -> &Node {
291		&self.root
292	}
293
294	/**
295	The top-level object or array, to change. Changes here can make a document that is not valid, such as one with two members with the same key; [`to_value`](Self::to_value) finds that. [`set`](Self::set) and [`remove`](Self::remove) keep the document valid.
296	*/
297	pub const fn root_mut(&mut self) -> &mut Node {
298		&mut self.root
299	}
300
301	/**
302	The text before a top-level collection written with braces, as its leading decor, and the text after it, as its trailing decor. Both are empty for a top-level object without braces, where that text belongs to its first member and to the object itself.
303	*/
304	#[must_use]
305	pub const fn outer_decor(&self) -> &Decor {
306		&self.outer
307	}
308
309	/**
310	The node at a path. `None` when nothing is there.
311
312	```rust
313	let document: soml::Document = "server: {port: 8080}\nhosts: ['a', 'b']".parse()?;
314
315	let port = document.get(["server", "port"]).and_then(soml::tree::Node::as_scalar);
316	assert_eq!(port.map(soml::tree::Scalar::value), Some(&soml::Value::Int(8080)));
317
318	let host = document.get([soml::PathSegment::from("hosts"), 1.into()]).and_then(soml::tree::Node::as_scalar);
319	assert_eq!(host.and_then(soml::tree::Scalar::raw), Some("'b'"));
320	# Ok::<(), soml::Error>(())
321	```
322	*/
323	#[must_use]
324	pub fn get<'a>(
325		&self,
326		path: impl IntoIterator<Item = impl Into<PathSegment<'a>>>,
327	) -> Option<&Node> {
328		let mut node = &self.root;
329
330		for segment in path {
331			let index = step(node, segment.into())?;
332
333			node = match node {
334				Node::Object(object) => object.members()[index].value(),
335				Node::Array(array) => array.items()[index].value(),
336				Node::Scalar(_) => unreachable!("a path does not step into a scalar"),
337			};
338		}
339
340		Some(node)
341	}
342
343	/**
344	The node at a path, to change. See [`get`](Self::get).
345	*/
346	pub fn get_mut<'a>(
347		&mut self,
348		path: impl IntoIterator<Item = impl Into<PathSegment<'a>>>,
349	) -> Option<&mut Node> {
350		let mut node = &mut self.root;
351
352		for segment in path {
353			let index = step(node, segment.into())?;
354
355			node = match node {
356				Node::Object(object) => object.members_mut()[index].value_mut(),
357				Node::Array(array) => array.items_mut()[index].value_mut(),
358				Node::Scalar(_) => unreachable!("a path does not step into a scalar"),
359			};
360		}
361
362		Some(node)
363	}
364
365	/**
366	Sets the value at a path, replacing what is there or adding it.
367
368	- An existing value is replaced, and the comments around it stay. A value that replaces a block string on the line after its key goes on the key's line, as the formatter writes it, unless a comment comes between them.
369	- A new member goes after the last member of its object, and after the comments that member owns (see [`remove`](Self::remove)), so `[1, 2 /* note */]` with a new item `3` becomes `[1, 2 /* note */, 3]`. When something follows that member on its line, such as the closing bracket, the new one goes on that line, after a comma. Otherwise, it goes on a line of its own, with the indentation of that member and no comma, because a line break separates it.
370	- A missing parent object is created with braces.
371	- An index equal to an array's length appends. The keys after it in the path are new objects in the new item, so setting `["b", 0, "c"]` to `1` in `b: []` adds the item `{c: 1}`.
372	- A new value is written in canonical style, on lines of its own. In a container that stays on one line, it is written on one line, so `[1, 2]` with a new item `{a: 3}` becomes `[1, 2, {a: 3}]`. A container stays on one line when its brackets are on one line and something other than spaces and tabs is between them, as in `[1, 2]` and `[/* note */]`, or when it is inside a container that stays on one line.
373	- In a container with no entries, a new entry goes on a line of its own, so `deps: {}` gets its first member on a line of its own, because the formatter writes every empty container as `{}`. In a container that stays on one line, it goes before the closing bracket instead, so `[/* note */]` becomes `[/* note */ 1]`, and `a: [1, []]` becomes `a: [1, [2]]`.
374
375	A change always gives a valid document with the expected value, and it keeps every comment except those inside a value it replaces and those that a member or an item it removes owns. These are the spec's editing rules, as in the JavaScript reference, so a change to a formatted document gives a formatted document, with the same text as there. A comment on a line of its own before a closing bracket belongs to no member or item, so a new entry goes before it, and it stays when the last entry is removed.
376
377	# Errors
378
379	Returns an error of kind [`ErrorKind::Data`](crate::ErrorKind::Data) when the path is empty, when it goes through a scalar, when it uses a key on an array or an index on an object, when an index is past the end of its array, so that the item before the new one would be missing, or when an index is below a value that does not exist, because a missing value is made as an object. Returns an error of kind [`ErrorKind::Write`](crate::ErrorKind::Write) when the value holds something SOML cannot represent, and when the result would not be a valid document, such as one nested more than 100 levels deep. Such an error has no position, because the place it is about is not in the document. The document is unchanged after an error.
380
381	Each change reads the result back to check it, so it takes time in proportion to the size of the document.
382	*/
383	pub fn set<'a>(
384		&mut self,
385		path: impl IntoIterator<Item = impl Into<PathSegment<'a>>>,
386		value: impl Into<Value>,
387	) -> Result<(), Error> {
388		let path = path_segments(path)?;
389
390		// Every key the change may write is checked up front, also one it nests in a new object, which no `Member::new` checks, so a key that cannot be written always gives the same error.
391		for segment in &path {
392			if let PathSegment::Key(key) = segment {
393				crate::write::check_representable(key, "key")?;
394			}
395		}
396
397		let value = tree::checked(value.into())?;
398		let before = self.root.clone();
399		// A document indented like the code around it, as in `\t{}`, gets new lines at the indentation of its top-level collection's line. The outer decor is empty for a top-level object without braces.
400		let indentation = tree::indentation_of(own_line(&self.outer.leading));
401		let result = set_in(&mut self.root, &path, &path, value, indentation, false);
402
403		// Every rule of the spec is checked by reading the result back, such as the nesting limit at the place the value goes, and a key that cannot be written. A failed change leaves the document as it was. The error has no position, because its position is in the text the change would have made, which nobody sees.
404		if let Err(error) = result.and_then(|()| {
405			crate::from_str::<serde_core::de::IgnoredAny>(&self.printed_text())
406				.map(|_| ())
407				.map_err(|error| Error::write(error.message()))
408		}) {
409			self.root = before;
410			return Err(error);
411		}
412
413		Ok(())
414	}
415
416	/**
417	Removes the member or item at a path, with the comments it owns and its comma. A member or an item owns the comments that the formatter keeps with it: the comments after it on its line, before its comma, or after its comma when nothing else follows on that line, and the block comments before it on its line, back to the comma or bracket before it. So in `[1 /* a */, /* b */ 2 /* c */]`, `1` owns `/* a */`, and `2` owns `/* b */` and `/* c */`. A comment on a line of its own belongs to no member or item, so the comment lines above and below a removed one stay.
418
419	The other entries keep their commas, except that when the removed entries are the last ones and the last of them has no comma after it, the comma directly before them goes too, when only spaces, tabs, and the comments the first of them owns are between, so `[1, 2]` and `[1, /* note */ 2]` become `[1]`, and `[\n\t1,\n\t2\n]` becomes `[\n\t1,\n]`. A blank line the removal leaves next to another blank line, or directly inside a bracket or at the start or end of the document, goes too, the one before it when there is a choice, so a formatted document stays formatted. This takes at most one blank line, so other blank lines stay as written.
420
421	Removing every entry of a container closes it up to `[]` or `{}`, unless a comment is left inside. Removing the only member of a top-level object without braces leaves `{}` in its place, because a document cannot be empty, and members set later go inside the braces. The `{}` keeps the comments that the member owned, so `a: 1 # note` without `a` becomes `{} # note`.
422
423	These are the spec's editing rules, as in the JavaScript reference. See [`set`](Self::set) for which layouts are kept exactly.
424
425	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, and anything below them. So removing the same path twice is safe. Returns whether something was removed, so a caller who expected a value can notice that it was missing.
426
427	# Errors
428
429	Returns an error of kind [`ErrorKind::Data`](crate::ErrorKind::Data) when the path is empty, when it goes through a scalar, or when it uses a key on an array or an index on an object, before it reaches a value that does not exist. The document is unchanged after an error.
430	*/
431	pub fn remove<'a>(
432		&mut self,
433		path: impl IntoIterator<Item = impl Into<PathSegment<'a>>>,
434	) -> Result<bool, Error> {
435		let path = path_segments(path)?;
436
437		// A top-level object without braces needs a member, so when its only member goes, `{}` takes its place, with its decor, and members set later go inside the braces, as in the JavaScript reference.
438		if let Node::Object(object) = &mut self.root
439			&& !object.is_braced()
440			&& let [member] = object.members()
441			&& [PathSegment::Key(member.key().value())] == path.as_slice()
442		{
443			let mut member = object.members_mut().remove(0);
444			let mut decor = std::mem::take(member.decor_mut());
445			decor.trailing.push_str(object.closing_decor());
446			self.outer = decor;
447			self.root = Node::Object(Object::default());
448			return Ok(true);
449		}
450
451		// `remove_in` fails only before it changes anything, so unlike `set`, this keeps no copy to restore.
452		remove_in(&mut self.root, &path, &path)
453	}
454
455	/**
456	The comments, in order, with their positions in the document's current text, which is the parsed text when nothing changed.
457
458	After a change, these spans do not fit [`position`](Self::position), which uses the parsed text. Print the document and parse it again to get both for the new text.
459	*/
460	#[must_use]
461	pub fn comments(&self) -> Vec<Comment> {
462		let mut printer = Printer::new(true);
463		printer.output.reserve(self.source.len());
464
465		printer.document(&self.outer, &self.root);
466		printer.comments.unwrap_or_default()
467	}
468
469	/**
470	The line and column of a byte offset in the text the document was parsed from, as for a node's span.
471
472	```rust
473	let document: soml::Document = "name: 'a'\nport: 80".parse()?;
474	let span = document.get(["port"]).and_then(soml::tree::Node::span).unwrap();
475
476	assert_eq!(document.position(span.start), soml::LineColumn { line: 2, column: 7 });
477	# Ok::<(), soml::Error>(())
478	```
479	*/
480	#[must_use]
481	pub fn position(&self, offset: usize) -> crate::LineColumn {
482		crate::LineColumn::locate(&self.source, offset)
483	}
484
485	/**
486	The document in the layout of the spec's formatter, which changes layout and nothing else.
487
488	It keeps the comments where they are, the member order, the spelling of every key and value, block strings, and a top level with or without braces. It writes one tab of indentation per level, every member and item on its own line, no commas, at most one blank line in a row, no trailing spaces or tabs, and one line feed at the end. An object or an array whose brackets are on one line stays on one line, with a comma and a space between its members or items. To give it one member or item per line, put a line break anywhere inside it. Formatting a formatted document gives the same text.
489
490	```rust
491	let document: soml::Document = "# Server\nserver: {host: 'a',   port: 0x50,} # Main.\n\n\nlist: [1,\n2]".parse()?;
492
493	assert_eq!(document.format(), "# Server\nserver: {host: 'a', port: 0x50} # Main.\n\nlist: [\n\t1\n\t2\n]\n");
494	# Ok::<(), soml::Error>(())
495	```
496
497	The spec's formatter rules are normative, so every conforming formatter gives the same text. The [`tree`](crate::tree) module lists them in detail.
498	*/
499	#[must_use]
500	pub fn format(&self) -> String {
501		tree::format::document(&self.outer, &self.root, self.source.len())
502	}
503
504	/**
505	The value of the document, with every check of the spec, such as for duplicate keys, which a change through [`root_mut`](Self::root_mut) can make.
506
507	It prints the document and reads it back, so an error's position refers to the printed text, which is the parsed text when nothing changed.
508
509	# Errors
510
511	Returns an error when the document, as changed, is not valid.
512	*/
513	pub fn to_value(&self) -> Result<Value, Error> {
514		self.printed_text().parse()
515	}
516}
517
518/**
519Whether a container stays on one line when a change adds or replaces a value in it: its brackets are on one line, and something other than spaces and tabs is between them, which the formatter keeps on one line. An empty `[]` or `{}` says nothing about layout, because the formatter writes every empty container that way. A top-level object without braces never does.
520*/
521fn stays_on_one_line(node: &Node) -> bool {
522	let has_content = |entry_count: usize, closing: &str| {
523		entry_count > 0 || !closing.trim_matches([' ', '\t']).is_empty()
524	};
525
526	let is_braced_with_content = match node {
527		Node::Object(object) => {
528			object.is_braced() && has_content(object.members().len(), object.closing_decor())
529		}
530		Node::Array(array) => has_content(array.items().len(), array.closing_decor()),
531		Node::Scalar(_) => false,
532	};
533
534	is_braced_with_content && node.is_on_one_line()
535}
536
537/**
538`value` inside new objects for the keys of `path` from `start` on, with braces, as canonical form writes a missing parent. An index there names an item of an array that does not exist yet, so it is an error, which names the last such index, as in the JavaScript reference.
539*/
540fn nest(path: &[PathSegment<'_>], start: usize, value: Value) -> Result<Value, Error> {
541	// The index error comes before the depth check, so that it names the index however long the path is, and before any object is made, because dropping a deep value could overflow the stack.
542	if let Some((position, index)) =
543		path.iter()
544			.enumerate()
545			.skip(start)
546			.rev()
547			.find_map(|(position, segment)| match segment {
548				PathSegment::Index(index) => Some((position, index)),
549				PathSegment::Key(_) => None,
550			}) {
551		return Err(path_error(
552			path,
553			position,
554			&format!("does not exist, so it has no index {index}"),
555		));
556	}
557
558	// The value goes inside one collection for each segment of the path, so a path longer than the nesting limit can only give a document that no reader accepts, and building its objects one inside the other could overflow the stack.
559	if path.len() > MAX_DEPTH {
560		return Err(Error::write(format!(
561			"The document is nested more than {MAX_DEPTH} levels deep"
562		)));
563	}
564
565	Ok(path[start..]
566		.iter()
567		.rev()
568		.fold(value, |value, segment| match segment {
569			PathSegment::Key(key) => {
570				Value::Object(crate::Object::from([((*key).to_owned(), value)]))
571			}
572			PathSegment::Index(_) => unreachable!("an index is an error above"),
573		}))
574}
575
576/**
577Sets `value` at `path` inside `node`, whose line has `indentation`. `is_inside_one_line` is whether `node` is inside a container that stays on one line, which keeps it on one line too. `full_path` is for error messages.
578*/
579fn set_in(
580	node: &mut Node,
581	path: &[PathSegment<'_>],
582	full_path: &[PathSegment<'_>],
583	value: Value,
584	indentation: &str,
585	is_inside_one_line: bool,
586) -> Result<(), Error> {
587	// The end of the path, where the value replaces `node`. It is on one line inside a container that stays on one line.
588	if path.is_empty() {
589		*node = Node::laid_out(value, (!is_inside_one_line).then_some(indentation));
590		return Ok(());
591	}
592
593	let is_one_line = is_inside_one_line || stays_on_one_line(node);
594	// Where `path` starts in `full_path`.
595	let offset = full_path.len() - path.len();
596
597	match (node, path[0]) {
598		(Node::Object(object), PathSegment::Key(key)) => set_in_object(
599			object,
600			key,
601			path,
602			full_path,
603			value,
604			indentation,
605			is_one_line,
606		),
607		(Node::Array(array), PathSegment::Index(index)) => {
608			let count = array.items().len();
609
610			if index > count {
611				let owner = if offset == 0 {
612					"the document".to_owned()
613				} else {
614					format!("the array at {}", describe_path(&full_path[..offset]))
615				};
616				let items = if count == 1 {
617					"1 item".to_owned()
618				} else {
619					format!("{count} items")
620				};
621				return Err(Error::data(format!(
622					"Cannot edit {}, because {owner} has {items}. Add an item at index {count}",
623					describe_path(full_path)
624				)));
625			}
626
627			// An index equal to the length appends, and the rest of the path is new objects in the new item, as in the JavaScript reference.
628			if index == count {
629				let value = nest(full_path, offset + 1, value)?;
630				// The null is a placeholder: `insert` puts the new value in its place, laid out for its line.
631				let item = Item::new(Value::Null).expect("null can be written");
632				array
633					.entries_mut()
634					.append(item, value, indentation, is_one_line);
635				return Ok(());
636			}
637
638			let item_indentation = entry_indentation(array.items(), index, false, indentation);
639
640			set_in(
641				array.items_mut()[index].value_mut(),
642				&path[1..],
643				full_path,
644				value,
645				&item_indentation,
646				is_one_line,
647			)
648		}
649		(node, _) => Err(segment_error(node, full_path, offset)),
650	}
651}
652
653/**
654Sets `value` at `path` inside `object`, where `key` is the first segment of `path`.
655*/
656fn set_in_object(
657	object: &mut Object,
658	key: &str,
659	path: &[PathSegment<'_>],
660	full_path: &[PathSegment<'_>],
661	value: Value,
662	indentation: &str,
663	is_one_line: bool,
664) -> Result<(), Error> {
665	let offset = full_path.len() - path.len();
666
667	if let Some(index) = object.position(key) {
668		let member = &mut object.members_mut()[index];
669
670		// A block string begins on the line after its key, and the new value is never one, so it goes on the key's line, as the formatter writes it, when only whitespace is between them.
671		if path.len() == 1
672			&& matches!(member.value(), Node::Scalar(scalar) if scalar.is_block_string())
673			&& member
674				.after_colon
675				.bytes()
676				.all(|byte| matches!(byte, b' ' | b'\t' | b'\n'))
677		{
678			member.after_colon = Cow::Borrowed(" ");
679		}
680
681		// A value on the line after its key, because a comment comes between them, is indented like its own line.
682		let entry_indentation =
683			entry_indentation(object.members(), index, !object.is_braced(), indentation);
684		let member_indentation =
685			line_indentation(&object.members()[index].after_colon, &entry_indentation);
686
687		return set_in(
688			object.members_mut()[index].value_mut(),
689			&path[1..],
690			full_path,
691			value,
692			&member_indentation,
693			is_one_line,
694		);
695	}
696
697	let value = nest(full_path, offset + 1, value)?;
698	// The null is a placeholder, as for a new item.
699	let member = Member::new(Key::new(key), Value::Null)?;
700	object
701		.entries_mut()
702		.append(member, value, indentation, is_one_line);
703	Ok(())
704}
705
706/**
707The indentation of the line an entry starts on, which may be the line of an entry before it. `starts_line` is whether the first entry starts a line, which is true at the top of a document.
708*/
709fn entry_indentation<T: Entry>(
710	entries: &[T],
711	index: usize,
712	starts_line: bool,
713	indentation: &str,
714) -> String {
715	for position in (0..=index).rev() {
716		let previous_trailing = match position.checked_sub(1) {
717			Some(previous) => entries[previous].separator().decor.trailing.as_str(),
718			None if starts_line => "\n",
719			None => "",
720		};
721		let leading = &entries[position].separator().decor.leading;
722		let decor = if previous_trailing.is_empty() {
723			Cow::Borrowed(leading.as_str())
724		} else if leading.is_empty() {
725			Cow::Borrowed(previous_trailing)
726		} else {
727			Cow::Owned([previous_trailing, leading].concat())
728		};
729
730		if let Some(start) = last_line_start(&decor) {
731			return tree::indentation_of(&decor[start..]).to_owned();
732		}
733
734		// Without a line feed in the decor, the entry is on the line where the entry before it ends.
735		if let Some(indentation) = position
736			.checked_sub(1)
737			.and_then(|previous| last_line_indentation(&entries[previous]))
738		{
739			return indentation;
740		}
741	}
742
743	indentation.to_owned()
744}
745
746/**
747The indentation of the last line of an entry that spans lines, as an object or a block string can, or `None` for an entry on one line. A line feed in a block comment does not start a line, as in decor.
748*/
749fn last_line_indentation<T: Entry>(entry: &T) -> Option<String> {
750	if entry.is_on_one_line() {
751		return None;
752	}
753	let mut printer = Printer::new(true);
754	entry.print(&mut printer);
755	let text = printer.output;
756	// The comments are in text order, so one walk back through them finds each comment a line feed may be in.
757	let mut comments = printer.comments.unwrap_or_default().into_iter().rev();
758	let mut comment = comments.next();
759	let mut end = text.len();
760
761	let line_feed = loop {
762		let line_feed = text[..end].rfind('\n')?;
763
764		while comment
765			.as_ref()
766			.is_some_and(|comment| comment.span.start > line_feed)
767		{
768			comment = comments.next();
769		}
770
771		match &comment {
772			Some(comment) if comment.span.contains(&line_feed) => end = comment.span.start,
773			_ => break line_feed,
774		}
775	};
776
777	Some(tree::indentation_of(&text[line_feed + 1..]).to_owned())
778}
779
780/**
781Ends the line of the token before a removed entry that ended it: the last kept entry, whose trailing decor holds the line feed that ends its line, as the parser gives it, or an opening bracket, whose line feed starts the decor after it.
782*/
783fn end_line<T: Entry>(kept: &mut [T], moved: &mut String) {
784	match kept.last_mut() {
785		Some(last) => last.separator_mut().decor.trailing.push('\n'),
786		None => moved.push('\n'),
787	}
788}
789
790impl<T: Entry> Entries<'_, T> {
791	/**
792	Moves the line feed that ends the last entry's line from the closing decor to the entry's trailing decor, where the parser puts it. An entry pushed through the node API has no decor, so that line feed can be in the closing decor, and then the entry would be taken as followed by something on its line, and the comment lines after it as its own.
793	*/
794	fn end_last_line(&mut self) {
795		// Note: Not using String::drain because it regressed complete append benchmarks for some container layouts.
796		let Some(last) = self.list.last_mut() else {
797			return;
798		};
799
800		if last.separator().decor.trailing.ends_with('\n') {
801			return;
802		}
803
804		if let Some(line_feed) = tree::first_line_end(self.closing) {
805			last.separator_mut()
806				.decor
807				.trailing
808				.push_str(&self.closing[..line_feed]);
809			self.closing.replace_range(..line_feed, "");
810		}
811	}
812
813	/**
814	Appends an entry with a value, as in the JavaScript reference. When something follows the entry before it on its line, such as the closing bracket, the new entry goes on that line after a comma, in the comma style of that entry. Otherwise, it goes on a line of its own with no comma, as a line break separates it, and so does an entry in an empty container, unless the container stays on one line. `indentation` is that of the container's line, and `is_one_line` is whether the container stays on one line, which keeps the new value on one line too.
815	*/
816	fn append(mut self, mut entry: T, value: Value, indentation: &str, is_one_line: bool) {
817		self.end_last_line();
818		let Self {
819			list: entries,
820			closing,
821			is_braced,
822		} = self;
823		let index = entries.len();
824		let (leading, trailing, has_comma, line) = match index.checked_sub(1) {
825			Some(previous) => {
826				let line = entry_indentation(entries, previous, !is_braced, indentation);
827				let separator = entries[previous].separator();
828				let decor = &separator.decor;
829
830				if is_braced && !decor.trailing.ends_with('\n') {
831					// Something follows the entry before it on its line, such as the next entry or the closing bracket, so the new entry goes on that line, after a comma, in the comma style of that entry, as in the JavaScript reference. That line is the one the entry before it ends on.
832					let line = last_line_indentation(&entries[previous]).unwrap_or(line);
833					let has_comma = separator.has_comma;
834
835					// The comments after the last entry on its line, before the closing bracket, are its own, so the new entry goes after them, and they go before the comma the entry gets.
836					if !has_comma {
837						let owned = closing.trim_end_matches([' ', '\t']).len();
838						entries[previous]
839							.separator_mut()
840							.before_comma
841							.push_str(&closing[..owned]);
842						closing.replace_range(..owned, "");
843					}
844
845					(" ".to_owned(), String::new(), has_comma, line)
846				} else if decor.trailing.ends_with('\n') {
847					// On a line of its own, a line break separates the entry, so it needs no comma, whatever the other entries have.
848					(line.clone(), "\n".to_owned(), false, line)
849				} else {
850					// The last member of a document without a final line feed. The line feed that now ends its line belongs to it, as its trailing decor, so a later removal of either member handles it. Spaces and tabs at the end of a line mean nothing, except in a line comment.
851					let trailing = &mut entries[previous].separator_mut().decor.trailing;
852
853					if !tree::ends_in_line_comment(trailing) {
854						trailing.truncate(trailing.trim_end_matches([' ', '\t']).len());
855					}
856
857					trailing.push('\n');
858					(line.clone(), String::new(), false, line)
859				}
860			}
861			// Only a change through the node API can empty a top-level object without braces, because `remove` puts `{}` in place of its last member.
862			None if !is_braced => (String::new(), "\n".to_owned(), false, String::new()),
863			// A container that stays on one line keeps the new entry on that line, before the closing bracket, so `[/* note */]` becomes `[/* note */ 1]`, and `[1, []]` becomes `[1, [2]]`.
864			None if is_one_line => {
865				let before = closing.trim_end_matches([' ', '\t']);
866				let leading = if before.is_empty() {
867					String::new()
868				} else {
869					[before, " "].concat()
870				};
871
872				closing.clear();
873				(leading, String::new(), false, indentation.to_owned())
874			}
875			None => {
876				let line = [indentation, "\t"].concat();
877
878				// A comment in the empty container stays, before the new entry. The entry's own line takes `line`, the indentation its value is written for, whatever the closing bracket's line had.
879				let leading = if tree::has_line_feed(closing)
880					&& own_line(closing).trim_matches([' ', '\t']).is_empty()
881				{
882					[comment_lines(closing), &line].concat()
883				} else {
884					[closing.trim_end_matches([' ', '\t']), "\n", &line].concat()
885				};
886
887				*closing = indentation.to_owned();
888				(leading, "\n".to_owned(), false, line)
889			}
890		};
891
892		*entry.node_mut() = Node::laid_out(value, (!is_one_line).then_some(line.as_str()));
893		let separator = entry.separator_mut();
894		separator.decor = tree::Decor { leading, trailing };
895		separator.has_comma = has_comma;
896		entries.push(entry);
897
898		// The entry and the one before it get the comma they need when they share a line with the next one, as the printer writes it, so a later change that puts a line break after them keeps it, as parsing the printed text would.
899		for position in index.saturating_sub(1)..=index {
900			if tree::shares_line_with_next(entries, position) {
901				entries[position].separator_mut().has_comma = true;
902			}
903		}
904	}
905}
906
907/**
908Removes what is at `path` inside `node`.
909*/
910fn remove_in(
911	node: &mut Node,
912	path: &[PathSegment<'_>],
913	full_path: &[PathSegment<'_>],
914) -> Result<bool, Error> {
915	// Where `path` starts in `full_path`.
916	let offset = full_path.len() - path.len();
917
918	// The path is never empty here: `path_segments` checks it, and a recursive call gets at least one segment.
919	match (node, path[0]) {
920		(Node::Object(object), PathSegment::Key(key)) => {
921			// Removing a member that is not there changes nothing, and so does removing something below it.
922			let Some(index) = object.position(key) else {
923				return Ok(false);
924			};
925
926			if path.len() > 1 {
927				return remove_in(
928					object.members_mut()[index].value_mut(),
929					&path[1..],
930					full_path,
931				);
932			}
933
934			Ok(object.entries_mut().remove(index))
935		}
936		(Node::Array(array), PathSegment::Index(index)) => {
937			// 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.
938			if index >= array.items().len() {
939				return Ok(false);
940			}
941
942			if path.len() > 1 {
943				return remove_in(array.items_mut()[index].value_mut(), &path[1..], full_path);
944			}
945
946			Ok(array.entries_mut().remove(index))
947		}
948		(node, _) => Err(segment_error(node, full_path, offset)),
949	}
950}
951
952impl<T: Entry> Entries<'_, T> {
953	/**
954	Removes one entry at a known index. A removed entry takes its own comments and comma; comment lines above it move to the next entry or the closing decor. Removing the last entry also takes the comma before it when only spaces and owned comments separate them.
955	*/
956	fn remove(mut self, index: usize) -> bool {
957		self.end_last_line();
958		let Self {
959			list: entries,
960			closing,
961			is_braced,
962		} = self;
963		// Note: Not using Vec::splice because removing a single entry from small collections benchmarks faster with remove.
964		let entry = entries.remove(index);
965		let separator = entry.separator();
966		let decor = &separator.decor;
967		let leading_has_line_feed = tree::has_line_feed(&decor.leading);
968		let trailing_has_line_feed = tree::has_line_feed(&decor.trailing);
969		let (previous, following) = entries.split_at_mut(index);
970		// The comment lines above the removed entry move once, without rebuilding the entries vector.
971		let mut moved = comment_lines(&decor.leading).to_owned();
972		// Where the removed entry was, after its comment lines.
973		let removed_at = moved.len();
974		// The text before the removed entry on its line, which the next entry takes as it takes its place.
975		let mut indentation = Some(tree::indentation_of(own_line(&decor.leading)));
976		// Whether the removed entry starts a line, whatever its own leading decor is.
977		let starts_line = !is_braced
978			|| previous
979				.last()
980				.is_some_and(|previous| tree::has_line_feed(&previous.separator().decor.trailing));
981		// Whether the removed entry ended the line of the token before it.
982		let ended_line = !starts_line && !leading_has_line_feed && trailing_has_line_feed;
983		// Whether the last entry was removed without a comma after it.
984		let is_last_removed_without_comma = following.is_empty() && !separator.has_comma;
985		// Only spaces, tabs, and owned comments may separate the removed entry from the preceding comma.
986		let is_comma_before_removed_spaced = previous
987			.last()
988			.is_some_and(|previous| previous.separator().decor.trailing.is_empty())
989			&& !leading_has_line_feed;
990		// Whether the closing decor is on the line of the last entry, which was removed, and owns its comments.
991		let is_closing_owned = is_last_removed_without_comma && !trailing_has_line_feed;
992
993		// What comes after an entry removed with the end of its line starts a line of its own.
994		if trailing_has_line_feed {
995			indentation = None;
996		}
997		// What comes after a removed entry that ended the line of the token before it stays on a line of its own.
998		if ended_line {
999			end_line(previous, &mut moved);
1000			indentation = None;
1001		}
1002
1003		if let Some(next) = following.first_mut() {
1004			let leading = &next.separator().decor.leading;
1005			let own = own_line(leading);
1006			// The next item takes the removed one's place on its line, with its own comments before it on that line.
1007			let own = match indentation {
1008				Some(indentation) => [indentation, own.trim_start_matches([' ', '\t'])].concat(),
1009				None => own.to_owned(),
1010			};
1011			let leading = [moved.as_str(), comment_lines(leading), &own].concat();
1012			next.separator_mut().decor.leading = without_extra_blank_lines(
1013				&leading,
1014				removed_at,
1015				Surroundings::before_entry(previous.last(), is_braced),
1016			);
1017		} else {
1018			// The comments after the last entry on its line, before the closing bracket, are its own, so they go with it.
1019			if is_closing_owned {
1020				closing.clear();
1021			}
1022			// A comment before the closing bracket on the removed entry's line takes its place. It belongs to no entry, so it stays.
1023			if let Some(indentation) = indentation
1024				&& !tree::has_line_feed(closing)
1025				&& !closing.trim_matches([' ', '\t']).is_empty()
1026			{
1027				*closing = [indentation, closing.trim_start_matches([' ', '\t'])].concat();
1028			}
1029			if !moved.is_empty() {
1030				moved.push_str(closing);
1031				*closing = without_extra_blank_lines(
1032					&moved,
1033					removed_at,
1034					Surroundings::before_closing(previous.last(), is_braced),
1035				);
1036			}
1037		}
1038
1039		if is_last_removed_without_comma
1040			&& is_comma_before_removed_spaced
1041			&& let Some(last) = entries.last_mut()
1042		{
1043			let separator = last.separator_mut();
1044			separator.has_comma = false;
1045
1046			// Without its comma, the text between the value and where the comma was is after the value, so it is split as the parser splits the text after a value: up to its first line feed for the entry, and the rest for the container. The spaces and tabs directly before the comma go with it, as in the JavaScript reference.
1047			if !separator.before_comma.is_empty() {
1048				let mut text = std::mem::take(&mut separator.before_comma);
1049				text.truncate(text.trim_end_matches([' ', '\t']).len());
1050				text.push_str(&separator.decor.trailing);
1051				// Without a line feed, all of it is before the closing bracket, on the entry's line, which the parser gives to the container.
1052				let line_end = tree::first_line_end(&text).unwrap_or(0);
1053				separator.decor.trailing = text[..line_end].to_owned();
1054				closing.insert_str(0, &text[line_end..]);
1055			}
1056		}
1057
1058		// A container that the removal emptied closes up to `[]` or `{}` when no comment remains.
1059		if entries.is_empty() && closing.trim_matches([' ', '\t', '\n']).is_empty() {
1060			closing.clear();
1061		}
1062		true
1063	}
1064}
1065
1066/**
1067Where decor that a removal joined is in its container or document.
1068*/
1069#[derive(Clone, Copy)]
1070struct Surroundings {
1071	/**
1072	Whether the decor starts a line. It does after an entry whose line it ended, and at the start of a document. The decor after an opening bracket starts on the bracket's line.
1073	*/
1074	starts_line: bool,
1075	/**
1076	Whether nothing comes before it.
1077	*/
1078	at_start: bool,
1079	/**
1080	Whether nothing comes after it.
1081	*/
1082	at_end: bool,
1083}
1084
1085impl Surroundings {
1086	/**
1087	The decor before an entry, which comes after `previous`, or first when there is none.
1088	*/
1089	fn before_entry<T: Entry>(previous: Option<&T>, is_braced: bool) -> Self {
1090		Self {
1091			starts_line: previous.map_or(!is_braced, |previous| {
1092				tree::has_line_feed(&previous.separator().decor.trailing)
1093			}),
1094			at_start: previous.is_none(),
1095			at_end: false,
1096		}
1097	}
1098
1099	/**
1100	The decor before a closing bracket or the end of a document, which comes after `previous`, or first when there is none.
1101	*/
1102	fn before_closing<T: Entry>(previous: Option<&T>, is_braced: bool) -> Self {
1103		Self {
1104			at_end: true,
1105			..Self::before_entry(previous, is_braced)
1106		}
1107	}
1108}
1109
1110/**
1111Decor that a removal joined, as in the JavaScript reference: the removal takes one blank line that it would leave next to another one, or directly after an opening bracket or the start of a document, or directly before a closing bracket or the end of a document. Only a run of blank lines at `removed_at`, where the entry was removed, changes, so every other blank line stays as written. A line with a comment is not blank.
1112*/
1113fn without_extra_blank_lines(decor: &str, removed_at: usize, surroundings: Surroundings) -> String {
1114	let Surroundings {
1115		starts_line,
1116		at_start,
1117		at_end,
1118	} = surroundings;
1119	let mut output = String::with_capacity(decor.len());
1120	// The run of blank lines since the last line that is not blank, as a range of `decor`.
1121	let mut blank_run: Option<std::ops::Range<usize>> = None;
1122	let mut has_content = !at_start;
1123	let mut line_start = 0;
1124
1125	let end_run =
1126		|output: &mut String, run: std::ops::Range<usize>, is_at_start: bool, is_at_end: bool| {
1127			// An entry removed at `run.start` or `run.end` counts as in the run.
1128			if removed_at < run.start || removed_at > run.end {
1129				output.push_str(&decor[run]);
1130				return;
1131			}
1132			let mut before = run.start..removed_at;
1133			let mut after = removed_at..run.end;
1134
1135			// Both ranges start and end at line starts, so each branch removes one whole blank line: the last one before the removed entries, or else the first one after them.
1136			if !before.is_empty() && (!after.is_empty() || is_at_end) {
1137				before.end = decor[before.start..before.end - 1]
1138					.rfind('\n')
1139					.map_or(before.start, |index| before.start + index + 1);
1140			} else if !after.is_empty() && is_at_start {
1141				after.start = decor[after.clone()]
1142					.find('\n')
1143					.map_or(after.end, |index| after.start + index + 1);
1144			}
1145
1146			output.push_str(&decor[before]);
1147			output.push_str(&decor[after]);
1148		};
1149
1150	for (part, range) in tree::decor_parts(decor) {
1151		if part != tree::DecorPart::LineFeed {
1152			continue;
1153		}
1154
1155		let line = line_start..range.end;
1156		let is_empty = decor[line.clone()]
1157			.bytes()
1158			.all(|byte| matches!(byte, b' ' | b'\t' | b'\n'));
1159		// When the decor does not start a line, its first line feed ends the line before it, such as the line of an opening bracket.
1160		let ends_earlier_line = line_start == 0 && !starts_line;
1161		line_start = range.end;
1162
1163		if is_empty && !ends_earlier_line {
1164			blank_run = Some(blank_run.map_or(line.clone(), |run| run.start..line.end));
1165			continue;
1166		}
1167
1168		if let Some(run) = blank_run.take() {
1169			end_run(&mut output, run, !has_content, false);
1170		}
1171
1172		// A comment on the line before, such as the line of an opening bracket, is not content inside the container.
1173		has_content |= !is_empty && !ends_earlier_line;
1174		output.push_str(&decor[line]);
1175	}
1176
1177	let rest = &decor[line_start..];
1178
1179	if let Some(run) = blank_run {
1180		let is_at_end = at_end && rest.bytes().all(|byte| byte == b' ' || byte == b'\t');
1181		end_run(&mut output, run, !has_content, is_at_end);
1182	}
1183
1184	output.push_str(rest);
1185	output
1186}
1187
1188impl FromStr for Document {
1189	type Err = Error;
1190
1191	/**
1192	Parses a document, with the same checks and errors as [`from_str`](crate::from_str).
1193	*/
1194	fn from_str(text: &str) -> Result<Self, Error> {
1195		let parts = tree::build(text, crate::parse::parse(text)?);
1196
1197		Ok(Self {
1198			outer: parts.outer,
1199			root: parts.root,
1200			source: text.to_owned(),
1201		})
1202	}
1203}
1204
1205/**
1206Prints the document: the exact text it was parsed from, with any changes.
1207*/
1208impl Display for Document {
1209	fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
1210		formatter.write_str(&self.printed_text())
1211	}
1212}