Index: trunk/LMDZ.TITAN/libf/muphytitan/argparse.F90
===================================================================
--- trunk/LMDZ.TITAN/libf/muphytitan/argparse.F90	(revision 1814)
+++ trunk/LMDZ.TITAN/libf/muphytitan/argparse.F90	(revision 1897)
@@ -1,5 +1,5 @@
-! Copyright Jérémie Burgalat (2010-2015)
+! Copyright Jérémie Burgalat (2010-2015,2017)
 ! 
-! burgalat.jeremie@gmail.com
+! jeremie.burgalat@univ-reims.fr
 ! 
 ! This software is a computer program whose purpose is to provide configuration 
@@ -33,7 +33,7 @@
 
 !! file: argparse.F90
-!! summary: Command-line parser source file
-!! author: burgalat
-!! date: 2013-2015
+!! summary: Command-line parser source file.
+!! author: J. Burgalat
+!! date: 2013-2015,2017
 
 #include "defined.h"
@@ -47,15 +47,10 @@
   !! 
   !! If you only wish to have an overview of argparse usage, you'd better go
-  !! [p_argparse](here).
+  !! [here](|url|/page/swift/p01_argparse.html).
+
   USE, INTRINSIC :: ISO_FORTRAN_ENV, ONLY : stdout=>OUTPUT_UNIT, stderr=>ERROR_UNIT
   USE ERRORS
   USE FSYSTEM, ONLY : fs_termsize
-  USE STRINGS, getpar => format_paragraph, &
-               splitstr  => format_string, & 
-               ap_string  => st_string,    & !! String value type ID
-               ap_complex  => st_complex,  & !! Complex value type ID
-               ap_logical => st_logical,   & !! Logical value type ID
-               ap_integer => st_integer,   & !! Integer value type ID
-               ap_real    => st_real         !! Floating point value type ID 
+  USE STRING_OP, getpar => format_paragraph, splitstr  => format_string  
   IMPLICIT NONE
 
@@ -66,8 +61,5 @@
   PUBLIC :: noerror,error, error_to_string,aborting
   ! from strings
-#if ! HAVE_FTNDTSTR
   PUBLIC :: st_slen, st_llen
-#endif
-  PUBLIC :: ap_string, ap_complex, ap_logical, ap_integer, ap_real
   PUBLIC :: stderr, stdout
   ! argparse module
@@ -92,4 +84,17 @@
   ! PARAMETERS (INTRISIC TYPES)
   ! ===========================
+
+  INTEGER, PARAMETER, PUBLIC :: ap_string  = st_string 
+    !! String value type identifier.
+  INTEGER, PARAMETER, PUBLIC :: ap_complex = st_complex
+    !! Complex value type identifier.
+  INTEGER, PARAMETER, PUBLIC :: ap_logical = st_logical
+    !! Logical value type identifier.
+  INTEGER, PARAMETER, PUBLIC :: ap_integer = st_integer
+    !! Integer value type identifier.
+  INTEGER, PARAMETER, PUBLIC :: ap_real = st_real
+    !! Real value type identifier.
+
+  !> List of all available actions
 
   INTEGER, PARAMETER, PUBLIC :: ap_store  = 1 
@@ -120,4 +125,44 @@
     
   !> Add an option to the parser
