///|
/// The object reached by a non-null HDF5 object reference.
///
/// `path` is the first hard-link path found by a bounded hierarchy walk. It is
/// `None` when the target is valid but has no named hard link.
#derive(Eq, @debug.Debug)
pub(all) struct Hdf5ReferenceTarget {
  address : UInt64
  kind : Hdf5ObjectKind
  path : String?
}

///|
pub extend Hdf5ReferenceTarget with Eq::{not_equal, equal}

///|
pub extend Hdf5ReferenceTarget with @debug.Debug::{to_repr}

///|
/// The object and attribute reached by a version-4 attribute reference.
#derive(Eq, @debug.Debug)
pub(all) struct Hdf5AttributeReferenceTarget {
  address : UInt64
  kind : Hdf5ObjectKind
  path : String?
  attribute_name : String
}

///|
pub extend Hdf5AttributeReferenceTarget with Eq::{not_equal, equal}

///|
pub extend Hdf5AttributeReferenceTarget with @debug.Debug::{to_repr}

///|
fn reference_is_null(reference : Bytes) -> Bool {
  let mut index = 0
  while index < reference.length() {
    if reference.unsafe_get(index) != b'\x00' {
      return false
    }
    index = index + 1
  }
  true
}

///|
fn is_version4_reference(reference : Bytes, offset_size : Int32) -> Bool {
  reference.length() == offset_size + 10 && reference.length() > 0
}

///|
fn version4_reference_header(
  reference : Bytes,
) -> (Int32, Int32, Reader) raise Hdf5Error {
  let reader = Reader::new(reference)
  let kind = reader.read_u8().to_int()
  let flags = reader.read_u8().to_int()
  guard (flags & 0xFE) == 0 else {
    raise InvalidField("version-4 reference has unsupported flags")
  }
  (kind, flags, reader)
}

///|
priv struct Version4ReferenceBody {
  token_size : Int32
  token_address : UInt64
  external_file : String?
  selection : Bytes?
  rank : Int32
  attribute_name : String?
}

///|
fn Hdf5File::version4_indirect_payload(
  self : Hdf5File,
  reader : Reader,
) -> Bytes raise Hdf5Error {
  let offset_size = self.superblock.offset_size
  let blob_size = reader.read_u32_le()
  guard blob_size <= 0x7FFFFFFFU else {
    raise InvalidField("version-4 reference blob is too large")
  }
  let heap_address = reader.read_uint_le(offset_size)
  let object_index = reader.read_u32_le()
  guard heap_address != 0UL &&
    heap_address != undefined_address &&
    object_index > 0U &&
    object_index <= 0xFFFFU else {
    raise InvalidField("invalid version-4 reference heap identifier")
  }
  let payload = self.read_reference_heap_object(
    heap_address,
    object_index.reinterpret_as_int(),
  )
  guard payload.length() == blob_size.reinterpret_as_int() else {
    raise InvalidField("version-4 reference blob size does not match the heap")
  }
  payload
}

