yaml_edit/lib.rs
1#![deny(missing_docs)]
2#![allow(clippy::type_complexity)]
3#![warn(clippy::unnecessary_to_owned)]
4#![warn(clippy::redundant_clone)]
5#![warn(clippy::inefficient_to_string)]
6#![warn(clippy::manual_string_new)]
7#![doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/README.md"))]
8
9//! A lossless YAML parser and editor.
10//!
11//! This library provides a lossless parser for YAML files, preserving
12//! all whitespace, comments, and formatting. It is based on the [rowan] library.
13//!
14//! # Mutability Model
15//!
16//! **Important:** This library uses interior mutability through the rowan library.
17//! This means methods taking `&self` can still modify the underlying syntax tree.
18//!
19//! ## What This Means
20//!
21//! - Types like [`Mapping`], [`Sequence`], and [`Document`] can mutate even from `&self`
22//! - Changes are immediately visible to all holders of the syntax tree
23//! - You don't need to mark variables as `mut` to call mutation methods
24//!
25//! ## Example
26//!
27//! ```rust
28//! use yaml_edit::Document;
29//! use std::str::FromStr;
30//!
31//! let doc = Document::from_str("name: Alice").unwrap(); // Note: not `mut`
32//! let mapping = doc.as_mapping().unwrap(); // Note: not `mut`
33//!
34//! // Yet we can still mutate!
35//! mapping.set("age", 30); // This works despite `mapping` not being `mut`
36//!
37//! assert_eq!(doc.to_string(), "name: Alice\nage: 30\n");
38//! ```
39//!
40//! ## Why This Design?
41//!
42//! This design enables:
43//! - **Efficient in-place mutations** without cloning the entire tree
44//! - **Sharing references** while still allowing modifications
45//! - **Lossless preservation** of formatting and comments during edits
46//!
47//! If you're familiar with `RefCell` or `Rc`, this is similar - the tree uses
48//! internal synchronization to allow shared mutable access.
49//!
50//! ## Migration Note
51//!
52//! If you're coming from other YAML libraries, this might seem unusual. In most
53//! libraries, you need `&mut` to modify data. Here, you don't. This is intentional
54//! and allows for a more flexible API while maintaining the guarantees of Rust's
55//! borrow checker.
56//!
57//! # Getting Started
58//!
59//! ## Parsing YAML
60//!
61//! ```rust
62//! use yaml_edit::Document;
63//! use std::str::FromStr;
64//!
65//! let yaml = Document::from_str("name: Alice\nage: 30").unwrap();
66//! let mapping = yaml.as_mapping().unwrap();
67//!
68//! // Get values
69//! let name = mapping.get("name").unwrap();
70//! assert_eq!(name.as_scalar().unwrap().to_string(), "Alice");
71//! ```
72//!
73//! ## Modifying YAML
74//!
75//! ```rust
76//! use yaml_edit::Document;
77//! use std::str::FromStr;
78//!
79//! let yaml = Document::from_str("name: Alice").unwrap();
80//! let mapping = yaml.as_mapping().unwrap();
81//!
82//! // Add a new field
83//! mapping.set("age", 30);
84//!
85//! // Update an existing field
86//! mapping.set("name", "Bob");
87//!
88//! // Remove a field
89//! mapping.remove("age");
90//! ```
91//!
92//! ## Path-based Access
93//!
94//! ```rust
95//! use yaml_edit::{Document, path::YamlPath};
96//! use std::str::FromStr;
97//!
98//! let yaml = Document::from_str("server:\n host: localhost").unwrap();
99//!
100//! // Get nested values
101//! let host = yaml.try_get_path("server.host").ok();
102//! assert!(host.is_some());
103//!
104//! // Set nested values (creates intermediate mappings)
105//! yaml.try_set_path("server.port", 8080).unwrap();
106//! yaml.try_set_path("database.host", "db.example.com").unwrap();
107//! ```
108//!
109//! ## Iterating Over Collections
110//!
111//! ```rust
112//! use yaml_edit::Document;
113//! use std::str::FromStr;
114//!
115//! let yaml = Document::from_str("a: 1\nb: 2\nc: 3").unwrap();
116//! let mapping = yaml.as_mapping().unwrap();
117//!
118//! // Iterate over key-value pairs
119//! for (key, value) in &mapping {
120//! println!("{:?}: {:?}", key, value);
121//! }
122//!
123//! // Use iterator methods
124//! let count = (&mapping).into_iter().count();
125//! assert_eq!(count, 3);
126//! ```
127//!
128//! ## Working with Sequences
129//!
130//! ```rust
131//! use yaml_edit::Document;
132//! use std::str::FromStr;
133//!
134//! let yaml = Document::from_str("items:\n - apple\n - banana").unwrap();
135//! let mapping = yaml.as_mapping().unwrap();
136//! let sequence = mapping.get_sequence("items").unwrap();
137//!
138//! // Iterate over items
139//! for item in &sequence {
140//! println!("{:?}", item);
141//! }
142//!
143//! // Get specific item
144//! let first = sequence.get(0);
145//! assert!(first.is_some());
146//! ```
147//!
148//! ## Schema Validation
149//!
150//! ```rust
151//! use yaml_edit::{Document, SchemaValidator};
152//! use std::str::FromStr;
153//!
154//! let yaml = Document::from_str("name: Alice\nage: 30").unwrap();
155//!
156//! // Validate against JSON schema (no custom types)
157//! let result = SchemaValidator::json().validate(&yaml);
158//! assert!(result.is_ok());
159//! ```
160//!
161//! ## Position Tracking
162//!
163//! ```rust
164//! use yaml_edit::Document;
165//! use std::str::FromStr;
166//!
167//! let text = "name: Alice\nage: 30";
168//! let doc = Document::from_str(text).unwrap();
169//!
170//! // Get line/column positions
171//! let start = doc.start_position(text);
172//! assert_eq!(start.line, 1);
173//! assert_eq!(start.column, 1);
174//! ```
175
176pub mod anchor_resolution;
177#[doc(inline)]
178pub use anchor_resolution::{
179 AnchorRegistry, DocumentMergedExt, DocumentResolvedExt, MappingMergedExt, MergedMapping,
180 MergedView,
181};
182pub mod mapping_view;
183#[doc(inline)]
184pub use mapping_view::MappingView;
185mod as_yaml;
186mod builder;
187pub mod custom_tags;
188pub mod debug;
189mod error;
190pub mod error_recovery;
191mod lex;
192mod nodes;
193mod parse;
194mod parser;
195pub mod path;
196mod scalar;
197mod schema;
198pub mod validator;
199mod value;
200pub mod visitor;
201mod yaml;
202
203pub use as_yaml::{yaml_eq, AsYaml, YamlKind, YamlNode};
204pub use builder::{MappingBuilder, SequenceBuilder, YamlBuilder};
205pub use error::{YamlError, YamlResult};
206pub use lex::{
207 lex, lex_with_validation, lex_with_validation_config, SyntaxKind, ValidationConfig,
208 WhitespaceError, WhitespaceErrorCategory,
209};
210pub use parse::Parse;
211pub use scalar::{CoreScalarType, ScalarStyle, ScalarType, ScalarValue};
212pub use schema::{
213 CustomSchema, CustomValidationResult, Schema, SchemaValidator, ValidationError,
214 ValidationErrorKind, ValidationResult,
215};
216pub use yaml::{
217 Alias, Comment, Directive, Document, Entry, Lang, Mapping, MappingEntry, OccupiedEntry, Scalar,
218 ScalarConversionError, Sequence, Set, TaggedNode, VacantEntry, YamlFile,
219};
220
221/// Advanced API for power users who need direct access to the underlying syntax tree.
222///
223/// This module provides low-level access to the rowan syntax tree implementation.
224/// Most users should not need this module - the main API provides high-level
225/// wrappers that are easier to use and don't expose implementation details.
226///
227/// # Example
228///
229/// ```rust
230/// use yaml_edit::{Document, advanced};
231/// use std::str::FromStr;
232///
233/// let doc = Document::from_str("key: value").unwrap();
234/// let mapping = doc.as_mapping().unwrap();
235///
236/// // Get a value node
237/// if let Some(value) = mapping.get("key") {
238/// // YamlNode provides access to the underlying structure
239/// println!("Found value: {}", value.to_string());
240/// }
241/// ```
242pub mod advanced {
243 pub use rowan::TextRange;
244
245 use crate::yaml::SyntaxNode;
246 use crate::TextPosition;
247
248 /// Get the text range of a syntax node
249 pub fn syntax_node_range(node: &SyntaxNode) -> TextRange {
250 node.text_range()
251 }
252
253 /// Convert a TextPosition to rowan's TextRange
254 pub fn text_position_to_range(pos: TextPosition) -> TextRange {
255 pos.into()
256 }
257
258 /// Convert rowan's TextRange to TextPosition
259 pub fn text_range_to_position(range: TextRange) -> TextPosition {
260 range.into()
261 }
262}
263
264// Re-export custom tags API
265pub use custom_tags::{
266 // Built-in handlers
267 CompressedBinaryHandler,
268 CustomTagError,
269 CustomTagHandler,
270 CustomTagParser,
271 CustomTagRegistry,
272 EnvVarHandler,
273 JsonHandler,
274 TimestampHandler,
275};
276
277/// A text position in a YAML document, represented as byte offsets.
278#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
279pub struct TextPosition {
280 /// The start byte offset
281 pub start: u32,
282 /// The end byte offset (exclusive)
283 pub end: u32,
284}
285
286impl TextPosition {
287 /// Create a new text position
288 pub fn new(start: u32, end: u32) -> Self {
289 Self { start, end }
290 }
291
292 /// Get the length of this text range
293 pub fn len(&self) -> u32 {
294 self.end - self.start
295 }
296
297 /// Check if this range is empty
298 pub fn is_empty(&self) -> bool {
299 self.start == self.end
300 }
301}
302
303/// A line and column position in a YAML document (1-indexed).
304///
305/// Line and column numbers are both 1-indexed (first line is line 1, first column is column 1).
306#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
307pub struct LineColumn {
308 /// Line number (1-indexed)
309 pub line: usize,
310 /// Column number (1-indexed, counts Unicode scalar values)
311 pub column: usize,
312}
313
314impl LineColumn {
315 /// Create a new line/column position
316 pub fn new(line: usize, column: usize) -> Self {
317 Self { line, column }
318 }
319}
320
321impl std::fmt::Display for LineColumn {
322 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
323 write!(f, "{}:{}", self.line, self.column)
324 }
325}
326
327/// Convert a byte offset to line and column numbers in the given text.
328///
329/// Line and column numbers are 1-indexed. Column numbers count Unicode scalar values,
330/// not bytes or grapheme clusters.
331///
332/// # Arguments
333///
334/// * `text` - The full source text
335/// * `byte_offset` - Byte offset into the text
336///
337/// # Returns
338///
339/// `LineColumn` with 1-indexed line and column numbers, or line 1, column 1 if offset is out of bounds.
340///
341/// # Examples
342///
343/// ```
344/// use yaml_edit::byte_offset_to_line_column;
345///
346/// let text = "line 1\nline 2\nline 3";
347/// let pos = byte_offset_to_line_column(text, 7); // Start of "line 2"
348/// assert_eq!(pos.line, 2);
349/// assert_eq!(pos.column, 1);
350/// ```
351pub fn byte_offset_to_line_column(text: &str, byte_offset: usize) -> LineColumn {
352 let mut line = 1;
353 let mut column = 1;
354
355 for (i, ch) in text.char_indices() {
356 if i >= byte_offset {
357 break;
358 }
359
360 if ch == '\n' {
361 line += 1;
362 column = 1;
363 } else {
364 column += 1;
365 }
366 }
367
368 LineColumn { line, column }
369}
370
371impl From<rowan::TextRange> for TextPosition {
372 fn from(range: rowan::TextRange) -> Self {
373 Self {
374 start: u32::from(range.start()),
375 end: u32::from(range.end()),
376 }
377 }
378}
379
380impl From<TextPosition> for rowan::TextRange {
381 fn from(pos: TextPosition) -> Self {
382 rowan::TextRange::new(pos.start.into(), pos.end.into())
383 }
384}
385
386/// The kind of parse error, enabling structured matching without string parsing.
387#[derive(Debug, Clone, PartialEq, Eq, Hash)]
388pub enum ParseErrorKind {
389 /// An unclosed flow sequence (missing `]`)
390 UnclosedFlowSequence,
391 /// An unclosed flow mapping (missing `}`)
392 UnclosedFlowMapping,
393 /// An unterminated quoted string (missing closing quote)
394 UnterminatedString,
395 /// Any other parse error
396 Other,
397}
398
399/// A positioned parse error containing location information.
400#[derive(Debug, Clone, PartialEq, Eq, Hash)]
401pub struct PositionedParseError {
402 /// The error message
403 pub message: String,
404 /// The text range where the error occurred
405 pub range: TextPosition,
406 /// Optional error code for categorization
407 pub code: Option<String>,
408 /// Structured error kind
409 pub kind: ParseErrorKind,
410}
411
412impl PositionedParseError {
413 /// Get the line and column where this error starts (if source text is available).
414 ///
415 /// # Arguments
416 ///
417 /// * `source_text` - The original YAML source text
418 ///
419 /// # Returns
420 ///
421 /// `LineColumn` with 1-indexed line and column numbers.
422 ///
423 /// # Examples
424 ///
425 /// ```
426 /// use yaml_edit::{YamlFile, Parse};
427 /// use std::str::FromStr;
428 ///
429 /// let text = "invalid:\n - [unclosed";
430 /// let parse = Parse::parse_yaml(text);
431 ///
432 /// if let Some(err) = parse.positioned_errors().first() {
433 /// let pos = err.start_position(text);
434 /// assert_eq!(pos.line, 2);
435 /// }
436 /// ```
437 pub fn start_position(&self, source_text: &str) -> LineColumn {
438 byte_offset_to_line_column(source_text, self.range.start as usize)
439 }
440
441 /// Get the line and column where this error ends (if source text is available).
442 ///
443 /// # Arguments
444 ///
445 /// * `source_text` - The original YAML source text
446 ///
447 /// # Returns
448 ///
449 /// `LineColumn` with 1-indexed line and column numbers.
450 pub fn end_position(&self, source_text: &str) -> LineColumn {
451 byte_offset_to_line_column(source_text, self.range.end as usize)
452 }
453}
454
455impl std::fmt::Display for PositionedParseError {
456 fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
457 write!(f, "{}", self.message)
458 }
459}
460
461impl std::error::Error for PositionedParseError {}
462
463/// The indentation to use when writing a YAML file.
464#[derive(Debug, Clone, Copy, PartialEq, Eq)]
465pub enum Indentation {
466 /// Use the same indentation as the original line for the value.
467 FieldNameLength,
468
469 /// The number of spaces to use for indentation.
470 Spaces(u32),
471}
472
473impl Default for Indentation {
474 fn default() -> Self {
475 Indentation::Spaces(2)
476 }
477}
478
479#[cfg(test)]
480mod tests {
481 use super::*;
482 use std::str::FromStr;
483
484 #[test]
485 fn test_byte_offset_to_line_column_basic() {
486 let text = "line 1\nline 2\nline 3";
487
488 let pos = byte_offset_to_line_column(text, 0);
489 assert_eq!(pos.line, 1);
490 assert_eq!(pos.column, 1);
491
492 let pos = byte_offset_to_line_column(text, 7);
493 assert_eq!(pos.line, 2);
494 assert_eq!(pos.column, 1);
495
496 let pos = byte_offset_to_line_column(text, 10);
497 assert_eq!(pos.line, 2);
498 assert_eq!(pos.column, 4);
499
500 let pos = byte_offset_to_line_column(text, 14);
501 assert_eq!(pos.line, 3);
502 assert_eq!(pos.column, 1);
503 }
504
505 #[test]
506 fn test_byte_offset_to_line_column_unicode() {
507 let text = "hello\n世界\nworld";
508
509 let pos = byte_offset_to_line_column(text, 0);
510 assert_eq!(pos.line, 1);
511 assert_eq!(pos.column, 1);
512
513 let pos = byte_offset_to_line_column(text, 6);
514 assert_eq!(pos.line, 2);
515 assert_eq!(pos.column, 1);
516
517 // After first Chinese character "世" (3 bytes)
518 let pos = byte_offset_to_line_column(text, 9);
519 assert_eq!(pos.line, 2);
520 assert_eq!(pos.column, 2);
521 }
522
523 #[test]
524 fn test_line_column_display() {
525 let pos = LineColumn::new(42, 17);
526 assert_eq!(format!("{}", pos), "42:17");
527
528 let pos2 = LineColumn::new(1, 1);
529 assert_eq!(format!("{}", pos2), "1:1");
530 }
531
532 #[test]
533 fn test_document_position() {
534 let text = "name: Alice\nage: 30";
535 let doc = Document::from_str(text).unwrap();
536
537 let start = doc.start_position(text);
538 assert_eq!(start.line, 1);
539 assert_eq!(start.column, 1);
540
541 let range = doc.byte_range();
542 assert_eq!(range.start, 0);
543 assert!(range.end > 0);
544 }
545
546 #[test]
547 fn test_mapping_position() {
548 let text = "server:\n host: localhost\n port: 8080";
549 let doc = Document::from_str(text).unwrap();
550 let mapping = doc.as_mapping().unwrap();
551
552 let start = mapping.start_position(text);
553 assert_eq!(start.line, 1);
554 assert_eq!(start.column, 1);
555
556 let server_mapping = mapping.get_mapping("server").unwrap();
557 let server_start = server_mapping.start_position(text);
558 assert_eq!(server_start.line, 2);
559 }
560
561 #[test]
562 fn test_scalar_position_via_nodes() {
563 let text = "name: Alice\nage: 30";
564 let doc = Document::from_str(text).unwrap();
565 let mapping = doc.as_mapping().unwrap();
566
567 let entries: Vec<_> = mapping.entries().collect();
568 assert!(entries.len() >= 2);
569
570 let first_entry = &entries[0];
571 let key_node = first_entry.key_node().unwrap();
572 assert_eq!(key_node.to_string().trim(), "name");
573
574 let value_node = first_entry.value_node().unwrap();
575 assert_eq!(value_node.to_string().trim(), "Alice");
576 }
577
578 #[test]
579 fn test_sequence_position() {
580 let text = "items:\n - apple\n - banana";
581 let doc = Document::from_str(text).unwrap();
582 let mapping = doc.as_mapping().unwrap();
583
584 let items_node = mapping.get("items").unwrap();
585 assert!(items_node.as_sequence().is_some());
586 }
587
588 #[test]
589 fn test_positioned_parse_error() {
590 let text = "invalid:\n - [unclosed";
591 let parse = Parse::parse_yaml(text);
592
593 let errors = parse.positioned_errors();
594 if errors.is_empty() {
595 return;
596 }
597
598 let err = &errors[0];
599 let start = err.start_position(text);
600 assert_eq!(start.line, 2);
601 }
602
603 #[test]
604 fn test_multiline_document_byte_offsets() {
605 // Leading comment is stream-level and can't be attached to a
606 // `Document`, so parse via `YamlFile` to reach the document.
607 let text = "# Comment\nname: Alice\n\nage: 30";
608 let doc = YamlFile::from_str(text).unwrap().document().unwrap();
609
610 let range = doc.byte_range();
611 assert_eq!(range.start, 10);
612 assert_eq!(range.end, 30);
613
614 let start = doc.start_position(text);
615 assert_eq!(start.line, 2);
616 assert_eq!(start.column, 1);
617 }
618
619 #[test]
620 fn test_nested_mapping_byte_ranges() {
621 let text = "server:\n database:\n host: localhost";
622 let doc = Document::from_str(text).unwrap();
623 let mapping = doc.as_mapping().unwrap();
624
625 let server_mapping = mapping.get_mapping("server").unwrap();
626 let server_range = server_mapping.byte_range();
627
628 assert!(server_range.end > server_range.start);
629
630 let server_pos = server_mapping.start_position(text);
631 assert!(server_pos.line > 0);
632 }
633
634 #[test]
635 fn test_empty_lines_positions() {
636 let text = "a: 1\n\n\nb: 2";
637
638 let pos1 = byte_offset_to_line_column(text, 0);
639 assert_eq!(pos1.line, 1);
640
641 let pos2 = byte_offset_to_line_column(text, 7);
642 assert_eq!(pos2.line, 4);
643 }
644
645 #[test]
646 fn test_document_end_position() {
647 let text = "key: value";
648 let doc = Document::from_str(text).unwrap();
649
650 let start = doc.start_position(text);
651 let end = doc.end_position(text);
652
653 assert_eq!(start.line, 1);
654 assert!(end.column >= start.column);
655 }
656
657 #[test]
658 fn test_mapping_end_position() {
659 let text = "a: 1\nb: 2";
660 let doc = Document::from_str(text).unwrap();
661 let mapping = doc.as_mapping().unwrap();
662
663 let start = mapping.start_position(text);
664 let end = mapping.end_position(text);
665
666 assert_eq!(start.line, 1);
667 assert_eq!(end.line, 2);
668 }
669}