//! Rustc 用于手写 MIR 的内部工具。
//!
//! 如果由于某些原因您没有编写 rustc 测试，并且发现自己正在考虑使用此特性，那么请返回。这是*非常*不稳定的。
//! 除了 rustc 测试套件恰好需要的那些东西之外，根本没有尝试使任何东西工作。
//! 如果您打错字，您可能会 ICE。
//! 真的，这不是解决您问题的方法。
//! 考虑改为支持 [稳定的 MIR 项目组](https://github.com/rust-lang/project-stable-mir)。
//!
//! 此模块的文档描述了如何使用此特性。
//! 如果您有兴趣破解实现，大部分文档都位于 `rustc_mir_build/src/build/custom/mod.rs`。
//!
//! 典型用法如下所示:
//!
//! ```rust
//! #![feature(core_intrinsics, custom_mir)]
//!
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! pub fn simple(x: i32) -> i32 {
//!     mir!(
//!         let temp2: i32;
//!
//!         {
//!             let temp1 = x;
//!             Goto(my_second_block)
//!         }
//!
//!         my_second_block = {
//!             temp2 = Move(temp1);
//!             RET = temp2;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! `custom_mir` 属性告诉编译器将函数视为自定义 MIR。
//! 此属性仅适用于函数 - 无法将自定义 MIR 插入另一个函数的中间。
//! `dialect` 和 `phase` 参数指示您要在此处插入哪个 [version of MIR][dialect docs]。
//! 一般来说，如果您希望您的 MIR 被完整的 MIR 管道修改，您将希望使用 `#![custom_mir(dialect = "built")]`，如果您不希望使用 `#![custom_mir(dialect = "runtime", phase = "optimized")]`。
//!
//!
//! [dialect docs]:
//!     https://doc.rust-lang.org/nightly/nightly-rustc/rustc_middle/mir/enum.MirPhase.html
//!
//! [`mir!`] 宏的输入是:
//!
//!  - `type RET = ...;` 形式的可选返回类注解。如果编译器无法推断 RET 的类型，则可能需要这样做。
//!  - 一个可能为空的本地声明列表。局部变量也可以通过 `let` 声明为内联赋值。类型推断通常有效。阴影没有。
//!  - 基本块列表。其中第一个是开始块，是执行开始的地方。
//!    除了起始块之外的所有块都需要命名，以便以后可以引用它们。
//!     - 每个块都是一个以分号结尾的语句列表，后跟一个终止符。
//!     各种语言句法和终止符的语法被设计为与原生 Rust 中类似概念的语法尽可能相似。
//!     请参见下面的列表。
//!
//! # Examples
//!
//! ```rust
//! #![feature(core_intrinsics, custom_mir)]
//!
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! pub fn choose_load(a: &i32, b: &i32, c: bool) -> i32 {
//!     mir!(
//!         {
//!             match c {
//!                 true => t,
//!                 _ => f,
//!             }
//!         }
//!
//!         t = {
//!             let temp = a;
//!             Goto(load_and_exit)
//!         }
//!
//!         f = {
//!             temp = b;
//!             Goto(load_and_exit)
//!         }
//!
//!         load_and_exit = {
//!             RET = *temp;
//!             Return()
//!         }
//!     )
//! }
//!
//! #[custom_mir(dialect = "built")]
//! fn unwrap_unchecked<T>(opt: Option<T>) -> T {
//!     mir!({
//!         RET = Move(Field(Variant(opt, 1), 0));
//!         Return()
//!     })
//! }
//!
//! #[custom_mir(dialect = "runtime", phase = "optimized")]
//! fn push_and_pop<T>(v: &mut Vec<T>, value: T) {
//!     mir!(
//!         let unused;
//!         let popped;
//!
//!         {
//!             Call(unused, pop, Vec::push(v, value))
//!         }
//!
//!         pop = {
//!             Call(popped, drop, Vec::pop(v))
//!         }
//!
//!         drop = {
//!             Drop(popped, ret)
//!         }
//!
//!         ret = {
//!             Return()
//!         }
//!     )
//! }
//!
//! #[custom_mir(dialect = "runtime", phase = "optimized")]
//! fn annotated_return_type() -> (i32, bool) {
//!     mir!(
//!         type RET = (i32, bool);
//!         {
//!             RET.0 = 1;
//!             RET.1 = true;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! 我们还可以触发在编译器足够晚的阶段发生的编译失败:
//!
//! ```rust,compile_fail
//! #![feature(core_intrinsics, custom_mir)]
//!
//! extern crate core;
//! use core::intrinsics::mir::*;
//!
//! #[custom_mir(dialect = "built")]
//! fn borrow_error(should_init: bool) -> i32 {
//!     mir!(
//!         let temp: i32;
//!
//!         {
//!             match should_init {
//!                 true => init,
//!                 _ => use_temp,
//!             }
//!         }
//!
//!         init = {
//!             temp = 0;
//!             Goto(use_temp)
//!         }
//!
//!         use_temp = {
//!             RET = temp;
//!             Return()
//!         }
//!     )
//! }
//! ```
//!
//! ```text
//! error[E0381]: used binding is possibly-uninitialized
//!   --> test.rs:24:13
//!    |
//! 8  | /     mir!(
//! 9  | |         let temp: i32;
//! 10 | |
//! 11 | |         {
//! ...  |
//! 19 | |             temp = 0;
//!    | |             -------- binding initialized here in some conditions
//! ...  |
//! 24 | |             RET = temp;
//!    | |             ^^^^^^^^^^ value used here but it is possibly-uninitialized
//! 25 | |             Return()
//! 26 | |         }
//! 27 | |     )
//!    | |_____- binding declared here but left uninitialized
//!
//! error: aborting due to previous error
//!
//! For more information about this error, try `rustc --explain E0381`.
//! ```
//!
//! # Syntax
//!
//! 下面的列表详尽地描述了如何创建各种 MIR 构造。
//! 列表中遗漏的任何内容都应假定为不受支持，欢迎 PR。
//!
//! #### Locals
//!
//!  - `_0` 返回本地始终可以通过 `RET` 访问。
//!  - 参数可以通过他们的常规名称访问。
//!  - 所有其他局部变量都需要在某处用 `let` 声明，然后才能通过名称访问。
//!
//! #### Places
//!  - 本地人隐式转换为地点。
//!  - 字段访问、解引用和索引工作正常。
//!  - 变体中的字段可以通过 [`Variant`] 和 [`Field`] 关联函数访问，请参见它们的文档以获取详细信息。
//!
//! #### Operands
//!  - 地方隐式转换为 `Copy` 操作数。
//!  - `Move` 操作数可以通过 [`Move`] 创建。
//!  - Const 块、字面量、命名常量和 const 参数都可以正常工作。
//!  - [`Static`] 和 [`StaticMut`] 可用于创建 `&T` 和 `*mut T` 到静态。这些是 MIR 中的常量，也是访问静态的唯一方法。
//!
//! #### Statements
//!  - 通过正常的 Rust 分配分配语言句子工作。
//!  - [`Retag`], [`StorageLive`], [`StorageDead`], [`Deinit`] 语句有一个关联函数。
//!
//! #### Rvalues
//!
//!  - 操作数隐式转换为 `Use` 右值。
//!  - `&`、`&mut`、`addr_of!` 和 `addr_of_mut!` 都用于创建其关联的右值。
//!  - [`Discriminant`]、[`Len`]、[`CopyForDeref`] 具有关联的函数。
//!  - 一元和二元运算使用其正常的 Rust 语法 --`a * b`、`!c` 等。
//!  - 二元运算 `Offset` 可以通过 [`Offset`] 创建。
//!  - 已检查的二进制操作通过将关联的 binop 包装在 [`Checked`] 中来表示。
//!  - 数组重复语法 (`[foo; 10]`) 创建关联的右值。
//!
//! #### Terminators
//!
//! 自定义 MIR 当前不支持清理块或非平凡展开路径。
//! 因此，没有恢复和中止终结符，并且，可能展开的终结符没有任何方式指示展开块。
//!
//!  - [`Goto`]、[`Return`]、[`Unreachable`]、[`Drop`](Drop()) 有关联函数。
//!  - `match some_int_operand` 变成 `SwitchInt`。每个 arm 应该是 `literal => basic_block`
//!     - 例外的是最后一个 arm，它必须是 `_ => basic_block`，并且对应于 otherwise 分支。
//!  - [`Call`] 也有一个关联函数。该函数的第三个参数是一个普通的函数调用表达式，例如 `my_other_function(a, 5)`。
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!
//!

#![unstable(
    feature = "custom_mir",
    reason = "MIR is an implementation detail and extremely unstable",
    issue = "none"
)]
#![allow(unused_variables, non_snake_case, missing_debug_implementations)]

