Mediawiki RawFile

From YobiWiki
Jump to navigation Jump to search

Introduction

The idea is to be able to download directly a portion of code as a file.
I've numerous code examples in my wiki and I wast an easy way to download them, easier than a copy/paste!

  • It must work with pre, nowiki, js, css, code, source, so let's make it general: take the tag that comes after the parser function we'll create and select data up to the closing tag.

2 parts:

  • the parser magic word that will be converted into a "Save it as <filename>"
  • an extended action=raw that will strip the raw output to keep the desired code

Documentation

Syntax

{{#rawsnippet: myscript.sh}}
Do we need a MIME type?
Transformation:
{{fullurl:{{PAGENAME}}|action=raw&rawsnippet=myscript.sh}}
Test: save the following code [{{#rawsnippet: myscript.sh}} as myscript.sh]

#!/bin/bash

echo 'Hello world!'
exit 0

{{#rawsnippet: myscript.sh}} combines in fact 2 elements: the text that will be replaced by the link and the anchor just before the code section.
We can separate both functionalities with:

One such declaration, just before the code section: {{#rawsnippetAnchor: myscript.sh}}

One or many such declarations to create the download links: {{#rawsnippetLink: myscript.sh}}

Example: {{#rawsnippetanchor: myotherscript.sh}}

#!/bin/bash

echo 'Hello earth!'
exit 0

[{{#rawsnippetlink: myotherscript.sh}} myotherscript.sh is available now below the code]

Hook on Raw

  • Must extract the right paragraph
    • Strip all up to the right rawsnippet: filename tag
    • Find the next tag
    • Select up to the closure tag
  • Must provide the filename to the browser
  • Tells the browser NOT to cache the raw

The code

Which you can of course download just by following [{{#rawsnippetlink: RawSnippet.php}} this link :-)]

So let's explain a bit the code in a Literate Programming way...

First some hooks for our functions... {{#rawsnippetanchor: RawSnippet.php}}

<?php

if (defined('MEDIAWIKI')) {

# Define a setup function
$wgExtensionFunctions[] = 'efRawSnippet_Setup';
# Add a hook to initialise the magic word
$wgHooks['LanguageGetMagic'][]       = 'efRawSnippet_Magic';
# Add a hook to intercept the raw output
$wgHooks['RawPageViewBeforeOutput'][] = 'fnRawSnippet_Strip';

Then the function to strip the code out of the raw wiki page, quite heavy as we've to parse the wiki page ourselves... {{#rawsnippetanchor: RawSnippet.php}}

function fnRawSnippet_Strip(&$rawPage, &$text) {
    // if our ext wasn't used, just exit
    if (!isset($_GET['rawsnippet']))
        return true;
    $filename=$_GET['rawsnippet'];
    header("Content-disposition:filename=".$filename);
    header("Content-type:application/octetstream"); 
    header("Content-Transfer-Encoding: binary"); 
    header("Expires: 0");
    header("Pragma: no-cache"); 
    header("Cache-Control: no-store");
    // First: find the right anchor
    // We mask nowiki sections
//TODO also mask source, js, css, pre, what else?
    //test2 will contain interpretable content, all static content is blanked out
    $maskedtext=preg_replace_callback('/<nowiki>(.*?)<\/nowiki>/', 
        create_function(
           '$matches',
           'return ereg_replace(".","X",$matches[0]);'
        ),
        $text);
    // We search rawsnippet anchor position
    if (preg_match_all('/{{#rawsnippetanchor: +'.$filename.' *}}/i', $maskedtext, $matches, PREG_OFFSET_CAPTURE))
        $offsets=$matches[0];
    else if (preg_match_all('/{{#rawsnippet: +'.$filename.' *}}/i', $maskedtext, $matches, PREG_OFFSET_CAPTURE))
        // If the shortcut "rawsnippet" is used, no nuweb, just the first hit is considered
        $offsets=array($matches[0][0]);
    else
        // We didn't find our anchor, let's output all the raw...
// TODO change headers & send error msg
        return true;
    // free some mem
    unset($maskedtext);
    $textorig=$text;
    $text='';
    foreach ($offsets as $offset) {
        // Now let's remove the text up to our anchor
        $out = substr($textorig, $offset[1]);
        // What's the type of tag do we have?
        $out = substr($out, strpos($out, '<'));
        if (!preg_match('/^<([^> ]+)/', $out, $matches))
// TODO send error, we could not find end of bloc
            return true;
        $key = $matches[1];
        // Let's extract the text up to the closing tag
        $begin = strpos($out, '>')+1;
        if (ord(substr($out,$begin,1))==10)
            $begin++;
        if (preg_match_all('/<\/'.$key.'>/', $out, $matches, PREG_OFFSET_CAPTURE))
            $text .= substr($out, $begin, $matches[0][0][1]-$begin);
        else
// TODO send error, we could not find end of bloc
            $text .= substr($out, $begin);
    }

    header("Content-Length: ".strlen($text)); 
    return true;
    //TODO: downloadAs..
}

That's again part of the hooks... {{#rawsnippetanchor: RawSnippet.php}}

function efRawSnippet_Setup() {
    global $wgParser;
    # Set a function hook associating the "rawsnippet" magic word with our function
    $wgParser->setFunctionHook( 'rawsnippet', 'efRawSnippet_Render' );
    $wgParser->setFunctionHook( 'rawsnippetlink', 'efRawSnippet_Render' );
    $wgParser->setFunctionHook( 'rawsnippetanchor', 'efRawSnippet_Empty' );
}

This part as well... {{#rawsnippetanchor: RawSnippet.php}}

function efRawSnippet_Magic( &$magicWords, $langCode ) {
    # Add the magic word
    # The first array element is case sensitive, in this case it is not case sensitive
    # All remaining elements are synonyms for our parser function
    $magicWords['rawsnippet'] = array( 0, 'rawsnippet', 'downloadAs' );
    $magicWords['rawsnippetlink'] = array( 0, 'rawsnippetlink', 'downloadLink' );
    $magicWords['rawsnippetanchor'] = array( 0, 'rawsnippetanchor', 'downloadAnchor' );
    # unless we return true, other parser functions extensions will not get loaded.
    return true;
}

The transformation rule to replace link shortcuts to actual links for download {{#rawsnippetanchor: RawSnippet.php}}

function efRawSnippet_Render( &$parser, $filename = '') {
    # The parser function itself
    # The input parameters are wikitext with templates expanded
    # The output should be wikitext too
    return '{{fullurl:{{PAGENAME}}|action=raw&rawsnippet='.$filename.'}}';
//TODO+support for other pages
}

Credits :-) {{#rawsnippetanchor: RawSnippet.php}}

$wgExtensionCredits['parserhook'][] = array('name' => 'RawSnippet',
                           'version' => '0.1',
                           'author' => 'Philippe Teuwen',
//                         'url' => 'http://www.mediawiki.org/wiki/Extension:LocalServer',
                           'url' => 'http://wiki.yobi.be/wiki/Mediawiki_RawSnippet',
                           'description' => 'Downloads a RAW copy of <nowiki><tag>data</tag></nowiki> in a file<br>'.
                                            'Useful e.g. to download an example code or a patch<br>'.
                                            'It also opens the path to [http://en.wikipedia.org/wiki/Literate_programming Literate Programming]');
}

?>