How Should a Plugin Indicate Incorrect Parameter Values

When developing plugins, how should a plugin indicate to a end-user that something is incorrect about the supplied parameters. For example, if a macro requires a certain parameter and it is not supplied by the user, what should the plugin's code do when in the tag handler code?

I've noticed from reading the source that a common action is to simply return nothing unless a parameter is defined. This causes the macro code to be rendered as is when the page is viewed. Is this the best practise? Is there ways of warning the user of the specific reason why their macro wasn't rendered?

From a newbie at plugin development

-- LeeRyman - 08 May 2009

Yes, the 'TmWiki' tradition was to return an empty string on most errors - but I think we'll be changing that in future - I've been toying with an 'error status' report for topics, and IF does also report errors in the parsing of the predicate section.

mostly it depends on your needs and what is appropriate for your plugin at this time - hopefully within the next year we can re-do the macro parameter work so that marcro registration also contains the parameter spec and some checking and reporting.

-- SvenDowideit - 08 May 2009

Error detection reporting is a ticklish subject. When I'm writing plugins myself, I use a sort of "defcon" approach to classify different "error events".

• Defcon 5:"normal peacetime readiness" - error can be treated as "non-fatal", except when in a dev environment
  • Use ASSERT() if DEBUG to verify critical conditions
  • Check, but silently ignore, error conditions.
• Defcon 4 "increased intelligence" - we might like to issue some silent debugging info, so that if something does go wrong, we can quickly debug it
  • Use print STDERR to report progress. Disable these statements with a flag in the code, but don't let users set that flag (other than by editing the code)
  • Use writeDebug and writeWarning to log significant events, but use a very light touch and disable the statements using a configure flag.
• Defcon 3 "readiness above normal" - a bad parameter may make the plugin appear not to work, and the risk is medium
  • Check all function parameters that might be SNAFU
  • Rather than returning an empty string, return an <span class="foswikiAlert">Error message</span> if it's an option
• Defcon 2 "just below maximum readiness" - we are seriously nervous about an error, and it could break Foswiki
  • Be prepared to use Carp::confess or throw Error::Simple to make a stack trace accessible and easy to report.
  • Consider the use of Foswiki::OopsException
• Defcon 1 "maximum readiness" - we are seriously nervous about an error, and one is highly likely to occur, and it could break Foswiki e.g. by corrupting data on disc
  • Use Foswiki::OopsException, and write a template for the exception so that you can interact with the user.

At some point I plan to expose the Foswiki::Logger interface to plugins to increase the flexibility of error reporting, but until then the above defcon approach should help.

-- CrawfordCurrie - 08 May 2009

Thanks for the answers Sven and Crawford. It does seem like most user macro stuffups will belong in the realm of Defcon 3. Perhaps there could be an API for returning the suggested foswikiAlert messages in an abstracted manner. I'm also dealing with relative wiki-newbies, so some sort of appropriately skinned error message when a parameter is missing or incorrect would be nice. I will have a look at the IF macro's code too. It is funny, but when ever I'm designing software it is always how to handle errors that seems to take the most time and thought. There is often a fine line between application error where the user stuffs-up, and system error when the application stuffs-up, and reporting and dealing with them appropriately can be challenging.

Could I suggest a new question Subject related to development of foswiki and/or extensions? Is this the appropriate place to ask such questions as above? Thanks again.

-- LeeRyman - 10 May 2009

Yes, it's a good place to ask such questions. There is some resistance among some of the community to acknowledging the role/existence of developers, but I'm sure we can sneak in a new Subject - and maybe even a new FAQ - under the radar

-- CrawfordCurrie - 10 May 2009