Add input() convenience function to stdlib_io with documentation, tests, and example (Fixes #259)

.gitignore

@@ -51,3 +51,4 @@ API-doc/
 scratch.txt
 *.dat
 *.stream
+.venv/

doc/specs/stdlib_io.md

@@ -247,6 +247,31 @@ Read a whole line from a formatted unit into a string variable
 {!example/io/example_get_line.f90!}
 ```
 
+## `input` — convenience prompt + read from standard input
+
+### Status
+
+Experimental / convenience
+
+### Description
+
+`input(prompt)` displays `prompt` (if provided) on the same line and returns the full user input as a string. Trailing spaces and tabs are preserved. Optionally the call can provide an `iostat`-like integer to capture the status.
+
+### Syntax
+
+`s = input(prompt [, iostat])`
+
+### Example
+
+```fortran
+use stdlib_io, only: input
+character(len=:), allocatable :: name
+integer :: st
+
+name = input('Enter your name: ')
+name = input('Enter name (with status): ', st)
+```
+
 ## Formatting constants
 
 ### Status

example/io/CMakeLists.txt

@@ -6,3 +6,6 @@ ADD_EXAMPLE(loadtxt)
 ADD_EXAMPLE(open)
 ADD_EXAMPLE(savenpy)
 ADD_EXAMPLE(savetxt)
+# ADD_EXAMPLE(input) -- Interactive example, do not run as test
+add_executable(example_input example_input.f90)
+target_link_libraries(example_input "${PROJECT_NAME}")

example/io/example_input.f90

@@ -0,0 +1,21 @@
+program example_input
+  use stdlib_io, only: input
+  implicit none
+  character(len=:), allocatable :: name
+  integer :: stat
+
+  print *, "Example of input() usage:"
+
+  ! Simple usage
+  name = input("Enter your name: ")
+  print *, "Hello, ", name, "!"
+
+  ! Usage with status check
+  name = input("Enter something else (or Ctrl+D to fail): ", stat)
+  if (stat == 0) then
+     print *, "You entered: ", name
+  else
+     print *, "Input failed or EOF encountered (stat=", stat, ")"
+  end if
+
+end program example_input