document run interface

Author: perazz

doc/specs/stdlib_system.md

@@ -0,0 +1,52 @@
+---
+title: system
+---
+
+# System
+
+[TOC]
+
+## `run` - Execute an external process
+
+### Status
+
+Experimental
+
+### Description
+
+The `run` interface allows execution of external processes using a single command string or a list of arguments.  
+Processes can be run either synchronously (blocking execution until the process finishes) or asynchronously (non-blocking execution).  
+Optional arguments enable the collection of standard output and error streams, as well as sending input via standard input.
+
+### Syntax
+
+`process = ` [[stdlib_subprocess(module):run(interface)]] `(args [, wait] [, stdin] [, want_stdout] [, want_stderr])`
+
+### Arguments
+
+`args`: Shall be a `character(*)` string (for command-line execution) or a `character(*), dimension(:)` array (for argument-based execution). It specifies the command and arguments to execute. This is an `intent(in)` argument.
+
+`wait` (optional): Shall be a `logical` flag. If `.true.` (default), the process will execute synchronously (blocking). If `.false.`, the process will execute asynchronously (non-blocking). This is an `intent(in)` argument.
+
+`stdin` (optional): Shall be a `character(*)` value containing input to send to the process via standard input (pipe). This is an `intent(in)` argument.
+
+`want_stdout` (optional): Shall be a `logical` flag. If `.true.`, the standard output of the process will be captured; if `.false.` (default), it will be lost. This is an `intent(in)` argument.
+
+`want_stderr` (optional): Shall be a logical flag. If `.true.`, the standard error output of the process will be captured. Default: `.false.`. This is an `intent(in)` argument.
+
+### Return Value
+
+Returns an object of type `process_type` that contains information about the state of the created process.
+
+### Example
+
+```fortran
+! Example usage with command line or list of arguments
+type(process_type) :: p(2)
+
+! Run a simple command line synchronously
+p(1) = run("echo 'Hello, world!'", wait=.true., want_stdout=.true.)
+
+! Run a command using an argument list asynchronously
+p(2) = run(["/usr/bin/ls", "-l"], wait=.false.)
+

src/stdlib_system.F90

@@ -54,30 +54,57 @@ module stdlib_system
 end type process_type
 
 interface run
-    !> Open a new process from a command line
-    module type(process_type) function process_open_cmd(cmd,wait,stdin,want_stdout,want_stderr) result(process)
-        !> The command and arguments
+    !! version: experimental
+    !!
+    !! Executes an external process, either synchronously or asynchronously.
+    !! ([Specification](../page/specs/stdlib_system.html#run-execute-an-external-process))
+    !!
+    !! ### Summary
+    !! Provides methods for executing external processes via a single command string or an argument list, 
+    !! with options for synchronous or asynchronous execution and output collection.
+    !!
+    !! ### Description
+    !! 
+    !! This interface allows the user to spawn external processes using either a single command string 
+    !! or a list of arguments. Processes can be executed synchronously (blocking) or asynchronously 
+    !! (non-blocking), with optional request to collect standard output and error streams, or to provide
+    !! a standard input stream via a `character` string.
+    !!
+    !! @note The implementation depends on system-level process management capabilities.
+    !!
+    !! #### Procedures
+    !!
+    !! - `process_open_cmd`: Opens a process using a command string.
+    !! - `process_open_args`: Opens a process using an array of arguments.
+    !! 
+    module type(process_type) function process_open_cmd(cmd, wait, stdin, want_stdout, want_stderr) result(process)
+        !> The command line string to execute.
         character(*), intent(in) :: cmd
-        !> Optional character input to be sent to the process via pipe
+        !> Optional input sent to the process via standard input (stdin).
         character(*), optional, intent(in) :: stdin
-        !> Define if the process should be synchronous (wait=.true.), or asynchronous(wait=.false.)
+        !> Whether to wait for process completion (synchronous).
         logical, optional, intent(in) :: wait
-        !> Require collecting output
-        logical, optional, intent(in) :: want_stdout, want_stderr        
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
     end function process_open_cmd
-    !> Open a new, asynchronous process from a list of arguments
-    module type(process_type) function process_open_args(args,wait,stdin,want_stdout,want_stderr) result(process)
-        !> The command and arguments
+
+    module type(process_type) function process_open_args(args, wait, stdin, want_stdout, want_stderr) result(process)
+        !> List of arguments for the process to execute.
         character(*), intent(in) :: args(:)
-        !> Optional character input to be sent to the process via pipe
+        !> Optional input sent to the process via standard input (stdin).
         character(*), optional, intent(in) :: stdin
-        !> Define if the process should be synchronous (wait=.true.), or asynchronous(wait=.false.)
+        !> Whether to wait for process completion (synchronous).
         logical, optional, intent(in) :: wait
-        !> Require collecting output
-        logical, optional, intent(in) :: want_stdout, want_stderr        
+        !> Whether to collect standard output.
+        logical, optional, intent(in) :: want_stdout
+        !> Whether to collect standard error output.
+        logical, optional, intent(in) :: want_stderr
     end function process_open_args
 end interface run
 
+
 !> Live check if a process is still running
 interface is_running
     module logical function process_is_running(process) result(is_running)

src/stdlib_system_subprocess.F90

@@ -6,9 +6,6 @@
     use stdlib_linalg_state, only: linalg_state_type, LINALG_ERROR, linalg_error_handling
     implicit none(type, external)
 
-    logical(c_bool), parameter :: C_FALSE = .false._c_bool
-    logical(c_bool), parameter :: C_TRUE  = .true._c_bool
-    
     ! Number of CPU ticks between status updates
     integer(TICKS), parameter :: CHECK_EVERY_TICKS = 100
 
@@ -70,6 +67,10 @@ end function process_has_win32
 
     end interface
 
+    ! C boolean constants
+    logical(c_bool), parameter :: C_FALSE = .false._c_bool
+    logical(c_bool), parameter :: C_TRUE  = .true._c_bool
+
 contains
 
     ! Call system-dependent wait implementation