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
100
101
/*
* Minparser Simple parsing functions
*
* Copyright (C) 2024-2026 Paolo De Donato
*
* This program is free software: you can redistribute it and/or modify
* it under the terms of the GNU General Public License as published by
* the Free Software Foundation, either version 3 of the License, or
* (at your option) any later version.
*
* This program is distributed in the hope that it will be useful,
* but WITHOUT ANY WARRANTY; without even the implied warranty of
* MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
* GNU General Public License for more details.
*
* You should have received a copy of the GNU General Public License
* along with this program. If not, see <https://www.gnu.org/licenses/>.
*/
//! Simple parsing tools
//!
//! This crate is a collection of objects and algorithms shared among different crates that needs
//! to implement a parser.
//!
//! A [``Position``](pos::Position) is an object representing a position inside some file,
//! it contains a *line index* and a *column index*. The main role of a `Position` object is to
//! uniquely identify a single character or a token inside a file in order to allow the
//! user to easily find it.
//!
//! All the parsing structures in this library take a lifetime parameter `'a` which represents the
//! lifetime of the parsed string. Indeed, this crate tries to avoid any sort of allocation by
//! keeping all the deducced information on the parsed string. If you need to dispose the parsed
//! string at some point of your program or you do not want to put a lifetime parameter in your
//! custom structures then you can just convert any returned `&'a str` into a `String`.
//!
//! The [``View<'a>``](tools::View) object is a structure that contains a reference to a string and the position
//! of its first character with respect to a file. It contains several useful parsing methods, the
//! most important of them is [``match_tool``](tools::View::match_tool) that applies a parsing
//! strategy to the underlying string represented by an argument implementing the
//! [``Tool<'a>``](tools::Tool) trait.
//!
//! You can find several useful objects implementing the `Tool` trait in [`tools`], [`moretools`]
//! and [`utils`] submodules.
//!
//! # Usage examples
//! ```
//! use minparser::prelude::*;
//! let (mtc, step) = View::from("My string value").match_tool_string(&"My string").unwrap();
//! assert_eq!(mtc, "My string");
//! assert_eq!(step.get_view(), " value");
//! ```
//!
//! ```
//! use minparser::prelude::*;
//! let (data, step) = View::new("9180029a")
//! .match_tool_data(&RepeatAny::new_unbounded(Predicate::new(|c : char| c.is_ascii_digit()), TrueTool)).unwrap();
//! // Data returned from a RepeatAny object is just the number of repetitions.
//! // Use instead .match_tool_string to get the matched string.
//! assert_eq!(data, 7);
//! assert_eq!(step.get_view(), "a");
//! ```
//! # Documented features
//! A list of features you can optionally enable. None of these are enabled by default:
//!
//! - `alloc`: Links the library with the [`alloc`] crate and enable associated functions that works
//! with [`Vec`](alloc::vec::Vec) and other containers in `alloc`;
//! - `std`: Links the library with the [`std`] crate;
//! - `unstable-features`: Enable experimental features. **Warning**: breaking changes may be introduced
//! even at minor releases;
//! - `nightly-features`: Enable `unstable-features` and other experimental functionalities that
//! requires the `nightly` toolchain.
extern crate alloc;
extern crate std;
/// Crate prelude