//! 定义新宏时为宏作者提供的支持库。
//!
//! 由标准发行版提供的该库提供了在过程定义的宏定义的接口中使用的类型，例如，类似函数的宏 `#[proc_macro]`，宏属性 `#[proc_macro_attribute]` 和自定义派生属性 `#[proc_macro_derive]`。
//!
//!
//! 有关更多信息，请参见 [这本书][the book]。
//!
//! [the book]: ../book/ch19-06-macros.html#procedural-macros-for-generating-code-from-attributes
//!
//!

#![stable(feature = "proc_macro_lib", since = "1.15.0")]
#![deny(missing_docs)]
#![doc(
    html_playground_url = "https://play.rust-lang.org/",
    issue_tracker_base_url = "https://github.com/rust-lang/rust/issues/",
    test(no_crate_inject, attr(deny(warnings))),
    test(attr(allow(dead_code, deprecated, unused_variables, unused_mut)))
)]
// 这个库被复制到 rust-analyzer 以允许加载 rustc 编译的 proc 宏。
// 请尽可能避免使用 rust-anazer on stable 编译所需的不稳定特性。
//
#![feature(rustc_allow_const_fn_unstable)]
#![feature(staged_api)]
#![feature(allow_internal_unstable)]
#![feature(decl_macro)]
#![feature(local_key_cell_methods)]
#![feature(maybe_uninit_write_slice)]
#![feature(negative_impls)]
#![feature(new_uninit)]
#![feature(restricted_std)]
#![feature(rustc_attrs)]
#![feature(min_specialization)]
#![feature(strict_provenance)]
#![recursion_limit = "256"]

#[unstable(feature = "proc_macro_internals", issue = "27812")]
#[doc(hidden)]
pub mod bridge;

mod diagnostic;

#[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
pub use diagnostic::{Diagnostic, Level, MultiSpan};

use std::cmp::Ordering;
use std::ops::{Range, RangeBounds};
use std::path::PathBuf;
use std::str::FromStr;
use std::{error, fmt};

/// 确定是否已使 proc_macro 可被当前正在运行的程序访问。
///
/// proc_macro crate 仅用于在过程宏的实现内部使用。crate panic 中的所有函数 (如果从程序宏外部调用，例如从构建脚本或单元测试或常规 Rust 二进制文件调用)。
///
/// 考虑到旨在支持宏和非宏用例的 Rust 库，`proc_macro::is_available()` 提供了一种非 panic 的方式来检测使用 proc_macro API 所需的基础结构是否当前可用。
/// 如果从程序宏内部调用，则返回 true; 如果从任何其他二进制文件中调用，则返回 false。
///
///
///
///
///
///
///
#[stable(feature = "proc_macro_is_available", since = "1.57.0")]
pub fn is_available() -> bool {
    bridge::client::is_available()
}

/// 此 crate 提供的主要类型，表示 tokens 的抽象流，或更具体地说，表示 token 树的序列。
/// 该类型提供用于迭代这些 token 树的接口，并且相反，将大量 token 树收集到一个流中。
///
///
/// 这是 `#[proc_macro]`，`#[proc_macro_attribute]` 和 `#[proc_macro_derive]` 定义的输入和输出。
///
///
#[rustc_diagnostic_item = "TokenStream"]
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
#[derive(Clone)]
pub struct TokenStream(Option<bridge::client::TokenStream>);

#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl !Send for TokenStream {}
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl !Sync for TokenStream {}

/// `TokenStream::from_str` 返回错误。
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
#[non_exhaustive]
#[derive(Debug)]
pub struct LexError;

#[stable(feature = "proc_macro_lexerror_impls", since = "1.44.0")]
impl fmt::Display for LexError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("cannot parse string into token stream")
    }
}

#[stable(feature = "proc_macro_lexerror_impls", since = "1.44.0")]
impl error::Error for LexError {}

#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl !Send for LexError {}
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl !Sync for LexError {}

/// 从 `TokenStream::expand_expr` 返回的错误。
#[unstable(feature = "proc_macro_expand", issue = "90765")]
#[non_exhaustive]
#[derive(Debug)]
pub struct ExpandError;

#[unstable(feature = "proc_macro_expand", issue = "90765")]
impl fmt::Display for ExpandError {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("macro expansion failed")
    }
}

#[unstable(feature = "proc_macro_expand", issue = "90765")]
impl error::Error for ExpandError {}

#[unstable(feature = "proc_macro_expand", issue = "90765")]
impl !Send for ExpandError {}

#[unstable(feature = "proc_macro_expand", issue = "90765")]
impl !Sync for ExpandError {}

impl TokenStream {
    /// 返回不包含 token 树的空 `TokenStream`。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn new() -> TokenStream {
        TokenStream(None)
    }

    /// 检查此 `TokenStream` 是否为空。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn is_empty(&self) -> bool {
        self.0.as_ref().map(|h| h.is_empty()).unwrap_or(true)
    }

    /// 将此 `TokenStream` 解析为表达式并尝试扩展其中的任何宏。返回扩展的 `TokenStream`。
    ///
    /// 目前只有扩展到字面量的表达式会成功，尽管这在 future 中可能会有所放松。
    ///
    /// NOTE: 在错误情况下，`expand_expr` 可能会保留未扩展的宏、报告错误、编译失败或者返回 `Err(..)`。
    /// 任何错误条件的具体行为，以及哪些条件被视为错误，是未指定的，可能会在 future 中发生变化。
    ///
    ///
    ///
    ///
    #[unstable(feature = "proc_macro_expand", issue = "90765")]
    pub fn expand_expr(&self) -> Result<TokenStream, ExpandError> {
        let stream = self.0.as_ref().ok_or(ExpandError)?;
        match bridge::client::TokenStream::expand_expr(stream) {
            Ok(stream) => Ok(TokenStream(Some(stream))),
            Err(_) => Err(ExpandError),
        }
    }
}

/// 尝试将字符串拆分为 tokens 并将那些 tokens 解析为 token 流。
/// 可能由于多种原因而失败，例如，如果字符串包含不平衡的定界符或该语言中不存在的字符。
///
/// 解析的流中的所有 tokens 都获得 `Span::call_site()` 跨度。
///
/// NOTE: 某些错误可能导致 panics 而不是返回 `LexError`。我们保留稍后将这些错误更改为 LexError 的权利。
///
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl FromStr for TokenStream {
    type Err = LexError;

    fn from_str(src: &str) -> Result<TokenStream, LexError> {
        Ok(TokenStream(Some(bridge::client::TokenStream::from_str(src))))
    }
}

