Extension:Pipe Escape

From MediaWiki.org

Jump to: navigation, search

           

Manual on MediaWiki Extensions
List of MediaWiki Extensions
Crystal Clear action run.png
Pipe Escape

Release status: beta
Implementation  Parser function
Description Escape pipe characters in parser function arguments/template arguments.
Author(s)  David M. Sledge (talk)
Last Version  0.1.1 (2009-03-10)
MediaWiki  ≥ 1.12
License GNU GPL 2.0 or later
Download Download snapshot

Subversion [Help]
Browse source code

check usage (experimental)

Contents

[edit] What can this extension do?

This extension allows for pipe characters in parser function arguments (and template argument calls) avoid being interpreted as an argument delimiter. This is primarily for the purpose of using wiki tables (or parts thereof) inside parser function calls.

For example, suppose you have the following wikitable in a template:

{|
|-
!       || Heading 1 || Heading 2
|-
| Row a || a1        || a2
|-
| Row b || b1        || b2
|}

but you only want the table to show up when a non-whitespace value is supplied for template argument targ. One possible solution is to use HTML instead of wiki syntax

{{#if: {{{targ|}}}|<table>
<tr>
<th> <th> Heading 1 <th> Heading 2
<tr>
<td> Row a <td> a1 <td> a2
<tr>
<td> Row b <td> b1 <td> b2
</table>}}

but this is less intuitive and therefore more error-prone, and, in part, defeats the purpose of a wiki. Another solution is to hide the pipe characters from the parser function in a template. (Common practice is to use the template Template:! with its includable contents being only a raw pipe character.)

{{#if: {{{targ|}}}
|{{{!}}
{{!}}-
!           {{!}}{{!}} Heading 1 {{!}}{{!}} Heading 2
{{!}}-
{{!}} Row a {{!}}{{!}} a1        {{!}}{{!}} a2
{{!}}-
{{!}} Row b {{!}}{{!}} b1        {{!}}{{!}} b2
{{!}}}
}}

This is a better solution, but things are a bit messy when you're trying to hide multiple pipes in an argument. This is where this simple parser function comes in handy.

[edit] Usage

{{#!: wiki text }}

This hides the pipe characters in wiki text so that outer parser functions and outer templates do not interpret them as argument delimiters. With this extension, the above example can be rewritten as

{{#if: {{{targ|}}}
| {{#!:
{|
|-
!       || Heading 1 || Heading 2
|-
| Row a || a1        || a2
|-
| Row b || b1        || b2
|}
}}
}}

In reality, the pipe characters are still treated as argument delimiters in this parser function, but it concatenates the arguments using a pipe character as a separator which outer parser functions do not register as delimiters.

Unlike most parser functions, pipe escape preserves the leading and trailing whitespace around its arguments except the first argument (due to the way MediaWiki handles the first argument in parser functions; See bug 12842), and the trailing whitespace in the last argument.

Pipe escape only affects top-level pipe characters. It does not affect pipe characters in other parser functions nested within the pipe escape parser function call. The same is true for pipe characters in template calls, template arguments, intrawiki links, tag extensions, etc...

[edit] Download

[edit] Version 0.1.1

You can download version 0.1.1 directly via svn from the MediaWiki source code repository, at http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/PipeEscape/. From a command line, you can call the following:

svn checkout http://svn.wikimedia.org/svnroot/mediawiki/trunk/extensions/PipeEscape/

Place the downloaded directory in your $IP/extensions/ directory, where $IP stands for the root directory of your MediaWiki installation. That is the directory holding your LocalSettings.php.

[edit] Version 0.1.0

Please cut and paste the code found below and place it in $IP/extensions/PipeEscape/PipeEscape.php. Note: $IP stands for the root directory of your MediaWiki installation, the same directory that holds LocalSettings.php.

[edit] Installation

To install this extension after having followed the download instructions abovem add the following to LocalSettings.php:

require_once($IP.'/extensions/PipeEscape/PipeEscape.php');

[edit] Code

Version 0.1.1 is available in the MediaWiki source code repository. Version 0.1.0 is published here:

<?php
 
/**
 * @package MediaWiki
 * @subpackage Extensions
 *
 * @link http://www.mediawiki.org/wiki/Extension:Pipe_Escape Documentation
 *
 * @author David M. Sledge
 * @copyright Copyright © 2008 David M. Sledge
 * @license http://www.gnu.org/copyleft/gpl.html GNU General Public License 2.0
 *     or later
 * @version 0.1.0
 *     initial creation.
 *
 * @todo
 */
 
if ( !defined( "MEDIAWIKI" ) )
{
    die( "This file is a MediaWiki extension, it is not a valid entry point" );
}
 
$wgHooks[ 'ParserFirstCallInit' ][] = "ExtPipeEsc::setup";
$wgExtensionCredits[ 'parserhook' ][] = array(
    "author"      => "David M. Sledge",
    "name"        => "Pipe Escape",
    "version"     => ExtPipeEsc::VERSION,
    "description" => "Parser function for when you want a pipe character " .
        "to be just a pipe character",
    "url"         => "http://www.mediawiki.org/wiki/Extension:Pipe_Escape",
);
 
$wgHooks[ 'LanguageGetMagic' ][]  = 'ExtPipeEsc::languageGetMagic';
 
class ExtPipeEsc
{
    const VERSION = "0.1.0";
    private static $parserFunctions = array(
        '!' => 'pipeChar',
    );
 
    public static function setup( &$parser )
    {
        // register each hook
        foreach( self::$parserFunctions as $hook => $function )
            $parser->setFunctionHook( $hook,
                array( __CLASS__, $function ), SFH_OBJECT_ARGS );
 
        return true;
    }
 
    public static function languageGetMagic( &$magicWords, $langCode )
    {
        $magicWords[ '!' ] = array( 0, '!' );
 
        return true;
    }
 
    public static function pipeChar( &$parser, $frame, $args )
    {
        $output = array_shift( $args );
 
        // no parameters means we're done.  spit out an empty string
        if ( !isset( $output ) )
            return '';
 
        // expand the first argument
        $output = $frame->expand( $output );
 
        // get the rest of the arguments, expand each one, prefix each expansion
        // with a pipe character, and append it to the output string.
        for ( $arg = array_shift( $args ); isset( $arg );
              $arg = array_shift( $args ) )
        {
            $output .= '|' . $frame->expand( $arg );
        }
 
        //return '<pre><nowiki>'. trim( $output ) . '</nowiki></pre>';
        return trim( $output );
    }
}
Retrieved from "http://www.mediawiki.org/wiki/Extension:Pipe_Escape"