///|
fn Hdf5File::version4_reference_body(
  self : Hdf5File,
  kind : Int32,
  flags : Int32,
  reader : Reader,
) -> Version4ReferenceBody raise Hdf5Error {
  let payload = self.version4_indirect_payload(reader)
  let blob = Reader::new(payload)
  let token_size = blob.read_u8().to_int()
  guard token_size == 4 || token_size == 8 else {
    raise UnsupportedFeature(
      "version-4 reference token size " +
      token_size.to_string() +
      " is not 4 or 8 bytes",
    )
  }
  let token_address = blob.read_uint_le(token_size)
  let external_file = if (flags & 0x01) != 0 {
    let length = blob.read_u16_le().to_int()
    guard length > 0 && length <= blob.remaining() else {
      raise InvalidField("truncated version-4 external file name")
    }
    let bytes = blob.read_bytes(length)
    Some(
      @utf8.decode(bytes.get_view().unwrap()) catch {
        _ => raise InvalidField("invalid UTF-8 external file name")
      },
    )
  } else {
    None
  }
  let mut selection : Bytes? = None
  let mut rank = 0
  let mut attribute_name : String? = None
  if kind == 3 {
    let selection_size = blob.read_u32_le().reinterpret_as_int()
    rank = blob.read_u32_le().reinterpret_as_int()
    guard selection_size >= 0 && selection_size <= blob.remaining() else {
      raise InvalidField("version-4 region reference selection is truncated")
    }
    selection = Some(blob.read_bytes(selection_size))
  } else if kind == 4 {
    let name_length = blob.read_u16_le().to_int()
    guard name_length > 0 && name_length <= blob.remaining() else {
      raise InvalidField("truncated version-4 attribute reference name")
    }
    let name_bytes = blob.read_bytes(name_length)
    attribute_name = Some(
      @utf8.decode(name_bytes.get_view().unwrap()) catch {
        _ => raise InvalidField("invalid UTF-8 attribute reference name")
      },
    )
  }
  let trailing = blob.read_bytes(blob.remaining())
  for byte in trailing {
    guard byte == b'\x00' else {
      raise InvalidField("version-4 reference has trailing bytes")
    }
  }
  { token_size, token_address, external_file, selection, rank, attribute_name, }
}

///|
fn Hdf5File::version4_object_reference_target(
  self : Hdf5File,
  reference : Bytes,
) -> Hdf5ReferenceTarget? raise Hdf5Error {
  let offset_size = self.superblock.offset_size
  let (kind, flags, reader) = version4_reference_header(reference)
  if kind == 0 {
    guard flags == 0 && reference_is_null(reference) else {
      raise InvalidField("invalid null version-4 reference")
    }
    return None
  }
  guard kind == 2 else {
    if kind == 3 {
      raise InvalidArgument(
        "region references require resolve_region_reference",
      )
    } else if kind == 4 {
      raise InvalidArgument(
        "attribute references require resolve_attribute_reference",
      )
    }
    raise InvalidField("invalid version-4 reference type")
  }
  guard flags == 0 else {
    raise UnsupportedFeature(
      "version-4 references to external files require Hdf5Resolver",
    )
  }
  let token_size = reader.read_u8().to_int()
  guard token_size == offset_size else {
    raise UnsupportedFeature(
      "version-4 reference token size " +
      token_size.to_string() +
      " does not match the file address size",
    )
  }
  let address = reader.read_uint_le(token_size)
  let header = self.object_header_at(address) catch {
    error =>
      raise InvalidField(
        "object reference target is not a valid object header: " +
        error.message(),
      )
  }
  let kind = object_kind(header)
  let path = self.find_reference_path(address)
  Some({ address, kind, path, })
}

///|
fn Hdf5File::find_reference_path_in_group(
  self : Hdf5File,
  path : String,
  address : UInt64,
  target : UInt64,
  visited : Array[UInt64],
  depth : Int32,
) -> String? raise Hdf5Error {
  guard depth < 128 else { raise InvalidField("group hierarchy is too deep") }
  if visited.contains(address) {
    return None
  }
  visited.push(address)
  let header = self.object_header_at(address)
  for link in self.links(header) {
    match link.link_target {
      Some(_) => ()
      None => {
        let child_path = join_path(path, link.name)
        if link.object_header_address == target {
          return Some(child_path)
        }
        let child_kind = object_kind(
          self.object_header_at(link.object_header_address),
        ) catch {
          _ => Unknown
        }
        if child_kind == Group {
          let found = self.find_reference_path_in_group(
            child_path,
            link.object_header_address,
            target,
            visited,
            depth + 1,
          )
          if found is Some(found_path) {
            return Some(found_path)
          }
        }
      }
    }
  }
  None
}

///|
fn Hdf5File::find_reference_path(
  self : Hdf5File,
  target : UInt64,
) -> String? raise Hdf5Error {
  if target == self.root_address() {
    return Some("/")
  }
  let visited : Array[UInt64] = []
  self.find_reference_path_in_group(
    "/",
    self.root_address(),
    target,
    visited,
    0,
  )
}

