@node Texinfo@asis{::}Report
@chapter Texinfo::Report

@node Texinfo@asis{::}Report NAME
@section Texinfo::Report NAME

Texinfo::Report - Error storing for Texinfo modules

@node Texinfo@asis{::}Report SYNOPSIS
@section Texinfo::Report SYNOPSIS

@verbatim
  use Texinfo::Report;

  my $registrar = Texinfo::Report::new();

  if ($warning_happened) {
    $registrar->line_warn($converter, sprintf(__("\@%s is wrongly used"),
                       $current->{'cmdname'}), $current->{'source_info'});
  }

  my ($errors, $errors_count) = $registrar->errors();
  foreach my $error_message (@$errors) {
    warn $error_message->{'error_line'};
  }

  $registrar->clear();
@end verbatim

@node Texinfo@asis{::}Report NOTES
@section Texinfo::Report NOTES

The Texinfo Perl module main purpose is to be used in @code{texi2any} to convert
Texinfo to other formats.  There is no promise of API stability.

@node Texinfo@asis{::}Report DESCRIPTION
@section Texinfo::Report DESCRIPTION

The @code{Texinfo::Report} module helps with error handling.  Errors
and warnings can be setup, stored and retrieved later on.
This module is used by the Texinfo modules @ref{Texinfo@asis{::}Parser NAME,, Texinfo::Parser} and
@ref{Texinfo@asis{::}Convert@asis{::}Converter NAME,, Texinfo::Convert::Converter}.

@node Texinfo@asis{::}Report METHODS
@section Texinfo::Report METHODS

No method is exported in the default case.

The @code{new} method initializes a @code{Texinfo::Report} object.
The errors collected are available through the @code{errors} method, the other
methods allow registering errors and warnings.

@table @asis
@item my $registrar = Texinfo::Report::new()
@anchor{Texinfo@asis{::}Report my $registrar = Texinfo@asis{::}Report@asis{::}new()}
@cindex @code{Texinfo::Report::new}

Return an initialized  @code{Texinfo::Report} object.

@item ($error_warnings_list, $error_count) = errors($registrar)
@anchor{Texinfo@asis{::}Report ($error_warnings_list@comma{} $error_count) = errors($registrar)}
@cindex @code{errors}

This function returns as @emph{$error_count} the count of errors since
calling @code{new}.  The @emph{$error_warnings_list} is an array of hash references
one for each error, warning or error line continuation.  Each of these has
the following keys:

@table @asis
@item continuation
@anchor{Texinfo@asis{::}Report continuation}

If set, the line is a continuation line of a message.

@item error_line
@anchor{Texinfo@asis{::}Report error_line}

The text of the error formatted with the macro name, as needed.

@item file_name
@anchor{Texinfo@asis{::}Report file_name}

The file name where the error or warning occurs.

@item line_nr
@anchor{Texinfo@asis{::}Report line_nr}

The line number of the error or warning.

@item macro
@anchor{Texinfo@asis{::}Report macro}

The user macro name that is expanded at the location of
the error or warning.

@item text
@anchor{Texinfo@asis{::}Report text}

The text of the error.

@item type
@anchor{Texinfo@asis{::}Report type}

May be @code{warning}, or @code{error}.

@end table

@item $registrar->clear ()
@anchor{Texinfo@asis{::}Report $registrar->clear ()}
@cindex @code{clear}

Clear the previously registered messages.

@item $registrar->add_formatted_message ($msg)
@anchor{Texinfo@asis{::}Report $registrar->add_formatted_message ($msg)}
@cindex @code{add_formatted_message}

Register the @emph{$msg} hash reference corresponding to an error, warning or error line
continuation.  The @emph{$msg} hash reference should correspond to the structure returned
by @code{errors}.

@item $registrar->line_warn($text, $error_location_info, $continuation, $debug, $silent)
@anchor{Texinfo@asis{::}Report $registrar->line_warn($text@comma{} $error_location_info@comma{} $continuation@comma{} $debug@comma{} $silent)}

@item $registrar->line_error($text, $error_location_info, $continuation, $debug, $silent)
@anchor{Texinfo@asis{::}Report $registrar->line_error($text@comma{} $error_location_info@comma{} $continuation@comma{} $debug@comma{} $silent)}
@cindex @code{line_warn}
@cindex @code{line_error}

Register a warning or an error.  The @emph{$text} is the text of the
error or warning.  The mandatory @emph{$error_location_info} holds the information
on the error or warning location.  The @emph{$error_location_info} reference on
hash may be obtained from Texinfo elements @emph{source_info} keys.   It may also
be setup to point to a file name, using the @code{file_name} key and to a line
number, using the @code{line_nr} key.  The @code{file_name} key value should be a
binary string.

The @emph{$continuation} optional arguments, if true, conveys that
the line is a continuation line of a message.

The @emph{$debug} optional integer arguments sets the debug level.

The @emph{$silent} optional arguments, if true, suppresses the output of
a message that is output immediatly if debugging is set.

The @emph{source_info} key of Texinfo tree elements is described
in more details in @ref{Texinfo@asis{::}Parser source_info}.

@item $registrar->document_warn($text, $program_name, $continuation)
@anchor{Texinfo@asis{::}Report $registrar->document_warn($text@comma{} $program_name@comma{} $continuation)}

@item $registrar->document_error($text, $program_name, $continuation)
@anchor{Texinfo@asis{::}Report $registrar->document_error($text@comma{} $program_name@comma{} $continuation)}
@cindex @code{document_warn}
@cindex @code{document_error}

Register a document-wide error or warning.  @emph{$text} is the error or
warning message.  The @emph{$program_name} is prepended to the
message, if defined.  The @emph{$continuation} optional arguments, if true, conveys
that the line is a continuation line of a message.

@end table

@node Texinfo@asis{::}Report AUTHOR
@section Texinfo::Report AUTHOR

Patrice Dumas, <pertusus@@free.fr>

@node Texinfo@asis{::}Report COPYRIGHT AND LICENSE
@section Texinfo::Report COPYRIGHT AND LICENSE

Copyright 2010- Free Software Foundation, Inc.  See the source file for
all copyright years.

This library is free software; you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation; either version 3 of the License, or (at
your option) any later version.

