ferogram_tl_parser/
lib.rs

1// Copyright (c) Ankit Chaubey <ankitchaubey.dev@gmail.com>
2// SPDX-License-Identifier: MIT OR Apache-2.0
3//
4// ferogram: async Telegram MTProto client in Rust
5// https://github.com/ankit-chaubey/ferogram
6//
7// If you use or modify this code, keep this notice at the top of your file
8// and include the LICENSE-MIT or LICENSE-APACHE file from this repository:
9// https://github.com/ankit-chaubey/ferogram
10
11#![cfg_attr(docsrs, feature(doc_cfg))]
12#![doc(html_root_url = "https://docs.rs/ferogram-tl-parser/0.3.3")]
13//! Parser for Telegram's Type Language (TL) schema files.
14//!
15//! This crate is part of [ferogram](https://crates.io/crates/ferogram), an async Rust
16//! MTProto client built by [Ankit Chaubey](https://github.com/ankit-chaubey).
17//!
18//! - Channel: [t.me/Ferogram](https://t.me/Ferogram)
19//! - Chat: [t.me/FerogramChat](https://t.me/FerogramChat)
20//!
21//! Converts raw `.tl` schema text into a [`tl::Definition`] AST. That AST is
22//! then consumed by `ferogram-tl-gen` to produce the Rust type bindings in
23//! `ferogram-tl-types`.
24//!
25//! Most users never touch this crate. It matters when you are upgrading the
26//! TL layer, writing a custom code generator, or doing schema introspection.
27//!
28//! # Usage
29//!
30//! ```rust
31//! use ferogram_tl_parser::parse_tl_file;
32//!
33//! let src = "user#12345678 id:long name:string = User;";
34//! for def in parse_tl_file(src) {
35//!     let def = def.unwrap();
36//!     println!("{} #{:08x}", def.name, def.id);
37//! }
38//! ```
39//!
40//! [`parse_tl_file`] returns an iterator of `Result<Definition, ParseError>`.
41//! It handles both constructor and function sections of a `.tl` file.
42//!
43//! # AST
44//!
45//! The main types are in the [`tl`] module:
46//! - [`tl::Definition`]: one parsed TL declaration (constructor or function).
47//! - [`tl::Parameter`]: a field name and type.
48//! - [`tl::Type`]: a TL type reference (with optional generic argument).
49//!
50//! [Type Language]: https://core.telegram.org/mtproto/TL
51#![deny(unsafe_code)]
52#![warn(missing_docs)]
53
54/// Parse error types for TL schema parsing.
55pub mod errors;
56mod iterator;
57/// Core TL schema types: definitions, parameters, types, flags, and categories.
58pub mod tl;
59mod utils;
60
61use errors::ParseError;
62use tl::Definition;
63
64/// Parses a complete TL schema file, yielding [`Definition`]s one by one.
65///
66/// Lines starting with `//` are treated as comments and skipped.
67/// The special `---functions---` and `---types---` section markers switch
68/// the [`tl::Category`] applied to the following definitions.
69///
70/// Returns an iterator of `Result<Definition, ParseError>` so callers can
71/// decide whether to skip or hard-fail on bad lines.
72pub fn parse_tl_file(contents: &str) -> impl Iterator<Item = Result<Definition, ParseError>> + '_ {
73    iterator::TlIterator::new(contents)
74}
ferogram_tl_parser/lib.rs

ferogram_tl_parser/
lib.rs