///|
/// Resolves a legacy HDF5 object reference to its target object.
///
/// The all-zero null reference returns `None`. Region references must be
/// resolved with `resolve_region_reference`; malformed references and dangling
/// addresses raise an error. References are local to this file; use
/// `Hdf5Resolver` to obtain a file that contains a remotely linked dataset
/// before resolving its stored references.
pub fn Hdf5File::resolve_object_reference(
  self : Hdf5File,
  reference : Bytes,
) -> Hdf5ReferenceTarget? raise Hdf5Error {
  let offset_size = self.superblock.offset_size
  if is_version4_reference(reference, offset_size) {
    return self.version4_object_reference_target(reference)
  }
  guard reference.length() == offset_size else {
    if reference.length() == offset_size + 4 {
      raise InvalidArgument(
        "region references require resolve_region_reference",
      )
    }
    raise InvalidField(
      "object reference must be " +
      offset_size.to_string() +
      " bytes, found " +
      reference.length().to_string(),
    )
  }
  if reference_is_null(reference) {
    return None
  }
  let reader = Reader::new(reference)
  let address = reader.read_uint_le(offset_size)
  let header = self.object_header_at(address) catch {
    error =>
      raise InvalidField(
        "object reference target is not a valid object header: " +
        error.message(),
      )
  }
  let kind = object_kind(header)
  let path = self.find_reference_path(address)
  Some({ address, kind, path, })
}

///|
/// Resolves a version-4 attribute reference to its object and attribute name.
///
/// Null references return `None`. External-file and non-native tokens are
/// outside the supported profile. Use `read_attribute_reference` to load the
/// referenced attribute value.
pub fn Hdf5File::resolve_attribute_reference(
  self : Hdf5File,
  reference : Bytes,
) -> Hdf5AttributeReferenceTarget? raise Hdf5Error {
  let offset_size = self.superblock.offset_size
  guard is_version4_reference(reference, offset_size) else {
    raise InvalidField("attribute references require version-4 encoding")
  }
  let (kind, flags, reader) = version4_reference_header(reference)
  if kind == 0 {
    guard flags == 0 && reference_is_null(reference) else {
      raise InvalidField("invalid null version-4 reference")
    }
    return None
  }
  guard kind == 4 else {
    if kind == 2 {
      raise InvalidArgument(
        "object references require resolve_object_reference",
      )
    } else if kind == 3 {
      raise InvalidArgument(
        "region references require resolve_region_reference",
      )
    }
    raise InvalidField("invalid version-4 reference type")
  }
  guard flags == 0 else {
    raise UnsupportedFeature(
      "version-4 references to external files require Hdf5Resolver",
    )
  }
  let body = self.version4_reference_body(kind, flags, reader)
  guard body.token_size == offset_size else {
    raise UnsupportedFeature(
      "version-4 reference token size " +
      body.token_size.to_string() +
      " does not match the file address size",
    )
  }
  let address = body.token_address
  let attribute_name = match body.attribute_name {
    Some(name) => name
    None => raise InvalidField("version-4 attribute reference has no name")
  }
  let header = self.object_header_at(address) catch {
    error =>
      raise InvalidField(
        "attribute reference target is not a valid object header: " +
        error.message(),
      )
  }
  let kind = object_kind(header)
  let path = self.find_reference_path(address)
  Some({ address, kind, path, attribute_name, })
}

///|
/// Reads the attribute selected by a version-4 attribute reference.
///
/// A null reference returns `None`. The target object must have a named hard
/// link so its attributes can be enumerated, and the named attribute must
/// still exist.
pub fn Hdf5File::read_attribute_reference(
  self : Hdf5File,
  reference : Bytes,
) -> Attribute? raise Hdf5Error {
  let target = match self.resolve_attribute_reference(reference) {
    Some(target) => target
    None => return None
  }
  let path = match target.path {
    Some(path) => path
    None =>
      raise InvalidField("attribute-reference target has no named hard link")
  }
  let attributes = self.attributes(path)
  match
    attributes.search_by(attribute => attribute.name == target.attribute_name) {
    Some(index) => Some(attributes[index])
    None =>
      raise InvalidField(
        "attribute-reference target does not exist: " + target.attribute_name,
      )
  }
}