1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
|
@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.
|