// 注意，网桥仅提供 `to_string`，基于它实现 `fmt::Display` (两者之间通常的关系相反)。
//
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl ToString for TokenStream {
    fn to_string(&self) -> String {
        self.0.as_ref().map(|t| t.to_string()).unwrap_or_default()
    }
}

/// 将 token 流打印为应该无损转换为相同 token 流 (模数跨度) 的字符串，但可能带有 `Delimiter::None` 分隔符和负数字字面量的 `TokenTree::Group` 除外。
///
///
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl fmt::Display for TokenStream {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.to_string())
    }
}

/// 以方便调试的形式打印 token。
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl fmt::Debug for TokenStream {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str("TokenStream ")?;
        f.debug_list().entries(self.clone()).finish()
    }
}

#[stable(feature = "proc_macro_token_stream_default", since = "1.45.0")]
impl Default for TokenStream {
    fn default() -> Self {
        TokenStream::new()
    }
}

#[unstable(feature = "proc_macro_quote", issue = "54722")]
pub use quote::{quote, quote_span};

fn tree_to_bridge_tree(
    tree: TokenTree,
) -> bridge::TokenTree<bridge::client::TokenStream, bridge::client::Span, bridge::client::Symbol> {
    match tree {
        TokenTree::Group(tt) => bridge::TokenTree::Group(tt.0),
        TokenTree::Punct(tt) => bridge::TokenTree::Punct(tt.0),
        TokenTree::Ident(tt) => bridge::TokenTree::Ident(tt.0),
        TokenTree::Literal(tt) => bridge::TokenTree::Literal(tt.0),
    }
}

/// 创建包含单个 token 树的 token 流。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl From<TokenTree> for TokenStream {
    fn from(tree: TokenTree) -> TokenStream {
        TokenStream(Some(bridge::client::TokenStream::from_token_tree(tree_to_bridge_tree(tree))))
    }
}

/// 非泛型助手，用于实现 `FromIterator<TokenTree>` 和 `Extend<TokenTree>`，在调用 crates 时具有较少的单态化。
///
struct ConcatTreesHelper {
    trees: Vec<
        bridge::TokenTree<
            bridge::client::TokenStream,
            bridge::client::Span,
            bridge::client::Symbol,
        >,
    >,
}

impl ConcatTreesHelper {
    fn new(capacity: usize) -> Self {
        ConcatTreesHelper { trees: Vec::with_capacity(capacity) }
    }

    fn push(&mut self, tree: TokenTree) {
        self.trees.push(tree_to_bridge_tree(tree));
    }

    fn build(self) -> TokenStream {
        if self.trees.is_empty() {
            TokenStream(None)
        } else {
            TokenStream(Some(bridge::client::TokenStream::concat_trees(None, self.trees)))
        }
    }

    fn append_to(self, stream: &mut TokenStream) {
        if self.trees.is_empty() {
            return;
        }
        stream.0 = Some(bridge::client::TokenStream::concat_trees(stream.0.take(), self.trees))
    }
}

/// 非泛型助手，用于实现 `FromIterator<TokenStream>` 和 `Extend<TokenStream>`，在调用 crates 时具有较少的单态化。
///
struct ConcatStreamsHelper {
    streams: Vec<bridge::client::TokenStream>,
}

impl ConcatStreamsHelper {
    fn new(capacity: usize) -> Self {
        ConcatStreamsHelper { streams: Vec::with_capacity(capacity) }
    }

    fn push(&mut self, stream: TokenStream) {
        if let Some(stream) = stream.0 {
            self.streams.push(stream);
        }
    }

    fn build(mut self) -> TokenStream {
        if self.streams.len() <= 1 {
            TokenStream(self.streams.pop())
        } else {
            TokenStream(Some(bridge::client::TokenStream::concat_streams(None, self.streams)))
        }
    }

    fn append_to(mut self, stream: &mut TokenStream) {
        if self.streams.is_empty() {
            return;
        }
        let base = stream.0.take();
        if base.is_none() && self.streams.len() == 1 {
            stream.0 = self.streams.pop();
        } else {
            stream.0 = Some(bridge::client::TokenStream::concat_streams(base, self.streams));
        }
    }
}

/// 将多个 token 树收集到单个流中。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl FromIterator<TokenTree> for TokenStream {
    fn from_iter<I: IntoIterator<Item = TokenTree>>(trees: I) -> Self {
        let iter = trees.into_iter();
        let mut builder = ConcatTreesHelper::new(iter.size_hint().0);
        iter.for_each(|tree| builder.push(tree));
        builder.build()
    }
}

/// 对 token 流的 "flattening" 操作将来自多个 token 流的 token 树收集到单个流中。
///
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl FromIterator<TokenStream> for TokenStream {
    fn from_iter<I: IntoIterator<Item = TokenStream>>(streams: I) -> Self {
        let iter = streams.into_iter();
        let mut builder = ConcatStreamsHelper::new(iter.size_hint().0);
        iter.for_each(|stream| builder.push(stream));
        builder.build()
    }
}

#[stable(feature = "token_stream_extend", since = "1.30.0")]
impl Extend<TokenTree> for TokenStream {
    fn extend<I: IntoIterator<Item = TokenTree>>(&mut self, trees: I) {
        let iter = trees.into_iter();
        let mut builder = ConcatTreesHelper::new(iter.size_hint().0);
        iter.for_each(|tree| builder.push(tree));
        builder.append_to(self);
    }
}

#[stable(feature = "token_stream_extend", since = "1.30.0")]
impl Extend<TokenStream> for TokenStream {
    fn extend<I: IntoIterator<Item = TokenStream>>(&mut self, streams: I) {
        let iter = streams.into_iter();
        let mut builder = ConcatStreamsHelper::new(iter.size_hint().0);
        iter.for_each(|stream| builder.push(stream));
        builder.append_to(self);
    }
}

