2 * @author Neil Kandalgaonkar, 2010
3 * @author Timo Tijhof, 2011-2013
7 /* eslint-disable no-use-before-define */
11 * Parse titles into an object structure. 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.
18 * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace
19 * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior,
20 * use #makeTitle. Compare:
22 * new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
23 * mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
24 * mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText(); // => 'Template:Foo'
26 * new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo'
27 * mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo'
28 * mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText(); // => 'Template:Category:Foo'
30 * new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
31 * mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
32 * mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText(); // => 'Template:Template:Foo'
35 * @param {string} title Title of the page. If no second argument given,
36 * this will be searched for a namespace
37 * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
38 * @throws {Error} When the title is invalid
40 function Title( title
, namespace ) {
41 var parsed
= parse( title
, namespace );
43 throw new Error( 'Unable to parse title' );
46 this.namespace = parsed
.namespace;
47 this.title
= parsed
.title
;
48 this.ext
= parsed
.ext
;
49 this.fragment
= parsed
.fragment
;
56 // eslint-disable-next-line vars-on-top
58 namespaceIds
= mw
.config
.get( 'wgNamespaceIds' ),
65 NS_MAIN
= namespaceIds
[ '' ],
72 NS_TALK
= namespaceIds
.talk
,
77 * @property NS_SPECIAL
79 NS_SPECIAL
= namespaceIds
.special
,
86 NS_MEDIA
= namespaceIds
.media
,
93 NS_FILE
= namespaceIds
.file
,
98 * @property FILENAME_MAX_BYTES
100 FILENAME_MAX_BYTES
= 240,
105 * @property TITLE_MAX_BYTES
107 TITLE_MAX_BYTES
= 255,
110 * Get the namespace id from a namespace name (either from the localized, canonical or alias
113 * Example: On a German wiki this would return 6 for any of 'File', 'Datei', 'Image' or
118 * @method getNsIdByName
119 * @param {string} ns Namespace name (case insensitive, leading/trailing space ignored)
120 * @return {number|boolean} Namespace id or boolean false
122 getNsIdByName = function ( ns
) {
125 // Don't cast non-strings to strings, because null or undefined should not result in
126 // returning the id of a potential namespace called "Null:" (e.g. on null.example.org/wiki)
127 // Also, toLowerCase throws exception on null/undefined, because it is a String method.
128 if ( typeof ns
!== 'string' ) {
131 // TODO: Should just use local var namespaceIds here but it
132 // breaks test which modify the config
133 id
= mw
.config
.get( 'wgNamespaceIds' )[ ns
.toLowerCase() ];
134 if ( id
=== undefined ) {
142 * @method getNamespacePrefix_
143 * @param {number} namespace
146 getNamespacePrefix = function ( namespace ) {
147 return namespace === NS_MAIN
?
149 ( mw
.config
.get( 'wgFormattedNamespaces' )[ namespace ].replace( / /g
, '_' ) + ':' );
152 rUnderscoreTrim
= /^_+|_+$/g,
154 rSplit
= /^(.+?)_*:_*(.*)$/,
156 // See MediaWikiTitleCodec.php#getTitleInvalidRegex
157 rInvalid
= new RegExp(
158 '[^' + mw
.config
.get( 'wgLegalTitleChars' ) + ']' +
159 // URL percent encoding sequences interfere with the ability
160 // to round-trip titles -- you can't link to them consistently.
162 // XML/HTML character references produce similar issues.
163 '|&[A-Za-z0-9\u0080-\uFFFF]+;' +
168 // From MediaWikiTitleCodec::splitTitleString() in PHP
169 // Note that this is not equivalent to /\s/, e.g. underscore is included, tab is not included.
170 rWhitespace
= /[ _\u00A0\u1680\u180E\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]+/g,
172 // From MediaWikiTitleCodec::splitTitleString() in PHP
173 rUnicodeBidi
= /[\u200E\u200F\u202A-\u202E]/g,
176 * Slightly modified from Flinfo. Credit goes to Lupo and Flominator.
179 * @property sanitationRules
188 // control characters
190 // eslint-disable-next-line no-control-regex
191 pattern
: /[\x00-\x1f\x7f]/g,
195 // URL encoding (possibly)
197 pattern
: /%([0-9A-Fa-f]{2})/g,
201 // HTML-character-entities
203 pattern
: /&(([A-Za-z0-9\x80-\xff]+|#[0-9]+|#x[0-9A-Fa-f]+);)/g,
207 // slash, colon (not supported by file systems like NTFS/Windows, Mac OS 9 [:], ext4 [/])
209 pattern
: new RegExp( '[' + mw
.config
.get( 'wgIllegalFileChars', '' ) + ']', 'g' ),
213 // brackets, greater than
219 // brackets, lower than
225 // everything that wasn't covered yet
227 pattern
: new RegExp( rInvalid
.source
, 'g' ),
231 // directory structures
233 pattern
: /^(\.|\.\.|\.\/.*|\.\.\/.*|.*\/\.\/.*|.*\/\.\.\/.*|.*\/\.|.*\/\.\.)$/g,
240 * Internal helper for #constructor and #newFromText.
242 * Based on Title.php#secureAndSplit
247 * @param {string} title
248 * @param {number} [defaultNamespace=NS_MAIN]
249 * @return {Object|boolean}
251 parse = function ( title
, defaultNamespace
) {
252 var namespace, m
, id
, i
, fragment
, ext
;
254 namespace = defaultNamespace
=== undefined ? NS_MAIN
: defaultNamespace
;
257 // Strip Unicode bidi override characters
258 .replace( rUnicodeBidi
, '' )
259 // Normalise whitespace to underscores and remove duplicates
260 .replace( rWhitespace
, '_' )
262 .replace( rUnderscoreTrim
, '' );
264 // Process initial colon
265 if ( title
!== '' && title
[ 0 ] === ':' ) {
266 // Initial colon means main namespace instead of specified default
272 .replace( rUnderscoreTrim
, '' );
275 if ( title
=== '' ) {
279 // Process namespace prefix (if any)
280 m
= title
.match( rSplit
);
282 id
= getNsIdByName( m
[ 1 ] );
283 if ( id
!== false ) {
284 // Ordinary namespace
288 // For Talk:X pages, make sure X has no "namespace" prefix
289 if ( namespace === NS_TALK
&& ( m
= title
.match( rSplit
) ) ) {
290 // Disallow titles like Talk:File:x (subject should roundtrip: talk:file:x -> file:x -> file_talk:x)
291 if ( getNsIdByName( m
[ 1 ] ) !== false ) {
299 i
= title
.indexOf( '#' );
304 // Get segment starting after the hash
307 // NB: Must not be trimmed ("Example#_foo" is not the same as "Example#foo")
308 .replace( /_
/g
, ' ' );
313 // Trim underscores, again (strips "_" from "bar" in "Foo_bar_#quux")
314 .replace( rUnderscoreTrim
, '' );
317 // Reject illegal characters
318 if ( title
.match( rInvalid
) ) {
322 // Disallow titles that browsers or servers might resolve as directory navigation
324 title
.indexOf( '.' ) !== -1 && (
325 title
=== '.' || title
=== '..' ||
326 title
.indexOf( './' ) === 0 ||
327 title
.indexOf( '../' ) === 0 ||
328 title
.indexOf( '/./' ) !== -1 ||
329 title
.indexOf( '/../' ) !== -1 ||
330 title
.slice( -2 ) === '/.' ||
331 title
.slice( -3 ) === '/..'
337 // Disallow magic tilde sequence
338 if ( title
.indexOf( '~~~' ) !== -1 ) {
342 // Disallow titles exceeding the TITLE_MAX_BYTES byte size limit (size of underlying database field)
343 // Except for special pages, e.g. [[Special:Block/Long name]]
344 // Note: The PHP implementation also asserts that even in NS_SPECIAL, the title should
345 // be less than 512 bytes.
346 if ( namespace !== NS_SPECIAL
&& $.byteLength( title
) > TITLE_MAX_BYTES
) {
350 // Can't make a link to a namespace alone.
351 if ( title
=== '' && namespace !== NS_MAIN
) {
355 // Any remaining initial :s are illegal.
356 if ( title
[ 0 ] === ':' ) {
360 // For backwards-compatibility with old mw.Title, we separate the extension from the
361 // rest of the title.
362 i
= title
.lastIndexOf( '.' );
363 if ( i
=== -1 || title
.length
<= i
+ 1 ) {
364 // Extensions are the non-empty segment after the last dot
367 ext
= title
.slice( i
+ 1 );
368 title
= title
.slice( 0, i
);
372 namespace: namespace,
380 * Convert db-key to readable text.
388 text = function ( s
) {
389 if ( s
!== null && s
!== undefined ) {
390 return s
.replace( /_
/g
, ' ' );
397 * Sanitizes a string based on a rule set and a filter
403 * @param {Array} filter
406 sanitize = function ( s
, filter
) {
407 var i
, ruleLength
, rule
, m
, filterLength
,
408 rules
= sanitationRules
;
410 for ( i
= 0, ruleLength
= rules
.length
; i
< ruleLength
; ++i
) {
412 for ( m
= 0, filterLength
= filter
.length
; m
< filterLength
; ++m
) {
413 if ( rule
[ filter
[ m
] ] ) {
414 s
= s
.replace( rule
.pattern
, rule
.replace
);
422 * Cuts a string to a specific byte length, assuming UTF-8
423 * or less, if the last character is a multi-byte one
427 * @method trimToByteLength
429 * @param {number} length
432 trimToByteLength = function ( s
, length
) {
433 var byteLength
, chopOffChars
, chopOffBytes
;
435 // bytelength is always greater or equal to the length in characters
436 s
= s
.substr( 0, length
);
437 while ( ( byteLength
= $.byteLength( s
) ) > length
) {
438 // Calculate how many characters can be safely removed
439 // First, we need to know how many bytes the string exceeds the threshold
440 chopOffBytes
= byteLength
- length
;
441 // A character in UTF-8 is at most 4 bytes
442 // One character must be removed in any case because the
443 // string is too long
444 chopOffChars
= Math
.max( 1, Math
.floor( chopOffBytes
/ 4 ) );
445 s
= s
.substr( 0, s
.length
- chopOffChars
);
451 * Cuts a file name to a specific byte length
455 * @method trimFileNameToByteLength
456 * @param {string} name without extension
457 * @param {string} extension file extension
458 * @return {string} The full name, including extension
460 trimFileNameToByteLength = function ( name
, extension
) {
461 // There is a special byte limit for file names and ... remember the dot
462 return trimToByteLength( name
, FILENAME_MAX_BYTES
- extension
.length
- 1 ) + '.' + extension
;
465 // Polyfill for ES5 Object.create
466 createObject
= Object
.create
|| ( function () {
467 return function ( o
) {
469 if ( o
!== Object( o
) ) {
470 throw new Error( 'Cannot inherit from a non-object' );
480 * Constructor for Title objects with a null return instead of an exception for invalid titles.
482 * Note that `namespace` is the **default** namespace only, and can be overridden by a namespace
483 * prefix in `title`. If you do not want this behavior, use #makeTitle. See #constructor for
487 * @param {string} title
488 * @param {number} [namespace=NS_MAIN] Default namespace
489 * @return {mw.Title|null} A valid Title object or null if the title is invalid
491 Title
.newFromText = function ( title
, namespace ) {
492 var t
, parsed
= parse( title
, namespace );
497 t
= createObject( Title
.prototype );
498 t
.namespace = parsed
.namespace;
499 t
.title
= parsed
.title
;
501 t
.fragment
= parsed
.fragment
;
507 * Constructor for Title objects with predefined namespace.
509 * Unlike #newFromText or #constructor, this function doesn't allow the given `namespace` to be
510 * overridden by a namespace prefix in `title`. See #constructor for details about this behavior.
512 * The single exception to this is when `namespace` is 0, indicating the main namespace. The
513 * function behaves like #newFromText in that case.
516 * @param {number} namespace Namespace to use for the title
517 * @param {string} title
518 * @return {mw.Title|null} A valid Title object or null if the title is invalid
520 Title
.makeTitle = function ( namespace, title
) {
521 return mw
.Title
.newFromText( getNamespacePrefix( namespace ) + title
);
525 * Constructor for Title objects from user input altering that input to
526 * produce a title that MediaWiki will accept as legal
529 * @param {string} title
530 * @param {number} [defaultNamespace=NS_MAIN]
531 * If given, will used as default namespace for the given title.
532 * @param {Object} [options] additional options
533 * @param {boolean} [options.forUploading=true]
534 * Makes sure that a file is uploadable under the title returned.
535 * There are pages in the file namespace under which file upload is impossible.
536 * Automatically assumed if the title is created in the Media namespace.
537 * @return {mw.Title|null} A valid Title object or null if the input cannot be turned into a valid title
539 Title
.newFromUserInput = function ( title
, defaultNamespace
, options
) {
540 var namespace, m
, id
, ext
, parts
;
542 // defaultNamespace is optional; check whether options moves up
543 if ( arguments
.length
< 3 && $.type( defaultNamespace
) === 'object' ) {
544 options
= defaultNamespace
;
545 defaultNamespace
= undefined;
548 // merge options into defaults
549 options
= $.extend( {
553 namespace = defaultNamespace
=== undefined ? NS_MAIN
: defaultNamespace
;
555 // Normalise additional whitespace
556 title
= $.trim( title
.replace( /\s/g, ' ' ) );
558 // Process initial colon
559 if ( title
!== '' && title
[ 0 ] === ':' ) {
560 // Initial colon means main namespace instead of specified default
566 .replace( rUnderscoreTrim
, '' );
569 // Process namespace prefix (if any)
570 m
= title
.match( rSplit
);
572 id
= getNsIdByName( m
[ 1 ] );
573 if ( id
!== false ) {
574 // Ordinary namespace
581 namespace === NS_MEDIA
||
582 ( options
.forUploading
&& ( namespace === NS_FILE
) )
585 title
= sanitize( title
, [ 'generalRule', 'fileRule' ] );
587 // Operate on the file extension
588 // Although it is possible having spaces between the name and the ".ext" this isn't nice for
589 // operating systems hiding file extensions -> strip them later on
590 parts
= title
.split( '.' );
592 if ( parts
.length
> 1 ) {
594 // Get the last part, which is supposed to be the file extension
597 // Remove whitespace of the name part (that W/O extension)
598 title
= $.trim( parts
.join( '.' ) );
600 // Cut, if too long and append file extension
601 title
= trimFileNameToByteLength( title
, ext
);
605 // Missing file extension
606 title
= $.trim( parts
.join( '.' ) );
608 // Name has no file extension and a fallback wasn't provided either
613 title
= sanitize( title
, [ 'generalRule' ] );
615 // Cut titles exceeding the TITLE_MAX_BYTES byte size limit
616 // (size of underlying database field)
617 if ( namespace !== NS_SPECIAL
) {
618 title
= trimToByteLength( title
, TITLE_MAX_BYTES
);
622 // Any remaining initial :s are illegal.
623 title
= title
.replace( /^\:+/, '' );
625 return Title
.newFromText( title
, namespace );
629 * Sanitizes a file name as supplied by the user, originating in the user's file system
630 * so it is most likely a valid MediaWiki title and file name after processing.
631 * Returns null on fatal errors.
634 * @param {string} uncleanName The unclean file name including file extension but
636 * @return {mw.Title|null} A valid Title object or null if the title is invalid
638 Title
.newFromFileName = function ( uncleanName
) {
640 return Title
.newFromUserInput( 'File:' + uncleanName
, {
646 * Get the file title from an image element
648 * var title = mw.Title.newFromImg( $( 'img:first' ) );
651 * @param {HTMLElement|jQuery} img The image to use as a base
652 * @return {mw.Title|null} The file title or null if unsuccessful
654 Title
.newFromImg = function ( img
) {
655 var matches
, i
, regex
, src
, decodedSrc
,
657 // thumb.php-generated thumbnails
658 thumbPhpRegex
= /thumb\.php/,
661 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)\/[^\s\/]+-[^\s\/]*$/,
664 /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s\/]+)$/,
666 // Thumbnails in non-hashed upload directories
667 /\/([^\s\/]+)\/[^\s\/]+-(?:\1|thumbnail)[^\s\/]*$/,
669 // Full-size images in non-hashed upload directories
673 recount
= regexes
.length
;
675 src
= img
.jquery
? img
[ 0 ].src
: img
.src
;
677 matches
= src
.match( thumbPhpRegex
);
680 return mw
.Title
.newFromText( 'File:' + mw
.util
.getParamValue( 'f', src
) );
683 decodedSrc
= decodeURIComponent( src
);
685 for ( i
= 0; i
< recount
; i
++ ) {
686 regex
= regexes
[ i
];
687 matches
= decodedSrc
.match( regex
);
689 if ( matches
&& matches
[ 1 ] ) {
690 return mw
.Title
.newFromText( 'File:' + matches
[ 1 ] );
698 * Whether this title exists on the wiki.
701 * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title
702 * @return {boolean|null} Boolean if the information is available, otherwise null
704 Title
.exists = function ( title
) {
706 type
= $.type( title
),
707 obj
= Title
.exist
.pages
;
709 if ( type
=== 'string' ) {
710 match
= obj
[ title
];
711 } else if ( type
=== 'object' && title
instanceof Title
) {
712 match
= obj
[ title
.toString() ];
714 throw new Error( 'mw.Title.exists: title must be a string or an instance of Title' );
717 if ( typeof match
=== 'boolean' ) {
725 * Store page existence
728 * @property {Object} exist
729 * @property {Object} exist.pages Keyed by title. Boolean true value indicates page does exist.
731 * @property {Function} exist.set The setter function.
733 * Example to declare existing titles:
735 * Title.exist.set( ['User:John_Doe', ...] );
737 * Example to declare titles nonexistent:
739 * Title.exist.set( ['File:Foo_bar.jpg', ...], false );
741 * @property {string|Array} exist.set.titles Title(s) in strict prefixedDb title form
742 * @property {boolean} [exist.set.state=true] State of the given titles
748 set: function ( titles
, state
) {
752 titles
= $.isArray( titles
) ? titles
: [ titles
];
753 state
= state
=== undefined ? true : !!state
;
755 for ( i
= 0, len
= titles
.length
; i
< len
; i
++ ) {
756 pages
[ titles
[ i
] ] = state
;
763 * Normalize a file extension to the common form, making it lowercase and checking some synonyms,
764 * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded.
765 * Keep in sync with File::normalizeExtension() in PHP.
767 * @param {string} extension File extension (without the leading dot)
768 * @return {string} File extension in canonical form
770 Title
.normalizeExtension = function ( extension
) {
772 lower
= extension
.toLowerCase(),
780 if ( squish
.hasOwnProperty( lower
) ) {
781 return squish
[ lower
];
782 } else if ( /^[0-9a-z]+$/.test( lower
) ) {
795 * Get the namespace number
797 * Example: 6 for "File:Example_image.svg".
801 getNamespaceId: function () {
802 return this.namespace;
806 * Get the namespace prefix (in the content language)
808 * Example: "File:" for "File:Example_image.svg".
809 * In #NS_MAIN this is '', otherwise namespace name plus ':'
813 getNamespacePrefix: function () {
814 return getNamespacePrefix( this.namespace );
818 * Get the page name without extension or namespace prefix
820 * Example: "Example_image" for "File:Example_image.svg".
822 * For the page title (full page name without namespace prefix), see #getMain.
826 getName: function () {
828 $.inArray( this.namespace, mw
.config
.get( 'wgCaseSensitiveNamespaces' ) ) !== -1 ||
833 return this.title
[ 0 ].toUpperCase() + this.title
.slice( 1 );
837 * Get the page name (transformed by #text)
839 * Example: "Example image" for "File:Example_image.svg".
841 * For the page title (full page name without namespace prefix), see #getMainText.
845 getNameText: function () {
846 return text( this.getName() );
850 * Get the extension of the page name (if any)
852 * @return {string|null} Name extension or null if there is none
854 getExtension: function () {
859 * Shortcut for appendable string to form the main page name.
861 * Returns a string like ".json", or "" if no extension.
865 getDotExtension: function () {
866 return this.ext
=== null ? '' : '.' + this.ext
;
870 * Get the main page name
872 * Example: "Example_image.svg" for "File:Example_image.svg".
876 getMain: function () {
877 return this.getName() + this.getDotExtension();
881 * Get the main page name (transformed by #text)
883 * Example: "Example image.svg" for "File:Example_image.svg".
887 getMainText: function () {
888 return text( this.getMain() );
892 * Get the full page name
894 * Example: "File:Example_image.svg".
895 * Most useful for API calls, anything that must identify the "title".
899 getPrefixedDb: function () {
900 return this.getNamespacePrefix() + this.getMain();
904 * Get the full page name (transformed by #text)
906 * Example: "File:Example image.svg" for "File:Example_image.svg".
910 getPrefixedText: function () {
911 return text( this.getPrefixedDb() );
915 * Get the page name relative to a namespace
919 * - "Foo:Bar" relative to the Foo namespace becomes "Bar".
920 * - "Bar" relative to any non-main namespace becomes ":Bar".
921 * - "Foo:Bar" relative to any namespace other than Foo stays "Foo:Bar".
923 * @param {number} namespace The namespace to be relative to
926 getRelativeText: function ( namespace ) {
927 if ( this.getNamespaceId() === namespace ) {
928 return this.getMainText();
929 } else if ( this.getNamespaceId() === NS_MAIN
) {
930 return ':' + this.getPrefixedText();
932 return this.getPrefixedText();
937 * Get the fragment (if any).
939 * Note that this method (by design) does not include the hash character and
940 * the value is not url encoded.
942 * @return {string|null}
944 getFragment: function () {
945 return this.fragment
;
949 * Get the URL to this title
951 * @see mw.util#getUrl
952 * @param {Object} [params] A mapping of query parameter names to values,
953 * e.g. `{ action: 'edit' }`.
956 getUrl: function ( params
) {
957 var fragment
= this.getFragment();
959 return mw
.util
.getUrl( this.toString() + '#' + fragment
, params
);
961 return mw
.util
.getUrl( this.toString(), params
);
966 * Whether this title exists on the wiki.
968 * @see #static-method-exists
969 * @return {boolean|null} Boolean if the information is available, otherwise null
971 exists: function () {
972 return Title
.exists( this );
977 * @alias #getPrefixedDb
980 Title
.prototype.toString
= Title
.prototype.getPrefixedDb
;
983 * @alias #getPrefixedText
986 Title
.prototype.toText
= Title
.prototype.getPrefixedText
;
991 }( mediaWiki
, jQuery
) );