Add getline to read whole line from formatted unit

Author: awvwgk

doc/specs/stdlib_io.md

@@ -223,3 +223,51 @@ program demo_savenpy
     call save_npy('example.npy', x)
 end program demo_savenpy
 ```
+
+## `getline`
+
+### Status
+
+Experimental
+
+### Description
+
+Read a whole line from a formatted unit into a string variable
+
+### Syntax
+
+`call [[stdlib_io(module):getline(interface)]](unit, line[, iostat][, iomsg])`
+
+### Arguments
+
+`unit`: Formatted input unit.
+        This argument is `intent(in)`.
+
+`line`: Deferred length character or `string_type` variable.
+        This argument is `intent(out)`.
+
+`iostat`: Default integer, contains status of reading from unit, zero in case of success.
+          It is an optional argument, in case not present the program will halt for non-zero status.
+          This argument is `intent(out)`.
+
+`iomsg`: Deferred length character value, contains error message in case `iostat` is non-zero.
+         It is an optional argument, error message will be dropped if not present.
+         This argument is `intent(out)`.
+
+### Example
+
+```fortran
+program demo_getline
+    use, intrinsic :: iso_fortran_env, only : input_unit, output_unit
+    use stdlib_io, only: getline
+    implicit none
+    character(len=:), allocatable :: line
+    integer :: stat
+
+    call getline(input_unit, line, stat)
+    do while(stat == 0)
+      write(output_unit, '(a)') line
+      call getline(input_unit, line, stat)
+    end do
+end program demo_getline
+```

src/Makefile.manual

@@ -91,6 +91,7 @@ stdlib_io.o: \
     stdlib_error.o \
     stdlib_optval.o \
     stdlib_kinds.o \
+    stdlib_string_type.o \
     stdlib_ascii.o
 stdlib_io_npy.o: \
     stdlib_kinds.o

src/stdlib_io.fypp

@@ -11,10 +11,11 @@ module stdlib_io
   use stdlib_error, only: error_stop
   use stdlib_optval, only: optval
   use stdlib_ascii, only: is_blank
+  use stdlib_string_type, only : string_type
   implicit none
   private
   ! Public API
-  public :: loadtxt, savetxt, open
+  public :: loadtxt, savetxt, open, getline
 
   ! Private API that is exposed so that we can test it in tests
   public :: parse_mode
@@ -31,6 +32,14 @@ module stdlib_io
     FMT_COMPLEX_XDP = '(*(es26.18e3,1x,es26.18e3))', &
     FMT_COMPLEX_QP = '(*(es44.35e4,1x,es44.35e4))'
 
+  !> Version: experimental
+  !>
+  !> Read a whole line from a formatted unit into a string variable
+  interface getline
+    module procedure :: getline_char
+    module procedure :: getline_string
+  end interface getline
+
   interface loadtxt
     !! version: experimental
     !!
@@ -331,4 +340,59 @@ contains
 
   end function parse_mode
 
+  !> Version: experimental
+  !>
+  !> Read a whole line from a formatted unit into a deferred length character variable
+  subroutine getline_char(unit, line, iostat, iomsg)
+    !> Formatted IO unit
+    integer, intent(in) :: unit
+    !> Line to read
+    character(len=:), allocatable, intent(out) :: line
+    !> Status of operation
+    integer, intent(out), optional :: iostat
+    !> Error message
+    character(len=:), allocatable, optional :: iomsg
+
+    integer, parameter :: bufsize = 512
+    character(len=bufsize) :: buffer, msg
+    integer :: chunk, stat
+
+    allocate(character(len=0) :: line)
+    do
+      read(unit, '(a)', advance='no', iostat=stat, iomsg=msg, size=chunk) buffer
+      if (stat > 0) exit
+      line = line // buffer(:chunk)
+      if (stat < 0) then
+        if (is_iostat_eor(stat)) stat = 0
+        exit
+      end if
+    end do
+
+    if (stat /= 0 .and. present(iomsg)) iomsg = trim(msg)
+    if (present(iostat)) then
+      iostat = stat
+    else if (stat /= 0) then
+      call error_stop(trim(msg))
+    end if
+  end subroutine getline_char
+
+  !> Version: experimental
+  !>
+  !> Read a whole line from a formatted unit into a string variable
+  subroutine getline_string(unit, line, iostat, iomsg)
+    !> Formatted IO unit
+    integer, intent(in) :: unit
+    !> Line to read
+    type(string_type), intent(out) :: line
+    !> Status of operation
+    integer, intent(out), optional :: iostat
+    !> Error message
+    character(len=:), allocatable, optional :: iomsg
+
+    character(len=:), allocatable :: buffer
+
+    call getline(unit, buffer, iostat, iomsg)
+    line = string_type(buffer)
+  end subroutine getline_string
+
 end module stdlib_io

src/tests/io/CMakeLists.txt

@@ -13,6 +13,7 @@ ADDTEST(savetxt_qp)
 set_tests_properties(loadtxt_qp PROPERTIES LABELS quadruple_precision)
 set_tests_properties(savetxt_qp PROPERTIES LABELS quadruple_precision)
 
+ADDTEST(getline)
 ADDTEST(npy)
 ADDTEST(open)
 ADDTEST(parse_mode)

src/tests/io/Makefile.manual

@@ -6,6 +6,7 @@ SRCGEN = $(SRCFYPP:.fypp=.f90)
 
 PROGS_SRC = test_loadtxt.f90 \
             test_savetxt.f90 \
+            test_getline.f90 \
             test_npy.f90 \
             test_parse_mode.f90 \
             test_open.f90 \

src/tests/io/test_getline.f90

@@ -0,0 +1,88 @@
+module test_getline
+    use stdlib_io, only : getline
+    use stdlib_string_type, only : string_type, len
+    use testdrive, only : new_unittest, unittest_type, error_type, check
+    implicit none
+    private
+
+    public :: collect_getline
+
+contains
+
+    !> Collect all exported unit tests
+    subroutine collect_getline(testsuite)
+        !> Collection of tests
+        type(unittest_type), allocatable, intent(out) :: testsuite(:)
+
+        testsuite = [ &
+            new_unittest("read-char", test_read_char), &
+            new_unittest("read-string", test_read_string) &
+            ]
+    end subroutine collect_getline
+
+    subroutine test_read_char(error)
+        !> Error handling
+        type(error_type), allocatable, intent(out) :: error
+
+        integer :: io, i, stat
+        character(len=:), allocatable :: line
+
+        open(newunit=io, status="scratch")
+        write(io, "(a)") repeat("abc", 10), repeat("def", 100), repeat("ghi", 1000)
+        rewind(io)
+
+        do i = 1, 3
+          call getline(io, line, stat)
+          call check(error, stat)
+          call check(error, len(line), 3*10**i)
+        end do
+        close(io)
+    end subroutine test_read_char
+
+    subroutine test_read_string(error)
+        !> Error handling
+        type(error_type), allocatable, intent(out) :: error
+
+        integer :: io, i, stat
+        type(string_type) :: line
+
+        open(newunit=io, status="scratch")
+        write(io, "(a)") repeat("abc", 10), repeat("def", 100), repeat("ghi", 1000)
+        rewind(io)
+
+        do i = 1, 3
+          call getline(io, line, stat)
+          call check(error, stat)
+          call check(error, len(line), 3*10**i)
+        end do
+        close(io)
+    end subroutine test_read_string
+
+end module test_getline
+
+
+program tester
+    use, intrinsic :: iso_fortran_env, only : error_unit
+    use testdrive, only : run_testsuite, new_testsuite, testsuite_type
+    use test_getline, only : collect_getline
+    implicit none
+    integer :: stat, is
+    type(testsuite_type), allocatable :: testsuites(:)
+    character(len=*), parameter :: fmt = '("#", *(1x, a))'
+
+    stat = 0
+
+    testsuites = [ &
+        new_testsuite("getline", collect_getline) &
+        ]
+
+    do is = 1, size(testsuites)
+        write(error_unit, fmt) "Testing:", testsuites(is)%name
+        call run_testsuite(testsuites(is)%collect, error_unit, stat)
+    end do
+
+    if (stat > 0) then
+        write(error_unit, '(i0, 1x, a)') stat, "test(s) failed!"
+        error stop
+    end if
+end program