rust_zw3d/

lib.rs

//! ZW3D SDK 的 Rust 绑定
//!
//! `rust-zw3d` 为 ZW3D CAD 软件提供了安全、惯用的 Rust API 封装。
//!
//! ## 架构
//!
//! - **[`raw`]** - 原始 FFI 绑定（来自 `rust-zw3d-raw` crate）
//! - **[`editor`]** - 编辑器交互功能（消息显示、用户输入等）
//! - **[`commands`]** - 命令和回调注册（通常由宏自动调用）
//!
//! ## 快速开始
//!
//! ### 创建一个简单的命令
//!
//! ```rust,ignore
//! use rust_zw3d::{*, editor};
//!
//! #[cmd]
//! fn hello(_code: i32) -> i32 {
//!     editor::msg_disp("Hello from Rust!");
//!     0
//! }
//!
//! // 生成模块进出点
//! zw3d_module!(my_plugin);
//! ```
//!
//! ### 编辑器交互
//!
//! ```rust,ignore
//! use rust_zw3d::editor;
//!
//! #[cmd]
//! fn interactive_command(_code: i32) -> i32 {
//!     // 显示消息
//!     editor::msg_disp("请输入角度");
//!     
//!     // 获取用户输入
//!     match editor::get_angle("旋转角度:", 90.0) {
//!         Ok(angle) => {
//!             editor::msg_disp(&format!("旋转 {} 度", angle));
//!             // 执行旋转操作...
//!             0
//!         }
//!         Err(_) => {
//!             editor::msg_disp("操作已取消");
//!             1
//!         }
//!     }
//! }
//! ```
//!
//! ## 特性
//!
//! - ✅ 自动中文支持（GBK ↔ UTF-8 转换）
//! - ✅ 类型安全的宏系统
//! - ✅ Rust 风格的 API 封装
//! - ✅ 完整的 FFI 绑定访问
//!
//! ## 相关 Crate
//!
//! - [`rust-zw3d-raw`](https://docs.rs/rust-zw3d-raw) - 原始 FFI 绑定
//! - [`rust-zw3d-macros`](https://docs.rs/rust-zw3d-macros) - 过程宏
//! - [`rust-zw3d-build`](https://docs.rs/rust-zw3d-build) - 构建工具

/// 重导出原始 FFI 绑定
///
/// 通过 `rust_zw3d::raw` 可以访问所有底层 ZW3D C API。
///
/// # Examples
///
/// ```rust,ignore
/// use rust_zw3d::raw;
///
/// // 直接调用原始 API
/// unsafe {
///     raw::cvxPartInqActive(&mut id);
/// }
/// ```
pub use rust_zw3d_raw as raw;

/// 字符串编码转换（内部使用）
mod encoding;

/// 错误类型定义
pub mod error;

/// 编辑器交互功能
///
/// 提供与 ZW3D 编辑器交互的高层封装。
pub mod editor;

/// 命令和回调注册（内部函数）
///
/// 此模块中的函数通常由宏自动调用，不需要手动使用。
pub mod commands;

// 重导出 commands 模块的内容，保持向后兼容
pub use commands::*;

// 重导出错误类型，方便使用
pub use error::{ZwError, ZwResult};

/// 当前编译所针对的 ZW3D SDK 主版本
pub const SDK_VERSION: &str = raw::SDK_VERSION;

/// 重导出 inventory 与 paste，供宏展开时通过 ::rust_zw3d::<crate> 访问
#[doc(hidden)]
pub use inventory;
#[doc(hidden)]
pub use paste;

// 重导出字符串转换辅助函数，供宏生成的代码使用
#[doc(hidden)]
pub use encoding::{from_gbk_cstr, to_gbk_bytes};

/// 当开启 `macros` feature 时，重导出属性宏
#[cfg(feature = "macros")]
pub use rust_zw3d_macros::{callback, cmd};

/// 命令条目，用于 `inventory` 收集并在运行时统一注册。
///
/// 这个结构体由 `#[cmd]` 宏自动生成，通常不需要手动创建。
#[derive(Copy, Clone)]
pub struct Command {
    /// 命令名称
    pub name: &'static str,
    /// 命令函数指针
    pub func: *mut core::ffi::c_void,
    /// 命令代码/类别
    pub code: f64,
}

unsafe impl Sync for Command {}

inventory::collect!(Command);