+  !!
+  !! ```
+  !! FUNCTION argparser_add_option(this,dest,sflag,lflag,type,action,default,nrec,help,meta) RESULT(err)
+  !!          argparser_add_option(this,dest,flag,type,action,default,nrec,help,meta) RESULT(err)
+  !! ```
+  !!
+  !! The function defines a new argument based on input parameters, checks it and finally sets it 
+  !! in the parser. 
+  !! 
+  !! In its first version both short (`sflag`) and long (`lflag`) options flags are mandatory. In its second
+  !! form, a single flag (`flag`) is expected: the method will automatically deduce if it belongs to short or
+  !! a long option flag based on the number of hyphens given.
+  !! 
+  !! `type` value should be one of the following module constants (which are aliases from [[string_op(module)]]):
+  !!
+  !! - `ap_string` ([[string_op(module):st_string(variable)]])
+  !! - `ap_complex` ([[string_op(module):st_complex(variable)]])
+  !! - `ap_logical` ([[string_op(module):st_logical(variable)]])
+  !! - `ap_integer` ([[string_op(module):st_integer(variable)]])
+  !! - `ap_real` ([[string_op(module):st_real(variable)]])
+  !! 
+  !! `action` value should be one of the following module constants:
+  !!
+  !! - [[argparse(module):ap_store(variable)]]
+  !! - [[argparse(module):ap_append(variable)]]
+  !! - [[argparse(module):ap_count(variable)]]
+  !! - [[argparse(module):ap_help(variable)]]
+  !!
+  !! `nrec` string can take the following forms:
+  !!
+  !! tag   | description
+  !! :---: | : -------------
+  !!  "?"  | zero or one argument's value
+  !!  "*"  | any number of arguments
+  !!  "+"  | one or more argument's value(s)
+  !!  "X"  | Exactly X values. Where X is the string representation of an integer (0 is accepted).
+  !!
+  !! On success, `noerror` is returned. Otherwise -9 error code is returned. Errors are only 
+  !! produced by misuse of the function arguments. In such case, the program should be
+  !! stopped: note that such error should not occur in _released_ programs.
   INTERFACE argparser_add_option
     MODULE PROCEDURE ap_add_option_1, ap_add_option_2
@@ -131,5 +176,10 @@
   !> Get optional argument value(s)
   !!
