internal package Foswiki::Configure::Reporter

See PublishedAPI for packages intended to be used by Plugin and Contrib authors, or browse all packages.
See also Developing plugins, Developer's Bible, Technical Overview

Perl Module:

Child packagesChild packages

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:

1. require_save - true if the reporter has hintged to require a save. This is done to trigger merge of Spec files, etc.
2. 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