/**
 * @file trajectory_convert_cli_config.h
 * @brief RM75 轨迹 CSV 转 C++ waypoint 程序命令行参数解析接口。
 *
 * @author mashiro
 * @date 2026-07-09
 * @last_modified 2026-07-09
 *
 * @details
 * 本文件声明 `rm_trajectory_convert` 的 CLI 参数解析接口。该工具只读取 CSV 并写出
 * C++ waypoint 文件，不连接真实机械臂。将参数解析单独封装后，入口文件只负责
 * 调用读取、转换和写出流程。
 *
 * @dependencies
 * - rm_control/common/result.h
 *
 * @note
 * 轨迹转换工具属于离线工具，任何后续改动都不应引入真实硬件依赖。
 */
#pragma once

#include "rm_control/common/result.h"

#include <iosfwd>
#include <string>

namespace rm_control::config {

/**
 * @brief 轨迹转换程序的命令行解析结果。
 *
 * @author mashiro
 * @date 2026-07-09
 * @last_modified 2026-07-09
 *
 * @details
 * 该结构体保存输入 CSV、输出 C++ 文件路径和从输入文件名推导出的 session name。
 * session name 用于生成稳定的 C++ 变量名，输出路径可以由用户显式指定或按默认规则生成。
 */
struct TrajectoryConvertCliConfig {
    bool help_requested = false;          ///< 是否请求帮助信息。
    std::string input_csv_path;           ///< 输入轨迹 CSV 文件路径。
    std::string output_cpp_path;          ///< 输出 C++ waypoint 文件路径。
    std::string session_name;             ///< 用于生成 C++ 标识符的会话名。
};

/**
 * @brief 打印轨迹转换程序的命令行使用说明。
 *
 * @author mashiro
 * @date 2026-07-09
 * @last_modified 2026-07-09
 *
 * @details
 * 该函数只输出 usage 文本，不读取 CSV、不创建输出文件。独立函数可以避免多个错误分支
 * 各自维护不同提示内容。
 *
 * @param[in] program_name 当前进程名，可以为空指针。
 * @param[out] out 使用说明输出流。
 *
 * @return 无返回值。
 *
 * @throws 本函数不主动抛出异常；输出流异常由调用方处理。
 *
 * @note
 * usage 中必须说明该工具不连接真实机器人。
 *
 * @warning
 * 命令行格式变化时必须同步更新此函数。
 *
 * @thread_safety
 * 函数无全局状态；并发写同一输出流时由调用方加锁。
 *
 * @par 边界条件
 * `program_name == nullptr` 时使用默认程序名。
 *
 * @par 后续维护
 * 保持提示文本和解析逻辑一致。
 */
void PrintTrajectoryConvertUsage(const char *program_name, std::ostream &out);

/**
 * @brief 解析轨迹转换程序的命令行参数。
 *
 * @author mashiro
 * @date 2026-07-09
 * @last_modified 2026-07-09
 *
 * @details
 * 该函数解析 `<input_csv> [output_cpp]`。如果用户没有提供输出路径，则基于输入文件名
 * 和默认轨迹目录生成输出 C++ 文件路径。函数不检查输入文件是否存在，文件读取模块会在
 * 实际加载时返回明确错误。
 *
 * @param[in] argc 命令行参数数量。
 * @param[in] argv 命令行参数数组，允许元素为空指针。
 *
 * @return 成功时返回 `TrajectoryConvertCliConfig`。
 * @return 失败时返回错误原因，例如参数数量错误或输入路径为空。
 *
 * @throws 本函数不主动抛出异常；所有错误通过 `Result` 返回。
 *
 * @note
 * `-h` 和 `--help` 只作为第一个业务参数处理。
 *
 * @warning
 * 本函数只处理路径字符串，不保证路径权限或磁盘空间。
 *
 * @thread_safety
 * 函数只使用局部变量和只读输入，线程安全。
 *
 * @par 边界条件
 * 输入路径为空或 `argv[1] == nullptr` 时返回失败。
 *
 * @par 后续维护
 * 如果未来支持更多输出格式，应把格式选项加入该配置结构，而不是在入口文件临时判断。
 */
common::Result<TrajectoryConvertCliConfig> ParseTrajectoryConvertCliArguments(int argc, char **argv);

} // namespace rm_control::config