-  !! This is the generic method that can be used to retrieve any kind of argument value(s) from the parser.
+  !! ```
+  !! FUNCTION argparser_get_value(this,name,output) RESULT(err)
+  !! ```
+  !! 
+  !! This is the generic method that can be used to retrieve any kind of argument value(s) from the parser for a given
+  !! argument name (as defined by the `dest` argument of [[argparse(module):argparser_add_option(interface)]].
   !! All the methods have the same dummy arguments only `output` dummy argument differs in type and shape.
   !! 
@@ -137,5 +187,5 @@
   !! For string vector, `output` is expected to be an allocatable vector of **assumed length**
   !! strings (thus string length is left to user responsability).
-  !! A good compromise for strings length is to use the [[strings(module):st_slen(variable)]] 
+  !! A good compromise for strings length is to use the [[string_op(module):st_slen(variable)]] 
   !! parameter.
   INTERFACE argparser_get_value
@@ -287,6 +337,4 @@
     PROCEDURE, PRIVATE :: ap_get_sv_ve
     PROCEDURE, PRIVATE :: ap_check_state
-    !PROCEDURE, PUBLIC  :: reset_values       => argparser_reset_values
-    !  !! Resets values stored in the parser
     PROCEDURE, PUBLIC  :: throw_error        => argparser_throw_error
       !! Throw an error and exit the program
@@ -415,9 +463,9 @@
 
   FUNCTION argparser_add_positionals(this,nargs,meta,help) RESULT(err)
-    !! Add positional arguments definition to the parser
+    !! Add positional arguments definition to the parser.
+    !!
     !! The method initializes the entry for positional arguments in the parser.
     !! Positional arguments are always seen by the parser as strings and the 
     !! default associated action is 'store'.
-
     OBJECT(argparser), INTENT(inout)                     :: this
       !! An argparser object reference
@@ -533,5 +581,5 @@
     IF (zauto) THEN
       IF (rhelp) CALL argparser_help(this)
-      IF (err /= 0.AND. err /= 255) CALL argparser_throw_error(this,err,2)
+      IF (err /= 0) CALL argparser_throw_error(this,err,2)
     ENDIF
     RETURN 
@@ -751,10 +799,10 @@
     !! in the parser. Both **short and long options flags** are mandatory input arguments of the function.
     !! 
-    !!  `type` value should be one of the following module constants (which are aliases from [[strings(module)]]):
-    !!  - ap_string ([[strings(module):st_string(variable)]])
-    !!  - ap_complex ([[strings(module):st_complex(variable)]])
-    !!  - ap_logical ([[strings(module):st_logical(variable)]])
-    !!  - ap_integer ([[strings(module):st_integer(variable)]])
-    !!  - ap_real ([[strings(module):st_real(variable)]])
+    !!  `type` value should be one of the following module constants (which are aliases from [[string_op(module)]]):
+    !!  - ap_string ([[string_op(module):st_string(variable)]])
+    !!  - ap_complex ([[string_op(module):st_complex(variable)]])
+    !!  - ap_logical ([[string_op(module):st_logical(variable)]])
+    !!  - ap_integer ([[string_op(module):st_integer(variable)]])
+    !!  - ap_real ([[string_op(module):st_real(variable)]])
     !! 
     !!  `action` value should be one of the following module constants:
@@ -772,5 +820,5 @@
     !!   X  | Exactly X values. Where X is the string representation of an integer (0 is accepted).
     !!
-    !! See also [[argparse(module):ap_add_option_2(function)]] documentation.
+    !! See also ap_add_option_2 documentation.
     OBJECT(argparser), INTENT(inout)                     :: this
       !! An argparser object reference
@@ -828,10 +876,10 @@
     !! Add an argument to the parser (interface #2)
     !!
-    !! The function is a wrapper to [[argparse(module):ap_add_option_1(function)]]. In this version, 
+    !! The function is a wrapper to ap_add_option_1. In this version, 
     !! only one option flag is required. The method only checks for the (trimmed) length of **flag** in
     !! order to choose wether it is a **short** or **long** option flag. Then the function simply calls 
-    !! [[argparse(module):ap_add_option_1(function)]] to set the argument.
+    !! ap_add_option_1 to set the argument.
     !! 
-    !! Other dummy arguments have the same meaning as in [[argparse(module):ap_add_option_1(function)]].
+    !! Other dummy arguments have the same meaning as in ap_add_option_1.
     OBJECT(argparser), INTENT(inout)                     :: this
       !! An argparser object reference
@@ -886,5 +934,5 @@
       !! An argc object to check
     TYPE(error) :: err
-      !! Error object with -15 id if object is already set, no error otherwise.
+      !! Error object with -8 id if object is already set, no error otherwise.
     INTEGER :: i
     err = noerror
@@ -914,5 +962,5 @@
       !! An argparser object reference
     TYPE(words), INTENT(inout)               :: cmd
-      !! A [[strings(module):words(type)]] object with the command-line to parse
+      !! A [[string_op(module):words(type)]] object with the command-line to parse
     LOGICAL, INTENT(out)                     :: help_req
       !! An output logical flag with `.true.` if help option has been found, `.false.` otherwise
@@ -987,5 +1035,5 @@
       !! An argparser object reference
     TYPE(words), INTENT(inout)       :: cmd
-      !! A [[strings(module):words(type)]] object with the command-line to parse
+      !! A [[string_op(module):words(type)]] object with the command-line to parse
     TYPE(error) :: err
       !! Error object with the first error encountered in the process
@@ -1068,5 +1116,5 @@
     ! Gets values as a function of the expected number of records
     IF (arg%nrec == 0) THEN
-      ! parse_args (main parsing method) reset all values: for 0 nrec
+      ! argparser_parse (main parsing method) reset all values: for 0 nrec
       ! we should have at least one value saved which is the default.
       ! if it is not the case we set default as values of the argument
@@ -1136,5 +1184,5 @@
     !! @warning
     !! For compilers that does not support allocatable strings in derived types,
-    !! computation are highly dependent of [[strings(module):st_slen(variable):
+    !! computation are highly dependent of [[string_op(module):st_slen(variable):
     !! tokens length are limited by this parameter. 
     IMPLICIT NONE
@@ -1144,5 +1192,5 @@
       !! A string to process
     TYPE(words), INTENT(out)      :: new_cmd
-      !! An output [[strings(module):words(type)]] object with the processed command line
+      !! An output [[string_op(module):words(type)]] object with the processed command line
     LOGICAL, INTENT(out)          :: rhelp   
       !! An output boolean flag with `.true.` if help is requested, `.false.` otherwise
@@ -1155,9 +1203,9 @@
     err = noerror ; rhelp = .false.
     IF (LEN_TRIM(string) == 0) THEN
-      err = error('internal error (empty string)',-2) 
+      err = error('internal error (empty string)',-255) 
       RETURN
     ENDIF
     ! split input command line in words !
-    splitted = new_words(string," ",.true.) ! tokens may be truncated :( 
+    call words_extend(splitted,string," ",.true.)
     ! reset iterator
     CALL words_reset(splitted)
@@ -1330,5 +1378,6 @@
 
   SUBROUTINE ap_format_usage(this,optmw)
-    !! Format command line usage
+    !! Format command line usage.
+    !!
     !! The subroutine creates and formats the command line usage of the 
     !! given argparser object. If [[argparser(type):usg(variable)]] is already set (i.e. not empty) 
@@ -1693,6 +1742,8 @@
     !! The function calls all the tests to perform on argc members. Some of these tests can 
     !! alter argc's member values to fit argparser's requirements. 
-    !! @note
-    !! Normally, program should be stopped if returned error is not 0 !
+    !!
+    !! On success, `noerror` is returned. Otherwise -9 error code is returned. Errors are only 
+    !! produced by misuse of the function arguments. In such case, the program should be
+    !! stopped: note that such ezrror should not occur in _released_ programs.
     TYPE(argc), INTENT(inout)                            :: this
       !! An argc object
@@ -1740,4 +1791,7 @@
     !! The method checks if input argument's options are valid and update the argc object 
     !! consequently. 
+    !!
+    !! On success, `noerror` is returned. Otherwise -9 error code is returned. Errors are only 
+    !! produced by misuse of the function arguments.
     TYPE(argc), INTENT(inout)  :: this
       !! An argc object to update
@@ -1756,6 +1810,6 @@
     ret = noerror
     eprf = 'argparse: '//"Invalid argument `"//TRIM(this%name)//"'"
-    uty = error(eprf//" (type)",-2) 
-    ina = error(eprf//" (inconsistent nargs)",-2)
+    uty = error(eprf//" (type)",-9) 
+    ina = error(eprf//" (inconsistent nargs)",-9)
     zna = TRIM(na)
     ! Checks action
@@ -1763,5 +1817,5 @@
       this%paction = ac 
     ELSE
-      ret = error(eprf//" (action)",-2) ; RETURN 
+      ret = error(eprf//" (action)",-9) ; RETURN 
     ENDIF
     ! Checks and sets type and default as a function of the action
@@ -1885,5 +1939,5 @@
             terr = error(eprf//" (inconsistent default value: expected '"// &
                            TRIM(st_type_names(this%ptype))//"', found '"// &
-                           TRIM(st_type_names(t))//"')",-2)
+                           TRIM(st_type_names(t))//"')",-9)
             RETURN
           ENDIF
@@ -1977,5 +2031,5 @@
       SELECT CASE(this%nrec)
         CASE(-3,-2,-1)
-          zmeta = str_to_upper(meta(1))
+          zmeta = to_upper(meta(1))
           blk = INDEX(TRIM(zmeta),CHAR(32)) - 1
           IF (blk <= 0) blk=LEN_TRIM(zmeta)
@@ -1987,5 +2041,5 @@
           DO i=1,this%nrec
             j=j+1 ; IF (j>ms) j=1
-            zmeta = str_to_upper(meta(j))
+            zmeta = to_upper(meta(j))
             blk=INDEX(TRIM(zmeta),CHAR(32))-1 
             IF (blk <= 0) blk=LEN_TRIM(zmeta)
@@ -1994,5 +2048,5 @@
       END SELECT
     ELSE
-      zmeta = str_to_upper(TRIM(this%name))
+      zmeta = to_upper(TRIM(this%name))
       SELECT CASE(this%nrec)
         CASE(-3,-2,-1)
@@ -2223,5 +2277,5 @@
     !! - -7  : argument not found (i.e. does not set in the parser)
     !! - -19 : parsing not done yet
-    !! - -20 : (previous) parsing failed
+    !! - -20 : parsing failed
     !! - -21 : inconsistent destination type
     !! @note
@@ -2480,5 +2534,5 @@
   !! @param[in,out] this An argc object 
   !! @param[out] output A scalar with the first value of the argument
-  !! @return An errors::error object with -12 if the destination variable's type
+  !! @return An errors::error object with -21 if the destination variable's type
   !! is inconsistent, 0 otherwise.
   FUNCTION ac_get_dv_sc(this, output) RESULT(ret)
@@ -2492,5 +2546,5 @@
       !! Output value
     TYPE(error) :: ret
-      !! Error object with the -12 if the destination variable's type is inconsistent, 0 otherwise
+      !! Error object with the -21 if the destination variable's type is inconsistent, 0 otherwise
     ret = noerror
     IF (this%ptype /= ap_real) THEN