/// `TokenStream` 类型的公共实现详细信息，例如迭代器。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub mod token_stream {
    use crate::{bridge, Group, Ident, Literal, Punct, TokenStream, TokenTree};

    /// 遍历 TokenStream 的 TokenTree 的迭代器。
    /// 迭代是 "shallow"，例如，迭代器不会递归到定界的组中，而是将整个组作为 token 树返回。
    ///
    #[derive(Clone)]
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub struct IntoIter(
        std::vec::IntoIter<
            bridge::TokenTree<
                bridge::client::TokenStream,
                bridge::client::Span,
                bridge::client::Symbol,
            >,
        >,
    );

    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    impl Iterator for IntoIter {
        type Item = TokenTree;

        fn next(&mut self) -> Option<TokenTree> {
            self.0.next().map(|tree| match tree {
                bridge::TokenTree::Group(tt) => TokenTree::Group(Group(tt)),
                bridge::TokenTree::Punct(tt) => TokenTree::Punct(Punct(tt)),
                bridge::TokenTree::Ident(tt) => TokenTree::Ident(Ident(tt)),
                bridge::TokenTree::Literal(tt) => TokenTree::Literal(Literal(tt)),
            })
        }

        fn size_hint(&self) -> (usize, Option<usize>) {
            self.0.size_hint()
        }

        fn count(self) -> usize {
            self.0.count()
        }
    }

    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    impl IntoIterator for TokenStream {
        type Item = TokenTree;
        type IntoIter = IntoIter;

        fn into_iter(self) -> IntoIter {
            IntoIter(self.0.map(|v| v.into_trees()).unwrap_or_default().into_iter())
        }
    }
}

/// `quote!(..)` 接受任意的 tokens 并扩展为描述输入的 `TokenStream`。
/// 例如，`quote!(a + b)` 将产生一个表达式，当求值时，它构造 `TokenStream` `[Ident("a"), Punct('+', Alone), Ident("b")]`。
///
///
/// 用 `$` 解引用，并通过将单个下一个标识符作为未引用的术语来工作。
/// 要引用 `$` 本身，请使用 `$$`。
#[unstable(feature = "proc_macro_quote", issue = "54722")]
#[allow_internal_unstable(proc_macro_def_site, proc_macro_internals)]
#[rustc_builtin_macro]
pub macro quote($($t:tt)*) {
    /* compiler built-in */
}

#[unstable(feature = "proc_macro_internals", issue = "27812")]
#[doc(hidden)]
mod quote;

/// 源代码区域以及宏展开信息。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
#[derive(Copy, Clone)]
pub struct Span(bridge::client::Span);

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Send for Span {}
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Sync for Span {}

macro_rules! diagnostic_method {
    ($name:ident, $level:expr) => {
        /// 使用跨度为 `self` 的给定 `message` 创建一个新的 `Diagnostic`。
        ///
        #[unstable(feature = "proc_macro_diagnostic", issue = "54140")]
        pub fn $name<T: Into<String>>(self, message: T) -> Diagnostic {
            Diagnostic::spanned(self, $level, message)
        }
    };
}

impl Span {
    /// 在宏定义站点解析的跨度。
    #[unstable(feature = "proc_macro_def_site", issue = "54724")]
    pub fn def_site() -> Span {
        Span(bridge::client::Span::def_site())
    }

    /// 当前过程宏的调用范围。
    /// 以此范围创建的标识符将被解析，就像它们是直接在宏调用位置 (调用站点卫生) 上编写的一样，宏调用站点上的其他代码也将能够引用它们。
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn call_site() -> Span {
        Span(bridge::client::Span::call_site())
    }

    /// 代表 `macro_rules` 卫生状况的跨度，有时在宏定义站点 (本地变量，标签，`$crate`) 解析，有时在宏调用站点 (其他所有解析) 解析。
    ///
    /// 跨度位置取自调用站点。
    ///
    #[stable(feature = "proc_macro_mixed_site", since = "1.45.0")]
    pub fn mixed_site() -> Span {
        Span(bridge::client::Span::mixed_site())
    }

    /// 此跨度指向的原始源文件。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn source_file(&self) -> SourceFile {
        SourceFile(self.0.source_file())
    }

    /// 上一个宏的 tokens 的 `Span` (如果有的话) 是从中生成 `self` 的。
    ///
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn parent(&self) -> Option<Span> {
        self.0.parent().map(Span)
    }

    /// 生成 `self` 的原始源代码的范围。
    /// 如果此 `Span` 不是由其他宏扩展生成的，则返回值与 `*self` 相同。
    ///
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn source(&self) -> Span {
        Span(self.0.source())
    }

    /// 返回源文件中 span 的字节位置范围。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn byte_range(&self) -> Range<usize> {
        self.0.byte_range()
    }

    /// 在源文件中获取此范围的起始 line/column。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn start(&self) -> LineColumn {
        self.0.start().add_1_to_column()
    }

    /// 在源文件中获取此跨度的结尾 line/column。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn end(&self) -> LineColumn {
        self.0.end().add_1_to_column()
    }

    /// 创建一个直接指向此跨度之前的空跨度。
    #[unstable(feature = "proc_macro_span_shrink", issue = "87552")]
    pub fn before(&self) -> Span {
        Span(self.0.before())
    }

    /// 创建一个直接指向此跨度之后的空跨度。
    #[unstable(feature = "proc_macro_span_shrink", issue = "87552")]
    pub fn after(&self) -> Span {
        Span(self.0.after())
    }

    /// 创建一个包含 `self` 和 `other` 的新跨度。
    ///
    /// 如果 `self` 和 `other` 来自不同的文件，则返回 `None`。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn join(&self, other: Span) -> Option<Span> {
        self.0.join(other.0).map(Span)
    }

    /// 创建一个具有与 `self` 相同的 line/column 信息的新跨度，但是可以像在 `other` 一样解析符号。
    ///
    #[stable(feature = "proc_macro_span_resolved_at", since = "1.45.0")]
    pub fn resolved_at(&self, other: Span) -> Span {
        Span(self.0.resolved_at(other.0))
    }

    /// 创建一个具有与 `self` 相同的名称解析行为但具有 `other` 的 line/column 信息的新跨度。
    ///
    #[stable(feature = "proc_macro_span_located_at", since = "1.45.0")]
    pub fn located_at(&self, other: Span) -> Span {
        other.resolved_at(*self)
    }

    /// 比较两个跨度以查看它们是否相等。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn eq(&self, other: &Span) -> bool {
        self.0 == other.0
    }

    /// 返回跨度后面的源文本。
    /// 这将保留原始源代码，包括空格和注释。
    /// 仅当范围与实际源代码相对应时，它才返回结果。
    ///
    /// Note: 宏的可观察结果应仅依赖于 tokens，而不依赖于此源文本。
    ///
    /// 该函数的结果是尽力而为，仅用于诊断。
    #[stable(feature = "proc_macro_source_text", since = "1.66.0")]
    pub fn source_text(&self) -> Option<String> {
        self.0.source_text()
    }

    // 由 `Span::quote` 的实现使用
    #[doc(hidden)]
    #[unstable(feature = "proc_macro_internals", issue = "27812")]
    pub fn save_span(&self) -> usize {
        self.0.save_span()
    }

    // 由 `Span::quote` 的实现使用
    #[doc(hidden)]
    #[unstable(feature = "proc_macro_internals", issue = "27812")]
    pub fn recover_proc_macro_span(id: usize) -> Span {
        Span(bridge::client::Span::recover_proc_macro_span(id))
    }

    diagnostic_method!(error, Level::Error);
    diagnostic_method!(warning, Level::Warning);
    diagnostic_method!(note, Level::Note);
    diagnostic_method!(help, Level::Help);
}

