Add developer documentation for run(3f) and example program (#933)

Author: perazz

src/fpm_filesystem.F90

@@ -774,31 +774,32 @@ subroutine filewrite(filename,filedata)
 
 end subroutine filewrite
 
-function which(command) result(pathname)
+!>AUTHOR: John S. Urban
+!!LICENSE: Public Domain
 !>
-!!##NAME
+!!##Name
 !!     which(3f) - [M_io:ENVIRONMENT] given a command name find the pathname by searching
 !!                 the directories in the environment variable $PATH
 !!     (LICENSE:PD)
 !!
-!!##SYNTAX
+!!##Syntax
 !!   function which(command) result(pathname)
 !!
 !!    character(len=*),intent(in)  :: command
 !!    character(len=:),allocatable :: pathname
 !!
-!!##DESCRIPTION
+!!##Description
 !!    Given a command name find the first file with that name in the directories
 !!    specified by the environment variable $PATH.
 !!
-!!##OPTIONS
+!!##options
 !!    COMMAND   the command to search for
 !!
-!!##RETURNS
+!!##Returns
 !!    PATHNAME  the first pathname found in the current user path. Returns blank
 !!              if the command is not found.
 !!
-!!##EXAMPLE
+!!##Example
 !!
 !!   Sample program:
 !!
@@ -812,11 +813,7 @@ function which(command) result(pathname)
 !!        write(*,*)'install is ',which('install')
 !!     end program demo_which
 !!
-!!##AUTHOR
-!!    John S. Urban
-!!##LICENSE
-!!    Public Domain
-
+function which(command) result(pathname)
 character(len=*),intent(in)     :: command
 character(len=:),allocatable    :: pathname, checkon, paths(:), exts(:)
 integer                         :: i, j
@@ -854,8 +851,66 @@ function which(command) result(pathname)
    enddo SEARCH
 end function which
 
-!> echo command string and pass it to the system for execution
-!call run(cmd,echo=.false.,exitstat=exitstat,verbose=.false.,redirect='')
+!>AUTHOR: fpm(1) contributors
+!!LICENSE: MIT
+!>
+!!##Name
+!!    run(3f) -  execute specified system command and selectively echo
+!!    command and output to a file and/or stdout.
+!!    (LICENSE:MIT)
+!!
+!!##Syntax
+!!    subroutine run(cmd,echo,exitstat,verbose,redirect)
+!!
+!!     character(len=*), intent(in)       :: cmd
+!!     logical,intent(in),optional        :: echo
+!!     integer, intent(out),optional      :: exitstat
+!!     logical, intent(in), optional      :: verbose
+!!     character(*), intent(in), optional :: redirect
+!!
+!!##Description
+!!   Execute the specified system command. Optionally
+!!
+!!   +  echo the command before execution
+!!   +  return the system exit status of the command.
+!!   +  redirect the output of the command to a file.
+!!   +  echo command output to stdout
+!!
+!!   Calling run(3f) is preferred to direct calls to
+!!   execute_command_line(3f) in the fpm(1) source to provide a standard
+!!   interface where output modes can be specified.
+!!
+!!##Options
+!!    CMD       System command to execute
+!!    ECHO      Whether to echo the command being executed or not
+!!              Defaults to .TRUE. .
+!!    VERBOSE   Whether to redirect the command output to a null device or not
+!!              Defaults to .TRUE. .
+!!    REDIRECT  Filename to redirect stdout and stderr of the command into.
+!!              If generated it is closed before run(3f) returns.
+!!    EXITSTAT  The system exit status of the command when supported by
+!!              the system. If not present and a non-zero status is
+!!              generated program termination occurs.
+!!
+!!##Example
+!!
+!!   Sample program:
+!!
+!!   Checking the error message and counting lines:
+!!
+!!     program demo_run
+!!     use fpm_filesystem, only : run
+!!     implicit none
+!!     logical,parameter :: T=.true., F=.false.
+!!     integer :: exitstat
+!!     character(len=:),allocatable :: cmd
+!!        cmd='ls -ltrasd *.md'
+!!        call run(cmd)
+!!        call run(cmd,exitstat=exitstat)
+!!        call run(cmd,echo=F)
+!!        call run(cmd,verbose=F)
+!!     end program demo_run
+!!
 subroutine run(cmd,echo,exitstat,verbose,redirect)
     character(len=*), intent(in) :: cmd
     logical,intent(in),optional  :: echo

src/fpm_strings.f90

@@ -236,9 +236,9 @@ pure function fnv_1a_string_t(input, seed) result(hash)
 end function fnv_1a_string_t
 
 
- !>Author: John S. Urban
- !!License: Public Domain
- !! Changes a string to lowercase over optional specified column range
+!>Author: John S. Urban
+!!License: Public Domain
+!! Changes a string to lowercase over optional specified column range
 elemental pure function lower(str,begin,end) result (string)
 
     character(*), intent(In)     :: str
@@ -624,8 +624,9 @@ pure function join(str,sep,trm,left,right,start,end) result (string)
    if(present(end))string=string//end
 end function join
 
-!>##AUTHOR John S. Urban
-!!##LICENSE Public Domain
+!>AUTHOR: John S. Urban
+!!LICENSE: Public Domain
+!>
 !!## NAME
 !!    glob(3f) - [fpm_strings:COMPARE] compare given string for match to
 !!    pattern which may contain wildcard characters
@@ -1259,6 +1260,8 @@ subroutine remove_newline_characters(string)
 
 end subroutine remove_newline_characters
 
+!>AUTHOR: John S. Urban
+!!LICENSE: Public Domain
 !>
 !!### NAME
 !!   notabs(3f) - [fpm_strings:NONALPHA] expand tab characters
@@ -1316,11 +1319,6 @@ end subroutine remove_newline_characters
 !!### SEE ALSO
 !!   GNU/Unix commands expand(1) and unexpand(1)
 !!
-!!### AUTHOR
-!!   John S. Urban
-!!
-!!### LICENSE
-!!   Public Domain
 elemental impure subroutine notabs(instr,outstr,ilen)
 
 ! ident_31="@(#)fpm_strings::notabs(3f): convert tabs to spaces while maintaining columns, remove CRLF chars"