// bom.mbt
//
// 规范 §6.1 "Legacy hooks for standards" 的三个入口:BOM sniff、decode 钩子、
// 以及 decode 钩子的流式形态(AutoDecoder)。
//
// 规范原文(encoding.bs @ 2c3853e):
//   To BOM sniff an I/O queue of bytes ioQueue: let BOM be the result of
//   peeking 3 bytes ... for each row in the table, if BOM starts with the
//   bytes given in the first column, return the encoding; otherwise return null.
//   To decode ... let BOMEncoding be the result of BOM sniffing ioQueue; if
//   non-null, set encoding to it and read three bytes (UTF-8) or two bytes
//   otherwise; then process with error mode "replacement".
//
// 规范特别说明:decode 无法把"我发现了 BOM、你给的 encoding 作废"回传给调用方,
// 故 BOM sniff 被单独暴露成钩子。本文件同样保留这个区分。

///|
/// 按规范 §6.1 的 BOM 表判定输入开头的字节序标记,返回对应编码的规范名。
/// 只看前 3 字节,不消费、不改写输入;不足 3 字节时按可匹配的前缀判定
/// (`FE FF` / `FF FE` 两字节即可确认,`EF BB BF` 需三字节)。
pub fn bom_sniff(bytes : Bytes) -> String? {
  let n = bytes.length()
  if n >= 3 &&
    bytes[0].to_int() == 0xEF &&
    bytes[1].to_int() == 0xBB &&
    bytes[2].to_int() == 0xBF {
    Some("UTF-8")
  } else if n >= 2 && bytes[0].to_int() == 0xFE && bytes[1].to_int() == 0xFF {
    Some("UTF-16BE")
  } else if n >= 2 && bytes[0].to_int() == 0xFF && bytes[1].to_int() == 0xFE {
    Some("UTF-16LE")
  } else {
    None
  }
}

///|
/// 规范 §6.1 的 decode 钩子:BOM 优先于调用方给的 fallback label,
/// 命中时**吞掉** BOM 字节(UTF-8 三个、其余两个),剩余字节按 replacement 模式解码。
/// fallback label 本身仍要能解析(未知 label 照常报 `UnknownLabel`)。
pub fn decode_auto(
  bytes : Bytes,
  fallback_label : String,
) -> Result[String, EncodingError] {
  // 规范先确定 fallback encoding(get an encoding 失败即结束),再看 BOM。
  let fallback = match label_to_encoding(fallback_label) {
    Err(e) => return Err(e)
    Ok(name) => name
  }
  let bom = bom_sniff(bytes)
  let name = match bom {
    Some(bom_name) => bom_name
    None => fallback
  }
  let skip = match bom {
    Some(bom_name) => if bom_name == "UTF-8" { 3 } else { 2 }
    None => 0
  }
  let decoder = match Decoder::new(name) {
    Err(e) => return Err(e)
    Ok(d) => d
  }
  // 库源码不能复用 wbtest 里的切片辅助函数,这里就地构造剩余字节。
  let rest : Array[Byte] = []
  let mut i = skip
  while i < bytes.length() {
    rest.push(bytes[i])
    i = i + 1
  }
  let head = decoder.consume(Bytes::from_array(rest.exact_view()))
  let tail = decoder.finish()
  if tail.is_empty() {
    Ok(head)
  } else {
    Ok(head + tail)
  }
}

///|
/// 流式 BOM 感知解码器 —— 规范 §6.1 decode 钩子的流式形态。
///
/// 为什么是独立类型而不是 `Decoder` 本身:BOM 未定案前必须缓冲字节、定案后要换成
/// BOM 指示的解码器,这要求改 `Decoder` 的字段;而 `Decoder` 已承载 175 项测试与 CLI,
/// 为了把回归风险压到零,这里用独立类型承担「先嗅探、后转交」这一段生命周期。
pub struct AutoDecoder {
  /// 定案前的回退编码(规范名)。
  priv fallback : String
  /// 定案前缓冲的字节;`inner` 一旦为 `Some` 即不再使用。
  priv pending : Array[Byte]
  /// 定案后的实际解码器;`None` 表示 BOM 尚未定案。
  priv mut inner : Decoder?
}

