MOM_file_parser.F90

! This file is part of MOM6, the Modular Ocean Model version 6.

! See the LICENSE file for licensing information.

! SPDX-License-Identifier: Apache-2.0

!> The MOM6 facility to parse input files for runtime parameters

module mom_file_parser

use mom_coms, only : root_pe, broadcast

use mom_coms, only : any_across_pes

use mom_error_handler, only : mom_error, fatal, warning, mom_mesg, assert

use mom_error_handler, only : is_root_pe, stdlog, stdout

use mom_time_manager, only : get_time, time_type, get_ticks_per_second

use mom_time_manager, only : set_date, get_date, real_to_time, operator(-), operator(==), set_time

use mom_document, only : doc_param, doc_module, doc_init, doc_end, doc_type

use mom_document, only : doc_openblock, doc_closeblock

use mom_string_functions, only : left_int, left_ints, slasher

use mom_string_functions, only : left_real, left_reals

implicit none ; private

! These are hard-coded limits that are used in the following code.  They should be set

! generously enough not to impose any significant limitations.

integer, parameter, public :: max_param_files = 5 !< Maximum number of parameter files.

integer, parameter :: input_str_length = 1024 !< Maximum line length in parameter file.  Lines that

                                              !! are combined by ending in '\' or '&' can exceed

                                              !! this limit after merging.

integer, parameter :: filename_length = 200   !< Maximum number of characters in file names.

!>@{ Default values for parameters

logical, parameter :: report_unused_default = .true.

logical, parameter :: unused_params_fatal_default = .false.

logical, parameter :: log_to_stdout_default = .false.

logical, parameter :: complete_doc_default = .true.

logical, parameter :: minimal_doc_default = .true.

!>@}

!> A simple type to allow lines in an array to be allocated with variable sizes.

type, private :: file_line_type ; private

  character(len=:), allocatable :: line !< An allocatable line with content

end type file_line_type

!> The valid lines extracted from an input parameter file without comments

type, private :: file_data_type ; private

  integer :: num_lines = 0 !< The number of lines in this type

  type(file_line_type), allocatable, dimension(:) :: fln !< Lines with the input content.

  logical,                  pointer, dimension(:) :: line_used => null() !< If true, the line has been read

end type file_data_type

!> A link in the list of variables that have already had override warnings issued

type, private :: link_parameter ; private

  type(link_parameter), pointer :: next => null() !< Facilitates linked list

  character(len=80) :: name                       !< Parameter name

  logical :: hasissuedoverridewarning = .false.   !< Has a default value

end type link_parameter

!> Specify the active parameter block

type, private :: parameter_block ; private

  character(len=240) :: name = ''   !< The active parameter block name

  logical :: log_access = .true.

    !< Log the entry and exit of the block (but not its contents)

end type parameter_block

!> A structure that can be parsed to read and document run-time parameters.

type, public :: param_file_type ; private

  integer  :: nfiles = 0            !< The number of open files.

  integer  :: iounit(max_param_files) !< The unit numbers of open files.

  character(len=FILENAME_LENGTH)  :: filename(max_param_files) !< The names of the open files.

  logical  :: netcdf_file(max_param_files) !< If true, the input file is in NetCDF.

                                    ! This is not yet implemented.

  type(file_data_type) :: param_data(max_param_files) !< Structures that contain

                                    !! the valid data lines from the parameter

                                    !! files, enabling all subsequent reads of

                                    !! parameter data to occur internally.

  logical  :: report_unused = report_unused_default !< If true, report any

                                    !! parameter lines that are not used in the run.

  logical  :: unused_params_fatal = unused_params_fatal_default  !< If true, kill

                                    !! the run if there are any unused parameters.

  logical  :: log_to_stdout = log_to_stdout_default !< If true, all log

                                    !! messages are also sent to stdout.

  logical  :: log_open = .false.    !< True if the log file has been opened.

  integer  :: max_line_len = 4      !< The maximum number of characters in the lines

                                    !! in any of the files in this param_file_type after

                                    !! any continued lines have been combined.

  integer  :: stdout                !< The unit number from stdout().

  integer  :: stdlog                !< The unit number from stdlog().

  character(len=240) :: doc_file    !< A file where all run-time parameters, their

                                    !! settings and defaults are documented.

  logical  :: complete_doc = complete_doc_default !< If true, document all

                                    !! run-time parameters.

  logical  :: minimal_doc = minimal_doc_default !< If true, document only those

                                    !! run-time parameters that differ from defaults.

  type(doc_type), pointer :: doc => null() !< A structure that contains information

                                    !! related to parameter documentation.

  type(link_parameter), pointer :: chain => null() !< Facilitates linked list

  type(parameter_block), pointer :: blockname => null() !< Name of active parameter block

end type param_file_type

public read_param, open_param_file, close_param_file, log_param, log_version

public doc_param, get_param

public clearparameterblock, openparameterblock, closeparameterblock

!> An overloaded interface to read various types of parameters

interface read_param

  module procedure read_param_int, read_param_real, read_param_logical, &

                   read_param_char, read_param_char_array, read_param_time, &

                   read_param_int_array, read_param_real_array

end interface

!> An overloaded interface to log the values of various types of parameters

interface log_param

  module procedure log_param_int, log_param_real, log_param_logical, &

                   log_param_char, log_param_time, &

                   log_param_int_array, log_param_real_array

end interface

!> An overloaded interface to read and log the values of various types of parameters

interface get_param

  module procedure get_param_int, get_param_real, get_param_logical, &

                   get_param_char, get_param_char_array, get_param_time, &

                   get_param_int_array, get_param_real_array

end interface

!> An overloaded interface to log version information about modules

interface log_version

  module procedure log_version_cs, log_version_plain

end interface

contains

!> Make the contents of a parameter input file available in a param_file_type

