Skip to main content

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}