Struct Source

pub struct Source { /* private fields */ }

源代码表示结构。

统一的源代码抽象，支持从文件、字符串等多种来源加载代码， 并提供完整的源码位置追踪和错误报告能力。

设计特点

内存共享

使用 Arc<Vec<char>> 来共享源码内容，避免重复拷贝， 多个 Token 和 AST 节点可以安全地引用同一份源码。

路径追踪

可选的文件路径信息，用于错误报告和调试时显示文件来源。

Unicode 友好

内部使用 Vec<char> 存储，完整支持 Unicode 字符， 便于处理多语言源码和字符边界计算。

序列化支持

实现了 Serde 序列化，支持 AST 的持久化存储和网络传输。

使用示例

// 从字符串创建
let source = Source::from_string("let x = 42".to_string());

// 从文件创建
let source = Source::from_file("example.onion")?;

// 带路径信息创建
let source = Source::from_string_with_file_path(
    "let y = x + 1".to_string(),
    "inline.onion"
);

Implementations

impl Source

pub fn from_string(source: String) -> Self

从字符串创建 Source。

创建不包含文件路径信息的源码实例，适用于内存中的代码片段、 动态生成的代码或测试用例。

参数

• source：源代码字符串

返回

新的 Source 实例

示例

let source = Source::from_string("let x = 42".to_string());

pub fn from_string_with_file_path<P: AsRef<Path>>( source: String, path: P, ) -> Self

从字符串和文件路径创建 Source。

创建包含文件路径信息的源码实例，适用于需要保留来源信息的场景， 如编辑器插件、调试器或错误报告。

参数

• source：源代码字符串
• path：文件路径，可以是任何可转换为 Path 的类型

返回

新的 Source 实例，包含路径信息

示例

let source = Source::from_string_with_file_path(
    "let y = x + 1".to_string(),
    "math.onion"
);

pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self>

从文件创建 Source。

读取文件内容并创建 Source 实例，自动设置文件路径信息。 这是从磁盘文件加载源码的标准方法。

参数

• path：文件路径，可以是任何可转换为 Path 的类型

返回

• Ok(Source)：成功时返回包含文件内容和路径的 Source
• Err(std::io::Error)：文件读取失败时返回 IO 错误

错误

当文件不存在、权限不足或读取过程中发生 IO 错误时返回错误。

示例

let source = Source::from_file("example.onion")?;

pub fn file_path(&self) -> Option<&Path>

获取文件路径。

返回源码的文件路径，如果源码不是来自文件则返回 None。 主要用于错误报告和调试信息显示。

返回

• Some(&Path)：如果源码来自文件
• None：如果源码来自内存字符串

pub fn content(&self) -> &Arc<Vec<char>>

获取源码内容的共享引用。

返回内部字符向量的 Arc 引用，允许多个地方共享同一份源码内容。 主要供内部模块使用，如词法分析器和 AST 节点。

返回

源码字符向量的共享引用

pub fn content_str(&self) -> String

获取源码内容的字符串表示。

将内部的字符向量转换为字符串，主要用于显示、打印或与 需要字符串的 API 交互。

返回

源码的字符串表示

Trait Implementations

impl Clone for Source

fn clone(&self) -> Source

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Source

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Debug 格式化输出。

提供源码的调试信息，包括文件路径（或标记为内存中）和 内容的前 40 个字符预览。有助于调试和日志输出。

输出格式

Source(file: "path/to/file.onion", content: "let x = 42...")

对于内存中的源码： Source(file: "<in-memory>", content: "let x = 42...")

impl Deref for Source

fn deref(&self) -> &Self::Target

解引用到内部的字符向量。

允许 Source 像 Arc<Vec<char>> 一样使用，提供对字符向量的直接访问。 这使得可以直接在 Source 上使用索引、切片等操作。

示例

let source = Source::from_string("hello".to_string());
let first_char = source[0];  // 等价于 source.content()[0]
let slice = &source[1..3];   // 等价于 &source.content()[1..3]

type Target = Arc<Vec<char>>

The resulting type after dereferencing.

impl<'de> Deserialize<'de> for Source

fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>

where D: Deserializer<'de>,

从字符串反序列化 Source。

将序列化的字符串转换回 Source 结构，文件路径信息设置为 None， 因为序列化时未包含路径信息。

impl Display for Source

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Display 格式化输出。

提供简洁的源码标识，主要用于用户友好的错误消息和日志输出。 只显示文件路径或匿名标记，不包含源码内容。

输出格式

• 有文件路径：/path/to/file.onion
• 无文件路径：<anonymous>

impl From<&str> for Source

fn from(source: &str) -> Self

从字符串切片转换为 Source。

提供便捷的转换方法，会将字符串切片复制为 String 再创建 Source。

impl From<String> for Source

fn from(source: String) -> Self

从 String 转换为 Source。

提供便捷的转换方法，等价于 Source::from_string()。

impl Serialize for Source

fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>

where S: Serializer,

序列化 Source 为字符串。

只序列化源码内容，忽略文件路径信息。这样可以避免路径信息在不同环境间的兼容性问题，同时减少序列化数据的大小。