Extension:Carp

The Carp extension enables template call stack backtracing and error reporting for parser functions.

Rationale
Advanced wiki sites are complex and complicated. A page source is not just wikitext, but rather a program — source can invoke dozens of templates, which invoke other templates, and so on. A page source and templates may invoke parser functions, which implements string processing and control structures, such as,  , etc. All this stuff forms ugly, but real programming language, doesn't it?

As in any programming language, there can be errors. A template expects two arguments, but only one is provided. An argument is expected to be a title of an existing page, but it is an empty string or contains characters not suitable for a page title, or it is a perfect title, but there is no page with such a title. And so on.

Well-written parser functions and templates will produce good error messages if something goes wrong. For example, a parser function may return a good error message like "Not enough arguments: 3 arguments expected, 1 provided". The cause of error is clear now, but where is the cause? Imagine this function is invoked many times from many locations, and some of calls are buried in deeply nested template calls.

If you write a program in a programming language like C or Perl or Java or many other languages, you name it, you can relatively easy locate the error by looking at call stack backtrace:

Oops! at assa.pl line 9 main::bar called at assa.pl line 13 main::foo called at assa.pl line 16

Why don't we have such well-known troubleshooting feature in wikitext? Well, we have now.

Users
End-users of the Carp extension are wiki writers, people who edit wiki pages, especially those who develop complex templates. They will get profit in form of error messages with call stack backtrace which allows to locate errors in wikitext more easily. But the Carp extension is not intended to be used by wiki writers and template developers directly.

The Carp is a tool to be used by MediaWiki extension developers, PHP programmers who write parser functions — they are expected to use Carp class in their PHP code to provide their users, template developers with good error messages.

Usage
Let us consider an (incomplete) implementation of  parser function which does not accept any arguments. If user makes a mistake and specifies any argument(s), we want s/he see an error with call stack backtrace.

Being called from "Sandbox" page with no arguments:

{{ #example }}

the function produces: Hello from example!

However, being called with an argument:

{{ #example: arg }}

The function produces:

&lt;span class="error"&gt; {{ Sandbox }} → {{ #example: Function does not accept any arguments }} &lt;/span&gt;

which looks like (exact result depends on site stylesheets):

{{ Sandbox }} → {{ #example: Function does not accept any arguments }}

Note the  — this is a call stack backtrace. In the example call stack is very shallow, because  is called directly from "Sandbox" page. However, this may look like

&lt;span class="error"&gt; {{ Sandbox }} → {{ Template:Foo }} → {{ Template:Bar }} → {{ #example: Function does not accept any arguments }} &lt;/span&gt;

Result is enclosed into  element with class , so it is:


 * visually highligted (exact result depends on user's skin and site's stylesheets), and
 * recognized as error by  parser function defined in ParserFunctions extension.

Error message itself ("Function does not accept any arguments"), call stack order and decorators (braces) depend on user's language:


 * Localization of error message should be provided by Example extension;
 * Decorators are internationalized by the Carp extension (see Carp.i18n.php file; localization for a particular language may be missed);
 * In case of right-to-left language call stack is shown in reverse order, frames will be separated by left arrows.

This is straightforward (and recommended) Carp extension usage, suitable for almost any extension implementing parser functions. Carp class also provides some low-level functionality (e. g. just template call stack backtracing without error formatting). See description of class Carp for details.