io: implement input() with tests and documentation (fixes #259)

Author: Brijesh-Thakkar

doc/specs/stdlib_io.md

@@ -255,7 +255,6 @@ Experimental
 ### Description
 
 Reads a line from standard input, optionally displaying a prompt.
-This is similar to Python’s `input()` function.
 
 The function returns the input as an allocatable character string.
 Trailing spaces and tabs are preserved.
@@ -268,16 +267,17 @@ No numeric conversion is performed.
 ### Arguments
 
 `prompt` (optional):  
-A character expression containing a prompt to be displayed before reading input.  
+A `character` scalar containing a prompt to be displayed before reading input.  
 This argument is `intent(in)`.
 
 `iostat` (optional):  
-Default integer, contains status of reading from standard input.
-Zero indicates success.
+Default `integer` scalar that contains the status of reading from standard input.
+The value is zero if the operation succeeds; otherwise the value is non-zero.
+If this argument is not provided and an error occurs, an `error stop` is triggered.
 This argument is `intent(out)`.
 
 `iomsg` (optional):  
-Deferred-length character variable containing an error message if `iostat` is non-zero.
+Deferred-length `character` variable containing an error message if `iostat` is non-zero.
 This argument is `intent(out)`.
 
 ### Return value
@@ -288,7 +288,7 @@ Returns a deferred-length allocatable `character` variable containing the input
 
 - Trailing spaces and tabs are preserved
 - No type conversion is performed
-- To convert to numbers, use `read(line, *)`
+- To convert to numbers, use `to_num` from `stdlib_string_to_num`
 
 ### Example
 

example/io/example_input.f90

@@ -1,6 +1,6 @@
 program example_input
   use stdlib_io, only : input
-  implicit none
+  implicit none(type, external)
 
   character(len=:), allocatable :: name
 

src/stdlib_io.fypp

@@ -6,7 +6,7 @@ module stdlib_io
   !! Provides a support for file handling
   !! ([Specification](../page/specs/stdlib_io.html))
 
-  use, intrinsic :: iso_fortran_env, only : input_unit
+  use, intrinsic :: iso_fortran_env, only : input_unit, output_unit
   use stdlib_kinds, only: sp, dp, xdp, qp, &
       int8, int16, int32, int64
   use stdlib_error, only: error_stop, state_type, STDLIB_IO_ERROR
@@ -607,14 +607,12 @@ contains
   !> Version: experimental
   !>
   !> Read a line from standard input with an optional prompt.
-  !! Similar to Python's input().
   !!
   !! - Preserves trailing whitespace
   !! - Returns allocatable character string
-  !! - Does not perform type conversion
-  !! - Does not stop on error unless caller chooses to
+  !! - Does not perform any type conversion; the input is returned as character data
+  !! - If `iostat` is present, errors are reported via `iostat`/`iomsg` instead of triggering `error_stop`
   function input_char(prompt, iostat, iomsg) result(line)
-    use, intrinsic :: iso_fortran_env, only : output_unit
     character(len=*), intent(in), optional :: prompt
     integer, intent(out), optional :: iostat
     character(len=:), allocatable, optional :: iomsg
@@ -627,7 +625,7 @@ contains
       write(output_unit, '(a)', advance='no') prompt
     end if
 
-    ! Read line from stdin
+    ! Read line from standard input
     call get_line_input_char(line, stat, iomsg)
 
     if (present(iostat)) then

test/test_input.f90

@@ -1,7 +1,6 @@
 module test_input
-  use testdrive, only : new_unittest, unittest_type, error_type, assert_equal
+  use testdrive, only : new_unittest, unittest_type, error_type, check
   use stdlib_io, only : input
-  use stdlib_test_utils, only : write_test_input
   implicit none
   private
   public :: collect
@@ -25,7 +24,7 @@ subroutine test_input_whitespace(error)
     type(error_type), allocatable, intent(out) :: error
     character(len=:), allocatable :: s
 
-    call write_test_input("  abc  ")
+    call feed_stdin("  abc  ")
     s = input()
     call assert_equal(error, s, "  abc  ")
   end subroutine test_input_whitespace