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