PerlDoc

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


Parent package: Foswiki::Configure
Child 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

    Topic revision: r1 - 06 Aug 2023, UnknownUser
    This site is powered by FoswikiCopyright © by the contributing authors. All material on this site is the property of the contributing authors.
    Ideas, requests, problems regarding Foswiki? Send feedback