Extension:Carp

From MediaWiki.org
Jump to navigation Jump to search
MediaWiki extensions manualManual:Extensions
Crystal Clear action run.svg
Carp

Release status:Extension status beta

DescriptionTemplate:Extension#description Provides error reporting and stack unwinding to other extensions
Author(s)Template:Extension#username Van de Buggertalk
MediaWikiTemplate:Extension#mediawiki 1.18+ (should work with earlier versions)
PHPTemplate:Extension#php 5.3+
Database changesTemplate:Extension#needs-updatephp No
LicenseTemplate:Extension#license GNU Affero General Public License 3.0
Download

Translate the Carp extension if it is available at translatewiki.net

Check usage and version matrix.

What?[edit]

The Carp extension enables template call stack backtracing and error reporting for parser functions. (Error reporting for templates is implemented in another extension named TemplateSpecial.)

Why?[edit]

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 #if, #while, 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.

Who[edit]

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.

(TemplateSpecial extension provides service for template developers.)

Download[edit]

git clone https://gerrit.wikimedia.org/r/p/mediawiki/extensions/Carp.git

Installation[edit]

  • Download and place the file(s) in a directory called Carp in your extensions/ folder.
  • Add the following code at the bottom of your LocalSettings.php:
    wfLoadExtension( 'Carp' );
    
  • YesY Done – Navigate to Special:Version on your wiki to verify that the extension is successfully installed.

To users running MediaWiki 1.24 or earlier:

The instructions above describe the new way of installing this extension using wfLoadExtension() If you need to install this extension on these earlier versions (MediaWiki 1.24 and earlier), instead of wfLoadExtension( 'Carp' );, you need to use:

require_once "$IP/extensions/Carp/Carp.php";

Configuration[edit]

There is no any configurable parameters, at least now.

Usage[edit]

Let us consider an (incomplete) implementation of #example 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.

class Example {
    static function onParserFirstCallInit( &$parser ) {
        $parser->setFunctionHook( 'example', 'Example::hookExample', SFH_OBJECT_ARGS );
        // Note the flag SFH_OBJECT_ARGS -- it is important. 
        // We need a frame to backtrace the call stack.
        return true;
    }
    static public function hookExample( $parser, $frame, $args ) {
        try {
            if ( count( $args ) > 0 ) {
                // Oops, error: there are argument. Throw an exception.
                // 'example-no-args' is not a message, but a *key* of message.
                Carp::throwNew( 'example-no-args' );
            };
            return 'Hello from example!';
        } catch ( Carp $ex ) {
            // An exception is caught. Return error instead of normal result.
            // User-visible name of parser function is '#example'.
            return Carp::confess( '#example', $frame, $ex );
        };
    }
}

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:

<span class="error">
{{ Sandbox }} → 
{{ #example: Function does not accept any arguments }}
</span>

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

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

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

<span class="error">
{{ Sandbox }} → 
{{ Template:Foo }} → 
{{ Template:Bar }} → 
{{ #example: Function does not accept any arguments }}
</span>

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

  • visually highligted (exact result depends on user's skin and site's stylesheets), and
  • recognized as error by #iferror 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.

See also[edit]

  • Carp, a well-known Perl module. It is a source of idea and some names (Carp, croak, confess).
  • TemplateSpecial, an MediaWiki extension providing similar service for template developers (TemplateSpecial uses Carp).

License[edit]

GNU Affero General Public License, version 3 or any later version. See AGPL-3.0.txt file for the full license text.