346ab33e9c4da9a753056995105c2020b724d1bf
2 * @author Neil Kandalgaonkar, 2010
3 * @author Timo Tijhof, 2011-2013
11 * Parse titles into an object struture. Note that when using the constructor
12 * directly, passing invalid titles will result in an exception. Use #newFromText to use the
13 * logic directly and get null for invalid titles which is easier to work with.
16 * @param {string} title Title of the page. If no second argument given,
17 * this will be searched for a namespace
18 * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
19 * @throws {Error} When the title is invalid
21 function Title( title
, namespace ) {
22 var parsed
= parse( title
, namespace );
24 throw new Error( 'Unable to parse title' );
27 this.namespace = parsed
.namespace;
28 this.title
= parsed
.title
;
29 this.ext
= parsed
.ext
;
30 this.fragment
= parsed
.fragment
;
56 * @property NS_SPECIAL
61 * Get the namespace id from a namespace name (either from the localized, canonical or alias
64 * Example: On a German wiki this would return 6 for any of 'File', 'Datei', 'Image' or
69 * @method getNsIdByName
70 * @param {string} ns Namespace name (case insensitive, leading/trailing space ignored)
71 * @return {number|boolean} Namespace id or boolean false
73 getNsIdByName = function ( ns
) {
76 // Don't cast non-strings to strings, because null or undefined should not result in
77 // returning the id of a potential namespace called "Null:" (e.g. on null.example.org/wiki)
78 // Also, toLowerCase throws exception on null/undefined, because it is a String method.
79 if ( typeof ns
!== 'string' ) {
82 ns
= ns
.toLowerCase();
83 id
= mw
.config
.get( 'wgNamespaceIds' )[ns
];
84 if ( id
=== undefined ) {
90 rUnderscoreTrim
= /^_+|_+$/g,
92 rSplit
= /^(.+?)_*:_*(.*)$/,
94 // See Title.php#getTitleInvalidRegex
95 rInvalid
= new RegExp(
96 '[^' + mw
.config
.get( 'wgLegalTitleChars' ) + ']' +
97 // URL percent encoding sequences interfere with the ability
98 // to round-trip titles -- you can't link to them consistently.
100 // XML/HTML character references produce similar issues.
101 '|&[A-Za-z0-9\u0080-\uFFFF]+;' +
107 * Internal helper for #constructor and #newFromtext.
109 * Based on Title.php#secureAndSplit
114 * @param {string} title
115 * @param {number} [defaultNamespace=NS_MAIN]
116 * @return {Object|boolean}
118 parse = function ( title
, defaultNamespace
) {
119 var namespace, m
, id
, i
, fragment
, ext
;
121 namespace = defaultNamespace
=== undefined ? NS_MAIN
: defaultNamespace
;
124 // Normalise whitespace to underscores and remove duplicates
125 .replace( /[ _\s]+/g, '_' )
127 .replace( rUnderscoreTrim
, '' );
129 if ( title
=== '' ) {
133 // Process initial colon
134 if ( title
.charAt( 0 ) === ':' ) {
135 // Initial colon means main namespace instead of specified default
141 .replace( rUnderscoreTrim
, '' );
144 // Process namespace prefix (if any)
145 m
= title
.match( rSplit
);
147 id
= getNsIdByName( m
[1] );
148 if ( id
!== false ) {
149 // Ordinary namespace
153 // For Talk:X pages, make sure X has no "namespace" prefix
154 if ( namespace === NS_TALK
&& ( m
= title
.match( rSplit
) ) ) {
155 // Disallow titles like Talk:File:x (subject should roundtrip: talk:file:x -> file:x -> file_talk:x)
156 if ( getNsIdByName( m
[1] ) !== false ) {
164 i
= title
.indexOf( '#' );
169 // Get segment starting after the hash
172 // NB: Must not be trimmed ("Example#_foo" is not the same as "Example#foo")
173 .replace( /_
/g
, ' ' );
178 // Trim underscores, again (strips "_" from "bar" in "Foo_bar_#quux")
179 .replace( rUnderscoreTrim
, '' );
183 // Reject illegal characters
184 if ( title
.match( rInvalid
) ) {
188 // Disallow titles that browsers or servers might resolve as directory navigation
190 title
.indexOf( '.' ) !== -1 && (
191 title
=== '.' || title
=== '..' ||
192 title
.indexOf( './' ) === 0 ||
193 title
.indexOf( '../' ) === 0 ||
194 title
.indexOf( '/./' ) !== -1 ||
195 title
.indexOf( '/../' ) !== -1 ||
196 title
.substr( -2 ) === '/.' ||
197 title
.substr( -3 ) === '/..'
203 // Disallow magic tilde sequence
204 if ( title
.indexOf( '~~~' ) !== -1 ) {
208 // Disallow titles exceeding the 255 byte size limit (size of underlying database field)
209 // Except for special pages, e.g. [[Special:Block/Long name]]
210 // Note: The PHP implementation also asserts that even in NS_SPECIAL, the title should
211 // be less than 512 bytes.
212 if ( namespace !== NS_SPECIAL
&& $.byteLength( title
) > 255 ) {
216 // Can't make a link to a namespace alone.
217 if ( title
=== '' && namespace !== NS_MAIN
) {
221 // Any remaining initial :s are illegal.
222 if ( title
.charAt( 0 ) === ':' ) {
226 // For backwards-compatibility with old mw.Title, we separate the extension from the
227 // rest of the title.
228 i
= title
.lastIndexOf( '.' );
229 if ( i
=== -1 || title
.length
<= i
+ 1 ) {
230 // Extensions are the non-empty segment after the last dot
233 ext
= title
.substr( i
+ 1 );
234 title
= title
.substr( 0, i
);
238 namespace: namespace,
246 * Convert db-key to readable text.
254 text = function ( s
) {
255 if ( s
!== null && s
!== undefined ) {
256 return s
.replace( /_
/g
, ' ' );
262 // Polyfill for ES5 Object.create
263 createObject
= Object
.create
|| ( function () {
264 return function ( o
) {
266 if ( o
!== Object( o
) ) {
267 throw new Error( 'Cannot inherit from a non-object' );
278 * Constructor for Title objects with a null return instead of an exception for invalid titles.
282 * @param {string} title
283 * @param {number} [namespace=NS_MAIN] Default namespace
284 * @return {mw.Title|null} A valid Title object or null if the title is invalid
286 Title
.newFromText = function ( title
, namespace ) {
287 var t
, parsed
= parse( title
, namespace );
292 t
= createObject( Title
.prototype );
293 t
.namespace = parsed
.namespace;
294 t
.title
= parsed
.title
;
296 t
.fragment
= parsed
.fragment
;
302 * Get the file title from an image element
304 * var title = mw.Title.newFromImg( $( 'img:first' ) );
307 * @param {HTMLImageElement|jQuery} img The image to use as a base.
308 * @return {mw.Title|null} The file title - null if unsuccessful.
310 Title
.newFromImg = function ( img
) {
311 var matches
, i
, regex
, src
, decodedSrc
,
313 // thumb.php-generated thumbnails
314 thumbPhpRegex
= /thumb\.php/,
318 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)\/[0-9]+px-\1[^\s\/]*$/,
320 // Thumbnails in non-hashed upload directories
321 /\/([^\s\/]+)\/[0-9]+px-\1[^\s\/]*$/,
324 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)$/,
326 // Full-size images in non-hashed upload directories
330 recount
= regexes
.length
;
332 img
= img
.jquery
? img
.get( 0 ) : img
;
336 matches
= src
.match( thumbPhpRegex
);
339 return mw
.Title
.newFromText( 'File:' + mw
.util
.getParamValue( 'f', src
) );
342 decodedSrc
= decodeURIComponent( src
);
344 for ( i
= 0; i
< recount
; i
++ ) {
346 matches
= decodedSrc
.match( regex
);
348 if ( matches
&& matches
[1] ) {
349 return mw
.Title
.newFromText( 'File:' + matches
[1] );
357 * Whether this title exists on the wiki.
360 * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title
361 * @return {boolean|null} Boolean if the information is available, otherwise null
363 Title
.exists = function ( title
) {
365 type
= $.type( title
),
366 obj
= Title
.exist
.pages
;
368 if ( type
=== 'string' ) {
370 } else if ( type
=== 'object' && title
instanceof Title
) {
371 match
= obj
[title
.toString()];
373 throw new Error( 'mw.Title.exists: title must be a string or an instance of Title' );
376 if ( typeof match
=== 'boolean' ) {
385 * Boolean true value indicates page does exist.
388 * @property {Object} exist.pages Keyed by PrefixedDb title.
393 * Example to declare existing titles:
394 * Title.exist.set(['User:John_Doe', ...]);
395 * Eample to declare titles nonexistent:
396 * Title.exist.set(['File:Foo_bar.jpg', ...], false);
399 * @property exist.set
400 * @param {string|Array} titles Title(s) in strict prefixedDb title form
401 * @param {boolean} [state=true] State of the given titles
404 set: function ( titles
, state
) {
405 titles
= $.isArray( titles
) ? titles
: [titles
];
406 state
= state
=== undefined ? true : !!state
;
407 var pages
= this.pages
, i
, len
= titles
.length
;
408 for ( i
= 0; i
< len
; i
++ ) {
409 pages
[ titles
[i
] ] = state
;
421 * Get the namespace number
423 * Example: 6 for "File:Example_image.svg".
427 getNamespaceId: function () {
428 return this.namespace;
432 * Get the namespace prefix (in the content language)
434 * Example: "File:" for "File:Example_image.svg".
435 * In #NS_MAIN this is '', otherwise namespace name plus ':'
439 getNamespacePrefix: function () {
440 return this.namespace === NS_MAIN
?
442 ( mw
.config
.get( 'wgFormattedNamespaces' )[ this.namespace ].replace( / /g
, '_' ) + ':' );
446 * Get the page name without extension or namespace prefix
448 * Example: "Example_image" for "File:Example_image.svg".
450 * For the page title (full page name without namespace prefix), see #getMain.
454 getName: function () {
455 if ( $.inArray( this.namespace, mw
.config
.get( 'wgCaseSensitiveNamespaces' ) ) !== -1 ) {
458 return $.ucFirst( this.title
);
463 * Get the page name (transformed by #text)
465 * Example: "Example image" for "File:Example_image.svg".
467 * For the page title (full page name without namespace prefix), see #getMainText.
471 getNameText: function () {
472 return text( this.getName() );
476 * Get the extension of the page name (if any)
478 * @return {string|null} Name extension or null if there is none
480 getExtension: function () {
485 * Shortcut for appendable string to form the main page name.
487 * Returns a string like ".json", or "" if no extension.
491 getDotExtension: function () {
492 return this.ext
=== null ? '' : '.' + this.ext
;
496 * Get the main page name (transformed by #text)
498 * Example: "Example_image.svg" for "File:Example_image.svg".
502 getMain: function () {
503 return this.getName() + this.getDotExtension();
507 * Get the main page name (transformed by #text)
509 * Example: "Example image.svg" for "File:Example_image.svg".
513 getMainText: function () {
514 return text( this.getMain() );
518 * Get the full page name
520 * Eaxample: "File:Example_image.svg".
521 * Most useful for API calls, anything that must identify the "title".
525 getPrefixedDb: function () {
526 return this.getNamespacePrefix() + this.getMain();
530 * Get the full page name (transformed by #text)
532 * Example: "File:Example image.svg" for "File:Example_image.svg".
536 getPrefixedText: function () {
537 return text( this.getPrefixedDb() );
541 * Get the fragment (if any).
543 * Note that this method (by design) does not include the hash character and
544 * the value is not url encoded.
546 * @return {string|null}
548 getFragment: function () {
549 return this.fragment
;
553 * Get the URL to this title
555 * @see mw.util#wikiGetlink
558 getUrl: function () {
559 return mw
.util
.wikiGetlink( this.toString() );
563 * Whether this title exists on the wiki.
565 * @see #static-method-exists
566 * @return {boolean|null} Boolean if the information is available, otherwise null
568 exists: function () {
569 return Title
.exists( this );
574 * @alias #getPrefixedDb
577 Title
.prototype.toString
= Title
.prototype.getPrefixedDb
;
581 * @alias #getPrefixedText
584 Title
.prototype.toText
= Title
.prototype.getPrefixedText
;
589 }( mediaWiki
, jQuery
) );