subroutine open_param_file(filename, CS, checkable, component, doc_file_dir, ensemble_num)

  character(len=*),           intent(in) :: filename !< An input file name, optionally with the full path

  type(param_file_type),   intent(inout) :: cs      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  logical,          optional, intent(in) :: checkable   !< If this is false, it disables checks of this

                                         !! file for unused parameters.  The default is True.

  character(len=*), optional, intent(in) :: component   !< If present, this component name is used

                                         !! to generate parameter documentation file names; the default is"MOM"

  character(len=*), optional, intent(in) :: doc_file_dir !< An optional directory in which to write out

                                         !! the documentation files.  The default is effectively './'.

  integer, optional, intent(in)          :: ensemble_num !< ensemble number to be appended to _doc filenames (optional)

  ! Local variables

  logical :: file_exists, netcdf_file, may_check, reopened_file

  integer :: ios, iounit, strlen, i

  character(len=240) :: doc_path

  character(len=5)  :: ensemble_suffix

  type(parameter_block), pointer :: block => null()

  may_check = .true. ; if (present(checkable)) may_check = checkable

  ! Check for non-blank filename

  strlen = len_trim(filename)

  if (strlen == 0) then

    call mom_error(fatal, "open_param_file: Input file has not been specified.")

  endif

  ! Check that this file has not already been opened

  if (cs%nfiles > 0) then

    reopened_file = .false.

    if (is_root_pe()) then

      inquire(file=trim(filename), number=iounit)

      if (iounit /= -1) then

        do i = 1, cs%nfiles

          if (cs%iounit(i) == iounit) then

            call assert(trim(cs%filename(1)) == trim(filename), &

                "open_param_file: internal inconsistency! "//trim(filename)// &

                " is registered as open but has the wrong unit number!")

            call mom_error(warning, &

                "open_param_file: file "//trim(filename)// &

                " has already been opened. This should NOT happen!"// &

                " Did you specify the same file twice in a namelist?")

            reopened_file = .true.

          endif ! unit numbers

        enddo ! i

      endif

    endif

    if (any_across_pes(reopened_file)) return

  endif

  ! Check that the file exists to readstdlog

  if (is_root_pe()) then

    inquire(file=trim(filename), exist=file_exists)

    if (.not.file_exists) call mom_error(fatal, &

        "open_param_file: Input file '"// trim(filename)//"' does not exist.")

  endif

  netcdf_file = .false.

  if (strlen > 3) then

    if (filename(strlen-2:strlen) == ".nc") netcdf_file = .true.

  endif

  if (netcdf_file) &

    call mom_error(fatal,"open_param_file: NetCDF files are not yet supported.")

  if (is_root_pe()) then

    open(newunit=iounit, file=trim(filename), access='SEQUENTIAL', &

         form='FORMATTED', action='READ', position='REWIND', iostat=ios)

    if (ios /= 0) call mom_error(fatal, "open_param_file: Error opening '"//trim(filename)//"'.")

  else

    iounit = 1

  endif

  ! Store/register the unit and details

  i = cs%nfiles + 1

  cs%nfiles = i

  cs%iounit(i) = iounit

  cs%filename(i) = filename

  cs%NetCDF_file(i) = netcdf_file

  if (associated(cs%blockName)) deallocate(cs%blockName)

  allocate(block) ; block%name = '' ; cs%blockName => block

  call mom_mesg("open_param_file: "// trim(filename)//" has been opened successfully.", 5)

  call populate_param_data(iounit, filename, cs%param_data(i))

  ! Increment the maximum line length, but always report values in blocks of 4 characters.

  cs%max_line_len = max(cs%max_line_len, 4 + 4*(max_input_line_length(cs, i) - 1) / 4)

  call read_param(cs,"SEND_LOG_TO_STDOUT",cs%log_to_stdout)

  call read_param(cs,"REPORT_UNUSED_PARAMS",cs%report_unused)

  call read_param(cs,"FATAL_UNUSED_PARAMS",cs%unused_params_fatal)

  cs%doc_file = "MOM_parameter_doc"

  if (present(ensemble_num)) then

    ! append instance suffix to doc_file

    write(ensemble_suffix,'(A,I0.4)') '_', ensemble_num

    cs%doc_file = trim(cs%doc_file)//ensemble_suffix

  endif

  if (present(component)) cs%doc_file = trim(component)//"_parameter_doc"

  call read_param(cs,"DOCUMENT_FILE", cs%doc_file)

  if (.not.may_check) then

    cs%report_unused = .false.

    cs%unused_params_fatal = .false.

  endif

  ! Open the log file.

  cs%stdlog = stdlog() ; cs%stdout = stdout()

  cs%log_open = (stdlog() > 0)

  doc_path = cs%doc_file

  if (len_trim(cs%doc_file) > 0) then

    cs%complete_doc = complete_doc_default

    call read_param(cs, "COMPLETE_DOCUMENTATION", cs%complete_doc)

    cs%minimal_doc = minimal_doc_default

    call read_param(cs, "MINIMAL_DOCUMENTATION", cs%minimal_doc)

    if (present(doc_file_dir)) then ; if (len_trim(doc_file_dir) > 0) then

      doc_path = trim(slasher(doc_file_dir))//trim(cs%doc_file)

    endif ; endif

  else

    cs%complete_doc = .false.

    cs%minimal_doc = .false.

  endif

  call doc_init(doc_path, cs%doc, minimal=cs%minimal_doc, complete=cs%complete_doc, &

                layout=cs%complete_doc, debugging=cs%complete_doc)

end subroutine open_param_file

!> Close any open input files and deallocate memory associated with this param_file_type.

!! To use this type again, open_param_file would have to be called again.

subroutine close_param_file(CS, quiet_close, component)

  type(param_file_type),   intent(inout) :: cs      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  logical,          optional, intent(in) :: quiet_close !< if present and true, do not do any

                                         !! logging with this call.

  character(len=*), optional, intent(in) :: component   !< If present, this component name is used

                                         !! to generate parameter documentation file names

  ! Local variables

  logical :: all_default

  character(len=128) :: docfile_default

  character(len=40)  :: mdl   ! This module's name.

  ! This include declares and sets the variable "version".

# include "version_variable.h"

  integer :: i, n, num_unused

  if (present(quiet_close)) then ; if (quiet_close) then

    do i = 1, cs%nfiles

      if (is_root_pe()) close(cs%iounit(i))

      call mom_mesg("close_param_file: "// trim(cs%filename(i))// &

                    " has been closed successfully.", 5)

      cs%iounit(i) = -1

      cs%filename(i) = ''

      cs%NetCDF_file(i) = .false.

      do n=1,cs%param_data(i)%num_lines ; deallocate(cs%param_data(i)%fln(n)%line) ; enddo

      deallocate (cs%param_data(i)%fln)

      deallocate (cs%param_data(i)%line_used)

    enddo

    cs%log_open = .false.

    call doc_end(cs%doc)

    deallocate(cs%doc)

    return

  endif ; endif

  ! Log the parameters for the parser.

  docfile_default = "MOM_parameter_doc"

  if (present(component)) docfile_default = trim(component)//"_parameter_doc"

  all_default = (cs%log_to_stdout .eqv. log_to_stdout_default)

  all_default = all_default .and. (trim(cs%doc_file) == trim(docfile_default))

  if (len_trim(cs%doc_file) > 0) then

    all_default = all_default .and. (cs%complete_doc .eqv. complete_doc_default)

    all_default = all_default .and. (cs%minimal_doc .eqv. minimal_doc_default)

  endif

  mdl = "MOM_file_parser"

  call log_version(cs, mdl, version, "", debugging=.true., log_to_all=.true., all_default=all_default)

  call log_param(cs, mdl, "SEND_LOG_TO_STDOUT", cs%log_to_stdout, &

                 "If true, all log messages are also sent to stdout.", &

                 default=log_to_stdout_default)

  call log_param(cs, mdl, "REPORT_UNUSED_PARAMS", cs%report_unused, &

                 "If true, report any parameter lines that are not used "//&

                 "in the run.", default=report_unused_default, &

                 debuggingparam=.true.)

  call log_param(cs, mdl, "FATAL_UNUSED_PARAMS", cs%unused_params_fatal, &

                 "If true, kill the run if there are any unused "//&

                 "parameters.", default=unused_params_fatal_default, &

                 debuggingparam=.true.)

  call log_param(cs, mdl, "DOCUMENT_FILE", cs%doc_file, &

                 "The basename for files where run-time parameters, their "//&

                 "settings, units and defaults are documented. Blank will "//&

                 "disable all parameter documentation.", default=docfile_default)

  if (len_trim(cs%doc_file) > 0) then

    call log_param(cs, mdl, "COMPLETE_DOCUMENTATION",  cs%complete_doc, &

                  "If true, all run-time parameters are "//&

                  "documented in "//trim(cs%doc_file)//&

                  ".all .", default=complete_doc_default)

    call log_param(cs, mdl, "MINIMAL_DOCUMENTATION", cs%minimal_doc, &

                  "If true, non-default run-time parameters are "//&

                  "documented in "//trim(cs%doc_file)//&

                  ".short .", default=minimal_doc_default)

  endif

  num_unused = 0

  do i = 1, cs%nfiles

    if (is_root_pe() .and. (cs%report_unused .or. &

                            cs%unused_params_fatal)) then

      ! Check for unused lines.

      do n=1,cs%param_data(i)%num_lines

        if (.not.cs%param_data(i)%line_used(n)) then

          num_unused = num_unused + 1

          if (cs%report_unused) &

            call mom_error(warning, "Unused line in "//trim(cs%filename(i))// &

                            " : "//trim(cs%param_data(i)%fln(n)%line))

        endif

      enddo

    endif

    if (is_root_pe()) close(cs%iounit(i))

    call mom_mesg("close_param_file: "// trim(cs%filename(i))//" has been closed successfully.", 5)

    cs%iounit(i) = -1

    cs%filename(i) = ''

    cs%NetCDF_file(i) = .false.

    do n=1,cs%param_data(i)%num_lines ; deallocate(cs%param_data(i)%fln(n)%line) ; enddo

    deallocate (cs%param_data(i)%fln)

    deallocate (cs%param_data(i)%line_used)

  enddo

  deallocate(cs%blockName)

  if (is_root_pe() .and. (num_unused>0) .and. cs%unused_params_fatal) &

    call mom_error(fatal, "Run stopped because of unused parameter lines.")

  cs%log_open = .false.

  call doc_end(cs%doc)

  deallocate(cs%doc)

end subroutine close_param_file

!> Read the contents of a parameter input file, and store the contents in a

!! file_data_type after removing comments and simplifying white space

subroutine populate_param_data(iounit, filename, param_data)

  integer,                 intent(in) :: iounit !< The IO unit number that is open for filename

  character(len=*),        intent(in) :: filename !< An input file name, optionally with the full path

  type(file_data_type), intent(inout) :: param_data !< A list of the input lines that set parameters

                                                !! after comments have been stripped out.

  ! Local variables

  character(len=INPUT_STR_LENGTH) :: line

  character(len=1), allocatable, dimension(:) :: char_buf

  integer, allocatable, dimension(:) :: line_len ! The trimmed length of each processed input line

  integer :: n, num_lines, total_chars, ch, rsc, llen, int_buf(2)

  logical :: inMultiLineComment

  ! Find the number of keyword lines in a parameter file

  if (is_root_pe()) then

    ! rewind the parameter file

    rewind(iounit)

    ! count the number of valid entries in the parameter file

    num_lines = 0

    total_chars = 0

    inmultilinecomment = .false.

    do while(.true.)

      read(iounit, '(a)', end=8) line

      line = replacetabs(line)

      if (inmultilinecomment) then

        if (closemultilinecomment(line)) inmultilinecomment=.false.

      else

        if (lastnoncommentnonblank(line)>0) then

          line = removecomments(line)

          line = simplifywhitespace(line(:len_trim(line)))

          num_lines = num_lines + 1

          total_chars = total_chars + len_trim(line)

        endif

        if (openmultilinecomment(line)) inmultilinecomment=.true.

      endif

    enddo ! while (.true.)

 8  continue ! get here when read() reaches EOF

    if (inmultilinecomment .and. is_root_pe()) &

      call mom_error(fatal, 'MOM_file_parser : A C-style multi-line comment '// &

                      '(/* ... */) was not closed before the end of '//trim(filename))

    int_buf(1) = num_lines

    int_buf(2) = total_chars

  endif  ! (is_root_pe())

  ! Broadcast the number of valid entries in parameter file

  call broadcast(int_buf, 2, root_pe())

  num_lines = int_buf(1)

  total_chars = int_buf(2)

  ! Set up the space for storing the actual lines.

  param_data%num_lines = num_lines

  allocate (line_len(num_lines), source=0)

  allocate (char_buf(total_chars), source=" ")

  ! Read the actual lines.

  if (is_root_pe()) then

    ! rewind the parameter file

    rewind(iounit)

    ! Populate param_data%fln%line

    num_lines = 0

    rsc = 0

    do while(.true.)

      read(iounit, '(a)', end=18) line

      line = replacetabs(line)

      if (inmultilinecomment) then

        if (closemultilinecomment(line)) inmultilinecomment=.false.

      else

        if (lastnoncommentnonblank(line)>0) then

          line = removecomments(line)

          if ((len_trim(line) > 1000) .and. is_root_pe()) then

            call mom_error(warning, "MOM_file_parser: Consider using continuation to split up "//&

                                    "the excessivley long parameter input line "//trim(line))

          endif

          line = simplifywhitespace(line(:len_trim(line)))

          num_lines = num_lines + 1

          llen = len_trim(line)

          line_len(num_lines) = llen

          do ch=1,llen ; char_buf(rsc+ch)(1:1) = line(ch:ch) ; enddo

          rsc = rsc + llen

        endif

        if (openmultilinecomment(line)) inmultilinecomment=.true.

      endif

    enddo ! while (.true.)

18  continue ! get here when read() reaches EOF

    call assert(num_lines == param_data%num_lines, &

        'MOM_file_parser: Found different number of valid lines on second ' &

        // 'reading of '//trim(filename))

  endif  ! (is_root_pe())

  ! Broadcast the populated arrays line_len and char_buf

  call broadcast(line_len, num_lines, root_pe())

  call broadcast(char_buf(1:total_chars), 1, root_pe())

  ! Allocate space to hold contents of the parameter file, including the lines in param_data%fln

  allocate(param_data%fln(num_lines))

  allocate(param_data%line_used(num_lines))

  param_data%line_used(:) = .false.

  ! Populate param_data%fln%line with the keyword lines from parameter file

  rsc = 0

  do n=1,num_lines

    line(1:input_str_length) = " "

    do ch=1,line_len(n) ; line(ch:ch) = char_buf(rsc+ch)(1:1) ; enddo

    param_data%fln(n)%line = trim(line)

    rsc = rsc + line_len(n)

  enddo

  deallocate(char_buf) ; deallocate(line_len)

end subroutine populate_param_data

!> Return True if a /* appears on this line without a closing */

function openmultilinecomment(string)

  character(len=*), intent(in) :: string  !< The input string to process

  logical                      :: openmultilinecomment

  ! Local variables

  integer :: icom, last

  openmultilinecomment = .false.

  last = lastnoncommentindex(string)+1

  icom = index(string(last:), "/*")

  if (icom > 0) then

    openmultilinecomment=.true.

    last = last+icom+1

  endif

  icom = index(string(last:), "*/") ; if (icom > 0) openmultilinecomment=.false.

end function openmultilinecomment

!> Return True if a */ appears on this line

function closemultilinecomment(string)

  character(len=*), intent(in) :: string  !< The input string to process

  logical                      :: closemultilinecomment

! True if a */ appears on this line

  closemultilinecomment = .false.

  if (index(string, "*/")>0) closemultilinecomment=.true.

end function closemultilinecomment

!> Find position of last character before any comments, As marked by "!", "//", or "/*"

!! following F90, C++, or C syntax

function lastnoncommentindex(string)

  character(len=*), intent(in) :: string  !< The input string to process

  integer                      :: lastnoncommentindex

  ! Local variables

  integer :: icom, last

  ! This subroutine is the only place where a comment needs to be defined

  last = len_trim(string)

  icom = index(string(:last), "!") ; if (icom > 0) last = icom-1 ! F90 style

  icom = index(string(:last), "//") ; if (icom > 0) last = icom-1 ! C++ style

  icom = index(string(:last), "/*") ; if (icom > 0) last = icom-1 ! C style

  lastnoncommentindex = last

end function lastnoncommentindex

!> Find position of last non-blank character before any comments

function lastnoncommentnonblank(string)

  character(len=*), intent(in) :: string  !< The input string to process

  integer                      :: lastnoncommentnonblank

  lastnoncommentnonblank = len_trim(string(:lastnoncommentindex(string))) ! Ignore remaining trailing blanks

end function lastnoncommentnonblank

!> Returns a string with tabs replaced by a blank

function replacetabs(string)

  character(len=*), intent(in) :: string  !< The input string to process

  character(len=len(string))   :: replacetabs

  integer :: i

  do i=1, len(string)

    if (string(i:i)==achar(9)) then

      replacetabs(i:i)=" "

    else

      replacetabs(i:i)=string(i:i)

    endif

  enddo

end function replacetabs

!> Trims comments and leading blanks from string

function removecomments(string)

  character(len=*), intent(in) :: string  !< The input string to process

  character(len=len(string))   :: removecomments

  integer :: last

  removecomments=repeat(" ",len(string))

  last = lastnoncommentnonblank(string)

  removecomments(:last)=adjustl(string(:last)) ! Copy only the non-comment part of string

end function removecomments

!> Constructs a string with all repeated white space replaced with single blanks

!! and insert white space where it helps delineate tokens (e.g. around =)

function simplifywhitespace(string)

  character(len=*), intent(in) :: string !< A string to modify to simplify white space

  character(len=len(string)+16)   :: simplifywhitespace

  ! Local variables

  integer :: i, j

  logical :: nonblank = .false., insidestring = .false.

  character(len=1) :: quotechar=" "

  nonblank  = .false. ; insidestring = .false. ! NOTE: For some reason this line is needed??

  i=0

  simplifywhitespace=repeat(" ",len(string)+16)

  do j=1,len_trim(string)

    if (insidestring) then ! Do not change formatting inside strings

      i=i+1

      simplifywhitespace(i:i)=string(j:j)

      if (string(j:j)==quotechar) insidestring=.false. ! End of string

    else ! The following is outside of string delimiters

      if (string(j:j)==" " .or. string(j:j)==achar(9)) then ! Space or tab

        if (nonblank) then ! Only copy a blank if the preceding character was non-blank

          i=i+1

          simplifywhitespace(i:i)=" " ! Not string(j:j) so that tabs are replace by blanks

          nonblank=.false.

        endif

      elseif (string(j:j)=='"' .or. string(j:j)=="'") then ! Start a sting

        i=i+1

        simplifywhitespace(i:i)=string(j:j)

        insidestring=.true.

        quotechar=string(j:j) ! Keep copy of starting quote

        nonblank=.true.       ! For exit from string

      elseif (string(j:j)=='=') then

        ! Insert spaces if this character is "=" so that line contains " = "

        if (nonblank) then

          i=i+1

          simplifywhitespace(i:i)=" "

        endif

        i=i+2

        simplifywhitespace(i-1:i)=string(j:j)//" "

        nonblank=.false.

      else ! All other characters

        i=i+1

        simplifywhitespace(i:i)=string(j:j)

        nonblank=.true.

      endif

    endif ! if (insideString)

  enddo ! j

  if (insidestring) then ! A missing close quote should be flagged

    if (is_root_pe()) call mom_error(fatal, &

      "There is a mismatched quote in the parameter file line: "// &

      trim(string))

  endif

end function simplifywhitespace

!> This subroutine reads the value of an integer model parameter from a parameter file.

subroutine read_param_int(CS, varname, value, fail_if_missing, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  integer,             intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then

    read(value_string(1),*,err = 1001) value

    if (present(set)) set = .true.

  else

    if (present(fail_if_missing)) then ; if (fail_if_missing) then

      if (.not.found) then

        call mom_error(fatal,'read_param_int: Unable to find variable '//trim(varname)// &

                             ' in any input files.')

      else

        call mom_error(fatal,'read_param_int: Variable '//trim(varname)// &

                             ' found but not set in input files.')

      endif

    endif ; endif

    if (present(set)) set = .false.

  endif

  return

 1001 call mom_error(fatal,'read_param_int: read error for integer variable '//trim(varname)// &

                             ' parsing "'//trim(value_string(1))//'"')

end subroutine read_param_int

!> This subroutine reads the values of an array of integer model parameters from a parameter file.

subroutine read_param_int_array(CS, varname, value, fail_if_missing, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  integer, dimension(:),  intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then

    if (present(set)) set = .true.

    read(value_string(1),*,end=991,err=1002) value

 991 return

  else

    if (present(fail_if_missing)) then ; if (fail_if_missing) then

      if (.not.found) then

        call mom_error(fatal,'read_param_int_array: Unable to find variable '//trim(varname)// &

                             ' in any input files.')

      else

        call mom_error(fatal,'read_param_int_array: Variable '//trim(varname)// &

                             ' found but not set in input files.')

      endif

    endif ; endif

    if (present(set)) set = .false.

  endif

  return

 1002 call mom_error(fatal,'read_param_int_array: read error for integer array '//trim(varname)// &

                             ' parsing "'//trim(value_string(1))//'"')

end subroutine read_param_int_array

!> This subroutine reads the value of a real model parameter from a parameter file.

subroutine read_param_real(CS, varname, value, fail_if_missing, scale, set)

  type(param_file_type), intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),      intent(in) :: varname !< The case-sensitive name of the parameter to read

  real,               intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,     optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  real,        optional, intent(in) :: scale   !< A scaling factor that the parameter is multiplied

                                         !! by before it is returned.

  logical,     optional, intent(out) :: set    !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then

    read(value_string(1),*,err=1003) value

    if (present(scale)) value = scale*value

    if (present(set)) set = .true.

  else

    if (present(fail_if_missing)) then ; if (fail_if_missing) then

      if (.not.found) then

        call mom_error(fatal,'read_param_real: Unable to find variable '//trim(varname)// &

                             ' in any input files.')

      else

        call mom_error(fatal,'read_param_real: Variable '//trim(varname)// &

                             ' found but not set in input files.')

      endif

    endif ; endif

    if (present(set)) set = .false.

  endif

  return

 1003 call mom_error(fatal,'read_param_real: read error for real variable '//trim(varname)// &

                             ' parsing "'//trim(value_string(1))//'"')

end subroutine read_param_real

!> This subroutine reads the values of an array of real model parameters from a parameter file.

subroutine read_param_real_array(CS, varname, value, fail_if_missing, scale, set)

  type(param_file_type), intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),      intent(in) :: varname !< The case-sensitive name of the parameter to read

  real, dimension(:), intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,     optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  real,        optional, intent(in) :: scale   !< A scaling factor that the parameter is multiplied

                                         !! by before it is returned.

  logical,     optional, intent(out) :: set    !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical                        :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then

    read(value_string(1),*,end=991,err=1004) value

991 continue

    if (present(scale)) value(:) = scale*value(:)

    if (present(set)) set = .true.

  else

    if (present(fail_if_missing)) then ; if (fail_if_missing) then

      if (.not.found) then

        call mom_error(fatal,'read_param_real_array: Unable to find variable '//trim(varname)// &

                             ' in any input files.')

      else

        call mom_error(fatal,'read_param_real_array: Variable '//trim(varname)// &

                             ' found but not set in input files.')

      endif

    endif ; endif

    if (present(set)) set = .false.

  endif

  return

 1004 call mom_error(fatal,'read_param_real_array: read error for real array '//trim(varname)// &

                             ' parsing "'//trim(value_string(1))//'"')

end subroutine read_param_real_array

!> This subroutine reads the value of a character string model parameter from a parameter file.

subroutine read_param_char(CS, varname, value, fail_if_missing, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  character(len=*),    intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found) then

    value = trim(strip_quotes(value_string(1)))

  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then

    call mom_error(fatal, 'Unable to find variable '//trim(varname)//' in any input files.')

  endif ; endif

  if (present(set)) set = found

end subroutine read_param_char

!> This subroutine reads the values of an array of character string model parameters from a parameter file.

subroutine read_param_char_array(CS, varname, value, fail_if_missing, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  character(len=*), dimension(:), intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1), loc_string

  logical            :: found, defined

  integer            :: i, i_out

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found) then

    loc_string = trim(value_string(1))

    i = index(loc_string,",")

    i_out = 1

    do while(i>0)

      value(i_out) = trim(strip_quotes(loc_string(:i-1)))

      i_out = i_out+1

      loc_string = trim(adjustl(loc_string(i+1:)))

      i = index(loc_string,",")

    enddo

    if (len_trim(loc_string)>0) then

      value(i_out) = trim(strip_quotes(adjustl(loc_string)))

      i_out = i_out+1

    endif

    do i=i_out,SIZE(value) ; value(i) = " " ; enddo

  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then

    call mom_error(fatal, 'Unable to find variable '//trim(varname)//' in any input files.')

  endif ; endif

  if (present(set)) set = found

end subroutine read_param_char_array

!> This subroutine reads the value of a logical model parameter from a parameter file.

subroutine read_param_logical(CS, varname, value, fail_if_missing, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  logical,             intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  logical            :: found, defined

  call get_variable_line(cs, varname, found, defined, value_string, paramislogical=.true.)

  if (found) then

    value = defined

  elseif (present(fail_if_missing)) then ; if (fail_if_missing) then

    call mom_error(fatal, 'Unable to find variable '//trim(varname)//' in any input files.')

  endif ; endif

  if (present(set)) set = found

end subroutine read_param_logical

!> This subroutine reads the value of a time_type model parameter from a parameter file.

subroutine read_param_time(CS, varname, value, timeunit, fail_if_missing, date_format, set)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  type(time_type),     intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file

  real,         optional, intent(in) :: timeunit !< The number of seconds in a time unit for real-number input.

  logical,      optional, intent(in) :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,     optional, intent(out) :: date_format !< If present, this indicates whether this

                                         !! parameter was read in a date format, so that it can

                                         !! later be logged in the same format.

  logical,     optional, intent(out) :: set     !< If present, this indicates whether this parameter

                                         !! has been found and successfully set in the input files.

  ! Local variables

  character(len=CS%max_line_len) :: value_string(1)

  character(len=240) :: err_msg

  logical            :: found, defined

  real               :: real_time, time_unit

  integer            :: vals(7)

  if (present(date_format)) date_format = .false.

  call get_variable_line(cs, varname, found, defined, value_string)

  if (found .and. defined .and. (len_trim(value_string(1)) > 0)) then

    ! Determine whether value string should be parsed for a real number

    ! or a date, in either a string format or a comma-delimited list of values.

    if ((index(value_string(1),'-') > 0) .and. &

        (index(value_string(1),'-',back=.true.) > index(value_string(1),'-'))) then

      ! There are two dashes, so this must be a date format.

      value = set_date(value_string(1), err_msg=err_msg)

      if (len_trim(err_msg) > 0) call mom_error(fatal,'read_param_time: '//&

          trim(err_msg)//' in integer list read error for time-type variable '//&

          trim(varname)// ' parsing "'//trim(value_string(1))//'"')

      if (present(date_format)) date_format = .true.

    elseif (index(value_string(1),',') > 0) then

      ! Initialize vals with an invalid date.

      vals(:) = (/ -999, -999, -999, 0, 0, 0, 0 /)

      read(value_string(1), *, end=995, err=1005) vals

      995 continue

      if ((vals(1) < 0) .or. (vals(2) < 0) .or. (vals(3) < 0)) &

        call mom_error(fatal,'read_param_time: integer list read error for time-type variable '//&

                       trim(varname)// ' parsing "'//trim(value_string(1))//'"')

      value = set_date(vals(1), vals(2), vals(3), vals(4), vals(5), vals(6), &

                       vals(7), err_msg=err_msg)

      if (len_trim(err_msg) > 0) call mom_error(fatal,'read_param_time: '//&

          trim(err_msg)//' in integer list read error for time-type variable '//&

          trim(varname)// ' parsing "'//trim(value_string(1))//'"')

      if (present(date_format)) date_format = .true.

    else

      time_unit = 1.0 ; if (present(timeunit)) time_unit = timeunit

      read( value_string(1), *) real_time

      value = real_to_time(real_time*time_unit)

    endif

    if (present(set)) set = .true.

  else

    if (present(fail_if_missing)) then ; if (fail_if_missing) then

      if (.not.found) then

        call mom_error(fatal, 'Unable to find variable '//trim(varname)//' in any input files.')

      else

        call mom_error(fatal, 'Variable '//trim(varname)//' found but not set in input files.')

      endif

    endif ; endif

    if (present(set)) set = .false.

  endif

  return

  1005 call mom_error(fatal, 'read_param_time: read error for time-type variable '//&

                             trim(varname)// ' parsing "'//trim(value_string(1))//'"')

end subroutine read_param_time

!> This function removes single and double quotes from a character string

function strip_quotes(val_str)

  character(len=*), intent(in) :: val_str !< The character string to work on

  character(len=len(val_str)) :: strip_quotes

  ! Local variables

  integer :: i

  strip_quotes = val_str

  i = index(strip_quotes,achar(34)) ! Double quote

  do while (i>0)

    if (i > 1) then ; strip_quotes = strip_quotes(:i-1)//strip_quotes(i+1:)

    else ; strip_quotes = strip_quotes(2:) ; endif

    i = index(strip_quotes,achar(34)) ! Double quote

  enddo

  i = index(strip_quotes,achar(39)) ! Single quote

  do while (i>0)

    if (i > 1) then ; strip_quotes = strip_quotes(:i-1)//strip_quotes(i+1:)

    else ; strip_quotes = strip_quotes(2:) ; endif

    i = index(strip_quotes,achar(39)) ! Single quote

  enddo

end function strip_quotes

!> This function returns the maximum number of characters in any input lines after they

!! have been combined by any line continuation.

function max_input_line_length(CS, pf_num) result(max_len)

  type(param_file_type),  intent(in) :: cs      !< The control structure for the file_parser module,

                                                !! it is also a structure to parse for run-time parameters

  integer,      optional, intent(in) :: pf_num  !< If present, only work on a single file in the

                                                !! param_file_type, or return 0 if this exceeds the

                                                !! number of files in the param_file_type.

  integer :: max_len !< The maximum number of characters in any input lines after they

                     !! have been combined by any line continuation.

  ! Local variables

  character(len=FILENAME_LENGTH) :: filename

  character :: last_char

  integer :: ipf, ipf_s, ipf_e

  integer :: last, line_len, count, contbufsize

  logical :: continuedline

  max_len = 0

  ipf_s = 1 ; ipf_e = cs%nfiles

  if (present(pf_num)) then

    if (pf_num > cs%nfiles) return

    ipf_s = pf_num ; ipf_e = pf_num

  endif

  paramfile_loop: do ipf = ipf_s, ipf_e

    filename = cs%filename(ipf)

    contbufsize = 0

    continuedline = .false.

    ! Scan through each line of the file

    do count = 1, cs%param_data(ipf)%num_lines

      ! line = CS%param_data(ipf)%fln(count)%line

      last = len_trim(cs%param_data(ipf)%fln(count)%line)

      last_char = " "

      if (last > 0) last_char = cs%param_data(ipf)%fln(count)%line(last:last)

      ! Check if line ends in continuation character (either & or \)

      ! Note achar(92) is a backslash

      if (last_char == achar(92) .or. last_char == "&") then

        contbufsize = contbufsize + last - 1

        continuedline = .true.

        if (count==cs%param_data(ipf)%num_lines .and. is_root_pe()) &

           call mom_error(fatal, "MOM_file_parser : the last line of the file ends in a"// &

                 " continuation character but there are no more lines to read. "// &

                 " Line: '"//trim(cs%param_data(ipf)%fln(count)%line(:last))//"'"// &

                 " in file "//trim(filename)//".")

        cycle ! cycle inorder to append the next line of the file

      elseif (continuedline) then

        ! If we reached this point then this is the end of line continuation

        line_len = contbufsize + last

        contbufsize = 0

        continuedline = .false.

      else  ! This is a simple line with no continuation.

        line_len = last

      endif

      max_len = max(max_len, line_len)

    enddo ! CS%param_data(ipf)%num_lines

  enddo paramfile_loop

end function max_input_line_length

!> This subroutine extracts the contents of lines in the param_file_type that refer to

!! a named parameter.  The value_string that is returned must be interpreted in a way

!! that depends on the type of this variable.

subroutine get_variable_line(CS, varname, found, defined, value_string, paramIsLogical)

  type(param_file_type),  intent(in) :: CS      !< The control structure for the file_parser module,

                                                !! it is also a structure to parse for run-time parameters

  character(len=*),       intent(in) :: varname !< The case-sensitive name of the parameter to read

  logical,               intent(out) :: found   !< If true, this parameter has been found in CS

  logical,               intent(out) :: defined !< If true, this parameter is set (or true) in the CS

  character(len=*),      intent(out) :: value_string(:) !< A string that encodes the new value

  logical, optional,      intent(in) :: paramIsLogical  !< If true, this is a logical parameter

                                                !! that can be simply defined without parsing a value_string.

  ! Local variables

  character(len=CS%max_line_len) :: val_str, lname, origLine

  character(len=CS%max_line_len) :: line, continuationBuffer

  character(len=240) :: blockName

  character(len=FILENAME_LENGTH) :: filename

  integer            :: is, id, isd, isu, ise, iso, ipf

  integer            :: last, last1, ival, oval, max_vals, count, contBufSize

  character(len=52)  :: set

  logical            :: found_override, found_equals

  logical            :: found_define, found_undef

  logical            :: force_cycle, defined_in_line, continuedLine

  logical            :: variableKindIsLogical, valueIsSame

  logical            :: inWrongBlock, fullPathParameter

  logical, parameter :: requireNamedClose = .false.

  integer, parameter :: verbose = 1

  set = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz"

  continuationbuffer = repeat(" ", cs%max_line_len)

  contbufsize = 0

  variablekindislogical=.false.

  if (present(paramislogical)) variablekindislogical = paramislogical

  ! Find the first instance (if any) where the named variable is found, and

  ! return variables indicating whether this variable is defined and the string

  ! that contains the value of this variable.

  found = .false.

  oval = 0 ; ival = 0

  max_vals = SIZE(value_string)

  do is=1,max_vals ; value_string(is) = " " ; enddo

  paramfile_loop: do ipf = 1, cs%nfiles

    filename = cs%filename(ipf)

    continuedline = .false.

    blockname = ''

    ! Scan through each line of the file

    do count = 1, cs%param_data(ipf)%num_lines

      line = cs%param_data(ipf)%fln(count)%line

      last = len_trim(line)

      last1 = max(1,last)

      ! Check if line ends in continuation character (either & or \)

      ! Note achar(92) is a backslash

      if (line(last1:last1) == achar(92).or.line(last1:last1) == "&") then

        continuationbuffer(contbufsize+1:contbufsize+len_trim(line))=line(:last-1)

        contbufsize=contbufsize + len_trim(line)-1

        continuedline = .true.

        if (count==cs%param_data(ipf)%num_lines .and. is_root_pe()) &

           call mom_error(fatal, "MOM_file_parser : the last line"// &

                 " of the file ends in a continuation character but"// &

                 " there are no more lines to read. "// &

                 " Line: '"//trim(line(:last))//"'"//&

                 " in file "//trim(filename)//".")

        cycle ! cycle inorder to append the next line of the file

      elseif (continuedline) then

        ! If we reached this point then this is the end of line continuation

        continuationbuffer(contbufsize+1:contbufsize+len_trim(line))=line(:last)

        line = continuationbuffer

        continuationbuffer=repeat(" ",cs%max_line_len) ! Clear for next use

        contbufsize = 0

        continuedline = .false.

        last = len_trim(line)

      endif

      origline = trim(line) ! Keep original for error messages

      ! Check for '#override' at start of line

      found_override = .false. ; found_define = .false. ; found_undef = .false.

      iso = index(line(:last), "#override " )! ; if (is > 0) found_override = .true.

      if (iso>1) call mom_error(fatal, "MOM_file_parser : #override was found "// &

                 " but was not the first keyword."// &

                 " Line: '"//trim(line(:last))//"'"//&

                 " in file "//trim(filename)//".")

      if (iso==1) then

        found_override = .true.

        if (index(line(:last), "#override define ")==1) found_define = .true.

        if (index(line(:last), "#override undef ")==1) found_undef = .true.

        line = trim(adjustl(line(iso+10:last))) ; last = len_trim(line)

      endif

      ! Newer form of parameter block, block%, %block or block%param or

      iso=index(line(:last),'%')

      fullpathparameter = .false.

      if (iso==1) then ! % is first character means this is a close

        if (len_trim(blockname)==0 .and. is_root_pe()) call mom_error(fatal, &

            'get_variable_line: An extra close block was encountered. Line="'// &

            trim(line(:last))//'"' )

        if (last>1 .and. trim(blockname)/=trim(line(2:last)) .and. is_root_pe()) &

            call mom_error(fatal, 'get_variable_line: A named close for a parameter'// &

            ' block did not match the open block. Line="'//trim(line(:last))//'"' )

        if (last==1 .and. requirenamedclose) & ! line = '%' is a generic (unnamed) close

            call mom_error(fatal, 'get_variable_line: A named close for a parameter'// &

            ' block is required but found "%". Block="'//trim(blockname)//'"' )

        blockname = popblocklevel(blockname)

        call flag_line_as_read(cs%param_data(ipf)%line_used,count)

      elseif (iso==last) then ! This is a new block if % is last character

        blockname = pushblocklevel(blockname, line(:iso-1))

        call flag_line_as_read(cs%param_data(ipf)%line_used,count)

      else ! This is of the form block%parameter = ... (full path parameter)

        iso=index(line(:last),'%',.true.)

        ! Check that the parameter block names on the line matches the state set by the caller

        if (iso>0 .and. trim(cs%blockName%name)==trim(line(:iso-1))) then

          fullpathparameter = .true.

          line = trim(line(iso+1:last)) ! Strip away the block name for subsequent processing

          last = len_trim(line)

        endif

      endif

      ! We should only interpret this line if this block is the active block

      inwrongblock = .false.

      if (len_trim(blockname)>0) then ! In a namelist block in file

        if (trim(cs%blockName%name)/=trim(blockname)) inwrongblock = .true. ! Not in the required block

      endif

      if (len_trim(cs%blockName%name)>0) then ! In a namelist block in the model

        if (trim(cs%blockName%name)/=trim(blockname)) inwrongblock = .true. ! Not in the required block

      endif

      if (inwrongblock .and. .not. fullpathparameter) then

        if (index(" "//line(:last+1), " "//trim(varname)//" ")>0) &

          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

               ' found outside of block '//trim(cs%blockName%name)//'%. Ignoring.')

        cycle

      endif

      ! Determine whether this line mentions the named parameter or not

      if (index(" "//line(:last)//" ", " "//trim(varname)//" ") == 0) cycle

      ! Detect keywords

      found_equals = .false.

      isd = index(line(:last), "define" )! ; if (isd > 0) found_define = .true.

      isu = index(line(:last), "undef" )! ; if (isu > 0) found_undef = .true.

      ise = index(line(:last), " = " ) ; if (ise > 1) found_equals = .true.

      if (index(line(:last), "#define ")==1) found_define = .true.

      if (index(line(:last), "#undef ")==1) found_undef = .true.

      ! Check for missing, mutually exclusive or incomplete keywords

      if (.not. (found_define .or. found_undef .or. found_equals)) then

        if (found_override) then

          call mom_error(fatal, "MOM_file_parser : override was found " // &

              " without a define or undef." // &

              " Line: '" // trim(line(:last)) // "'" // &

              " in file " // trim(filename) // ".")

        else

          call mom_error(fatal, "MOM_file_parser : the parameter name '" // &

              trim(varname) // "' was found without define or undef." // &

              " Line: '" // trim(line(:last)) // "'" // &

              " in file " // trim(filename) // ".")

        endif

      endif

      if (found_equals .and. (found_define .or. found_undef)) &

             call mom_error(fatal, &

               "MOM_file_parser : Both 'a=b' and 'undef/define' syntax occur."// &

               " Line: '"//trim(line(:last))//"'"//&

               " in file "//trim(filename)//".")

      ! Interpret the line and collect values, if any

      ! NOTE: At least one of these must be true

      if (found_define) then

        ! Move starting pointer to first letter of defined name.

        is = isd + 5 + scan(line(isd+6:last), set)

        id = scan(line(is:last), ' ')  ! Find space between name and value

        if ( id == 0 ) then

          ! There is no space so the name is simply being defined.

          lname = trim(line(is:last))

          if (trim(lname) /= trim(varname)) cycle

          val_str = " "

        else

          ! There is a string or number after the name.

          lname = trim(line(is:is+id-1))

          if (trim(lname) /= trim(varname)) cycle

          val_str = trim(adjustl(line(is+id:last)))

        endif

        found = .true. ; defined_in_line = .true.

      elseif (found_undef) then

        ! Move starting pointer to first letter of undefined name.

        is = isu + 4 + scan(line(isu+5:last), set)

        id = scan(line(is:last), ' ')  ! Find the first space after the name.

        if (id > 0) last = is + id - 1

        lname = trim(line(is:last))

        if (trim(lname) /= trim(varname)) cycle

        val_str = " "

        found = .true. ; defined_in_line = .false.

      elseif (found_equals) then

        ! Move starting pointer to first letter of defined name.

        is = scan(line(1:ise), set)

        lname = trim(line(is:ise-1))

        if (trim(lname) /= trim(varname)) cycle

        val_str = trim(adjustl(line(ise+3:last)))

        if (variablekindislogical) then ! Special handling for logicals

          read(val_str(:len_trim(val_str)),*) defined_in_line

        else

          defined_in_line = .true.

        endif

        found = .true.

      endif

      ! This line has now been used.

      call flag_line_as_read(cs%param_data(ipf)%line_used,count)

      ! Detect inconsistencies

      force_cycle = .false.

      valueissame = (trim(val_str) == trim(value_string(max_vals)))

      if (found_override .and. (oval >= max_vals)) then

        if (is_root_pe()) then

          if ((defined_in_line .neqv. defined) .or. .not. valueissame) then

            call mom_error(fatal,"MOM_file_parser : "//trim(varname)// &

                     " found with multiple inconsistent overrides."// &

                     " Line A: '"//trim(value_string(max_vals))//"'"//&

                     " Line B: '"//trim(line(:last))//"'"//&

                     " in file "//trim(filename)//" caused the model failure.")

          else

            call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

                     " over-ridden more times than is permitted."// &

                     " Line: '"//trim(line(:last))//"'"//&

                     " in file "//trim(filename)//" is being ignored.")

          endif

        endif

        force_cycle = .true.

      endif

      if (.not.found_override .and. (oval > 0)) then

        if (is_root_pe()) &

          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

                   " has already been over-ridden."// &

                   " Line: '"//trim(line(:last))//"'"//&

                   " in file "//trim(filename)//" is being ignored.")

        force_cycle = .true.

      endif

      if (.not.found_override .and. (ival >= max_vals)) then

        if (is_root_pe()) then

          if ((defined_in_line .neqv. defined) .or. .not. valueissame) then

            call mom_error(fatal,"MOM_file_parser : "//trim(varname)// &

                     " found with multiple inconsistent definitions."// &

                     " Line A: '"//trim(value_string(max_vals))//"'"//&

                     " Line B: '"//trim(line(:last))//"'"//&

                     " in file "//trim(filename)//" caused the model failure.")

          else

            call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

                     " occurs more times than is permitted."// &

                     " Line: '"//trim(line(:last))//"'"//&

                     " in file "//trim(filename)//" is being ignored.")

          endif

        endif

        force_cycle = .true.

      endif

      if (force_cycle) cycle

      ! Store new values

      if (found_override) then

        oval = oval + 1

        value_string(oval) = trim(val_str)

        defined = defined_in_line

        if (verbose > 0 .and. ival > 0 .and. is_root_pe() .and. &

            .not. overridewarninghasbeenissued(cs%chain, trim(varname)) ) &

          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

                 " over-ridden.  Line: '"//trim(line(:last))//"'"//&

                 " in file "//trim(filename)//".")

      else ! (.not. found_overide)

        ival = ival + 1

        value_string(ival) = trim(val_str)

        defined = defined_in_line

        if (verbose > 1 .and. is_root_pe()) &

          call mom_error(warning,"MOM_file_parser : "//trim(varname)// &

                 " set.  Line: '"//trim(line(:last))//"'"//&

                 " in file "//trim(filename)//".")

      endif

    enddo ! CS%param_data(ipf)%num_lines

    if (len_trim(blockname)>0 .and. is_root_pe()) call mom_error(fatal, &

      'A namelist/parameter block was not closed. Last open block appears '// &

      'to be "'//trim(blockname)//'".')

  enddo paramfile_loop

end subroutine get_variable_line

!> Record that a line has been used to set a parameter

subroutine flag_line_as_read(line_used, count)

  logical, dimension(:), pointer    :: line_used !< A structure indicating which lines have been read

  integer,               intent(in) :: count !< The parameter on this line number has been read

  line_used(count) = .true.

end subroutine flag_line_as_read

!> Returns true if an override warning has been issued for the variable varName

function overridewarninghasbeenissued(chain, varName)

  type(link_parameter), pointer    :: chain   !< The linked list of variables that have already had

                                              !! override warnings issued

  character(len=*),     intent(in) :: varname !< The name of the variable being queried for warnings

  logical                          :: overridewarninghasbeenissued

  ! Local variables

  type(link_parameter), pointer :: newlink => null(), this => null()

  overridewarninghasbeenissued = .false.

  this => chain

  do while( associated(this) )

    if (trim(varname) == trim(this%name)) then

      overridewarninghasbeenissued = .true.

      return

    endif

    this => this%next

  enddo

  allocate(newlink)

  newlink%name = trim(varname)

  newlink%hasIssuedOverrideWarning = .true.

  newlink%next => chain

  chain => newlink

end function overridewarninghasbeenissued

! The following subroutines write out to a log file.

!> Log the version of a module to a log file and/or stdout, and/or to the

!! parameter documentation file.

subroutine log_version_cs(CS, modulename, version, desc, log_to_all, all_default, layout, debugging)

  type(param_file_type),      intent(in) :: CS         !< File parser type

  character(len=*),           intent(in) :: modulename !< Name of calling module

  character(len=*),           intent(in) :: version    !< Version string of module

  character(len=*), optional, intent(in) :: desc       !< Module description

  logical,          optional, intent(in) :: log_to_all !< If present and true, log this parameter to the

                                                       !! ..._doc.all files, even if this module also has layout

                                                       !! or debugging parameters.

  logical,          optional, intent(in) :: all_default !< If true, all parameters take their default values.

  logical,          optional, intent(in) :: layout     !< If present and true, this module has layout parameters.

  logical,          optional, intent(in) :: debugging  !< If present and true, this module has debugging parameters.

  ! Local variables

  character(len=240) :: mesg

  mesg = trim(modulename)//": "//trim(version)

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  if (present(desc)) call doc_module(cs%doc, modulename, desc, log_to_all, all_default, layout, debugging)

end subroutine log_version_cs

!> Log the version of a module to a log file and/or stdout.

subroutine log_version_plain(modulename, version)

  character(len=*),           intent(in) :: modulename !< Name of calling module

  character(len=*),           intent(in) :: version    !< Version string of module

  ! Local variables

  character(len=240) :: mesg

  mesg = trim(modulename)//": "//trim(version)

  if (is_root_pe()) then

    write(stdlog(),'(a)') trim(mesg)

  endif

end subroutine log_version_plain

!> Log the name and value of an integer model parameter in documentation files.

subroutine log_param_int(CS, modulename, varname, value, desc, units, &

                         default, layoutParam, debuggingParam, like_default)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the module using this parameter

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  integer,                    intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in) :: units   !< The units of this parameter

  integer,          optional, intent(in) :: default !< The default value of the parameter

  logical,          optional, intent(in) :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  character(len=240) :: mesg, myunits

  write(mesg, '("  ",a," ",a,": ",a)') trim(modulename), trim(varname), trim(left_int(value))

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  myunits = " " ; if (present(units)) write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, value, default, &

                   layoutparam=layoutparam, debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_int

!> Log the name and values of an array of integer model parameter in documentation files.

subroutine log_param_int_array(CS, modulename, varname, value, desc, &

                               units, default, defaults, layoutParam, debuggingParam, like_default)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the module using this parameter

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  integer, dimension(:),      intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in) :: units   !< The units of this parameter

  integer,          optional, intent(in) :: default !< The uniform default value of this parameter

  integer,          optional, intent(in) :: defaults(:) !< The element-wise default values of this parameter

  logical,          optional, intent(in) :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  character(len=CS%max_line_len+120) :: mesg

  character(len=240) :: myunits

  write(mesg, '("  ",a," ",a,": ",A)') trim(modulename), trim(varname), trim(left_ints(value))

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  myunits = " " ; if (present(units)) write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, value, default, defaults, &

                   layoutparam=layoutparam, debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_int_array

!> Log the name and value of a real model parameter in documentation files.

subroutine log_param_real(CS, modulename, varname, value, desc, units, &

                          default, debuggingParam, like_default, unscale)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the calling module

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  real,                       intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*),           intent(in) :: units   !< The units of this parameter

  real,             optional, intent(in) :: default !< The default value of the parameter

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  real,             optional, intent(in) :: unscale   !< A reciprocal scaling factor that the parameter is

                                         !! multiplied by before it is logged

  real :: log_val ! The parameter value that is written out

  character(len=240) :: mesg, myunits

  log_val = value ; if (present(unscale)) log_val = unscale * value

  write(mesg, '("  ",a," ",a,": ",a)') &

    trim(modulename), trim(varname), trim(left_real(log_val))

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, log_val, default, &

                   debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_real

!> Log the name and values of an array of real model parameter in documentation files.

subroutine log_param_real_array(CS, modulename, varname, value, desc, &

                                units, default, defaults, debuggingParam, like_default, unscale)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the calling module

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  real, dimension(:),         intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                             !! present, this parameter is not written to a doc file

  character(len=*),           intent(in) :: units   !< The units of this parameter

  real,             optional, intent(in) :: default !< A uniform default value of the parameter

  real,             optional, intent(in) :: defaults(:) !< The element-wise defaults of the parameter

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  real,             optional, intent(in) :: unscale   !< A reciprocal scaling factor that the parameter is

                                         !! multiplied by before it is logged

  real, dimension(size(value)) :: log_val ! The array of parameter values that is written out

  character(len=:), allocatable :: mesg

  character(len=240) :: myunits

  log_val(:) = value(:) ; if (present(unscale)) log_val(:) = unscale * value(:)

 !write(mesg, '("  ",a," ",a,": ",ES19.12,99(",",ES19.12))') &

 !write(mesg, '("  ",a," ",a,": ",G,99(",",G))') &

 !  trim(modulename), trim(varname), value

  mesg = "  " // trim(modulename) // " " // trim(varname) // ": " // trim(left_reals(log_val))

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, log_val, default, defaults, &

                   debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_real_array

!> Log the name and value of a logical model parameter in documentation files.

subroutine log_param_logical(CS, modulename, varname, value, desc, &

                             units, default, layoutParam, debuggingParam, like_default)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the calling module

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  logical,                    intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in) :: units   !< The units of this parameter

  logical,          optional, intent(in) :: default !< The default value of the parameter

  logical,          optional, intent(in) :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  character(len=240) :: mesg, myunits

  if (value) then

    write(mesg, '("  ",a," ",a,": True")') trim(modulename), trim(varname)

  else

    write(mesg, '("  ",a," ",a,": False")') trim(modulename), trim(varname)

  endif

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  myunits = "Boolean" ; if (present(units)) write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, value, default, &

                   layoutparam=layoutparam, debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_logical

!> Log the name and value of a character string model parameter in documentation files.

subroutine log_param_char(CS, modulename, varname, value, desc, units, &

                          default, layoutParam, debuggingParam, like_default)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the calling module

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  character(len=*),           intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in) :: units   !< The units of this parameter

  character(len=*), optional, intent(in) :: default !< The default value of the parameter

  logical,          optional, intent(in) :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  character(len=:), allocatable :: mesg

  character(len=240) :: myunits

  mesg = "  " // trim(modulename) // " " // trim(varname) // ": " // trim(value)

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  myunits = " " ; if (present(units)) write(myunits(1:240),'(A)') trim(units)

  if (present(desc)) &

    call doc_param(cs%doc, varname, desc, myunits, value, default, &

                   layoutparam=layoutparam, debuggingparam=debuggingparam, like_default=like_default)

end subroutine log_param_char

!> This subroutine writes the value of a time-type parameter to a log file,

!! along with its name and the module it came from.

subroutine log_param_time(CS, modulename, varname, value, desc, units, &

                          default, timeunit, layoutParam, debuggingParam, log_date, like_default)

  type(param_file_type),      intent(in) :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: modulename !< The name of the calling module

  character(len=*),           intent(in) :: varname !< The name of the parameter to log

  type(time_type),            intent(in) :: value   !< The value of the parameter to log

  character(len=*), optional, intent(in) :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in) :: units   !< The units of this parameter

  type(time_type),  optional, intent(in) :: default !< The default value of the parameter

  real,             optional, intent(in) :: timeunit !< The number of seconds in a time unit for

                                         !! real-number output.

  logical,          optional, intent(in) :: log_date   !< If true, log the time_type in date format.

                                         !! If missing the default is false.

  logical,          optional, intent(in) :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in) :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in) :: like_default !< If present and true, log this parameter as

                                         !! though it has the default value, even if there is no default.

  ! Local variables

  real :: real_time, real_default

  logical :: use_timeunit, date_format

  character(len=240) :: mesg, myunits

  character(len=80) :: date_string, default_string

  integer :: days, secs, ticks

  use_timeunit = .false.

  date_format = .false. ; if (present(log_date)) date_format = log_date

  call get_time(value, secs, days, ticks)

  if (ticks == 0) then

    write(mesg, '("  ",a," ",a," (Time): ",i0,":",i0)') trim(modulename), &

       trim(varname), days, secs

  else

    write(mesg, '("  ",a," ",a," (Time): ",i0,":",i0,":",i0)') trim(modulename), &

       trim(varname), days, secs, ticks

  endif

  if (is_root_pe()) then

    if (cs%log_open) write(cs%stdlog,'(a)') trim(mesg)

    if (cs%log_to_stdout) write(cs%stdout,'(a)') trim(mesg)

  endif

  if (present(desc)) then

    if (present(timeunit)) use_timeunit = (timeunit > 0.0)

    if (date_format) then

      myunits='[date]'

      date_string = convert_date_to_string(value)

      if (present(default)) then

        default_string = convert_date_to_string(default)

        call doc_param(cs%doc, varname, desc, myunits, date_string, &

                       default=default_string, layoutparam=layoutparam, &

                       debuggingparam=debuggingparam, like_default=like_default)

      else

        call doc_param(cs%doc, varname, desc, myunits, date_string, &

                       layoutparam=layoutparam, debuggingparam=debuggingparam, like_default=like_default)

      endif

    elseif (use_timeunit) then

      if (present(units)) then

        write(myunits(1:240),'(A)') trim(units)

      else

        if (abs(timeunit-1.0) < 0.01) then ; myunits = "seconds"

        elseif (abs(timeunit-3600.0) < 1.0) then ; myunits = "hours"

        elseif (abs(timeunit-86400.0) < 1.0) then ; myunits = "days"

        elseif (abs(timeunit-3.1e7) < 1.0e6) then ; myunits = "years"

        else ; write(myunits,'(es8.2," sec")') timeunit ; endif

      endif

      real_time = (86400.0/timeunit)*days + secs/timeunit

      if (ticks > 0) real_time = real_time + &

                           real(ticks) / (timeunit*get_ticks_per_second())

      if (present(default)) then

        call get_time(default, secs, days, ticks)

        real_default = (86400.0/timeunit)*days + secs/timeunit

        if (ticks > 0) real_default = real_default + &

                           real(ticks) / (timeunit*get_ticks_per_second())

        call doc_param(cs%doc, varname, desc, myunits, real_time, real_default, like_default=like_default)

      else

        call doc_param(cs%doc, varname, desc, myunits, real_time, like_default=like_default)

      endif

    else

      call doc_param(cs%doc, varname, desc, value, default, units=units, like_default=like_default)

    endif

  endif

end subroutine log_param_time

!> This function converts a date into a string, valid with ticks and for dates up to year 99,999,999

function convert_date_to_string(date) result(date_string)

  type(time_type), intent(in) :: date !< The date to be translated into a string.

  character(len=40) :: date_string    !< A date string in a format like YYYY-MM-DD HH:MM:SS.sss

  ! Local variables

  character(len=40) :: sub_string

  real    :: real_secs

  integer :: yrs, mons, days, hours, mins, secs, ticks, ticks_per_sec

  call get_date(date, yrs, mons, days, hours, mins, secs, ticks)

  write (date_string, '(i8.4)') yrs

  write (sub_string, '("-", i2.2, "-", I2.2, " ", i2.2, ":", i2.2, ":")') &

         mons, days, hours, mins

  date_string = trim(adjustl(date_string)) // trim(sub_string)

  if (ticks > 0) then

    ticks_per_sec = get_ticks_per_second()

    real_secs = secs + ticks/ticks_per_sec

    if (ticks_per_sec <= 100) then

      write (sub_string, '(F7.3)') real_secs

    else

      write (sub_string, '(F10.6)') real_secs

    endif

  else

    write (sub_string, '(i2.2)') secs

  endif

  date_string = trim(date_string) // trim(adjustl(sub_string))

end function convert_date_to_string

!> This subroutine reads the value of an integer model parameter from a parameter file

!! and logs it in documentation files.

subroutine get_param_int(CS, modulename, varname, value, desc, units, &

               default, fail_if_missing, do_not_read, do_not_log, &

               layoutParam, debuggingParam, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  integer,                    intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  integer,          optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  integer :: new_name_value  ! The value that is set when the standard name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then

    if (present(default)) value = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value = value

      call read_param_int(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_int(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = (value == new_name_value)

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_int(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_int(cs, modulename, varname, value, desc, units, &

                       default, layoutparam, debuggingparam)

  endif

end subroutine get_param_int

!> This subroutine reads the values of an array of integer model parameters from a parameter file

!! and logs them in documentation files.

subroutine get_param_int_array(CS, modulename, varname, value, desc, units, &

               default, defaults, fail_if_missing, do_not_read, do_not_log, &

               layoutParam, debuggingParam, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  integer, dimension(:),      intent(inout) :: value   !< The value of the parameter that may be reset

                                         !! from the parameter file

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  integer,          optional, intent(in)    :: default !< The uniform default value of this parameter

  integer,          optional, intent(in)    :: defaults(:) !< The element-wise default values of this parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  integer :: new_name_value(size(value))  ! The values that are set when the old name is used.

  integer :: m

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (present(defaults)) then

    if (present(default)) call mom_error(fatal, &

          "get_param_int_array: Only one of default and defaults can be specified at a time.")

    if (size(defaults) /= size(value)) call mom_error(fatal, &

          "get_param_int_array: The size of defaults and value are not the same.")

  endif

  if (do_read) then

    if (present(default)) value(:) = default

    if (present(defaults)) value(:) = defaults(:)

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value(:) = value(:)

      call read_param_int_array(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_int_array(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = .true.

        do m=1,size(value) ; if (value(m) /= new_name_value(m)) same_value = .false. ; enddo

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_int_array(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_int_array(cs, modulename, varname, value, desc, units, &

                             default, defaults, layoutparam, debuggingparam)

  endif

end subroutine get_param_int_array

!> This subroutine reads the value of a real model parameter from a parameter file

!! and logs it in documentation files.

subroutine get_param_real(CS, modulename, varname, value, desc, units, &

               default, fail_if_missing, do_not_read, do_not_log, &

               debuggingParam, scale, unscaled, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  real,                       intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*),           intent(in)    :: units   !< The units of this parameter

  real,             optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  real,             optional, intent(in)    :: scale   !< A scaling factor that the parameter is

                                         !! multiplied by before it is returned.

  real,             optional, intent(out)   :: unscaled !< The value of the parameter that would be

                                         !! returned without any multiplication by a scaling factor.

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  real :: new_name_value  ! The value that is set when the old name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then

    if (present(default)) value = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value = value

      call read_param_real(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_real(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = (new_name_used .and. old_name_used .and. (value == new_name_value))

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_real(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_real(cs, modulename, varname, value, desc, units, &

                        default, debuggingparam)

  endif

  if (present(unscaled)) unscaled = value

  if (present(scale)) value = scale*value

end subroutine get_param_real

!> This subroutine reads the values of an array of real model parameters from a parameter file

!! and logs them in documentation files.

subroutine get_param_real_array(CS, modulename, varname, value, desc, units, &

               default, defaults, fail_if_missing, do_not_read, do_not_log, debuggingParam, &

               scale, unscaled, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  real, dimension(:),         intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*),           intent(in)    :: units   !< The units of this parameter

  real,             optional, intent(in)    :: default !< A uniform default value of the parameter

  real,             optional, intent(in)    :: defaults(:) !< The element-wise defaults of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  real,             optional, intent(in)    :: scale   !< A scaling factor that the parameter is

                                         !! multiplied by before it is returned.

  real, dimension(:), optional, intent(out) :: unscaled !< The value of the parameter that would be

                                         !! returned without any multiplication by a scaling factor.

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  real    :: new_name_value(size(value))  ! The values that are set when the standard name is used.

  integer :: m

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (present(defaults)) then

    if (present(default)) call mom_error(fatal, &

          "get_param_real_array: Only one of default and defaults can be specified at a time.")

    if (size(defaults) /= size(value)) call mom_error(fatal, &

          "get_param_real_array: The size of defaults and value are not the same.")

  endif

  if (do_read) then

    if (present(default)) value(:) = default

    if (present(defaults)) value(:) = defaults(:)

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value(:) = value(:)

      call read_param_real_array(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_real_array(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = .true.

        do m=1,size(value) ; if (value(m) /= new_name_value(m)) same_value = .false. ; enddo

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_real_array(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_real_array(cs, modulename, varname, value, desc, &

                              units, default, defaults, debuggingparam)

  endif

  if (present(unscaled)) unscaled(:) = value(:)

  if (present(scale)) value(:) = scale*value(:)

end subroutine get_param_real_array

!> This subroutine reads the value of a character string model parameter from a parameter file

!! and logs it in documentation files.

subroutine get_param_char(CS, modulename, varname, value, desc, units, &

               default, fail_if_missing, do_not_read, do_not_log, &

               layoutParam, debuggingParam, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  character(len=*),           intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  character(len=*), optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  character(len=:), allocatable :: new_name_value  ! The value that is set when the standard name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then

    if (present(default)) value = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value = value

      call read_param_char(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_char(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = (trim(value) == trim(new_name_value))

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_char(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_char(cs, modulename, varname, value, desc, units, &

                        default, layoutparam, debuggingparam)

  endif

end subroutine get_param_char

!> This subroutine reads the values of an array of character string model parameters

!! from a parameter file and logs them in documentation files.

subroutine get_param_char_array(CS, modulename, varname, value, desc, units, &

               default, fail_if_missing, do_not_read, do_not_log, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  character(len=*), dimension(:), intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  character(len=*), optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  integer :: i, m, len_tot, len_val

  character(len=:), allocatable :: cat_val

  character(len=:), allocatable :: new_name_value(:)  ! The value that is set when the standard name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then

    if (present(default)) value(:) = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value(:) = value(:)

      call read_param_char_array(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_char_array(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = .true.

        do m=1,size(value) ; if (trim(value(m)) /= trim(new_name_value(m))) same_value = .false. ; enddo

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_char_array(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    cat_val = trim(value(1)) ; len_tot = len_trim(value(1))

    do i=2,size(value)

      len_val = len_trim(value(i))

      if ((len_val > 0) .and. (len_tot + len_val + 2 < 240)) then

        cat_val = trim(cat_val)//achar(34)// ", "//achar(34)//trim(value(i))

        len_tot = len_tot + len_val

      endif

    enddo

    call log_param_char(cs, modulename, varname, cat_val, desc, &

                        units, default)

  endif

end subroutine get_param_char_array

!> This subroutine reads the value of a logical model parameter from a parameter file

!! and logs it in documentation files.

subroutine get_param_logical(CS, modulename, varname, value, desc, units, &

               default, fail_if_missing, do_not_read, do_not_log, &

               layoutParam, debuggingParam, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  logical,                    intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  logical,          optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  logical,          optional, intent(in)    :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log

  logical :: new_name_used, old_name_used, same_value

  logical :: new_name_value  ! The value that is set when the standard name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  if (do_read) then

    if (present(default)) value = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value = value

      call read_param_logical(cs, old_name, value, set=old_name_used)

      if (old_name_used) then

        call read_param_logical(cs, varname, new_name_value, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = (value .eqv. new_name_value)

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_logical(cs, varname, value, fail_if_missing)

    endif

  endif

  if (do_log) then

    call log_param_logical(cs, modulename, varname, value, desc, &

                           units, default, layoutparam, debuggingparam)

  endif

end subroutine get_param_logical

!> This subroutine reads the value of a time-type model parameter from a parameter file

!! and logs it in documentation files.

subroutine get_param_time(CS, modulename, varname, value, desc, units, &

                          default, fail_if_missing, do_not_read, do_not_log, &

                          timeunit, layoutParam, debuggingParam, &

                          log_as_date, old_name)

  type(param_file_type),      intent(in)    :: CS      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in)    :: modulename !< The name of the calling module

  character(len=*),           intent(in)    :: varname !< The case-sensitive name of the parameter to read

  type(time_type),            intent(inout) :: value   !< The value of the parameter that may be

                                         !! read from the parameter file and logged

  character(len=*), optional, intent(in)    :: desc    !< A description of this variable; if not

                                         !! present, this parameter is not written to a doc file

  character(len=*), optional, intent(in)    :: units   !< The units of this parameter

  type(time_type),  optional, intent(in)    :: default !< The default value of the parameter

  logical,          optional, intent(in)    :: fail_if_missing !< If present and true, a fatal error occurs

                                         !! if this variable is not found in the parameter file

  logical,          optional, intent(in)    :: do_not_read  !< If present and true, do not read a

                                         !! value for this parameter, although it might be logged.

  logical,          optional, intent(in)    :: do_not_log !< If present and true, do not log this

                                         !! parameter to the documentation files

  real,             optional, intent(in)    :: timeunit !< The number of seconds in a time unit for

                                         !! real-number input to be translated to a time.

  logical,          optional, intent(in)    :: layoutParam !< If present and true, this parameter is

                                         !! logged in the layout parameter file

  logical,          optional, intent(in)    :: debuggingParam !< If present and true, this parameter is

                                         !! logged in the debugging parameter file

  logical,          optional, intent(in)    :: log_as_date  !< If true, log the time_type in date

                                         !! format. The default is false.

  character(len=*), optional, intent(in)    :: old_name !< A case-sensitive archaic name of the parameter

                                         !! to read.  Errors or warnings are issued if the old name

                                         !! is being used.

  ! Local variables

  logical :: do_read, do_log, log_date

  logical :: new_name_used, old_name_used, same_value

  type(time_type) :: new_name_value  ! The value that is set when the standard name is used.

  do_read = .true. ; if (present(do_not_read)) do_read = .not.do_not_read

  do_log  = .true. ; if (present(do_not_log))  do_log  = .not.do_not_log

  log_date = .false.

  if (do_read) then

    if (present(default)) value = default

    old_name_used = .false.

    if (present(old_name)) then

      new_name_value = value

      call read_param_time(cs, old_name, value, timeunit, date_format=log_date, set=old_name_used)

      if (old_name_used) then

        call read_param_time(cs, varname, new_name_value, timeunit, date_format=log_date, set=new_name_used)

        ! Issue appropriate warnings or error messages.

        same_value = (value == new_name_value)

        call archaic_param_name_message(varname, old_name, new_name_used, same_value)

      endif

    endif

    if (.not.old_name_used) then ! Old name is either not present or not set.

      call read_param_time(cs, varname, value, timeunit, fail_if_missing, date_format=log_date)

    endif

  endif

  if (do_log) then

    if (present(log_as_date)) log_date = log_as_date

    call log_param_time(cs, modulename, varname, value, desc, units, default, &

                        timeunit, layoutparam=layoutparam, &

                        debuggingparam=debuggingparam, log_date=log_date)

  endif

end subroutine get_param_time

!> Issue error messages or warnings about the use of an archaic parameter name.

subroutine archaic_param_name_message(varname, old_name, new_name_used, same_value)

  character(len=*), intent(in) :: varname  !< The case-sensitive name of the parameter to read

  character(len=*), intent(in) :: old_name !< The case-sensitive archaic name of the parameter

  logical,          intent(in) :: new_name_used  !< True if varname is used in the parameter file.

  logical,          intent(in) :: same_value !< True if varname and old_name give the same values.

  if (new_name_used .and. same_value) then

    call mom_error(warning, "The runtime parameter "//trim(varname)//&

                 " is also being set consistently via its older name of "//trim(old_name)//&

                 ".  Please migrate to only using "//trim(varname)//".")

  elseif (new_name_used .and. .not.same_value) then

    call mom_error(fatal, "The runtime parameter "//trim(varname)//&

                 " is also being set inconsistently via its older name of "//trim(old_name)//&

                 ".  Only use "//trim(varname)//".")

  else

    call mom_error(warning, "The runtime parameter "//trim(varname)//&

                   " is being set via its soon to be obsolete name of "//trim(old_name)//&

                   ".  Please migrate to using "//trim(varname)//".")

  endif

end subroutine archaic_param_name_message

! -----------------------------------------------------------------------------

!> Resets the parameter block name to blank

subroutine clearparameterblock(CS)

  type(param_file_type), intent(in) :: cs      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  type(parameter_block), pointer :: block => null()

  if (associated(cs%blockName)) then

    block => cs%blockName

    block%name = ''

  else

    if (is_root_pe()) call mom_error(fatal, &

      'clearParameterBlock: A clear was attempted before allocation.')

  endif

end subroutine clearparameterblock

!> Tags blockName onto the end of the active parameter block name

subroutine openparameterblock(CS, blockName, desc, do_not_log)

  type(param_file_type),      intent(in) :: cs      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  character(len=*),           intent(in) :: blockname !< The name of a parameter block being added

  character(len=*), optional, intent(in) :: desc    !< A description of the parameter block being added

  logical, optional, intent(in) :: do_not_log

    !< Log block entry if true.  This only prevents logging of entry to the block, and not the contents.

  type(parameter_block), pointer :: block => null()

  logical :: do_log

  do_log = .true.

  if (present(do_not_log)) do_log = .not. do_not_log

  if (associated(cs%blockName)) then

    block => cs%blockName

    block%name = pushblocklevel(block%name,blockname)

    if (do_log) then

      call doc_openblock(cs%doc, block%name, desc)

      block%log_access = .true.

    else

      block%log_access = .false.

    endif

  else

    if (is_root_pe()) call mom_error(fatal, &

      'openParameterBlock: A push was attempted before allocation.')

  endif

end subroutine openparameterblock

!> Remove the lowest level of recursion from the active block name

subroutine closeparameterblock(CS)

  type(param_file_type), intent(in) :: cs      !< The control structure for the file_parser module,

                                         !! it is also a structure to parse for run-time parameters

  type(parameter_block), pointer :: block => null()

  if (associated(cs%blockName)) then

    block => cs%blockName

    if (is_root_pe().and.len_trim(block%name)==0) call mom_error(fatal, &

      'closeParameterBlock: A pop was attempted on an empty stack. ("'//&

      trim(block%name)//'")')

    if (block%log_access) call doc_closeblock(cs%doc, block%name)

  else

    if (is_root_pe()) call mom_error(fatal, &

      'closeParameterBlock: A pop was attempted before allocation.')

  endif

  block%name = popblocklevel(block%name)

end subroutine closeparameterblock

!> Extends block name (deeper level of parameter block)

function pushblocklevel(oldblockName,newBlockName)

  character(len=*),        intent(in) :: oldblockname  !< A sequence of hierarchical parameter block names

  character(len=*),        intent(in) :: newblockname  !< A new block name to add to the end of the sequence

  character(len=len(oldBlockName)+40) :: pushblocklevel

  if (len_trim(oldblockname)>0) then

    pushblocklevel=trim(oldblockname)//'%'//trim(newblockname)

  else

    pushblocklevel=trim(newblockname)

  endif

end function pushblocklevel

!> Truncates block name (shallower level of parameter block)

function popblocklevel(oldblockName)

  character(len=*),        intent(in) :: oldblockname !< A sequence of hierarchical parameter block names

  character(len=len(oldBlockName)+40) :: popblocklevel

  integer :: i

  i = index(trim(oldblockname), '%', .true.)

  if (i>1) then

    popblocklevel = trim(oldblockname(1:i-1))

  elseif (i==0) then

    popblocklevel = ''

  else ! i==1

    if (is_root_pe()) call mom_error(fatal, &

      'popBlockLevel: A pop was attempted leaving an empty block name.')

  endif

end function popblocklevel

!> \namespace mom_file_parser

!!

!!  By Robert Hallberg and Alistair Adcroft, updated 9/2013.

!!

!!    The subroutines here parse a set of input files for the value

!!  a named parameter and sets that parameter at run time.  Currently

!!  these files use use one of several formats:

!!    \#define VAR      ! To set the logical VAR to true.

!!    VAR = True        ! To set the logical VAR to true.

!!    \#undef VAR       ! To set the logical VAR to false.

!!    VAR = False       ! To set the logical VAR to false.

!!    \#define VAR 999  ! To set the real or integer VAR to 999.

!!    VAR = 999         ! To set the real or integer VAR to 999.

!!    \#override VAR = 888 ! To override a previously set value.

!!    VAR = 1.1, 2.2, 3.3  ! To set an array of real values.

  ! Note that in the comments above, dOxygen translates \# to # .

!!

!!  In addition, when set by the get_param interface, the values of

!!  parameters are automatically logged, along with defaults, units,

!!  and a description.  It is an error for a variable to be overridden

!!  more than once, and MOM6 has a facility to check for unused lines

!!  to set variables, which may indicate miss-spelled or archaic

!!  parameters.  Parameter names are case-specific, and lines may use

!!  a F90 or C++ style comment, starting with ! or //.

end module mom_file_parser