ferogram-tl-parser 0.3.8

Parser for Telegram's Type Language (.tl) schema files
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

// Copyright (c) Ankit Chaubey <ankitchaubey.dev@gmail.com>
//
// ferogram: async Telegram MTProto client in Rust
// https://github.com/ankit-chaubey/ferogram
//
// Licensed under either the MIT License or the Apache License 2.0.
// See the LICENSE-MIT or LICENSE-APACHE file in this repository:
// https://github.com/ankit-chaubey/ferogram
//
// Feel free to use, modify, and share this code.
// Please keep this notice when redistributing.

#![cfg_attr(docsrs, feature(doc_cfg))]
#![doc(html_root_url = "https://docs.rs/ferogram-tl-parser/0.3.7")]
//! Parser for Telegram's Type Language (TL) schema files.
//!
//! This crate is part of [ferogram](https://crates.io/crates/ferogram), an async Rust
//! MTProto client built by [Ankit Chaubey](https://github.com/ankit-chaubey).
//!
//! - Channel: [t.me/Ferogram](https://t.me/Ferogram)
//! - Chat: [t.me/FerogramChat](https://t.me/FerogramChat)
//!
//! Converts raw `.tl` schema text into a [`tl::Definition`] AST. That AST is
//! then consumed by `ferogram-tl-gen` to produce the Rust type bindings in
//! `ferogram-tl-types`.
//!
//! Most users never touch this crate. It matters when you are upgrading the
//! TL layer, writing a custom code generator, or doing schema introspection.
//!
//! # Usage
//!
//! ```rust
//! use ferogram_tl_parser::parse_tl_file;
//!
//! let src = "user#12345678 id:long name:string = User;";
//! for def in parse_tl_file(src) {
//!     let def = def.unwrap();
//!     println!("{} #{:08x}", def.name, def.id);
//! }
//! ```
//!
//! [`parse_tl_file`] returns an iterator of `Result<Definition, ParseError>`.
//! It handles both constructor and function sections of a `.tl` file.
//!
//! # AST
//!
//! The main types are in the [`tl`] module:
//! - [`tl::Definition`]: one parsed TL declaration (constructor or function).
//! - [`tl::Parameter`]: a field name and type.
//! - [`tl::Type`]: a TL type reference (with optional generic argument).
//!
//! [Type Language]: https://core.telegram.org/mtproto/TL
#![deny(unsafe_code)]
#![warn(missing_docs)]

/// Parse error types for TL schema parsing.
pub mod errors;
mod iterator;
/// Core TL schema types: definitions, parameters, types, flags, and categories.
pub mod tl;
mod utils;

use errors::ParseError;
use tl::Definition;

/// Parses a complete TL schema file, yielding [`Definition`]s one by one.
///
/// Lines starting with `//` are treated as comments and skipped.
/// The special `---functions---` and `---types---` section markers switch
/// the [`tl::Category`] applied to the following definitions.
///
/// Returns an iterator of `Result<Definition, ParseError>` so callers can
/// decide whether to skip or hard-fail on bad lines.
pub fn parse_tl_file(contents: &str) -> impl Iterator<Item = Result<Definition, ParseError>> + '_ {
    iterator::TlIterator::new(contents)
}