internal package
Foswiki::Configure::Reporter
Report package for configure, supporting text reporting and
simple TML expansion to HTML.
This class doesn't actually handle expansion of TML to anything else;
it simply stores messages for processing by formatting back ends.
However it is a sensible place to define the subset of TML that is expected
to be supported by renderers.
- Single level of lists (* and 1)
- Blank line = paragraph break <p />
- > at start of line = <br> before and after (i.e. line stands alone)
- Simple tables | like | this |
- Text styling e.g. *bold*, =code= etc
- URL links [[http://that][text description]]
- <verbatim>...</verbatim>
- HTML types
button
, select
, option
and textarea
are supported for wizard inputs, if the renderer supports them. Non-interactive renderers should ignore them.
- ---+++ Headings
Each of the reporting methods (NOTE, WARN, ERROR) accepts any number of
message parameters. These are treated as individual error messages, rather
than being concatenated into a single message. \n can be used in any
message, and it will survive into the final TML.
Most renderers will assume an implicit > at the front of every WARN and
ERROR message.
ObjectMethod
NOTE(@notes) → $this
Report one or more notes. Each parameter is handled as an independent
message. Returns the reporter to allow chaining.
ObjectMethod
WARN(@warnings)
Report one or more warnings. Each parameter is handled as an independent
message. Returns the reporter to allow chaining.
ObjectMethod
ERROR(@errors) → $this
Report one or more errors. Each parameter is handled as an independent
message. Returns the reporter to allow chaining.
ObjectMethod
CHANGED($keys) → $this
Report that a
Foswiki::cfg
entry has changed. The new value will
be taken from the current value in
$Foswiki::cfg
at the time of
the call to CHANGED.
Example:
$reporter->CHANGED('{Email}{Method}')
Returns the reporter to allow chaining.
ObjectMethod
WIZARD($label, $data) → $note
Generate a wizard button suitable for adding to the stream.
This should return '' if the reporter does not support wizards.
The default is to create an HTML button.
Caller is expected to add the result to the reporter stream using
NOTE etc.
ObjectMethod
has_level( $level ) → $boolean
Return true if the reporter has seen at least one $level message, where
$level is one of notes, warnings or errors.
ObjectMethod
hint( $hint [, $value] ) → $value
Get/set a hint in the report
Supported hints are:
-
require_save
- true if the reporter has hintged to require a save. This is done to trigger merge of Spec files, etc.
-
reset_may_repair
- true if resetting the value of the key to the default may repair the error.
undef
is returned if the hint is not set.
If
$value
is given, the previous value is returned.
ObjectMethod
clear() → $this
Clear all contents from the reporter.
Returns the reporter to allow chaining.
ObjectMethod
messages() → \@messages
Get the content of the reporter. @messages is an ordered array of hashes,
each of which has fields:
- level: one of errors, warnings, notes
- text: text of the message
Each message corresponds to a single parameter to one of the ERROR,
WARN or NOTES methods.
ObjectMethod
changes() → \%changes
Get the content of the reporter. %changes is a hash mapping a key
to a (new) value. Each entry corresponds to a call to the CHANGED
method (though multiple calls to CHANGED with the same keys will
only result in one entry).
ObjectMethod
hints() → \%hints
Get the content of the hints hash. Flags are used to supply hints to the
UI as to how errors may be resolved.
ObjectMethod
stringify(@levels) → $text
Used for debugging, simply generates a plain text string from the
content of the reporter.
-
@levels
optional list of levels to report (default is all levels) from notes, warnings, errors, changes
StaticMethod
uneval($datum [, $indent]) → $string
Serialise the perl datum $datum as a perl string that can be
evalled to recover the original value.
$indent can be used to override the default setting (0) for
$Data::Dumper::Indent. See perldoc Data::Dumper for more information.
StaticMethod
ellipsis($string, $limit) → $string
If $string exceeds $limit in length, truncate the string to
$limit-3 characters and append ellipsis (...)
StaticMethod
stripStacktrace($stacktrace) → $message
Strip traceback from die and carp for a user message