/// 以便于调试的形式打印跨度。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for Span {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.0.fmt(f)
    }
}

/// 代表 `Span` 开头或结尾的行 - 列对。
#[unstable(feature = "proc_macro_span", issue = "54725")]
#[derive(Copy, Clone, Debug, PartialEq, Eq, Hash)]
pub struct LineColumn {
    /// 源文件中跨度开始或结束 (inclusive) 的 1 索引行。
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub line: usize,
    /// 跨度开始或结束 (inclusive) 的源文件中的 1 索引列 (UTF-8 编码中的字节数)。
    ///
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub column: usize,
}

impl LineColumn {
    fn add_1_to_column(self) -> Self {
        LineColumn { line: self.line, column: self.column + 1 }
    }
}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl !Send for LineColumn {}
#[unstable(feature = "proc_macro_span", issue = "54725")]
impl !Sync for LineColumn {}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl Ord for LineColumn {
    fn cmp(&self, other: &Self) -> Ordering {
        self.line.cmp(&other.line).then(self.column.cmp(&other.column))
    }
}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl PartialOrd for LineColumn {
    fn partial_cmp(&self, other: &Self) -> Option<Ordering> {
        Some(self.cmp(other))
    }
}

/// 给定 `Span` 的源文件。
#[unstable(feature = "proc_macro_span", issue = "54725")]
#[derive(Clone)]
pub struct SourceFile(bridge::client::SourceFile);

impl SourceFile {
    /// 获取此源文件的路径。
    ///
    /// ### Note
    /// 如果与此 `SourceFile` 关联的代码跨度是由外部宏生成的，则此宏可能不是文件系统上的实际路径。
    /// 使用 [`is_real`] 进行检查。
    ///
    /// 另请注意，即使 `is_real` 返回 `true`，如果 `--remap-path-prefix` 在命令行上传递，给定的路径实际上可能无效。
    ///
    ///
    /// [`is_real`]: Self::is_real
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn path(&self) -> PathBuf {
        PathBuf::from(self.0.path())
    }

    /// 如果此源文件是真实的源文件，并且不是由外部宏的扩展生成的，则返回 `true`。
    ///
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn is_real(&self) -> bool {
        // 在实现跨度跨度之前，这是一个技巧，我们可以为外部宏中生成的跨度提供真实的源文件。
        //
        // https://github.com/rust-lang/rust/pull/43604#issuecomment-333334368
        self.0.is_real()
    }
}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl fmt::Debug for SourceFile {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("SourceFile")
            .field("path", &self.path())
            .field("is_real", &self.is_real())
            .finish()
    }
}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl PartialEq for SourceFile {
    fn eq(&self, other: &Self) -> bool {
        self.0.eq(&other.0)
    }
}

#[unstable(feature = "proc_macro_span", issue = "54725")]
impl Eq for SourceFile {}

/// 单个 token 或 token 树的定界序列 (例如 `[1, (), ..]`)。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
#[derive(Clone)]
pub enum TokenTree {
    /// 由括号定界符包围的 token 流。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Group(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Group),
    /// 标识符。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Ident(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Ident),
    /// 单个标点符号 (`+`，`,`，`$` 等)。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Punct(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Punct),
    /// 字面量字符 (`'a'`)，字符串 (`"hello"`)，数字 (`2.3`) 等。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Literal(#[stable(feature = "proc_macro_lib2", since = "1.29.0")] Literal),
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Send for TokenTree {}
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Sync for TokenTree {}

impl TokenTree {
    /// 返回此树的范围，委托给包含的 token 或分隔流的 `span` 方法。
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn span(&self) -> Span {
        match *self {
            TokenTree::Group(ref t) => t.span(),
            TokenTree::Ident(ref t) => t.span(),
            TokenTree::Punct(ref t) => t.span(),
            TokenTree::Literal(ref t) => t.span(),
        }
    }

