New command -msg_op

libisoburn/trunk/xorriso/xorriso.texi

@@ -50,7 +50,7 @@
 @c man .\" First parameter, NAME, should be all caps
 @c man .\" Second parameter, SECTION, should be 1-8, maybe w/ subsection
 @c man .\" other parameters are allowed: see man(7), man(1)
-@c man .TH XORRISO 1 "Version 1.2.5, Nov 05, 2012"
+@c man .TH XORRISO 1 "Version 1.2.5, Dec 08, 2012"
 @c man .\" Please adjust this date whenever revising the manpage.
 @c man .\"
 @c man .\" Some roff macros, for reference:
@@ -5248,6 +5248,85 @@ If text is not empty it will get put out on "M" channel each time
 @command{xorriso} is ready for the next dialog line or before
 @command{xorriso} performs a command that was entered to the pager prompt.
 @c man .TP
+@item -msg_op opcode parameter_text
+@kindex -msg_op   perform operations on program messages
+@cindex Program messages, perform operations, -msg_op
+This command shall facilitate extraction of particular information from
+the message output of other commands. It gives access to the C API function
+Xorriso_parse_line and to the message sieve that is provided by the C API.
+Please refer to their description in file xorriso.h.
+@*
+Intended users are frontend programs which operate xorriso in dialog mode.
+@*
+The result output of this command is not caught by the message sieve.
+@*
+The following opcodes are defined:
+@*
+@strong{start_sieve}
+@*
+Install the message sieve as of Xorriso_sieve_big() and start watching
+program messages. The parameter_text has no meaning.
+@*
+@strong{show_sieve}
+@*
+Show a list of filter rule names. The parameter_text has no meaning.
+The list begins by a line with the return value of Xorriso_sieve_get_result()
+with flag bit3. If this value is larger than 0, then the next line tells
+the number of names. The following lines show one name each.
+@*
+@strong{read_sieve}
+@*
+Use the parameter_text as name of a filter rule and inquire its next
+recorded result.
+See Xorriso_sieve_big() for a list of names and reply strings.
+@*
+The recorded strings are put out on result channel. They get wrapped
+into lines which tell their structure.
+The first line tells the return value of Xorriso_sieve_get_result().
+The next line tells the number of strings. Each string begins by a line that
+tells the number of lines of the string. Then follow these lines. They are to
+be concatenated with a newline character inbetween each of them.
+Finally the number of still available recorded results of the given name
+is put out.
+@*
+@strong{clear_sieve}
+@*
+Dispose all recorded strings and continue watching program messages.
+The parameter_text has no meaning.
+@*
+@strong{end_sieve}
+@*
+Dispose the sieve with its filter rules and stop watching program messages.
+The parameter_text has no meaning.
+@*
+@strong{parse}
+@*
+Read a text from dialog input and submit it to Xorriso_parse_line().
+The parameter_text word shall consist of several words separated by blanks.
+It will be necessary to use both kinds of quotation marks.
+@*
+E.g. "'ISO session  :' '' 0 0 1"
+@*
+The five parameter words are: prefix, separators, max_words, flag,
+number_of_input_lines.
+The former four are handed over to Xorriso_parse_line(). The number of
+input lines minus one tells xorriso how many newline characters are
+part of the input text.
+@*
+The announced number of text lines will be read from dialog input,
+concatenated with a newline character inbetween each of them,
+and submitted to Xorriso_parse_line() as parameter line.
+Note that newlines outside of quotation marks are
+interpreted as separators if the separators parameter is empty.
+@*
+The parsed strings are put out on result channel. They get wrapped
+into lines which tell their structure.
+The first line tells the return value of Xorriso_parse_line().
+The next line tells the number of strings. Each string begins by a line that
+tells the number of lines of the string. Then follow these lines. They are to 
+be concatenated with a newline character inbetween each of them.
+@*
+@c man .TP
 @item -prog text
 @kindex -prog   sets program name
 @cindex Program, set name, -prog