New API calls Xorriso_parse_line() and Xorriso__dispose_words()

libisoburn/trunk/xorriso/xorriso.h

@@ -287,10 +287,7 @@ int Xorriso_read_rc(struct XorrisO *xorriso, int flag);
                   (*argv)[1] to (*argv)[argc-1] contain commands and parameters
                   If argv after the call differs from argv before the call,
                   then one should dispose it later by:
-                    for(i= 0; i < argc; i++)
-                      if(argv[i] != NULL)
-                        free(argv[i]);
-                    free(argv);
+                    Xorriso__dispose_words(argc, argv);
    @param flag    unused yet, submit 0
    @return        <= 0 error , > 0 success
 */
@@ -305,7 +302,7 @@ int Xorriso_program_arg_bsl(struct XorrisO *xorriso, int argc, char ***argv,
    parameters. All parameters must be given in the same call as their command.
    @since 1.2.2:
    Commands may get arranged in a sequence that is most likely to make sense.
-   E.g. image loading settings before drive aquiration, then commands fori
+   E.g. image loading settings before drive aquiration, then commands for
    adding files, then settings for writing, then writing.
    This feature may be enabled by command "-x" in Xorriso_prescan_args()
    or by parameter flag of this call.
@@ -357,6 +354,71 @@ int Xorriso_interpreter(struct XorrisO *xorriso,
 int Xorriso_execute_option(struct XorrisO *xorriso, char *line, int flag);
 
 
+/* Parse a text line into words. This parsing obeys the same rules as
+   command line parsing but allows to skip a prefix, to use a user provided
+   set of separator characters, and to restrict the number of parsed words.
+   @since 1.2.6
+   @param xorriso     The context object which provides settings for parsing
+   @param line        A text of one or more words according to man xorriso
+                      paragraph "Command processing" up to and including
+                      "Backslash Interpretation".
+   @param prefix      If not empty then the line will only be parsed if it
+                      begins by the prefix text. Parsing will then begin after
+                      the end of the prefix.
+                      If the prefix does not match, then 0 will be returned
+                      in *argc, argv will be NULL, and the return value will
+                      be 2.
+   @param separators  If not empty this overrides the default list of word
+                      separating characters. Default set is the one of
+                      isspace(3).
+   @param max_words   If not 0: Maximum number of words to parse. If there
+                      remains line text after the last parsed word and its
+                      following separators, then this remainder is copied
+                      unparsed into a final result word. In this case *argc
+                      will be larger than max_words by one. Note that trailing
+                      separators are considered to be followed by an empty
+                      word.
+   @param argc        Will return the number of allocated and filled word
+                      strings.
+   @param argv        Will return the array of word strings.
+                      Do not forget to dispose the allocated memory by a
+                      call to Xorriso__dispose_words().
+   @param flag        Bitfield for control purposes
+                      bit0=   Override setting of -backslash_codes
+                      bit1-4= With bit1: backslash behavior
+                              0= off
+                              1= in_double_quotes
+                              2= in_quotes
+                              3= with_quoted_input resp. on
+                      bit5=   Prepend the program name as (*argv)[0], so that
+                              *argv is suitable for Xorriso_interpreter()
+                              and other calls which expect this.
+                      bit6=   Issue failure message in case of return 0
+   @return            <=0 means error and invalidity of *argv:
+                              0 = Input format error. E.g. bad quotation mark.
+                             -1 = Lack of resources. E.g. memory.
+                      >0 means success but not necessarily a valid result:
+                              1 = Result in argc and argv is valid (but may
+                                  be empty by argc == 0, argv == NULL).
+                              2 = Line did not match prefix. Result is invalid
+                                  and empty.
+*/
+int Xorriso_parse_line(struct XorrisO *xorriso, char *line,
+                       char *prefix, char *separators, int max_words,
+                       int *argc, char ***argv, int flag);
+
+
+/* Dispose a list of strings as allocated by Xorriso_parse_line() or
+   Xorriso_program_arg_bsl().
+   @since 1.2.6
+   @param argc        A pointer to the number of allocated and filled word
+                      strings. *argc will be set to 0 by this call.
+   @param argv        A pointer to the array of word strings.
+                      *argv will be set to NULL by this call.
+*/
+void Xorriso__dispose_words(int *argc, char ***argv);
+
+
 /* Enter xorriso command line dialog mode, using libreadline if configured
    at build time and not disabled at run time.
    This call returns immediately if not option -dialog "on" was performed