    /// 为 *only this token* 配置范围。
    ///
    /// 请注意，如果此 token 是 `Group`，则此方法将不会配置每个内部 tokens 的跨度，这将仅委托给每个变体的 `set_span` 方法。
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn set_span(&mut self, span: Span) {
        match *self {
            TokenTree::Group(ref mut t) => t.set_span(span),
            TokenTree::Ident(ref mut t) => t.set_span(span),
            TokenTree::Punct(ref mut t) => t.set_span(span),
            TokenTree::Literal(ref mut t) => t.set_span(span),
        }
    }
}

/// 以方便调试的形式打印 token 树。
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for TokenTree {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        // 它们中的每一个在派生调试中的结构体类型中都具有名称，因此不必担心额外的间接层
        //
        match *self {
            TokenTree::Group(ref tt) => tt.fmt(f),
            TokenTree::Ident(ref tt) => tt.fmt(f),
            TokenTree::Punct(ref tt) => tt.fmt(f),
            TokenTree::Literal(ref tt) => tt.fmt(f),
        }
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl From<Group> for TokenTree {
    fn from(g: Group) -> TokenTree {
        TokenTree::Group(g)
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl From<Ident> for TokenTree {
    fn from(g: Ident) -> TokenTree {
        TokenTree::Ident(g)
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl From<Punct> for TokenTree {
    fn from(g: Punct) -> TokenTree {
        TokenTree::Punct(g)
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl From<Literal> for TokenTree {
    fn from(g: Literal) -> TokenTree {
        TokenTree::Literal(g)
    }
}

// 注意，网桥仅提供 `to_string`，基于它实现 `fmt::Display` (两者之间通常的关系相反)。
//
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl ToString for TokenTree {
    fn to_string(&self) -> String {
        match *self {
            TokenTree::Group(ref t) => t.to_string(),
            TokenTree::Ident(ref t) => t.to_string(),
            TokenTree::Punct(ref t) => t.to_string(),
            TokenTree::Literal(ref t) => t.to_string(),
        }
    }
}

/// 将 token 树打印为应该无损转换为同一 token 树 (取模跨度) 的字符串，但可能带有 `Delimiter::None` 定界符和负数字字面量的 `TokenTree::Group` 除外。
///
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for TokenTree {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.to_string())
    }
}

/// 分隔的 token 流。
///
/// `Group` 内部包含一个 `TokenStream`，该 `TokenStream` 被 `Delimiter` 包围。
#[derive(Clone)]
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub struct Group(bridge::Group<bridge::client::TokenStream, bridge::client::Span>);

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Send for Group {}
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Sync for Group {}

/// 描述如何分隔 token 树的序列。
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub enum Delimiter {
    /// `( ... )`
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Parenthesis,
    /// `{ ... }`
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Brace,
    /// `[ ... ]`
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Bracket,
    /// `Ø ... Ø`
    /// 一个不可见的分隔符，例如，可能出现在来自 "macro variable" `$var` 的 tokens 周围。
    /// 在诸如 `$var` 为 `1 + 2` 的 `$var * 3` 之类的情况下，保留操作员的优先级很重要。
    /// 不可见的分隔符可能无法在 token 流通过字符串的往返过程中幸存下来。
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    None,
}

impl Group {
    /// 使用给定的定界符和 token 流创建一个新的 `Group`。
    ///
    /// 此构造函数将将此组的跨度设置为 `Span::call_site()`。
    /// 要更改跨度，可以使用下面的 `set_span` 方法。
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn new(delimiter: Delimiter, stream: TokenStream) -> Group {
        Group(bridge::Group {
            delimiter,
            stream: stream.0,
            span: bridge::DelimSpan::from_single(Span::call_site().0),
        })
    }

    /// 返回此 `Group` 的定界符
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn delimiter(&self) -> Delimiter {
        self.0.delimiter
    }

    /// 返回在此 `Group` 中定界的 tokens 的 `TokenStream`。
    ///
    /// 请注意，返回的 token 流不包括上面返回的定界符。
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn stream(&self) -> TokenStream {
        TokenStream(self.0.stream.clone())
    }

    /// 返回此 token 流的定界符的范围，该范围跨越整个 `Group`。
    ///
    ///
    /// ```text
    /// pub fn span(&self) -> Span {
    ///            ^^^^^^^
    /// ```
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn span(&self) -> Span {
        Span(self.0.span.entire)
    }

    /// 返回指向该组的开始定界符的跨度。
    ///
    /// ```text
    /// pub fn span_open(&self) -> Span {
    ///                 ^
    /// ```
    #[stable(feature = "proc_macro_group_span", since = "1.55.0")]
    pub fn span_open(&self) -> Span {
        Span(self.0.span.open)
    }

    /// 返回指向该组的结束定界符的跨度。
    ///
    /// ```text
    /// pub fn span_close(&self) -> Span {
    ///                        ^
    /// ```
    #[stable(feature = "proc_macro_group_span", since = "1.55.0")]
    pub fn span_close(&self) -> Span {
        Span(self.0.span.close)
    }

    /// 配置此 `Group` 定界符的范围，但不配置其内部 tokens 的范围。
    ///
    /// 此方法将不设置该组所跨越的所有内部 tokens 的跨度，而只会将定界符 tokens 的跨度设置为 `Group` 的水平。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn set_span(&mut self, span: Span) {
        self.0.span = bridge::DelimSpan::from_single(span.0);
    }
}

// 注意，网桥仅提供 `to_string`，基于它实现 `fmt::Display` (两者之间通常的关系相反)。
//
#[stable(feature = "proc_macro_lib", since = "1.15.0")]
impl ToString for Group {
    fn to_string(&self) -> String {
        TokenStream::from(TokenTree::from(self.clone())).to_string()
    }
}

/// 将组打印为字符串，该字符串应无损地转换回同一组 (模跨度)，但可能带有 `Delimiter::None` 分隔符的 'TokenTree::Group' 除外。
///
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for Group {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.write_str(&self.to_string())
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for Group {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Group")
            .field("delimiter", &self.delimiter())
            .field("stream", &self.stream())
            .field("span", &self.span())
            .finish()
    }
}

/// `Punct` 是单个标点符号，例如 `+`、`-` 或 `#`。
///
/// 像 `+=` 这样的多字符运算符表示为 `Punct` 的两个实例，它们返回了不同形式的 `Spacing`。
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
#[derive(Clone)]
pub struct Punct(bridge::Punct<bridge::client::Span>);

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Send for Punct {}
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl !Sync for Punct {}

/// 描述 `Punct` 后面是紧跟另一个 `Punct` ([`Spacing::Joint`]) 还是不同的 token 或空格 ([`Spacing::Alone`])。
///
#[derive(Copy, Clone, Debug, PartialEq, Eq)]
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub enum Spacing {
    /// 一个 `Punct` 后面不会紧跟另一个 `Punct`。
    /// 例如，`+ =`、`+ident` 和 `+()` 中的 `+` 是 `Alone`。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Alone,
    /// `Punct` 紧随其后的是另一个 `Punct`。
    /// 例如，`+` 在 `+=` 和 `++` 中是 `Joint`。
    ///
    /// 此外，单引号 `'` 可以与标识符连接以形成生命周期: `'ident`。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    Joint,
}

impl Punct {
    /// 根据给定的字符和间距创建一个新的 `Punct`。
    /// `ch` 参数必须是语言允许的有效标点符号，否则函数将为 panic。
    ///
    /// 返回的 `Punct` 将具有默认范围 `Span::call_site()`，可以使用下面的 `set_span` 方法对其进行进一步配置。
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn new(ch: char, spacing: Spacing) -> Punct {
        const LEGAL_CHARS: &[char] = &[
            '=', '<', '>', '!', '~', '+', '-', '*', '/', '%', '^', '&', '|', '@', '.', ',', ';',
            ':', '#', '$', '?', '\'',
        ];
        if !LEGAL_CHARS.contains(&ch) {
            panic!("unsupported character `{:?}`", ch);
        }
        Punct(bridge::Punct {
            ch: ch as u8,
            joint: spacing == Spacing::Joint,
            span: Span::call_site().0,
        })
    }

    /// 将此标点符号的值返回为 `char`。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn as_char(&self) -> char {
        self.0.ch as char
    }

    /// 返回此标点符号的间距，指示其是否紧随 token 流中的另一个 `Punct`，以便可以将它们组合为多字符运算符 (`Joint`)，也可以将其与其他 token 或空格 (`Alone`) 组合在一起，因此该运算符肯定具有结束了。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn spacing(&self) -> Spacing {
        if self.0.joint { Spacing::Joint } else { Spacing::Alone }
    }

    /// 返回此标点符号字符的跨度。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn span(&self) -> Span {
        Span(self.0.span)
    }

    /// 配置该标点字符的跨度。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn set_span(&mut self, span: Span) {
        self.0.span = span.0;
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl ToString for Punct {
    fn to_string(&self) -> String {
        self.as_char().to_string()
    }
}

/// 将标点符号打印为字符串，该字符串应可以无损地转换回相同的字符。
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for Punct {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        write!(f, "{}", self.as_char())
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for Punct {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Punct")
            .field("ch", &self.as_char())
            .field("spacing", &self.spacing())
            .field("span", &self.span())
            .finish()
    }
}

#[stable(feature = "proc_macro_punct_eq", since = "1.50.0")]
impl PartialEq<char> for Punct {
    fn eq(&self, rhs: &char) -> bool {
        self.as_char() == *rhs
    }
}

#[stable(feature = "proc_macro_punct_eq_flipped", since = "1.52.0")]
impl PartialEq<Punct> for char {
    fn eq(&self, rhs: &Punct) -> bool {
        *self == rhs.as_char()
    }
}

/// 标识符 (`ident`)。
#[derive(Clone)]
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub struct Ident(bridge::Ident<bridge::client::Span, bridge::client::Symbol>);

impl Ident {
    /// 使用给定的 `string` 和指定的 `span` 创建新的 `Ident`。
    /// `string` 参数必须是该语言允许的有效标识符 (包括关键字，例如 `self` 或 `fn`)。否则，函数将为 panic。
    ///
    /// 请注意，当前位于 rustc 中的 `span` 为此标识符配置了卫生信息。
    ///
    /// 截止到目前，`Span::call_site()` 明确选择采用 "call-site" 卫生标准，这意味着使用该跨度创建的标识符将被解析，就好像它们直接写在宏调用的位置一样，并且宏调用站点上的其他代码将能够引用他们也是。
    ///
    ///
    /// 以后的跨度 (例如 `Span::def_site()`) 将允许选择使用 "definition-site" 卫生，这意味着用该跨度创建的标识符将在宏定义的位置解析，而宏调用站点上的其他代码将无法引用它们。
    ///
    /// 由于当前对卫生的重要性，与其他 tokens 不同，该构造函数需要在构造时指定 `Span`。
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn new(string: &str, span: Span) -> Ident {
        Ident(bridge::Ident {
            sym: bridge::client::Symbol::new_ident(string, false),
            is_raw: false,
            span: span.0,
        })
    }

    /// 与 `Ident::new` 相同，但创建原始标识符 (`r#ident`)。
    /// `string` 参数是该语言允许的有效标识符 (包括关键字，例如 `fn`)。
    /// 在路径段中可用的关键字 (例如，
    /// `self`、`super`) 不受支持，会导致 panic。
    #[stable(feature = "proc_macro_raw_ident", since = "1.47.0")]
    pub fn new_raw(string: &str, span: Span) -> Ident {
        Ident(bridge::Ident {
            sym: bridge::client::Symbol::new_ident(string, true),
            is_raw: true,
            span: span.0,
        })
    }

    /// 返回此 `Ident` 的跨度，包括 [`to_string`](ToString::to_string) 返回的整个字符串。
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn span(&self) -> Span {
        Span(self.0.span)
    }

    /// 配置此 `Ident` 的跨度，可能会更改其卫生状况。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn set_span(&mut self, span: Span) {
        self.0.span = span.0;
    }
}

/// 将标识符转换为应该可以无损转换回相同标识符的字符串。
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl ToString for Ident {
    fn to_string(&self) -> String {
        self.0.sym.with(|sym| if self.0.is_raw { ["r#", sym].concat() } else { sym.to_owned() })
    }
}

/// 将标识符打印为字符串，该字符串应可以无损地转换回相同的标识符。
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for Ident {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        if self.0.is_raw {
            f.write_str("r#")?;
        }
        fmt::Display::fmt(&self.0.sym, f)
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for Ident {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Ident")
            .field("ident", &self.to_string())
            .field("span", &self.span())
            .finish()
    }
}

/// 字符串字面量 (`"hello"`)，字节字符串 (`b"hello"`)，字符 (`'a'`)，字节字符 (`b'a'`)，带或不带后缀 ('1'，`1u8`，`2.3`，`2.3f32`) 的整数或浮点数。
///
/// `true` 和 `false` 之类的布尔字面量在这里不属于它们，它们是 `Ident`。
///
#[derive(Clone)]
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
pub struct Literal(bridge::Literal<bridge::client::Span, bridge::client::Symbol>);

macro_rules! suffixed_int_literals {
    ($($name:ident => $kind:ident,)*) => ($(
        /// 用指定的值创建一个新的后缀整数字面量。
        ///
        /// 此函数将创建一个类似于 `1u32` 的整数，其中指定的整数值是 token 的第一部分，并且整数也以结尾加后缀。
        /// 从负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
        ///
        ///
        /// 通过此方法创建的字面量默认情况下具有 `Span::call_site()` 跨度，可以使用以下 `set_span` 方法进行配置。
        ///
        ///
        ///
        ///
        #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
        pub fn $name(n: $kind) -> Literal {
            Literal(bridge::Literal {
                kind: bridge::LitKind::Integer,
                symbol: bridge::client::Symbol::new(&n.to_string()),
                suffix: Some(bridge::client::Symbol::new(stringify!($kind))),
                span: Span::call_site().0,
            })
        }
    )*)
}

macro_rules! unsuffixed_int_literals {
    ($($name:ident => $kind:ident,)*) => ($(
        /// 用指定的值创建一个新的无后缀的整数字面量。
        ///
        /// 此函数将创建一个类似于 `1` 的整数，其中指定的整数值是 token 的第一部分。
        /// 在此 token 上未指定后缀，这意味着像 `Literal::i8_unsuffixed(1)` 这样的调用等效于 `Literal::u32_unsuffixed(1)`。
        /// 由负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
        ///
        ///
        /// 通过此方法创建的字面量默认情况下具有 `Span::call_site()` 跨度，可以使用以下 `set_span` 方法进行配置。
        ///
        ///
        ///
        ///
        ///
        #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
        pub fn $name(n: $kind) -> Literal {
            Literal(bridge::Literal {
                kind: bridge::LitKind::Integer,
                symbol: bridge::client::Symbol::new(&n.to_string()),
                suffix: None,
                span: Span::call_site().0,
            })
        }
    )*)
}

impl Literal {
    fn new(kind: bridge::LitKind, value: &str, suffix: Option<&str>) -> Self {
        Literal(bridge::Literal {
            kind,
            symbol: bridge::client::Symbol::new(value),
            suffix: suffix.map(bridge::client::Symbol::new),
            span: Span::call_site().0,
        })
    }

    suffixed_int_literals! {
        u8_suffixed => u8,
        u16_suffixed => u16,
        u32_suffixed => u32,
        u64_suffixed => u64,
        u128_suffixed => u128,
        usize_suffixed => usize,
        i8_suffixed => i8,
        i16_suffixed => i16,
        i32_suffixed => i32,
        i64_suffixed => i64,
        i128_suffixed => i128,
        isize_suffixed => isize,
    }

    unsuffixed_int_literals! {
        u8_unsuffixed => u8,
        u16_unsuffixed => u16,
        u32_unsuffixed => u32,
        u64_unsuffixed => u64,
        u128_unsuffixed => u128,
        usize_unsuffixed => usize,
        i8_unsuffixed => i8,
        i16_unsuffixed => i16,
        i32_unsuffixed => i32,
        i64_unsuffixed => i64,
        i128_unsuffixed => i128,
        isize_unsuffixed => isize,
    }

    /// 创建一个新的不带后缀的浮点字面量。
    ///
    /// 此构造函数类似于 `Literal::i8_unsuffixed`，后者将 float 的值直接发出到 token 中，但不使用后缀，因此可以在以后的编译器中推断出它是 `f64`。
    ///
    /// 由负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
    ///
    /// # Panics
    ///
    /// 此函数要求指定的浮点数是有限的，例如，如果它是无穷大或 NaN，则此函数将为 panic。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn f32_unsuffixed(n: f32) -> Literal {
        if !n.is_finite() {
            panic!("Invalid float literal {n}");
        }
        let mut repr = n.to_string();
        if !repr.contains('.') {
            repr.push_str(".0");
        }
        Literal::new(bridge::LitKind::Float, &repr, None)
    }

    /// 创建一个新的后缀浮点字面量。
    ///
    /// 该构造函数将创建一个像 `1.0f32` 这样的字面量，其中指定的值是 token 的前一部分，而 `f32` 是 token 的后缀。
    /// token 在编译器中将始终被推断为 `f32`。
    /// 由负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
    ///
    ///
    /// # Panics
    ///
    /// 此函数要求指定的浮点数是有限的，例如，如果它是无穷大或 NaN，则此函数将为 panic。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn f32_suffixed(n: f32) -> Literal {
        if !n.is_finite() {
            panic!("Invalid float literal {n}");
        }
        Literal::new(bridge::LitKind::Float, &n.to_string(), Some("f32"))
    }

