neure 0.10.0

A fast little combinational parsing library
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99

use core::fmt::Debug;

use crate::ctor::Ctor;

use crate::ctor::Handler;
use crate::ctx::Context;
use crate::ctx::Match;
use crate::err::Error;
use crate::regex::Regex;
use crate::span::Span;

use super::impl_not_for_regex;

///
/// A zero-width regex combinator that always fails without consuming any input.
///
/// [`FailRegex`] acts as an atomic failure primitive in the regex combinator system—like a gate
/// that never opens. It immediately rejects any input stream while preserving the parser position,
/// ensuring no characters are consumed during its execution. This zero-width failure combinator
/// compiles down to a single error-returning instruction under compiler optimizations,
/// yet plays a pivotal role in parser logic composition.
///
/// # Regex
///
/// - **Always fail** at any position in the input stream
/// - **Zero-width match**: Returns Err([`Error::Fail`])
/// - **No consumption**: Parser position remains unchanged after match
/// - **No failure cases**: Never returns an error (not even at input end)
///
/// # Ctor
///
/// Uses identical matching logic as regex mode, then constructs a value from the result.
///
/// # Example
/// ```
/// # use neure::prelude::*;
/// #
/// # fn main() -> Result<(), Box<dyn core::error::Error>> {
///     let parser = regex::empty();
///     let mut ctx = BytesCtx::new(b"rust is so awesome!");
///
///     assert_eq!(ctx.try_mat(&parser)?, Span::new(0, 0));
/// #   Ok(())
/// # }
/// ```
#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, PartialOrd, Ord, Hash)]
pub struct FailRegex;

impl_not_for_regex!(FailRegex);

impl FailRegex {
    pub const fn new() -> Self {
        Self
    }
}

impl<'a, C> Regex<C> for FailRegex
where
    C: Context<'a>,
{
    #[inline(always)]
    fn try_parse(&self, _: &mut C) -> Result<Span, Error> {
        crate::debug_regex_reval!("FailRegex", Err(Error::Fail))
    }
}

impl<'a, C, O, H> Ctor<C, O, H> for FailRegex
where
    C: Match<'a>,
    H: Handler<C, Out = O>,
{
    #[inline(always)]
    fn construct(&self, ctx: &mut C, handler: &mut H) -> Result<O, Error> {
        let ret = ctx.try_mat(self);

        handler.invoke(ctx, &ret?).map_err(Into::into)
    }
}

///
/// A zero-width regex combinator that always fails without consuming any input.
///
/// # Example
///
/// ```
/// # use neure::prelude::*;
/// #
/// # fn main() -> Result<(), Box<dyn core::error::Error>> {
///     let fail = regex::fail();
///     let mut ctx = CharsCtx::new("aabbccgg");
///
///     assert!(ctx.try_mat(&fail).is_err());
///
/// #   Ok(())
/// # }
/// ```
pub const fn fail() -> FailRegex {
    FailRegex::new()
}