Struct Options 

#[non_exhaustive]
pub struct Options {
    pub strict_indentation: bool,
    pub disallow_directives: bool,
    pub emit_unresolved_aliases: bool,
    pub emit_anchor_events: bool,
    pub emit_comments: bool,
    pub max_buffered_comment_events: usize,
    pub simple_key_max_lookahead: usize,
    pub flow_nesting_limit: usize,
    pub block_nesting_limit: usize,
    pub max_directive_bytes: usize,
    pub max_reserved_directive_params: usize,
}

Options controlling parser and scanner behavior and resource usage.

Construct this type with crate::options! so that code remains compatible when new options are added in future releases.

Examples

let options = granit_parser::options! {
    strict_indentation: true,
    flow_nesting_limit: 512,
    block_nesting_limit: 256,
};

assert!(options.strict_indentation);
assert_eq!(options.flow_nesting_limit, 512);
assert_eq!(options.block_nesting_limit, 256);

Fields (Non-exhaustive)

Non-exhaustive structs could have additional fields added in future. Therefore, non-exhaustive structs cannot be constructed in external crates using the traditional Struct { .. } syntax; cannot be matched against without a wildcard ..; and struct update syntax will not work.

strict_indentation: bool

Whether to enforce strict YAML indentation rules for flow collections, scalar continuations, and content following explicit-key anchor or tag properties.

The default parsing is compatible with PyYAML and ruamel.yaml. true sets stricter indentation rules as required by the YAML specification, some non-compliant YAML that passes with the two libraries above will fail. Default is false.

disallow_directives: bool

Reject all YAML directives, including reserved directives.

When enabled, directive syntax recognized by the scanner in any document reports crate::ErrorKind::DirectiveDisallowed at the directive’s % indicator. Percent signs inside scalars and comments are unaffected. Defaults to false.

emit_unresolved_aliases: bool

Emit unresolved alias nodes instead of stopping at an unknown anchor.

Defaults to false. When omitted or explicitly set to false, an alias without a preceding anchor definition in its document reports crate::ErrorKind::UnknownAnchor and stops parsing, preserving the default behavior.

When true, the parser emits crate::Event::UnresolvedAlias with the original name (without *) and a span covering the complete alias token, then continues structural parsing. Consumers must handle this event as a node, including in mapping-key and mapping-value positions; silently ignoring it in a wildcard match can lose structure. Successful parsing in this mode does not establish full YAML validity: unresolved aliases remain invalid references, whose diagnostics the consumer can report separately.

Resolved aliases still emit crate::Event::Alias. Each alias resolves against the most recent preceding definition in the same document. An unresolved occurrence neither allocates an anchor ID nor becomes resolved by a later definition. Repeated missing names produce separate unresolved events, and anchor names do not carry across documents. Scanning, grammar, input, and resource-limit errors still stop parsing normally. This option has no effect on a scanner used directly.

use granit_parser::{Event, Parser};

let options = granit_parser::options! { emit_unresolved_aliases: true };
let events = Parser::new_from_str_with_options("[*missing, value]", options)
    .collect::<Result<Vec<_>, _>>()?;
assert!(events.iter().any(|(event, _)| {
    matches!(event, Event::UnresolvedAlias(name) if name == "missing")
}));
assert!(matches!(events.last(), Some((Event::StreamEnd, _))));

emit_anchor_events: bool

Emit anchor definition metadata immediately after its node event.

Defaults to false, preserving the existing event stream. When enabled, each anchored scalar or collection start is immediately followed by crate::Event::Anchor carrying the assigned ID and original name (without &). Its companion span covers the complete &name token. Collection anchors are emitted before their children, including aliases referring to the collection itself. This adjacency guarantee applies to each crate::Parser; see crate::ParserStack for ordering across stack pushes.

The node event comes first so the parser never emits anchor metadata for a node that failed before its event could be emitted, including when recovering to the next document.

Anchor events are presentation metadata, not additional YAML nodes. Their spans refer back to properties preceding the node, so event spans need not be in source order. This option is independent of comment emission and has no effect on a standalone scanner.

emit_comments: bool

Whether scanners emit comment tokens and parsers emit comment events.

The default is true with the comments Cargo feature and false without it. When this is false, comments are still recognized and validated as YAML syntax, but their text is not captured and no comment tokens or events are emitted. Comment bytes are still consumed, so this is not an input-size or processing-time limit. This option is always available, but has no effect without the comments Cargo feature. Self::max_buffered_comment_events has no effect while comment emission is disabled.

max_buffered_comment_events: usize

Maximum number of consecutive comment events buffered while resolving an ambiguous collection entry or looking for the next document during recovery.

The default is 96. A value of zero rejects the first comment that would need buffering. This option is available only with the comments Cargo feature.

simple_key_max_lookahead: usize

Maximum number of characters inspected while resolving a simple key.

The default is 1024, matching YAML’s simple-key length restriction. A key at exactly this limit is accepted. Lower values impose a stricter resource limit; higher values relax that YAML restriction.

flow_nesting_limit: usize

Maximum number of simultaneously nested flow collections.

The default is 255. A value of zero rejects the first flow collection opener.

block_nesting_limit: usize

Maximum number of simultaneously nested block collections parsed, or block indentation levels retained by a scanner used directly.

The default is 255. A value of zero rejects the first block sequence or mapping. This bounds both indentation state retained while scanning and the number of closing tokens queued when nested block collections end together. Parsers also count indentless block sequences, which do not add scanner indentation state.

max_directive_bytes: usize

Maximum number of UTF-8 source bytes retained for a directive name and payload.

The default is 1024. Separating blanks before retained values count toward the limit. %YAML version components instead have a fixed nine-digit limit and are stored as integers. Real directives are far shorter than the default.

max_reserved_directive_params: usize

Maximum number of parameters retained for a single reserved directive.

The default is 16. The parser ignores reserved directives, so their parameters only reach code driving crate::Scanner directly. A value of zero rejects the first parameter.

Implementations

impl Options

pub fn set_emit_comments(&mut self, emit_comments: bool)

Controls whether scanners emit comment tokens and parsers emit comment events.

When emission is disabled, comments are still recognized and validated, but their text is not captured. This sets Self::emit_comments in every build, but has no effect on parsing or scanning without the comments Cargo feature.

This method is always available so downstream crates can disable comment emission even when another dependency enables the comments feature through feature unification.

Trait Implementations

impl Clone for Options

fn clone(&self) -> Options

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Options

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Options

fn default() -> Self

Returns the “default value” for a type.

impl Eq for Options

impl PartialEq for Options

fn eq(&self, other: &Options) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for Options