    /// 创建一个新的不带后缀的浮点字面量。
    ///
    /// 此构造函数类似于 `Literal::i8_unsuffixed`，后者将 float 的值直接发出到 token 中，但不使用后缀，因此可以在以后的编译器中推断出它是 `f64`。
    ///
    /// 由负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
    ///
    /// # Panics
    ///
    /// 此函数要求指定的浮点数是有限的，例如，如果它是无穷大或 NaN，则此函数将为 panic。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn f64_unsuffixed(n: f64) -> Literal {
        if !n.is_finite() {
            panic!("Invalid float literal {n}");
        }
        let mut repr = n.to_string();
        if !repr.contains('.') {
            repr.push_str(".0");
        }
        Literal::new(bridge::LitKind::Float, &repr, None)
    }

    /// 创建一个新的后缀浮点字面量。
    ///
    /// 该构造函数将创建一个像 `1.0f64` 这样的字面量，其中指定的值是 token 的前一部分，而 `f64` 是 token 的后缀。
    /// token 在编译器中将始终被推断为 `f64`。
    /// 由负数创建的字面量可能无法通过 `TokenStream` 或字符串进行往返，并且可能会分解为两个 tokens (`-` 和正字面量)。
    ///
    ///
    /// # Panics
    ///
    /// 此函数要求指定的浮点数是有限的，例如，如果它是无穷大或 NaN，则此函数将为 panic。
    ///
    ///
    ///
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn f64_suffixed(n: f64) -> Literal {
        if !n.is_finite() {
            panic!("Invalid float literal {n}");
        }
        Literal::new(bridge::LitKind::Float, &n.to_string(), Some("f64"))
    }

    /// 字符串字面量。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn string(string: &str) -> Literal {
        let quoted = format!("{:?}", string);
        assert!(quoted.starts_with('"') && quoted.ends_with('"'));
        let symbol = &quoted[1..quoted.len() - 1];
        Literal::new(bridge::LitKind::Str, symbol, None)
    }

    /// 字符字面量。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn character(ch: char) -> Literal {
        let quoted = format!("{:?}", ch);
        assert!(quoted.starts_with('\'') && quoted.ends_with('\''));
        let symbol = &quoted[1..quoted.len() - 1];
        Literal::new(bridge::LitKind::Char, symbol, None)
    }

    /// 字节字符串字面量。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn byte_string(bytes: &[u8]) -> Literal {
        let string = bytes.escape_ascii().to_string();
        Literal::new(bridge::LitKind::ByteStr, &string, None)
    }

    /// 返回包含此字面量的范围。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn span(&self) -> Span {
        Span(self.0.span)
    }

    /// 配置与此字面量关联的范围。
    #[stable(feature = "proc_macro_lib2", since = "1.29.0")]
    pub fn set_span(&mut self, span: Span) {
        self.0.span = span.0;
    }

    /// 返回 `Span`，它是 `self.span()` 的子集，仅包含范围 `range` 中的源字节。
    /// 如果要修剪的跨度超出 `self` 的边界，则返回 `None`。
    ///
    // FIXME(SergioBenitez): 检查字节范围是否在源的 UTF-8 边界开始和结束。
    // 否则，在打印源文本时，panic 可能会出现在其他位置。
    // FIXME(SergioBenitez): 用户无法知道 `self.span()` 实际映射成什么，因此当前只能盲目调用此方法。
    // 例如，字符 'c' 的 `to_string()` 返回 "'\u{63}'"； 用户无法知道源文本是 'c' 还是 '\u{63}'。
    //
    //
    //
    //
    #[unstable(feature = "proc_macro_span", issue = "54725")]
    pub fn subspan<R: RangeBounds<usize>>(&self, range: R) -> Option<Span> {
        self.0.span.subspan(range.start_bound().cloned(), range.end_bound().cloned()).map(Span)
    }

    fn with_symbol_and_suffix<R>(&self, f: impl FnOnce(&str, &str) -> R) -> R {
        self.0.symbol.with(|symbol| match self.0.suffix {
            Some(suffix) => suffix.with(|suffix| f(symbol, suffix)),
            None => f(symbol, ""),
        })
    }

    /// 使用由字面量表示的每个部分组成的 `&[&str]` 调用回调。
    /// 这样做是为了允许 `ToString` 和 `Display` 实现借用引用到符号值，并且都经过优化以减少开销。
    ///
    ///
    fn with_stringify_parts<R>(&self, f: impl FnOnce(&[&str]) -> R) -> R {
        /// 返回正好包含 `num` '#' 字符的字符串。
        /// 使用 256 个字符的源字符串字面量，它始终可以安全地使用 `u8` 索引进行索引。
        ///
        fn get_hashes_str(num: u8) -> &'static str {
            const HASHES: &str = "\
            ################################################################\
            ################################################################\
            ################################################################\
            ################################################################\
            ";
            const _: () = assert!(HASHES.len() == 256);
            &HASHES[..num as usize]
        }

        self.with_symbol_and_suffix(|symbol, suffix| match self.0.kind {
            bridge::LitKind::Byte => f(&["b'", symbol, "'", suffix]),
            bridge::LitKind::Char => f(&["'", symbol, "'", suffix]),
            bridge::LitKind::Str => f(&["\"", symbol, "\"", suffix]),
            bridge::LitKind::StrRaw(n) => {
                let hashes = get_hashes_str(n);
                f(&["r", hashes, "\"", symbol, "\"", hashes, suffix])
            }
            bridge::LitKind::ByteStr => f(&["b\"", symbol, "\"", suffix]),
            bridge::LitKind::ByteStrRaw(n) => {
                let hashes = get_hashes_str(n);
                f(&["br", hashes, "\"", symbol, "\"", hashes, suffix])
            }
            _ => f(&[symbol, suffix]),
        })
    }
}

