subroutine read_file(file, lines, form, iostat, iomsg)
!< Read a file as a single string stream.
!<
!< The lines are returned as an array of strings that are read until the eof is reached.
!< The line is read as an ascii stream read until the eor is reached.
!<
!< @note For unformatted read only `access='stream'` is supported with new_line as line terminator.
!<
!<```fortran
!< type(string) :: astring
!< type(string), allocatable :: strings(:)
!< type(string) :: line(3)
!< integer :: iostat
!< character(len=99) :: iomsg
!< integer :: scratch
!< integer :: l
!< logical :: test_passed(8)
!< line(1) = ' Hello World! '
!< line(2) = 'How are you? '
!< line(3) = ' All say: "Fine thanks"'
!< open(newunit=scratch, file='read_file_test.tmp')
!< write(scratch, "(A)") line(1)%chars()
!< write(scratch, "(A)") line(2)%chars()
!< write(scratch, "(A)") line(3)%chars()
!< close(scratch)
!< call read_file(file='read_file_test.tmp', lines=strings, iostat=iostat, iomsg=iomsg)
!< test_passed(1) = (size(strings, dim=1)==size(line, dim=1))
!< do l=1, size(strings, dim=1)
!< test_passed(l+1) = (strings(l)==line(l))
!< enddo
!< open(newunit=scratch, file='read_file_test.tmp', form='UNFORMATTED', access='STREAM')
!< write(scratch) line(1)%chars()//new_line('a')
!< write(scratch) line(2)%chars()//new_line('a')
!< write(scratch) line(3)%chars()//new_line('a')
!< close(scratch)
!< call read_file(file='read_file_test.tmp', lines=strings, form='unformatted', iostat=iostat, iomsg=iomsg)
!< test_passed(5) = (size(strings, dim=1)==size(line, dim=1))
!< do l=1, size(strings, dim=1)
!< test_passed(l+5) = (strings(l)==line(l))
!< enddo
!< open(newunit=scratch, file='read_file_test.tmp', form='UNFORMATTED', access='STREAM')
!< close(scratch, status='DELETE')
!< print '(L1)', all(test_passed)
!<```
!=> T <<<
character(len=*), intent(in) :: file !< File name.
type(string), intent(out), allocatable :: lines(:) !< The lines.
character(len=*), intent(in), optional :: form !< Format of unit.
integer, intent(out), optional :: iostat !< IO status code.
character(len=*), intent(inout), optional :: iomsg !< IO status message.
type(string) :: form_ !< Format of unit, local variable.
integer :: iostat_ !< IO status code, local variable.
character(len=:), allocatable :: iomsg_ !< IO status message, local variable.
integer :: unit !< Logical unit.
logical :: does_exist !< Check if file exist.
iomsg_ = repeat(' ', 99) ; if (present(iomsg)) iomsg_ = iomsg
inquire(file=file, iomsg=iomsg_, iostat=iostat_, exist=does_exist)
if (does_exist) then
form_ = 'FORMATTED' ; if (present(form)) form_ = form ; form_ = form_%upper()
select case(form_%chars())
case('FORMATTED')
open(newunit=unit, file=file, status='OLD', action='READ', iomsg=iomsg_, iostat=iostat_, err=10)
case('UNFORMATTED')
open(newunit=unit, file=file, status='OLD', action='READ', form='UNFORMATTED', access='STREAM', &
iomsg=iomsg_, iostat=iostat_, err=10)
endselect
call read_lines(unit=unit, lines=lines, form=form, iomsg=iomsg_, iostat=iostat_)
10 close(unit)
endif
if (present(iostat)) iostat = iostat_
if (present(iomsg)) iomsg = iomsg_
endsubroutine read_file