MediaWiki:Gadget-libLua.js
/* ___________________________________________________________________________
* | |
* | === WARNING: GLOBAL GADGET FILE === |
* | Changes to this page affect many users. |
* | Please discuss changes on the talk page or on Wikipedia_talk:Gadget |
* | before editing. |
* |___________________________________________________________________________|
*
*
* libLua provides functions for interacting with Lua modules from JavaScript.
*
*
* === USAGE ===
*
* The library should be loaded as a MediaWiki gadget, using mw.loader.load,
* mw.loader.using, or similar. The name of the gadget is
* "ext.gadget.libLua". Once the gadget is loaded, you can access its
* functions from mw.libs.lua.
* functions can be found in the JSDoc comment blocks in the library code. For
* example:
*
* // Call p.main("foo", "bar") in Module:Example
* mw.loader.using( [ 'ext.gadget.libLua' ], function () {
* mw.libs.lua.call( {
* module: 'Example',
* func: 'main',
* args: [ 'foo', 'bar' ]
* } ).then( function ( result ) {
* // Do something with the result
* } );
* } );
*
*
* === LICENCE ===
*
* Author: Mr. Stradivarius
* Licence: MIT
*
* The MIT License (MIT)
*
* Copyright (c) 2016 Mr. Stradivarius
*
* Permission is hereby granted, free of charge, to any person obtaining a copy
* of this software and associated documentation files (the "Software"), to deal
* in the Software without restriction, including without limitation the rights
* to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
* copies of the Software, and to permit persons to whom the Software is
* furnished to do so, subject to the following conditions:
*
* The above copyright notice and this permission notice shall be included in
* all copies or substantial portions of the Software.
*
* THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
* IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
* FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
* AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
* LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
* OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
* THE SOFTWARE.
*/
( function ( $, mw, undefined ) {
'use strict';
/**
* Encode a string for including in a Lua question.
* At the moment this is just a wrapper for JSON.stringify, as that does
* what we need. However, encoding a Lua string is conceptually different
* from encoding JSON, so we use different function names for the two tasks.
* This will also make it easier to update the code in the future, if
* necessary.
* @private
*/
function makeLuaString( s ) {
return JSON.stringify( s );
}
/**
* Make a Lua question string from a module name, a function name and an
* optional args array.
* @private
*/
function makeQuestion( module, func, args ) {
var escapedModule = makeLuaString( 'Module:' + module ),
escapedFunc = makeLuaString( func ),
json, escapedJson, argString;
if ( args ) {
json = JSON.stringify( args );
escapedJson = makeLuaString( json );
argString = 'unpack(mw.text.jsonDecode(' + escapedJson + '))';
} else {
argString = '';
}
return '=require(' + escapedModule + ')[' + escapedFunc + '](' + argString + ')';
}
/**
* Reject a deferred object with the specified error code and error message.
* If no deferred object is supplied with the third parameter, a new one is
* created. We use this particular format for the error objects as it is the
* same one used by the MediaWiki API, and so clients will only have to
* worry about errors being formatted in one way.
* @private
*/
function rejectDeferred( code, msg, deferred ) {
if ( !deferred ) {
deferred = $.Deferred();
}
return deferred.reject(
code,
{ error: {
code: code,
info: msg
} }
);
}
mw.libs.lua = {
/**
* Call a function in a Lua module. The function call is made
* asynchronously through the MediaWiki Action API, and its result is
* wrapped in a jQuery promise.
*
* @param {Object} options
*
* @param {string} options.module - The name of the module to load.
* (Don't use a "Module:" prefix.)
*
* @param {string} options.func - The name of the function to call.
* Only strings are accepted as function names.
*
* @param {*[]} [options.args] - An array of arguments to pass to the
* function. These must be serializable as JSON. The arguments will be
* unpacked when passed to the function; when calling a function "func",
* an args array of ["foo", "bar", "baz"] will be called as
* func("foo", "bar", "baz"). There are limitations in what can be
* decoded from JSON in Lua: for example, keys may be dropped from
* arrays containing null values. See
* https://www.mediawiki.org/wiki/Extension:Scribunto/Lua_reference_manual#mw.text.jsonDecode
* for more details. For this reason, calls like func('foo', nil, 'bar')
* cannot be made directly. To work around this you can define an
* intermediary function in a Lua module that calls the desired function
* indirectly, and then call that function from this library instead.
*
* @param {('string'|'json')} [options.format=string] - The expected
* return format. If this is "string" or undefined, then the return value
* will be a string. (If the Lua function call returns a non-string value
* it will be converted to a string, and if the function call returns
* multiple values then they will be converted to strings and
* concatenated with tabs as separators.) If this is "json", then the
* return string from the function call is assumed to be JSON, and is
* converted to a JavaScript object using JSON.parse. If the return
* string is not valid JSON, the promise returned from the function is
* rejected, but no error is thrown.
*
* @param {mw.Api} [options.api] - An mw.Api object to use for API
* calls. If this is not specified, a new mw.Api object using default
* values is created.
*
* @return {$.Promise}
* A jQuery Promise that is resolved with the result of the function
* call.
*
@example
// Load the gadget
mw.loader.using( 'ext.gadget.libLua', function () {
// Call p.main( "foo", "bar", "baz" ) in Module:Example.
mw.libs.lua.call( {
"module": "Example",
"func": "main",
"args": [ "foo", "bar", "baz" ]
} ).done( function( resultString ) {
doSomething( resultString );
} );
} );
*
@example
// Load the gadget
mw.loader.using( 'ext.gadget.libLua', function () {
// Call p.getJson( "foo" ) in Module:Example.
mw.libs.lua.call( {
"format": "json",
"module": "Example",
"func": "getJson",
"args": [ "foo" ]
} ).done( function( data ) {
doSomething( data.bar.baz );
} );
} );
*
*/
call: function ( options ) {
// Deal with bad arguments
if ( !( options instanceof Object ) ) {
return rejectDeferred(
'liblua-call-options-type-error',
"type error in arg #1 to 'call' (object expected)"
);
} else if ( typeof options.module !== 'string' ) {
return rejectDeferred(
'liblua-call-module-type-error',
'type error in options.module (string expected)'
);
} else if ( typeof options.func !== 'string' ) {
return rejectDeferred(
'liblua-call-func-type-error',
'type error in options.func (string expected)'
);
} else if ( options.args !== undefined && !$.isArray( options.args ) ) {
return rejectDeferred(
'liblua-call-invalid-args',
'options.args was defined but was not an array'
);
} else if ( options.format !== undefined
&& options.format !== 'json'
&& options.format !== 'string' ) {
return rejectDeferred(
'liblua-call-format-type-error',
"invalid format specified (must be 'json', 'string' or undefined)"
);
} else if ( options.api !== undefined && !( options.api instanceof mw.Api ) ) {
return rejectDeferred(
'liblua-call-invalid-api-object',
'options.api is not a valid mw.Api object.'
);
}
// Generate a new API object if we weren't passed one.
var api = options.api || new mw.Api();
// Make the API call.
// The title field in scribunto-console doesn't seem to allow us to
// use the p variable to load the module content, so set it to a
// dummy value with blank content and load the module in the
// question instead.
return api.postWithToken( 'csrf', {
action: 'scribunto-console',
format: 'json',
title: 'Example',
content: '',
question: makeQuestion( options.module, options.func, options.args ),
clear: true
} ).then( function ( obj ) {
// Wrap the API query in a new jQuery Deferred object so that
// we can reject API results that are invalid Lua but not
// treated as errors by the API.
return $.Deferred( function ( deferred ) {
// Deal with any errors from the API or from Lua.
if ( obj.type === 'error' ) {
// Lua command failed but API call succeeded
return rejectDeferred(
obj.messagename,
obj.message,
deferred
);
} else if ( obj.error ) {
// API call failed
return deferred.reject( obj.error.code, obj );
} else if ( obj.type !== 'normal' ) {
// Unknown API response
return rejectDeferred(
'liblua-call-unknown-api-response',
'Unknown API response',
deferred
);
}
var result = obj['return'];
// Try to parse JSON if options.format equals 'json'
if ( options.format == 'json' ) {
try {
result = JSON.parse( result );
} catch ( e ) {
if ( e instanceof SyntaxError ) {
return rejectDeferred(
'liblua-call-json-syntax-error',
'The Lua function call returned invalid JSON: ' + e.message,
deferred
);
} else {
return rejectDeferred(
'liblua-call-json-unexpected-error',
'An unexpected error occurred while trying to ' +
'parse the JSON returned from the Lua function call',
deferred
);
}
}
}
return deferred.resolve( result );
} ).promise();
} );
}
};
} )( jQuery, mediaWiki );