/// 从字符串化表示中解析单个字面量。
///
/// 为了成功解析，输入字符串不能包含除字面量 token 之外的任何内容。
///
/// 具体来说，它不能包含除字面量之外的空格或注释。
///
/// 生成的字面量 token 将具有 `Span::call_site()` span。
///
/// NOTE: 某些错误可能导致 panics 而不是返回 `LexError`。
/// 我们保留稍后将这些错误更改为 LexError 的权利。
#[stable(feature = "proc_macro_literal_parse", since = "1.54.0")]
impl FromStr for Literal {
    type Err = LexError;

    fn from_str(src: &str) -> Result<Self, LexError> {
        match bridge::client::FreeFunctions::literal_from_str(src) {
            Ok(literal) => Ok(Literal(literal)),
            Err(()) => Err(LexError),
        }
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl ToString for Literal {
    fn to_string(&self) -> String {
        self.with_stringify_parts(|parts| parts.concat())
    }
}

/// 将字面量打印为一个字符串，该字符串应可以无损地转换回相同的字面量 (但浮点型字面量的可能取整除外)。
///
#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Display for Literal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        self.with_stringify_parts(|parts| {
            for part in parts {
                fmt::Display::fmt(part, f)?;
            }
            Ok(())
        })
    }
}

#[stable(feature = "proc_macro_lib2", since = "1.29.0")]
impl fmt::Debug for Literal {
    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
        f.debug_struct("Literal")
            // 即使在 {:#?} 模式下，也可以在一行上格式化类型
            .field("kind", &format_args!("{:?}", &self.0.kind))
            .field("symbol", &self.0.symbol)
            // 即使在 {:#?} 模式下，也可以在一行上格式化 `Some("...")`
            .field("suffix", &format_args!("{:?}", &self.0.suffix))
            .field("span", &self.0.span)
            .finish()
    }
}

