///|
/// 文件系统操作辅助模块
///
/// 本模块提供了针对SRT字幕处理优化的文件读写功能。
/// 主要功能包括：
/// 1. 读取文本文件并自动处理换行符和注释过滤
/// 2. 将字符串数组写入文件
///
/// 这些函数专门为处理字幕文本文件设计，会自动过滤中文全角括号注释。
///
/// 使用示例：
/// ```moonbit
/// // 读取文件
/// let lines = read_lines("input.txt")
/// 
/// // 处理内容...
/// 
/// // 写入文件
/// write_lines("output.txt", processed_lines)
/// ```

///|
/// 从文本文件读取所有行，并进行预处理。
///
/// 此函数执行以下操作：
/// 1. 读取整个文件内容为字符串
/// 2. 统一换行符为`\n`（处理Windows的`\r\n`）
/// 3. 按换行符分割为行数组
/// 4. 过滤掉以全角括号开头和结尾的行（通常用于中文注释）
///
/// 参数：
/// * `file_path` : 要读取的文件路径
///
/// 返回：经过预处理的行数组
///
/// 可能抛出的错误：`@fs.IOError` - 当文件读取失败时
///
/// 示例：
/// ```moonbit nocheck
/// // 假设文件内容为：
/// // 第一行
/// // （这是注释）
/// // 第二行
/// let lines = read_lines("example.txt")
/// inspect(lines.length(), content="2")
/// inspect(lines[0], content="第一行")
/// inspect(lines[1], content="第二行")
/// ```
pub fn read_lines(file_path : String) -> Array[String] raise @fs.IOError {
  let content = @fs.read_file_to_string(file_path)
  let lines = content
    .replace_all(old="\r\n", new="\n") // 统一换行符
    .split("\n") // 按行分割
    .filter(fn(line) { !(line.has_prefix("（") && line.has_suffix("）")) }) // 过滤中文注释
  lines.map(fn(line) { line.to_string() }).collect()
}

///|
/// 将字符串数组写入文件，每行用换行符分隔。
///
/// 此函数执行以下操作：
/// 1. 将字符串数组用`\n`连接成单个字符串
/// 2. 将结果字符串写入指定文件
///
/// 参数：
/// * `file_path` : 要写入的文件路径
/// * `lines` : 要写入的字符串数组，每个元素将成为文件的一行
///
/// 可能抛出的错误：`@fs.IOError` - 当文件写入失败时
///
/// 示例：
/// ```moonbit nocheck
/// let lines = ["第一行", "第二行", "第三行"]
/// write_lines("output.txt", lines)
/// // 文件内容将是：
/// // 第一行
/// // 第二行
/// // 第三行
/// ```
pub fn write_lines(
  file_path : String,
  lines : Array[String],
) -> Unit raise @fs.IOError {
  let content = lines.join("\n") // 用换行符连接所有行
  @fs.write_string_to_file(file_path, content) // 写入文件
}