/// 回调条目，用于 `inventory` 收集并在运行时统一注册。
///
/// 这个结构体由 `#[callback]` 宏自动生成，通常不需要手动创建。
#[derive(Copy, Clone)]
pub struct Callback {
    /// 回调名称
    pub name: &'static str,
    /// 回调函数指针
    pub func: *mut core::ffi::c_void,
}

unsafe impl Sync for Callback {}

inventory::collect!(Callback);

/// 批量注册由 `#[cmd]` 收集到的所有命令。
#[macro_export]
macro_rules! register_commands {
    () => {{
        inventory::iter::<rust_zw3d::Command>().for_each(|cmd| {
            rust_zw3d::commands::cvxCmdFunc(cmd.name, cmd.func, cmd.code);
        });
    }};
}

/// 批量注册由 `#[callback]` 收集到的所有回调。
#[macro_export]
macro_rules! register_callbacks {
    () => {{
        inventory::iter::<rust_zw3d::Callback>().for_each(|cb| {
            rust_zw3d::commands::cvxCmdCallback(cb.name, cb.func);
        });
    }};
}

/// 批量卸载由 `#[cmd]` 收集到的所有命令。
#[macro_export]
macro_rules! unregister_commands {
    () => {{
        inventory::iter::<rust_zw3d::Command>().for_each(|cmd| {
            rust_zw3d::commands::cvxCmdFuncUnload(cmd.name);
        });
    }};
}

/// 批量卸载由 `#[callback]` 收集到的所有回调。
#[macro_export]
macro_rules! unregister_callbacks {
    () => {{
        inventory::iter::<rust_zw3d::Callback>().for_each(|cb| {
            rust_zw3d::commands::cvxCmdCallbackUnload(cb.name);
        });
    }};
}

/// 生成模块进/出点：`<Name>Init` 与 `<Name>Exit`。
///
/// # 基本用法
///
/// ```rust,ignore
/// zw3d_module!(hello);
/// ```
///
/// 生成 `helloInit` 和 `helloExit` 函数，自动注册/卸载命令和回调。
///
/// # 带初始化函数
///
/// ```rust,ignore
/// fn my_init() -> i32 {
///     editor::msg_disp("模块初始化");
///     0
/// }
///
/// zw3d_module!(hello, init: my_init);
/// ```
///
/// # 带退出函数
///
/// ```rust,ignore
/// fn my_exit() -> i32 {
///     editor::msg_disp("模块退出");
///     0
/// }
///
/// zw3d_module!(hello, exit: my_exit);
/// ```
///
/// # 同时指定初始化和退出
///
/// ```rust,ignore
/// zw3d_module!(hello, init: my_init, exit: my_exit);
/// ```
#[macro_export]
macro_rules! zw3d_module {
    ($modulename:ident) => {
        ::rust_zw3d::paste::paste! {
            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Init>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::register_commands!();
                rust_zw3d::register_callbacks!();
                0
            }

            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Exit>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::unregister_callbacks!();
                rust_zw3d::unregister_commands!();
                0
            }
        }
    };

    ($modulename:ident, init: $init_fn:expr) => {
        ::rust_zw3d::paste::paste! {
            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Init>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                let result = $init_fn();
                if result != 0 {
                    return result;
                }

                rust_zw3d::register_commands!();
                rust_zw3d::register_callbacks!();
                0
            }

            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Exit>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::unregister_callbacks!();
                rust_zw3d::unregister_commands!();
                0
            }
        }
    };

    ($modulename:ident, exit: $exit_fn:expr) => {
        ::rust_zw3d::paste::paste! {
            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Init>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::register_commands!();
                rust_zw3d::register_callbacks!();
                0
            }

            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Exit>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::unregister_callbacks!();
                rust_zw3d::unregister_commands!();

                $exit_fn()
            }
        }
    };

    ($modulename:ident, init: $init_fn:expr, exit: $exit_fn:expr) => {
        ::rust_zw3d::paste::paste! {
            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Init>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                let result = $init_fn();
                if result != 0 {
                    return result;
                }

                rust_zw3d::register_commands!();
                rust_zw3d::register_callbacks!();
                0
            }

            #[unsafe(no_mangle)]
            pub extern "C" fn [<$modulename Exit>](_code: core::ffi::c_int, _ptr: *const core::ffi::c_void) -> core::ffi::c_int {
                rust_zw3d::unregister_callbacks!();
                rust_zw3d::unregister_commands!();

                $exit_fn()
            }
        }
    };
}