do not try to html-escape anything but strings; fixes failing unit tests
[lhc/web/wiklou.git] / resources / mediawiki / mediawiki.jqueryMsg.js
1 /**
2 * Experimental advanced wikitext parser-emitter.
3 * See: http://www.mediawiki.org/wiki/Extension:UploadWizard/MessageParser for docs
4 *
5 * @author neilk@wikimedia.org
6 */
7
8 ( function( mw, $, undefined ) {
9
10 mw.jqueryMsg = {};
11
12 /**
13 * Given parser options, return a function that parses a key and replacements, returning jQuery object
14 * @param {Object} parser options
15 * @return {Function} accepting ( String message key, String replacement1, String replacement2 ... ) and returning {jQuery}
16 */
17 function getFailableParserFn( options ) {
18 var parser = new mw.jqueryMsg.parser( options );
19 /**
20 * Try to parse a key and optional replacements, returning a jQuery object that may be a tree of jQuery nodes.
21 * If there was an error parsing, return the key and the error message (wrapped in jQuery). This should put the error right into
22 * the interface, without causing the page to halt script execution, and it hopefully should be clearer how to fix it.
23 *
24 * @param {Array} first element is the key, replacements may be in array in 2nd element, or remaining elements.
25 * @return {jQuery}
26 */
27 return function( args ) {
28 var key = args[0];
29 var argsArray = $.isArray( args[1] ) ? args[1] : $.makeArray( args ).slice( 1 );
30 var escapedArgsArray = $.map( argsArray, function( arg ) {
31 return typeof arg === 'string' ? mw.html.escape( arg ) : arg;
32 } );
33 try {
34 return parser.parse( key, escapedArgsArray );
35 } catch ( e ) {
36 return $( '<span></span>' ).append( key + ': ' + e.message );
37 }
38 };
39 }
40
41 /**
42 * Class method.
43 * Returns a function suitable for use as a global, to construct strings from the message key (and optional replacements).
44 * e.g.
45 * window.gM = mediaWiki.parser.getMessageFunction( options );
46 * $( 'p#headline' ).html( gM( 'hello-user', username ) );
47 *
48 * Like the old gM() function this returns only strings, so it destroys any bindings. If you want to preserve bindings use the
49 * jQuery plugin version instead. This is only included for backwards compatibility with gM().
50 *
51 * @param {Array} parser options
52 * @return {Function} function suitable for assigning to window.gM
53 */
54 mw.jqueryMsg.getMessageFunction = function( options ) {
55 var failableParserFn = getFailableParserFn( options );
56 /**
57 * N.B. replacements are variadic arguments or an array in second parameter. In other words:
58 * somefunction(a, b, c, d)
59 * is equivalent to
60 * somefunction(a, [b, c, d])
61 *
62 * @param {String} message key
63 * @param {Array} optional replacements (can also specify variadically)
64 * @return {String} rendered HTML as string
65 */
66 return function( /* key, replacements */ ) {
67 return failableParserFn( arguments ).html();
68 };
69 };
70
71 /**
72 * Class method.
73 * Returns a jQuery plugin which parses the message in the message key, doing replacements optionally, and appends the nodes to
74 * the current selector. Bindings to passed-in jquery elements are preserved. Functions become click handlers for [$1 linktext] links.
75 * e.g.
76 * $.fn.msg = mediaWiki.parser.getJqueryPlugin( options );
77 * var userlink = $( '<a>' ).click( function() { alert( "hello!!") } );
78 * $( 'p#headline' ).msg( 'hello-user', userlink );
79 *
80 * @param {Array} parser options
81 * @return {Function} function suitable for assigning to jQuery plugin, such as $.fn.msg
82 */
83 mw.jqueryMsg.getPlugin = function( options ) {
84 var failableParserFn = getFailableParserFn( options );
85 /**
86 * N.B. replacements are variadic arguments or an array in second parameter. In other words:
87 * somefunction(a, b, c, d)
88 * is equivalent to
89 * somefunction(a, [b, c, d])
90 *
91 * We append to 'this', which in a jQuery plugin context will be the selected elements.
92 * @param {String} message key
93 * @param {Array} optional replacements (can also specify variadically)
94 * @return {jQuery} this
95 */
96 return function( /* key, replacements */ ) {
97 var $target = this.empty();
98 $.each( failableParserFn( arguments ).contents(), function( i, node ) {
99 $target.append( node );
100 } );
101 return $target;
102 };
103 };
104
105 var parserDefaults = {
106 'magic' : {},
107 'messages' : mw.messages,
108 'language' : mw.language
109 };
110
111 /**
112 * The parser itself.
113 * Describes an object, whose primary duty is to .parse() message keys.
114 * @param {Array} options
115 */
116 mw.jqueryMsg.parser = function( options ) {
117 this.settings = $.extend( {}, parserDefaults, options );
118 this.emitter = new mw.jqueryMsg.htmlEmitter( this.settings.language, this.settings.magic );
119 };
120
121 mw.jqueryMsg.parser.prototype = {
122
123 // cache, map of mediaWiki message key to the AST of the message. In most cases, the message is a string so this is identical.
124 // (This is why we would like to move this functionality server-side).
125 astCache: {},
126
127 /**
128 * Where the magic happens.
129 * Parses a message from the key, and swaps in replacements as necessary, wraps in jQuery
130 * If an error is thrown, returns original key, and logs the error
131 * @param {String} message key
132 * @param {Array} replacements for $1, $2... $n
133 * @return {jQuery}
134 */
135 parse: function( key, replacements ) {
136 return this.emitter.emit( this.getAst( key ), replacements );
137 },
138
139 /**
140 * Fetch the message string associated with a key, return parsed structure. Memoized.
141 * Note that we pass '[' + key + ']' back for a missing message here.
142 * @param {String} key
143 * @return {String|Array} string of '[key]' if message missing, simple string if possible, array of arrays if needs parsing
144 */
145 getAst: function( key ) {
146 if ( this.astCache[ key ] === undefined ) {
147 var wikiText = this.settings.messages.get( key );
148 if ( typeof wikiText !== 'string' ) {
149 wikiText = "\\[" + key + "\\]";
150 }
151 this.astCache[ key ] = this.wikiTextToAst( wikiText );
152 }
153 return this.astCache[ key ];
154 },
155
156 /*
157 * Parses the input wikiText into an abstract syntax tree, essentially an s-expression.
158 *
159 * CAVEAT: This does not parse all wikitext. It could be more efficient, but it's pretty good already.
160 * n.b. We want to move this functionality to the server. Nothing here is required to be on the client.
161 *
162 * @param {String} message string wikitext
163 * @throws Error
164 * @return {Mixed} abstract syntax tree
165 */
166 wikiTextToAst: function( input ) {
167
168 // Indicates current position in input as we parse through it.
169 // Shared among all parsing functions below.
170 var pos = 0;
171
172 // =========================================================
173 // parsing combinators - could be a library on its own
174 // =========================================================
175
176
177 // Try parsers until one works, if none work return null
178 function choice( ps ) {
179 return function() {
180 for ( var i = 0; i < ps.length; i++ ) {
181 var result = ps[i]();
182 if ( result !== null ) {
183 return result;
184 }
185 }
186 return null;
187 };
188 }
189
190 // try several ps in a row, all must succeed or return null
191 // this is the only eager one
192 function sequence( ps ) {
193 var originalPos = pos;
194 var result = [];
195 for ( var i = 0; i < ps.length; i++ ) {
196 var res = ps[i]();
197 if ( res === null ) {
198 pos = originalPos;
199 return null;
200 }
201 result.push( res );
202 }
203 return result;
204 }
205
206 // run the same parser over and over until it fails.
207 // must succeed a minimum of n times or return null
208 function nOrMore( n, p ) {
209 return function() {
210 var originalPos = pos;
211 var result = [];
212 var parsed = p();
213 while ( parsed !== null ) {
214 result.push( parsed );
215 parsed = p();
216 }
217 if ( result.length < n ) {
218 pos = originalPos;
219 return null;
220 }
221 return result;
222 };
223 }
224
225 // There is a general pattern -- parse a thing, if that worked, apply transform, otherwise return null.
226 // But using this as a combinator seems to cause problems when combined with nOrMore().
227 // May be some scoping issue
228 function transform( p, fn ) {
229 return function() {
230 var result = p();
231 return result === null ? null : fn( result );
232 };
233 }
234
235 // Helpers -- just make ps out of simpler JS builtin types
236
237 function makeStringParser( s ) {
238 var len = s.length;
239 return function() {
240 var result = null;
241 if ( input.substr( pos, len ) === s ) {
242 result = s;
243 pos += len;
244 }
245 return result;
246 };
247 }
248
249 function makeRegexParser( regex ) {
250 return function() {
251 var matches = input.substr( pos ).match( regex );
252 if ( matches === null ) {
253 return null;
254 }
255 pos += matches[0].length;
256 return matches[0];
257 };
258 }
259
260
261 /**
262 * ===================================================================
263 * General patterns above this line -- wikitext specific parsers below
264 * ===================================================================
265 */
266
267 // Parsing functions follow. All parsing functions work like this:
268 // They don't accept any arguments.
269 // Instead, they just operate non destructively on the string 'input'
270 // As they can consume parts of the string, they advance the shared variable pos,
271 // and return tokens (or whatever else they want to return).
272
273 // some things are defined as closures and other things as ordinary functions
274 // converting everything to a closure makes it a lot harder to debug... errors pop up
275 // but some debuggers can't tell you exactly where they come from. Also the mutually
276 // recursive functions seem not to work in all browsers then. (Tested IE6-7, Opera, Safari, FF)
277 // This may be because, to save code, memoization was removed
278
279
280 var regularLiteral = makeRegexParser( /^[^{}[\]$\\]/ );
281 var regularLiteralWithoutBar = makeRegexParser(/^[^{}[\]$\\|]/);
282 var regularLiteralWithoutSpace = makeRegexParser(/^[^{}[\]$\s]/);
283
284 var backslash = makeStringParser( "\\" );
285 var anyCharacter = makeRegexParser( /^./ );
286
287 function escapedLiteral() {
288 var result = sequence( [
289 backslash,
290 anyCharacter
291 ] );
292 return result === null ? null : result[1];
293 }
294
295 var escapedOrLiteralWithoutSpace = choice( [
296 escapedLiteral,
297 regularLiteralWithoutSpace
298 ] );
299
300 var escapedOrLiteralWithoutBar = choice( [
301 escapedLiteral,
302 regularLiteralWithoutBar
303 ] );
304
305 var escapedOrRegularLiteral = choice( [
306 escapedLiteral,
307 regularLiteral
308 ] );
309
310 // Used to define "literals" without spaces, in space-delimited situations
311 function literalWithoutSpace() {
312 var result = nOrMore( 1, escapedOrLiteralWithoutSpace )();
313 return result === null ? null : result.join('');
314 }
315
316 // Used to define "literals" within template parameters. The pipe character is the parameter delimeter, so by default
317 // it is not a literal in the parameter
318 function literalWithoutBar() {
319 var result = nOrMore( 1, escapedOrLiteralWithoutBar )();
320 return result === null ? null : result.join('');
321 }
322
323 function literal() {
324 var result = nOrMore( 1, escapedOrRegularLiteral )();
325 return result === null ? null : result.join('');
326 }
327
328 var whitespace = makeRegexParser( /^\s+/ );
329 var dollar = makeStringParser( '$' );
330 var digits = makeRegexParser( /^\d+/ );
331
332 function replacement() {
333 var result = sequence( [
334 dollar,
335 digits
336 ] );
337 if ( result === null ) {
338 return null;
339 }
340 return [ 'REPLACE', parseInt( result[1], 10 ) - 1 ];
341 }
342
343
344 var openExtlink = makeStringParser( '[' );
345 var closeExtlink = makeStringParser( ']' );
346
347 // this extlink MUST have inner text, e.g. [foo] not allowed; [foo bar] is allowed
348 function extlink() {
349 var result = null;
350 var parsedResult = sequence( [
351 openExtlink,
352 nonWhitespaceExpression,
353 whitespace,
354 expression,
355 closeExtlink
356 ] );
357 if ( parsedResult !== null ) {
358 result = [ 'LINK', parsedResult[1], parsedResult[3] ];
359 }
360 return result;
361 }
362
363 var openLink = makeStringParser( '[[' );
364 var closeLink = makeStringParser( ']]' );
365
366 function link() {
367 var result = null;
368 var parsedResult = sequence( [
369 openLink,
370 expression,
371 closeLink
372 ] );
373 if ( parsedResult !== null ) {
374 result = [ 'WLINK', parsedResult[1] ];
375 }
376 return result;
377 }
378
379 var templateName = transform(
380 // see $wgLegalTitleChars
381 // not allowing : due to the need to catch "PLURAL:$1"
382 makeRegexParser( /^[ !"$&'()*,.\/0-9;=?@A-Z\^_`a-z~\x80-\xFF+-]+/ ),
383 function( result ) { return result.toString(); }
384 );
385
386 function templateParam() {
387 var result = sequence( [
388 pipe,
389 nOrMore( 0, paramExpression )
390 ] );
391 if ( result === null ) {
392 return null;
393 }
394 var expr = result[1];
395 // use a "CONCAT" operator if there are multiple nodes, otherwise return the first node, raw.
396 return expr.length > 1 ? [ "CONCAT" ].concat( expr ) : expr[0];
397 }
398
399 var pipe = makeStringParser( '|' );
400
401 function templateWithReplacement() {
402 var result = sequence( [
403 templateName,
404 colon,
405 replacement
406 ] );
407 return result === null ? null : [ result[0], result[2] ];
408 }
409
410 var colon = makeStringParser(':');
411
412 var templateContents = choice( [
413 function() {
414 var res = sequence( [
415 templateWithReplacement,
416 nOrMore( 0, templateParam )
417 ] );
418 return res === null ? null : res[0].concat( res[1] );
419 },
420 function() {
421 var res = sequence( [
422 templateName,
423 nOrMore( 0, templateParam )
424 ] );
425 if ( res === null ) {
426 return null;
427 }
428 return [ res[0] ].concat( res[1] );
429 }
430 ] );
431
432 var openTemplate = makeStringParser('{{');
433 var closeTemplate = makeStringParser('}}');
434
435 function template() {
436 var result = sequence( [
437 openTemplate,
438 templateContents,
439 closeTemplate
440 ] );
441 return result === null ? null : result[1];
442 }
443
444 var nonWhitespaceExpression = choice( [
445 template,
446 link,
447 extlink,
448 replacement,
449 literalWithoutSpace
450 ] );
451
452 var paramExpression = choice( [
453 template,
454 link,
455 extlink,
456 replacement,
457 literalWithoutBar
458 ] );
459
460 var expression = choice( [
461 template,
462 link,
463 extlink,
464 replacement,
465 literal
466 ] );
467
468 function start() {
469 var result = nOrMore( 0, expression )();
470 if ( result === null ) {
471 return null;
472 }
473 return [ "CONCAT" ].concat( result );
474 }
475
476 // everything above this point is supposed to be stateless/static, but
477 // I am deferring the work of turning it into prototypes & objects. It's quite fast enough
478
479 // finally let's do some actual work...
480
481 var result = start();
482
483 /*
484 * For success, the p must have gotten to the end of the input
485 * and returned a non-null.
486 * n.b. This is part of language infrastructure, so we do not throw an internationalizable message.
487 */
488 if (result === null || pos !== input.length) {
489 throw new Error( "Parse error at position " + pos.toString() + " in input: " + input );
490 }
491 return result;
492 }
493
494 };
495
496 /**
497 * htmlEmitter - object which primarily exists to emit HTML from parser ASTs
498 */
499 mw.jqueryMsg.htmlEmitter = function( language, magic ) {
500 this.language = language;
501 var _this = this;
502
503 $.each( magic, function( key, val ) {
504 _this[ key.toLowerCase() ] = function() { return val; };
505 } );
506
507 /**
508 * (We put this method definition here, and not in prototype, to make sure it's not overwritten by any magic.)
509 * Walk entire node structure, applying replacements and template functions when appropriate
510 * @param {Mixed} abstract syntax tree (top node or subnode)
511 * @param {Array} replacements for $1, $2, ... $n
512 * @return {Mixed} single-string node or array of nodes suitable for jQuery appending
513 */
514 this.emit = function( node, replacements ) {
515 var ret = null;
516 var _this = this;
517 switch( typeof node ) {
518 case 'string':
519 case 'number':
520 ret = node;
521 break;
522 case 'object': // node is an array of nodes
523 var subnodes = $.map( node.slice( 1 ), function( n ) {
524 return _this.emit( n, replacements );
525 } );
526 var operation = node[0].toLowerCase();
527 if ( typeof _this[operation] === 'function' ) {
528 ret = _this[ operation ]( subnodes, replacements );
529 } else {
530 throw new Error( 'unknown operation "' + operation + '"' );
531 }
532 break;
533 case 'undefined':
534 // Parsing the empty string (as an entire expression, or as a paramExpression in a template) results in undefined
535 // Perhaps a more clever parser can detect this, and return the empty string? Or is that useful information?
536 // The logical thing is probably to return the empty string here when we encounter undefined.
537 ret = '';
538 break;
539 default:
540 throw new Error( 'unexpected type in AST: ' + typeof node );
541 }
542 return ret;
543 };
544
545 };
546
547 // For everything in input that follows double-open-curly braces, there should be an equivalent parser
548 // function. For instance {{PLURAL ... }} will be processed by 'plural'.
549 // If you have 'magic words' then configure the parser to have them upon creation.
550 //
551 // An emitter method takes the parent node, the array of subnodes and the array of replacements (the values that $1, $2... should translate to).
552 // Note: all such functions must be pure, with the exception of referring to other pure functions via this.language (convertPlural and so on)
553 mw.jqueryMsg.htmlEmitter.prototype = {
554
555 /**
556 * Parsing has been applied depth-first we can assume that all nodes here are single nodes
557 * Must return a single node to parents -- a jQuery with synthetic span
558 * However, unwrap any other synthetic spans in our children and pass them upwards
559 * @param {Array} nodes - mixed, some single nodes, some arrays of nodes
560 * @return {jQuery}
561 */
562 concat: function( nodes ) {
563 var span = $( '<span>' ).addClass( 'mediaWiki_htmlEmitter' );
564 $.each( nodes, function( i, node ) {
565 if ( node instanceof jQuery && node.hasClass( 'mediaWiki_htmlEmitter' ) ) {
566 $.each( node.contents(), function( j, childNode ) {
567 span.append( childNode );
568 } );
569 } else {
570 // strings, integers, anything else
571 span.append( node );
572 }
573 } );
574 return span;
575 },
576
577 /**
578 * Return replacement of correct index, or string if unavailable.
579 * Note that we expect the parsed parameter to be zero-based. i.e. $1 should have become [ 0 ].
580 * if the specified parameter is not found return the same string
581 * (e.g. "$99" -> parameter 98 -> not found -> return "$99" )
582 * TODO throw error if nodes.length > 1 ?
583 * @param {Array} of one element, integer, n >= 0
584 * @return {String} replacement
585 */
586 replace: function( nodes, replacements ) {
587 var index = parseInt( nodes[0], 10 );
588 return index < replacements.length ? replacements[index] : '$' + ( index + 1 );
589 },
590
591 /**
592 * Transform wiki-link
593 * TODO unimplemented
594 */
595 wlink: function( nodes ) {
596 return "unimplemented";
597 },
598
599 /**
600 * Transform parsed structure into external link
601 * If the href is a jQuery object, treat it as "enclosing" the link text.
602 * ... function, treat it as the click handler
603 * ... string, treat it as a URI
604 * TODO: throw an error if nodes.length > 2 ?
605 * @param {Array} of two elements, {jQuery|Function|String} and {String}
606 * @return {jQuery}
607 */
608 link: function( nodes ) {
609 var arg = nodes[0];
610 var contents = nodes[1];
611 var $el;
612 if ( arg instanceof jQuery ) {
613 $el = arg;
614 } else {
615 $el = $( '<a>' );
616 if ( typeof arg === 'function' ) {
617 $el.click( arg ).attr( 'href', '#' );
618 } else {
619 $el.attr( 'href', arg.toString() );
620 }
621 }
622 $el.append( contents );
623 return $el;
624 },
625
626 /**
627 * Transform parsed structure into pluralization
628 * n.b. The first node may be a non-integer (for instance, a string representing an Arabic number).
629 * So convert it back with the current language's convertNumber.
630 * @param {Array} of nodes, [ {String|Number}, {String}, {String} ... ]
631 * @return {String} selected pluralized form according to current language
632 */
633 plural: function( nodes ) {
634 var count = parseInt( this.language.convertNumber( nodes[0], true ), 10 );
635 var forms = nodes.slice(1);
636 return forms.length ? this.language.convertPlural( count, forms ) : '';
637 },
638
639 /**
640 * Transform parsed structure into gender
641 * Usage {{gender:[gender| mw.user object ] | masculine|feminine|neutral}}.
642 * @param {Array} of nodes, [ {String|mw.User}, {String}, {String} , {String} ]
643 * @return {String} selected gender form according to current language
644 */
645 gender: function( nodes ) {
646 var gender;
647 if ( nodes[0] && nodes[0].options instanceof mw.Map ){
648 gender = nodes[0].options.get( 'gender' );
649 } else {
650 gender = nodes[0];
651 }
652 var forms = nodes.slice(1);
653 return this.language.gender( gender, forms );
654 }
655
656 };
657
658 // TODO figure out a way to make magic work with common globals like wgSiteName, without requiring init from library users...
659 // var options = { magic: { 'SITENAME' : mw.config.get( 'wgSiteName' ) } };
660
661 // deprecated! don't rely on gM existing.
662 // the window.gM ought not to be required - or if required, not required here. But moving it to extensions breaks it (?!)
663 // Need to fix plugin so it could do attributes as well, then will be okay to remove this.
664 window.gM = mw.jqueryMsg.getMessageFunction();
665
666 $.fn.msg = mw.jqueryMsg.getPlugin();
667
668 // Replace the default message parser with jqueryMsg
669 var oldParser = mw.Message.prototype.parser;
670 mw.Message.prototype.parser = function() {
671 // TODO: should we cache the message function so we don't create a new one every time? Benchmark this maybe?
672 // Caching is somewhat problematic, because we do need different message functions for different maps, so
673 // we'd have to cache the parser as a member of this.map, which sounds a bit ugly.
674
675 // Do not use mw.jqueryMsg unless required
676 if ( this.map.get( this.key ).indexOf( '{{' ) < 0 ) {
677 // Fall back to mw.msg's simple parser
678 return oldParser.apply( this );
679 }
680
681 var messageFunction = mw.jqueryMsg.getMessageFunction( { 'messages': this.map } );
682 return messageFunction( this.key, this.parameters );
683 };
684
685 } )( mediaWiki, jQuery );