nml_enum Function

   function nml_enum(name, tgt, doc, allowed, units, required, dead_on_ocean_path, &
                     retired, retired_hint) result(key)
      !! Construct an enum key restricted to `allowed`, capturing the
      !! current target as default.
      !!
      !! `retired` lists spellings that were legal in an earlier release.
      !! They are NOT accepted — they fail loud, quoting `retired_hint`,
      !! so a stale namelist is told what the value is called now instead
      !! of being handed the generic allowed-set message.
      character(len=*), intent(in) :: name, doc
      character(len=:), pointer, intent(in) :: tgt
      character(len=*), intent(in) :: allowed(:)
      character(len=*), intent(in), optional :: units
      logical, intent(in), optional :: required
      character(len=*), intent(in), optional :: dead_on_ocean_path
      character(len=*), intent(in), optional :: retired(:)
      character(len=*), intent(in), optional :: retired_hint
      type(nml_enum_key_t) :: key

      key%name = name
      key%doc = doc
      key%units = ""
      if (present(units)) key%units = units
      if (present(required)) key%required = required
      key%dead_reason = ""
      if (present(dead_on_ocean_path)) key%dead_reason = dead_on_ocean_path
      key%tgt => tgt
      key%default = tgt
      ! Explicit allocate + element copy on purpose: the auto-allocating
      ! `key%allowed = allowed` makes NVHPC's str_copy write one byte past
      ! the allocation (heap corruption once enough enums register).
      block
         integer :: i
         allocate (character(len=len(allowed)) :: key%allowed(size(allowed)))
         do i = 1, size(allowed)
            key%allowed(i) = allowed(i)
         end do
      end block
      if (present(retired)) then
         block
            integer :: i
            allocate (character(len=len(retired)) :: key%retired(size(retired)))
            do i = 1, size(retired)
               key%retired(i) = retired(i)
            end do
         end block
      end if
      if (present(retired_hint)) key%retired_hint = retired_hint
   end function nml_enum