gaia_types/reader/
mod.rs

1#![doc = include_str!("readme.md")]
2
3pub use self::{token::Token, token_stream::TokenStream};
4use crate::GaiaError;
5use byteorder::{ByteOrder, ReadBytesExt};
6use serde::{Deserialize, Serialize};
7use std::{
8    io::{Read, Seek, SeekFrom},
9    marker::PhantomData,
10};
11use url::Url;
12
13mod token;
14mod token_stream;
15
16/// 二进制读取器，用于从实现了 ReadBytesExt trait 的类型中读取数据
17///
18/// 这是一个泛型结构体，可以包装任何实现了 ReadBytesExt trait 的类型，
19/// 提供二进制数据的读取功能。
20#[derive(Debug)]
21pub struct BinaryReader<R, E> {
22    reader: R,
23    position: u64,
24    endian: PhantomData<E>,
25}
26
27impl<R: Read, E> Read for BinaryReader<R, E> {
28    fn read(&mut self, buffer: &mut [u8]) -> std::io::Result<usize> {
29        let bytes_read = self.reader.read(buffer)?;
30        self.position += bytes_read as u64;
31        Ok(bytes_read)
32    }
33}
34
35impl<R: Seek, E> Seek for BinaryReader<R, E> {
36    fn seek(&mut self, pos: SeekFrom) -> std::io::Result<u64> {
37        let new_position = self.reader.seek(pos)?;
38        self.position = new_position;
39        Ok(new_position)
40    }
41}
42
43impl<R, E> BinaryReader<R, E> {
44    /// 创建新的二进制读取器
45    ///
46    /// # Arguments
47    /// * `lexer` - 要读取的数据
48    ///
49    /// # Returns
50    /// 返回新的 BinaryReader 实例
51    pub fn new(reader: R) -> Self {
52        Self { reader, position: 0, endian: Default::default() }
53    }
54
55    /// 获取当前读取位置
56    ///
57    /// # Returns
58    /// 返回当前的字节偏移位置
59    pub fn get_position(&self) -> u64 {
60        self.position
61    }
62
63    /// 设置读取位置
64    ///
65    /// 注意：如果底层reader不支持Seek操作，此函数将返回错误
66    ///
67    /// # Arguments
68    /// * `pos` - 新的读取位置
69    ///
70    /// # Returns
71    /// 返回操作结果
72    pub fn set_position(&mut self, position: u64) -> Result<u64, GaiaError>
73    where
74        R: Seek,
75    {
76        self.reader.seek(SeekFrom::Start(position))?;
77        self.position = position;
78        Ok(position)
79    }
80    pub fn finish(self) -> R {
81        self.reader
82    }
83}
84
85impl<R: ReadBytesExt, E: ByteOrder> BinaryReader<R, E> {
86    /// 读取 u8
87    ///
88    /// # Returns
89    /// 返回读取的 u8 值或 IO 错误
90    pub fn read_u8(&mut self) -> std::io::Result<u8> {
91        let value = self.reader.read_u8()?;
92        self.position += 1;
93        Ok(value)
94    }
95
96    /// 读取 u16
97    ///
98    /// # Returns
99    /// 返回读取的 u16 值或 IO 错误
100    pub fn read_u16(&mut self) -> std::io::Result<u16> {
101        let value = self.reader.read_u16::<E>()?;
102        self.position += 2;
103        Ok(value)
104    }
105
106    /// 读取 i16
107    ///
108    /// # Returns
109    /// 返回读取的 i16 值或 IO 错误
110    pub fn read_i16(&mut self) -> std::io::Result<i16> {
111        let value = self.reader.read_i16::<E>()?;
112        self.position += 2;
113        Ok(value)
114    }
115
116    /// 读取 u32
117    ///
118    /// # Returns
119    /// 返回读取的 u32 值或 IO 错误
120    pub fn read_u32(&mut self) -> std::io::Result<u32> {
121        let value = self.reader.read_u32::<E>()?;
122        self.position += 4;
123        Ok(value)
124    }
125
126    /// 读取 u64
127    ///
128    /// # Returns
129    /// 返回读取的 u64 值或 IO 错误
130    pub fn read_u64(&mut self) -> std::io::Result<u64> {
131        let value = self.reader.read_u64::<E>()?;
132        self.position += 8;
133        Ok(value)
134    }
135
136    /// 读取指定长度的字节数组
137    ///
138    /// # Arguments
139    /// * `len` - 要读取的字节数
140    ///
141    /// # Returns
142    /// 返回读取的字节数组或 IO 错误
143    pub fn read_bytes(&mut self, len: usize) -> std::io::Result<Vec<u8>> {
144        let mut buf = vec![0u8; len];
145        self.reader.read_exact(&mut buf)?;
146        self.position += len as u64;
147        Ok(buf)
148    }
149
150    /// 读取固定长度的字节数组
151    ///
152    /// # Returns
153    /// 返回读取的字节数组或 IO 错误
154    pub fn read_array<const N: usize>(&mut self) -> std::io::Result<[u8; N]> {
155        let mut buf = [0u8; N];
156        self.reader.read_exact(&mut buf)?;
157        self.position += N as u64;
158        Ok(buf)
159    }
160
161    /// 跳过指定数量的字节
162    ///
163    /// 注意：如果底层reader不支持Seek操作，此函数将返回错误
164    ///
165    /// # Arguments
166    /// * `count` - 要跳过的字节数
167    ///
168    /// # Returns
169    /// 返回操作结果
170    pub fn skip(&mut self, count: u64) -> std::io::Result<u64>
171    where
172        R: Seek,
173    {
174        let new_pos = self.reader.seek(SeekFrom::Current(count as i64))?;
175        self.position = new_pos;
176        Ok(new_pos)
177    }
178}
179
180/// 源代码位置信息，表示代码在源文件中的位置
181///
182/// 该结构体用于跟踪源代码的位置信息，包括行号、列号等。
183#[derive(Copy, Clone, Debug, Eq, PartialEq, Serialize, Deserialize)]
184pub struct SourcePosition {
185    /// 行号，从 1 开始计数
186    ///
187    /// 表示当前位置所在的行号，第一行为 1。
188    pub line: u32,
189    /// 列号，从 1 开始计数
190    ///
191    /// 表示当前位置所在的列号，第一列为 1。
192    pub column: u32,
193    /// 字节偏移量，从 0 开始计数
194    ///
195    /// 表示从文件开始到当前位置的字节偏移量。
196    pub offset: usize,
197    /// 长度，表示该位置所覆盖的字节数
198    ///
199    /// 通常用于表示标记或符号的长度。
200    pub length: usize,
201}
202
203/// 源代码位置，包含文件 URL 和位置信息
204///
205/// 该结构体扩展了 SourcePosition，增加了文件 URL 信息，
206/// 可以表示代码在特定文件中的位置。
207#[derive(Clone, Debug, Serialize, Deserialize)]
208pub struct SourceLocation {
209    /// 行号，从 1 开始计数
210    ///
211    /// 表示当前位置所在的行号。
212    pub line: u32,
213    /// 列号，从 1 开始计数
214    ///
215    /// 表示当前位置所在的列号。
216    pub column: u32,
217    /// 源文件的 URL，可选
218    ///
219    /// 如果存在，表示包含该代码的文件的 URL 或路径。
220    /// 可以是文件系统路径或网络 URL。
221    pub url: Option<Url>,
222}
223
224impl Default for SourceLocation {
225    fn default() -> Self {
226        Self { line: 1, column: 1, url: None }
227    }
228}
gaia_types/reader/mod.rs

gaia_types/reader/
mod.rs