///|
/// 构造流式 BOM 感知解码器。`fallback_label` 与 `decode_auto` 一样必须先能解析,
/// 未知 label 在构造期就报 `UnknownLabel`(不推迟到第一次 `consume`)。
pub fn Decoder::new_auto(
  fallback_label : String,
) -> Result[AutoDecoder, EncodingError] {
  let name = match label_to_encoding(fallback_label) {
    Err(e) => return Err(e)
    Ok(n) => n
  }
  Ok({ fallback: name, pending: [], inner: None, })
}

///|
/// 定案判定。返回值:`-1` 继续等(字节还不够且仍可能是 BOM),
/// `0` 无 BOM,`3` UTF-8(吞 3 字节),`4` UTF-16BE(吞 2 字节),`5` UTF-16LE(吞 2 字节)。
/// `at_end` 为真时不再等待,短缓冲一律按「无 BOM」定案。
fn AutoDecoder::auto_decide(self : AutoDecoder, at_end : Bool) -> Int32 {
  let n = self.pending.length()
  if n == 0 {
    return if at_end { 0 } else { -1 }
  }
  let first = self.pending[0].to_int()
  // 首字节不可能是任何 BOM 前缀:立即透传,否则整个流会卡在缓冲里。
  if first != 0xEF && first != 0xFE && first != 0xFF {
    return 0
  }
  if first == 0xEF {
    if n >= 3 {
      if self.pending[1].to_int() == 0xBB && self.pending[2].to_int() == 0xBF {
        return 3
      }
      return 0
    }
    if n == 2 && self.pending[1].to_int() != 0xBB {
      return 0
    }
    return if at_end { 0 } else { -1 }
  }
  // first 是 0xFE 或 0xFF:两字节即可定案。
  if n >= 2 {
    if first == 0xFE && self.pending[1].to_int() == 0xFF {
      return 4
    }
    if first == 0xFF && self.pending[1].to_int() == 0xFE {
      return 5
    }
    return 0
  }
  return if at_end { 0 } else { -1 }
}

///|
/// 按判定结果建立内部解码器,并把缓冲里 BOM 之后的字节立刻喂进去,返回这段文本。
/// 之后所有 `consume` / `finish` 都直接转交给 `inner`。
fn AutoDecoder::auto_settle(self : AutoDecoder, code : Int32) -> String {
  let name = if code == 3 {
    "UTF-8"
  } else if code == 4 {
    "UTF-16BE"
  } else if code == 5 {
    "UTF-16LE"
  } else {
    self.fallback
  }
  let skip = if code == 3 { 3 } else if code >= 4 { 2 } else { 0 }
  let decoder = match Decoder::new(name) {
    Ok(d) => d
    Err(_) =>
      // 规范名都由本库自身解析而来,理论上不会失败;失败则退回 fallback。
      match Decoder::new(self.fallback) {
        Ok(d) => d
        Err(_) => return ""
      }
  }
  self.inner = Some(decoder)
  let rest : Array[Byte] = []
  let mut i = skip
  while i < self.pending.length() {
    rest.push(self.pending[i])
    i = i + 1
  }
  decoder.consume(Bytes::from_array(rest.exact_view()))
}

///|
/// 喂入一个字节块。BOM 未定案时先缓冲(可能返回空串),定案后转交内部解码器。
pub fn AutoDecoder::consume(self : AutoDecoder, chunk : Bytes) -> String {
  match self.inner {
    Some(decoder) => decoder.consume(chunk)
    None => {
      for i in 0.. String {
  match self.inner {
    Some(decoder) => decoder.finish()
    None => {
      let code = self.auto_decide(true)
      let head = self.auto_settle(code)
      let tail = match self.inner {
        Some(decoder) => decoder.finish()
        None => ""
      }
      if tail.is_empty() {
        head
      } else {
        head + tail
      }
    }
  }
}