Texinfo::Report
***************

Texinfo::Report NAME
====================

Texinfo::Report - Error storing for Texinfo modules

Texinfo::Report SYNOPSIS
========================

  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'};
  }

Texinfo::Report NOTES
=====================

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

Texinfo::Report DESCRIPTION
===========================

The Texinfo::Report module helps with error handling.  It is used by the Texinfo modules Texinfo::Parser and Texinfo::Convert::Converter.  To use this module, either create a new Texinfo::Report object or initialize another object such as to be able to call Texinfo::Report methods.  In any case, Texinfo::Report::new() is called to setup the module.

Besides the new method, errors is used for reporting errors, and the other methods to store errors (and warnings).

Texinfo::Report METHODS
=======================

No method is exported in the default case.

The new method initializes Texinfo::Report related fields. The errors collected are available through the errors method, the other methods allow registering errors and warnings.

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

$converter->Texinfo::Report::new()

     If called without argument, a Texinfo::Report object is initialized and returned.  This is how the module is used in the Texinfo Parsers, as a separate object.

     If called on a $converter, the $converter is initialized itself such as to be able to call Texinfo::Report methods.  It is how it is used in the Converters.

($error_warnings_list, $error_count) = errors($registrar)

     This function returns as $error_count the count of errors since calling new.  The $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:

     type

          May be warning, or error.

     text

          The text of the error.

     error_line

          The text of the error formatted with the file name, line number and macro name, as needed.

     line_nr

          The line number of the error or warning.

     file_name

          The file name where the error or warning occurs.

     macro

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

$registrar->line_warn($text, $configuration_information, $error_location_info, $continuation, $silent)

$registrar->line_error($text, $configuration_information, $error_location_info, $continuation, $silent)

     Register a warning or an error.  The $text is the text of the error or warning.  The $configuration_information object gives some information that can modify the messages or their delivery. The optional $error_location_info holds the information on the error or warning location.  The $error_location_info reference on hash may be obtained from Texinfo elements source_info keys.   It may also be setup to point to a file name, using the file_name key and to a line number, using the line_nr key.  The file_name key value should be a binary string.

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

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

     The source_info key of Texinfo tree elements is described in more details in Texinfo::Parser source_info.

$registrar->document_warn($configuration_information, $text, $continuation)

$registrar->document_error($configuration_information, $text, $continuation)

     Register a document-wide error or warning.  $text is the error or warning message.  The $configuration_information object gives some information that can modify the messages or their delivery. The $continuation optional arguments, if true, conveys that the line is a continuation line of a message.

Texinfo::Report AUTHOR
======================

Patrice Dumas, <pertusus@free.fr>

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.