/// 表示基本块的类型。
///
/// 所有终止符都将此类型作为返回类型。它有助于实现某种类型的安全性。
pub struct BasicBlock;

macro_rules! define {
    ($name:literal, $( #[ $meta:meta ] )* fn $($sig:tt)*) => {
        #[rustc_diagnostic_item = $name]
        #[inline]
        $( #[ $meta ] )*
        pub fn $($sig)* { panic!() }
    }
}

define!("mir_return", fn Return() -> BasicBlock);
define!("mir_goto", fn Goto(destination: BasicBlock) -> BasicBlock);
define!("mir_unreachable", fn Unreachable() -> BasicBlock);
define!("mir_drop", fn Drop<T>(place: T, goto: BasicBlock));
define!("mir_call", fn Call<T>(place: T, goto: BasicBlock, call: T));
define!("mir_storage_live", fn StorageLive<T>(local: T));
define!("mir_storage_dead", fn StorageDead<T>(local: T));
define!("mir_deinit", fn Deinit<T>(place: T));
define!("mir_checked", fn Checked<T>(binop: T) -> (T, bool));
define!("mir_len", fn Len<T>(place: T) -> usize);
define!("mir_copy_for_deref", fn CopyForDeref<T>(place: T) -> T);
define!("mir_retag", fn Retag<T>(place: T));
define!("mir_move", fn Move<T>(place: T) -> T);
define!("mir_static", fn Static<T>(s: T) -> &'static T);
define!("mir_static_mut", fn StaticMut<T>(s: T) -> *mut T);
define!(
    "mir_discriminant",
    /// 获取一个地方的判别式。
    fn Discriminant<T>(place: T) -> <T as ::core::marker::DiscriminantKind>::Discriminant
);
define!("mir_set_discriminant", fn SetDiscriminant<T>(place: T, index: u32));
define!("mir_offset", fn Offset<T, U>(ptr: T, count: U) -> T);
define!(
    "mir_field",
    /// 访问具有某个地方的给定索引的字段。
    ///
    /// 这只有与 [`Variant`] 结合使用才有意义。
    /// 如果您要访问的字段的类型没有变体，您可以使用普通字段投影语法。
    ///
    /// 在 Rust 中没有对变体进行位置投影的正确方法，因此这两个函数是一种解决方法。
    /// 您可以通过 `Field(Variant(place, var_idx), field_idx)` 访问变体的字段，其中 `var_idx` 和 `field_idx` 是合适的字面量。
    /// 一些警告:
    ///
    ///  - `Variant` 的返回类型始终为 `()`。不用担心，仍然会生成正确的 MIR。
    ///  - 在某些情况下，无法推断 `Field` 的返回类型。在这些情况下，您可能需要在函数上注解。
    ///  - 由于 `Field` 是一个函数调用，它不是一个位置表达式，因此在表达式的左侧使用它会被编译器拒绝。
    ///
    ///  [`place!`] 是为解决该问题而提供的宏。
    ///  将赋值的左侧包裹在宏中，以说服编译器它没问题。
    ///
    /// # Examples
    ///
    /// ```rust
    /// #![feature(custom_mir, core_intrinsics)]
    ///
    /// use core::intrinsics::mir::*;
    ///
    /// #[custom_mir(dialect = "built")]
    /// fn unwrap_deref(opt: Option<&i32>) -> i32 {
    ///     mir!({
    ///         RET = *Field::<&i32>(Variant(opt, 1), 0);
    ///         Return()
    ///     })
    /// }
    ///
    /// #[custom_mir(dialect = "built")]
    /// fn set(opt: &mut Option<i32>) {
    ///     mir!({
    ///         place!(Field(Variant(*opt, 1), 0)) = 5;
    ///         Return()
    ///     })
    /// }
    /// ```
    ///
    ///
    ///
    fn Field<F>(place: (), field: u32) -> F
);
define!(
    "mir_variant",
    /// 将具有给定索引的变体投影添加到该位置。
    ///
    /// 有关文档，请参见 [`Field`]。
    fn Variant<T>(place: T, index: u32) -> ()
);
define!(
    "mir_cast_transmute",
    /// 触发一个 `CastKind::Transmute` cast。
    ///
    /// `sizeof(T) != sizeof(U)` 时需要测试 UB，普通 `mem::transmute` 无法生成。
    ///
    fn CastTransmute<T, U>(operand: T) -> U
);
define!(
    "mir_make_place",
    #[doc(hidden)]
    fn __internal_make_place<T>(place: T) -> *mut T
);

/// 用于生成自定义 MIR。
///
/// 有关语法详细信息，请参见模块文档。
/// 这个宏并不神奇 -- 它只是将您的 MIR 转换成更容易在编译器中解析的东西。
#[rustc_macro_transparency = "transparent"]
pub macro mir {
    (
        $(type RET = $ret_ty:ty ;)?
        $(let $local_decl:ident $(: $local_decl_ty:ty)? ;)*

        {
            $($entry:tt)*
        }

        $(
            $block_name:ident = {
                $($block:tt)*
            }
        )*
    ) => {{
        // 首先，我们声明所有基本块。
        $(
            let $block_name: ::core::intrinsics::mir::BasicBlock;
        )*

        {
            // 现在都是局部的
            #[allow(non_snake_case)]
            let RET $(: $ret_ty)?;
            $(
                let $local_decl $(: $local_decl_ty)? ;
            )*

            ::core::intrinsics::mir::__internal_extract_let!($($entry)*);
            $(
                ::core::intrinsics::mir::__internal_extract_let!($($block)*);
            )*

            {
                // 最后是基本块的内容
                ::core::intrinsics::mir::__internal_remove_let!({
                    {}
                    { $($entry)* }
                });
                $(
                    ::core::intrinsics::mir::__internal_remove_let!({
                        {}
                        { $($block)* }
                    });
                )*

                RET
            }
        }
    }}
}

/// Helper 宏允许您将值表达式视为位置表达式。
///
/// 请参见 [`Variant`] 上的文档了解为什么这是必要的以及如何使用它。
pub macro place($e:expr) {
    (*::core::intrinsics::mir::__internal_make_place($e))
}

/// 从一堆语言中提取 `let` 声明的助手宏。
///
/// 这个宏是用 "statement muncher" 策略写的。
/// 每次调用都会从输入中解析出第一条语句，对其执行适当的操作，然后对输入的其余部分递归调用相同的宏。
///
#[doc(hidden)]
pub macro __internal_extract_let {
    // 如果是类似 `let` 的语句，则保留 `let`
    (
        let $var:ident $(: $ty:ty)? = $expr:expr; $($rest:tt)*
    ) => {
        let $var $(: $ty)?;
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    // 由于 #86730，我们必须单独处理 const 块
    (
        let $var:ident $(: $ty:ty)? = const $block:block; $($rest:tt)*
    ) => {
        let $var $(: $ty)?;
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    // 否则什么都不输出
    (
        $stmt:stmt; $($rest:tt)*
    ) => {
        ::core::intrinsics::mir::__internal_extract_let!($($rest)*);
    },
    (
        $expr:expr
    ) => {}
}

/// 从一堆语言中删除 `let` 声明的助手宏。
/// 因为表达式位置宏不能展开成语句 + 表达式，这里需要稍微有点创意。一般的策略也是像上面一样的语句咀嚼，但是在随后的宏调用中宏的输出是 "stored"。通过示例最容易理解:
///
/// ```text
/// invoke!(
///     {
///         {
///             x = 5;
///         }
///         {
///             let d = e;
///             Call()
///         }
///     }
/// )
/// ```
///
/// becomes
///
/// ```text
/// invoke!(
///     {
///         {
///             x = 5;
///             d = e;
///         }
///         {
///             Call()
///         }
///     }
/// )
/// ```
#[doc(hidden)]
pub macro __internal_remove_let {
    // 如果是类似 `let` 的语句，去掉 `let`
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                let $var:ident $(: $ty:ty)? = $expr:expr;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $var = $expr;
            }
            {
                $($rest)*
            }
        }
    )},
    // 由于 #86730，我们必须单独处理 const 块
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                let $var:ident $(: $ty:ty)? = const $block:block;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $var = const $block;
            }
            {
                $($rest)*
            }
        }
    )},
    // 否则，继续
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                $stmt:stmt;
                $($rest:tt)*
            }
        }
    ) => { ::core::intrinsics::mir::__internal_remove_let!(
        {
            {
                $($already_parsed)*
                $stmt;
            }
            {
                $($rest)*
            }
        }
    )},
    (
        {
            {
                $($already_parsed:tt)*
            }
            {
                $expr:expr
            }
        }
    ) => {
        {
            $($already_parsed)*
            $expr
        }
    },
}