/// 跟踪对环境变量的访问。
#[unstable(feature = "proc_macro_tracked_env", issue = "99515")]
pub mod tracked_env {
    use std::env::{self, VarError};
    use std::ffi::OsStr;

    /// 检索环境变量并将其添加以构建依赖项信息。
    /// 执行编译器的构建系统将知道在编译期间访问了该变量，并且能够在该变量的值更改时重新运行构建。
    ///
    /// 除了依赖项跟踪之外，此函数应与标准库中的 `env::var` 等效，除了参数必须为 UTF-8。
    ///
    #[unstable(feature = "proc_macro_tracked_env", issue = "99515")]
    pub fn var<K: AsRef<OsStr> + AsRef<str>>(key: K) -> Result<String, VarError> {
        let key: &str = key.as_ref();
        let value = env::var(key);
        crate::bridge::client::FreeFunctions::track_env_var(key, value.as_deref().ok());
        value
    }
}

/// 跟踪对其他文件的访问。
#[unstable(feature = "track_path", issue = "99515")]
pub mod tracked_path {

    /// 明确跟踪文件。
    ///
    /// 通常用于跟踪资源预处理。
    #[unstable(feature = "track_path", issue = "99515")]
    pub fn path<P: AsRef<str>>(path: P) {
        let path: &str = path.as_ref();
        crate::bridge::client::FreeFunctions::track_path(path);
    }
}