resources/src/mediawiki.Title/Title.js

   1 /*!
   2  * @author Neil Kandalgaonkar, 2010
   3  * @since 1.18
   4  */
   5
   6 /**
   7  * Parse titles into an object structure. Note that when using the constructor
   8  * directly, passing invalid titles will result in an exception. Use #newFromText to use the
   9  * logic directly and get null for invalid titles which is easier to work with.
  10  *
  11  * Note that in the constructor and #newFromText method, `namespace` is the **default** namespace
  12  * only, and can be overridden by a namespace prefix in `title`. If you do not want this behavior,
  13  * use #makeTitle. Compare:
  14  *
  15  *     new mw.Title( 'Foo', NS_TEMPLATE ).getPrefixedText();                  // => 'Template:Foo'
  16  *     mw.Title.newFromText( 'Foo', NS_TEMPLATE ).getPrefixedText();          // => 'Template:Foo'
  17  *     mw.Title.makeTitle( NS_TEMPLATE, 'Foo' ).getPrefixedText();            // => 'Template:Foo'
  18  *
  19  *     new mw.Title( 'Category:Foo', NS_TEMPLATE ).getPrefixedText();         // => 'Category:Foo'
  20  *     mw.Title.newFromText( 'Category:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Category:Foo'
  21  *     mw.Title.makeTitle( NS_TEMPLATE, 'Category:Foo' ).getPrefixedText();   // => 'Template:Category:Foo'
  22  *
  23  *     new mw.Title( 'Template:Foo', NS_TEMPLATE ).getPrefixedText();         // => 'Template:Foo'
  24  *     mw.Title.newFromText( 'Template:Foo', NS_TEMPLATE ).getPrefixedText(); // => 'Template:Foo'
  25  *     mw.Title.makeTitle( NS_TEMPLATE, 'Template:Foo' ).getPrefixedText();   // => 'Template:Template:Foo'
  26  *
  27  * @class mw.Title
  28  */
  29
  30 /* Private members */
  31
  32 var
  33         mwString = require( 'mediawiki.String' ),
  34
  35         toUpperMapping = require( './phpCharToUpper.json' ),
  36
  37         namespaceIds = mw.config.get( 'wgNamespaceIds' ),
  38
  39         /**
  40          * @private
  41          * @static
  42          * @property NS_MAIN
  43          */
  44         NS_MAIN = namespaceIds[ '' ],
  45
  46         /**
  47          * @private
  48          * @static
  49          * @property NS_TALK
  50          */
  51         NS_TALK = namespaceIds.talk,
  52
  53         /**
  54          * @private
  55          * @static
  56          * @property NS_SPECIAL
  57          */
  58         NS_SPECIAL = namespaceIds.special,
  59
  60         /**
  61          * @private
  62          * @static
  63          * @property NS_MEDIA
  64          */
  65         NS_MEDIA = namespaceIds.media,
  66
  67         /**
  68          * @private
  69          * @static
  70          * @property NS_FILE
  71          */
  72         NS_FILE = namespaceIds.file,
  73
  74         /**
  75          * @private
  76          * @static
  77          * @property FILENAME_MAX_BYTES
  78          */
  79         FILENAME_MAX_BYTES = 240,
  80
  81         /**
  82          * @private
  83          * @static
  84          * @property TITLE_MAX_BYTES
  85          */
  86         TITLE_MAX_BYTES = 255,
  87
  88         /**
  89          * Get the namespace id from a namespace name (either from the localized, canonical or alias
  90          * name).
  91          *
  92          * Example: On a German wiki this would return 6 for any of 'File', 'Datei', 'Image' or
  93          * even 'Bild'.
  94          *
  95          * @private
  96          * @static
  97          * @method getNsIdByName
  98          * @param {string} ns Namespace name (case insensitive, leading/trailing space ignored)
  99          * @return {number|boolean} Namespace id or boolean false
 100          */
 101         getNsIdByName = function ( ns ) {
 102                 var id;
 103
 104                 // Don't cast non-strings to strings, because null or undefined should not result in
 105                 // returning the id of a potential namespace called "Null:" (e.g. on null.example.org/wiki)
 106                 // Also, toLowerCase throws exception on null/undefined, because it is a String method.
 107                 if ( typeof ns !== 'string' ) {
 108                         return false;
 109                 }
 110                 // TODO: Should just use local var namespaceIds here but it
 111                 // breaks test which modify the config
 112                 id = mw.config.get( 'wgNamespaceIds' )[ ns.toLowerCase() ];
 113                 if ( id === undefined ) {
 114                         return false;
 115                 }
 116                 return id;
 117         },
 118
 119         /**
 120          * @private
 121          * @method getNamespacePrefix_
 122          * @param {number} namespace
 123          * @return {string}
 124          */
 125         getNamespacePrefix = function ( namespace ) {
 126                 return namespace === NS_MAIN ?
 127                         '' :
 128                         ( mw.config.get( 'wgFormattedNamespaces' )[ namespace ].replace( / /g, '_' ) + ':' );
 129         },
 130
 131         rUnderscoreTrim = /^_+|_+$/g,
 132
 133         rSplit = /^(.+?)_*:_*(.*)$/,
 134
 135         // See MediaWikiTitleCodec.php#getTitleInvalidRegex
 136         rInvalid = new RegExp(
 137                 '[^' + mw.config.get( 'wgLegalTitleChars' ) + ']' +
 138                 // URL percent encoding sequences interfere with the ability
 139                 // to round-trip titles -- you can't link to them consistently.
 140                 '|%[0-9A-Fa-f]{2}' +
 141                 // XML/HTML character references produce similar issues.
 142                 '|&[A-Za-z0-9\u0080-\uFFFF]+;' +
 143                 '|&#[0-9]+;' +
 144                 '|&#x[0-9A-Fa-f]+;'
 145         ),
 146
 147         // From MediaWikiTitleCodec::splitTitleString() in PHP
 148         // Note that this is not equivalent to /\s/, e.g. underscore is included, tab is not included.
 149         rWhitespace = /[ _\u00A0\u1680\u180E\u2000-\u200A\u2028\u2029\u202F\u205F\u3000]+/g,
 150
 151         // From MediaWikiTitleCodec::splitTitleString() in PHP
 152         rUnicodeBidi = /[\u200E\u200F\u202A-\u202E]/g,
 153
 154         /**
 155          * Slightly modified from Flinfo. Credit goes to Lupo and Flominator.
 156          * @private
 157          * @static
 158          * @property sanitationRules
 159          */
 160         sanitationRules = [
 161                 // "signature"
 162                 {
 163                         pattern: /~{3}/g,
 164                         replace: '',
 165                         generalRule: true
 166                 },
 167                 // control characters
 168                 {
 169                         // eslint-disable-next-line no-control-regex
 170                         pattern: /[\x00-\x1f\x7f]/g,
 171                         replace: '',
 172                         generalRule: true
 173                 },
 174                 // URL encoding (possibly)
 175                 {
 176                         pattern: /%([0-9A-Fa-f]{2})/g,
 177                         replace: '% $1',
 178                         generalRule: true
 179                 },
 180                 // HTML-character-entities
 181                 {
 182                         pattern: /&(([A-Za-z0-9\x80-\xff]+|#[0-9]+|#x[0-9A-Fa-f]+);)/g,
 183                         replace: '& $1',
 184                         generalRule: true
 185                 },
 186                 // slash, colon (not supported by file systems like NTFS/Windows, Mac OS 9 [:], ext4 [/])
 187                 {
 188                         pattern: new RegExp( '[' + mw.config.get( 'wgIllegalFileChars', '' ) + ']', 'g' ),
 189                         replace: '-',
 190                         fileRule: true
 191                 },
 192                 // brackets, greater than
 193                 {
 194                         pattern: /[}\]>]/g,
 195                         replace: ')',
 196                         generalRule: true
 197                 },
 198                 // brackets, lower than
 199                 {
 200                         pattern: /[{[<]/g,
 201                         replace: '(',
 202                         generalRule: true
 203                 },
 204                 // everything that wasn't covered yet
 205                 {
 206                         pattern: new RegExp( rInvalid.source, 'g' ),
 207                         replace: '-',
 208                         generalRule: true
 209                 },
 210                 // directory structures
 211                 {
 212                         pattern: /^(\.|\.\.|\.\/.*|\.\.\/.*|.*\/\.\/.*|.*\/\.\.\/.*|.*\/\.|.*\/\.\.)$/g,
 213                         replace: '',
 214                         generalRule: true
 215                 }
 216         ],
 217
 218         /**
 219          * Internal helper for #constructor and #newFromText.
 220          *
 221          * Based on Title.php#secureAndSplit
 222          *
 223          * @private
 224          * @static
 225          * @method parse
 226          * @param {string} title
 227          * @param {number} [defaultNamespace=NS_MAIN]
 228          * @return {Object|boolean}
 229          */
 230         parse = function ( title, defaultNamespace ) {
 231                 var namespace, m, id, i, fragment, ext;
 232
 233                 namespace = defaultNamespace === undefined ? NS_MAIN : defaultNamespace;
 234
 235                 title = title
 236                         // Strip Unicode bidi override characters
 237                         .replace( rUnicodeBidi, '' )
 238                         // Normalise whitespace to underscores and remove duplicates
 239                         .replace( rWhitespace, '_' )
 240                         // Trim underscores
 241                         .replace( rUnderscoreTrim, '' );
 242
 243                 // Process initial colon
 244                 if ( title !== '' && title[ 0 ] === ':' ) {
 245                         // Initial colon means main namespace instead of specified default
 246                         namespace = NS_MAIN;
 247                         title = title
 248                                 // Strip colon
 249                                 .slice( 1 )
 250                                 // Trim underscores
 251                                 .replace( rUnderscoreTrim, '' );
 252                 }
 253
 254                 if ( title === '' ) {
 255                         return false;
 256                 }
 257
 258                 // Process namespace prefix (if any)
 259                 m = title.match( rSplit );
 260                 if ( m ) {
 261                         id = getNsIdByName( m[ 1 ] );
 262                         if ( id !== false ) {
 263                                 // Ordinary namespace
 264                                 namespace = id;
 265                                 title = m[ 2 ];
 266
 267                                 // For Talk:X pages, make sure X has no "namespace" prefix
 268                                 if ( namespace === NS_TALK && ( m = title.match( rSplit ) ) ) {
 269                                         // Disallow titles like Talk:File:x (subject should roundtrip: talk:file:x -> file:x -> file_talk:x)
 270                                         if ( getNsIdByName( m[ 1 ] ) !== false ) {
 271                                                 return false;
 272                                         }
 273                                 }
 274                         }
 275                 }
 276
 277                 // Process fragment
 278                 i = title.indexOf( '#' );
 279                 if ( i === -1 ) {
 280                         fragment = null;
 281                 } else {
 282                         fragment = title
 283                                 // Get segment starting after the hash
 284                                 .slice( i + 1 )
 285                                 // Convert to text
 286                                 // NB: Must not be trimmed ("Example#_foo" is not the same as "Example#foo")
 287                                 .replace( /_/g, ' ' );
 288
 289                         title = title
 290                                 // Strip hash
 291                                 .slice( 0, i )
 292                                 // Trim underscores, again (strips "_" from "bar" in "Foo_bar_#quux")
 293                                 .replace( rUnderscoreTrim, '' );
 294                 }
 295
 296                 // Reject illegal characters
 297                 if ( title.match( rInvalid ) ) {
 298                         return false;
 299                 }
 300
 301                 // Disallow titles that browsers or servers might resolve as directory navigation
 302                 if (
 303                         title.indexOf( '.' ) !== -1 && (
 304                                 title === '.' || title === '..' ||
 305                                 title.indexOf( './' ) === 0 ||
 306                                 title.indexOf( '../' ) === 0 ||
 307                                 title.indexOf( '/./' ) !== -1 ||
 308                                 title.indexOf( '/../' ) !== -1 ||
 309                                 title.slice( -2 ) === '/.' ||
 310                                 title.slice( -3 ) === '/..'
 311                         )
 312                 ) {
 313                         return false;
 314                 }
 315
 316                 // Disallow magic tilde sequence
 317                 if ( title.indexOf( '~~~' ) !== -1 ) {
 318                         return false;
 319                 }
 320
 321                 // Disallow titles exceeding the TITLE_MAX_BYTES byte size limit (size of underlying database field)
 322                 // Except for special pages, e.g. [[Special:Block/Long name]]
 323                 // Note: The PHP implementation also asserts that even in NS_SPECIAL, the title should
 324                 // be less than 512 bytes.
 325                 if ( namespace !== NS_SPECIAL && mwString.byteLength( title ) > TITLE_MAX_BYTES ) {
 326                         return false;
 327                 }
 328
 329                 // Can't make a link to a namespace alone.
 330                 if ( title === '' && namespace !== NS_MAIN ) {
 331                         return false;
 332                 }
 333
 334                 // Any remaining initial :s are illegal.
 335                 if ( title[ 0 ] === ':' ) {
 336                         return false;
 337                 }
 338
 339                 // For backwards-compatibility with old mw.Title, we separate the extension from the
 340                 // rest of the title.
 341                 i = title.lastIndexOf( '.' );
 342                 if ( i === -1 || title.length <= i + 1 ) {
 343                         // Extensions are the non-empty segment after the last dot
 344                         ext = null;
 345                 } else {
 346                         ext = title.slice( i + 1 );
 347                         title = title.slice( 0, i );
 348                 }
 349
 350                 return {
 351                         namespace: namespace,
 352                         title: title,
 353                         ext: ext,
 354                         fragment: fragment
 355                 };
 356         },
 357
 358         /**
 359          * Convert db-key to readable text.
 360          *
 361          * @private
 362          * @static
 363          * @method text
 364          * @param {string} s
 365          * @return {string}
 366          */
 367         text = function ( s ) {
 368                 return s.replace( /_/g, ' ' );
 369         },
 370
 371         /**
 372          * Sanitizes a string based on a rule set and a filter
 373          *
 374          * @private
 375          * @static
 376          * @method sanitize
 377          * @param {string} s
 378          * @param {Array} filter
 379          * @return {string}
 380          */
 381         sanitize = function ( s, filter ) {
 382                 var i, ruleLength, rule, m, filterLength,
 383                         rules = sanitationRules;
 384
 385                 for ( i = 0, ruleLength = rules.length; i < ruleLength; ++i ) {
 386                         rule = rules[ i ];
 387                         for ( m = 0, filterLength = filter.length; m < filterLength; ++m ) {
 388                                 if ( rule[ filter[ m ] ] ) {
 389                                         s = s.replace( rule.pattern, rule.replace );
 390                                 }
 391                         }
 392                 }
 393                 return s;
 394         },
 395
 396         /**
 397          * Cuts a string to a specific byte length, assuming UTF-8
 398          * or less, if the last character is a multi-byte one
 399          *
 400          * @private
 401          * @static
 402          * @method trimToByteLength
 403          * @param {string} s
 404          * @param {number} length
 405          * @return {string}
 406          */
 407         trimToByteLength = function ( s, length ) {
 408                 return mwString.trimByteLength( '', s, length ).newVal;
 409         },
 410
 411         /**
 412          * Cuts a file name to a specific byte length
 413          *
 414          * @private
 415          * @static
 416          * @method trimFileNameToByteLength
 417          * @param {string} name without extension
 418          * @param {string} extension file extension
 419          * @return {string} The full name, including extension
 420          */
 421         trimFileNameToByteLength = function ( name, extension ) {
 422                 // There is a special byte limit for file names and ... remember the dot
 423                 return trimToByteLength( name, FILENAME_MAX_BYTES - extension.length - 1 ) + '.' + extension;
 424         };
 425
 426 /**
 427  * @method constructor
 428  * @param {string} title Title of the page. If no second argument given,
 429  *  this will be searched for a namespace
 430  * @param {number} [namespace=NS_MAIN] If given, will used as default namespace for the given title
 431  * @throws {Error} When the title is invalid
 432  */
 433 function Title( title, namespace ) {
 434         var parsed = parse( title, namespace );
 435         if ( !parsed ) {
 436                 throw new Error( 'Unable to parse title' );
 437         }
 438
 439         this.namespace = parsed.namespace;
 440         this.title = parsed.title;
 441         this.ext = parsed.ext;
 442         this.fragment = parsed.fragment;
 443 }
 444
 445 /* Static members */
 446
 447 /**
 448  * Constructor for Title objects with a null return instead of an exception for invalid titles.
 449  *
 450  * Note that `namespace` is the **default** namespace only, and can be overridden by a namespace
 451  * prefix in `title`. If you do not want this behavior, use #makeTitle. See #constructor for
 452  * details.
 453  *
 454  * @static
 455  * @param {string} title
 456  * @param {number} [namespace=NS_MAIN] Default namespace
 457  * @return {mw.Title|null} A valid Title object or null if the title is invalid
 458  */
 459 Title.newFromText = function ( title, namespace ) {
 460         var t, parsed = parse( title, namespace );
 461         if ( !parsed ) {
 462                 return null;
 463         }
 464
 465         t = Object.create( Title.prototype );
 466         t.namespace = parsed.namespace;
 467         t.title = parsed.title;
 468         t.ext = parsed.ext;
 469         t.fragment = parsed.fragment;
 470
 471         return t;
 472 };
 473
 474 /**
 475  * Constructor for Title objects with predefined namespace.
 476  *
 477  * Unlike #newFromText or #constructor, this function doesn't allow the given `namespace` to be
 478  * overridden by a namespace prefix in `title`. See #constructor for details about this behavior.
 479  *
 480  * The single exception to this is when `namespace` is 0, indicating the main namespace. The
 481  * function behaves like #newFromText in that case.
 482  *
 483  * @static
 484  * @param {number} namespace Namespace to use for the title
 485  * @param {string} title
 486  * @return {mw.Title|null} A valid Title object or null if the title is invalid
 487  */
 488 Title.makeTitle = function ( namespace, title ) {
 489         return mw.Title.newFromText( getNamespacePrefix( namespace ) + title );
 490 };
 491
 492 /**
 493  * Constructor for Title objects from user input altering that input to
 494  * produce a title that MediaWiki will accept as legal
 495  *
 496  * @static
 497  * @param {string} title
 498  * @param {number|Object} [defaultNamespaceOrOptions=NS_MAIN]
 499  *  If given, will used as default namespace for the given title.
 500  *  This method can also be called with two arguments, in which case
 501  *  this becomes options (see below).
 502  * @param {Object} [options] additional options
 503  * @param {boolean} [options.forUploading=true]
 504  *  Makes sure that a file is uploadable under the title returned.
 505  *  There are pages in the file namespace under which file upload is impossible.
 506  *  Automatically assumed if the title is created in the Media namespace.
 507  * @return {mw.Title|null} A valid Title object or null if the input cannot be turned into a valid title
 508  */
 509 Title.newFromUserInput = function ( title, defaultNamespaceOrOptions, options ) {
 510         var namespace, m, id, ext, parts,
 511                 defaultNamespace;
 512
 513         // defaultNamespace is optional; check whether options moves up
 514         if ( arguments.length < 3 && typeof defaultNamespace === 'object' ) {
 515                 options = defaultNamespaceOrOptions;
 516         } else {
 517                 defaultNamespace = defaultNamespaceOrOptions;
 518         }
 519
 520         // merge options into defaults
 521         options = $.extend( {
 522                 forUploading: true
 523         }, options );
 524
 525         namespace = defaultNamespace === undefined ? NS_MAIN : defaultNamespace;
 526
 527         // Normalise additional whitespace
 528         title = title.replace( /\s/g, ' ' ).trim();
 529
 530         // Process initial colon
 531         if ( title !== '' && title[ 0 ] === ':' ) {
 532                 // Initial colon means main namespace instead of specified default
 533                 namespace = NS_MAIN;
 534                 title = title
 535                         // Strip colon
 536                         .substr( 1 )
 537                         // Trim underscores
 538                         .replace( rUnderscoreTrim, '' );
 539         }
 540
 541         // Process namespace prefix (if any)
 542         m = title.match( rSplit );
 543         if ( m ) {
 544                 id = getNsIdByName( m[ 1 ] );
 545                 if ( id !== false ) {
 546                         // Ordinary namespace
 547                         namespace = id;
 548                         title = m[ 2 ];
 549                 }
 550         }
 551
 552         if (
 553                 namespace === NS_MEDIA ||
 554                 ( options.forUploading && ( namespace === NS_FILE ) )
 555         ) {
 556
 557                 title = sanitize( title, [ 'generalRule', 'fileRule' ] );
 558
 559                 // Operate on the file extension
 560                 // Although it is possible having spaces between the name and the ".ext" this isn't nice for
 561                 // operating systems hiding file extensions -> strip them later on
 562                 parts = title.split( '.' );
 563
 564                 if ( parts.length > 1 ) {
 565
 566                         // Get the last part, which is supposed to be the file extension
 567                         ext = parts.pop();
 568
 569                         // Remove whitespace of the name part (that W/O extension)
 570                         title = parts.join( '.' ).trim();
 571
 572                         // Cut, if too long and append file extension
 573                         title = trimFileNameToByteLength( title, ext );
 574
 575                 } else {
 576
 577                         // Missing file extension
 578                         title = parts.join( '.' ).trim();
 579
 580                         // Name has no file extension and a fallback wasn't provided either
 581                         return null;
 582                 }
 583         } else {
 584
 585                 title = sanitize( title, [ 'generalRule' ] );
 586
 587                 // Cut titles exceeding the TITLE_MAX_BYTES byte size limit
 588                 // (size of underlying database field)
 589                 if ( namespace !== NS_SPECIAL ) {
 590                         title = trimToByteLength( title, TITLE_MAX_BYTES );
 591                 }
 592         }
 593
 594         // Any remaining initial :s are illegal.
 595         title = title.replace( /^:+/, '' );
 596
 597         return Title.newFromText( title, namespace );
 598 };
 599
 600 /**
 601  * Sanitizes a file name as supplied by the user, originating in the user's file system
 602  * so it is most likely a valid MediaWiki title and file name after processing.
 603  * Returns null on fatal errors.
 604  *
 605  * @static
 606  * @param {string} uncleanName The unclean file name including file extension but
 607  *   without namespace
 608  * @return {mw.Title|null} A valid Title object or null if the title is invalid
 609  */
 610 Title.newFromFileName = function ( uncleanName ) {
 611
 612         return Title.newFromUserInput( 'File:' + uncleanName, {
 613                 forUploading: true
 614         } );
 615 };
 616
 617 /**
 618  * Get the file title from an image element
 619  *
 620  *     var title = mw.Title.newFromImg( $( 'img:first' ) );
 621  *
 622  * @static
 623  * @param {HTMLElement|jQuery} img The image to use as a base
 624  * @return {mw.Title|null} The file title or null if unsuccessful
 625  */
 626 Title.newFromImg = function ( img ) {
 627         var matches, i, regex, src, decodedSrc,
 628
 629                 // thumb.php-generated thumbnails
 630                 thumbPhpRegex = /thumb\.php/,
 631                 regexes = [
 632                         // Thumbnails
 633                         /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s/]+)\/[^\s/]+-[^\s/]*$/,
 634
 635                         // Full size images
 636                         /\/[a-f0-9]\/[a-f0-9]{2}\/([^\s/]+)$/,
 637
 638                         // Thumbnails in non-hashed upload directories
 639                         /\/([^\s/]+)\/[^\s/]+-(?:\1|thumbnail)[^\s/]*$/,
 640
 641                         // Full-size images in non-hashed upload directories
 642                         /\/([^\s/]+)$/
 643                 ],
 644
 645                 recount = regexes.length;
 646
 647         src = img.jquery ? img[ 0 ].src : img.src;
 648
 649         matches = src.match( thumbPhpRegex );
 650
 651         if ( matches ) {
 652                 return mw.Title.newFromText( 'File:' + mw.util.getParamValue( 'f', src ) );
 653         }
 654
 655         decodedSrc = decodeURIComponent( src );
 656
 657         for ( i = 0; i < recount; i++ ) {
 658                 regex = regexes[ i ];
 659                 matches = decodedSrc.match( regex );
 660
 661                 if ( matches && matches[ 1 ] ) {
 662                         return mw.Title.newFromText( 'File:' + matches[ 1 ] );
 663                 }
 664         }
 665
 666         return null;
 667 };
 668
 669 /**
 670  * Check if a given namespace is a talk namespace
 671  *
 672  * See MWNamespace::isTalk in PHP
 673  *
 674  * @param {number} namespaceId Namespace ID
 675  * @return {boolean} Namespace is a talk namespace
 676  */
 677 Title.isTalkNamespace = function ( namespaceId ) {
 678         return !!( namespaceId > NS_MAIN && namespaceId % 2 );
 679 };
 680
 681 /**
 682  * Check if signature buttons should be shown in a given namespace
 683  *
 684  * See MWNamespace::wantSignatures in PHP
 685  *
 686  * @param {number} namespaceId Namespace ID
 687  * @return {boolean} Namespace is a signature namespace
 688  */
 689 Title.wantSignaturesNamespace = function ( namespaceId ) {
 690         return Title.isTalkNamespace( namespaceId ) ||
 691                 mw.config.get( 'wgExtraSignatureNamespaces' ).indexOf( namespaceId ) !== -1;
 692 };
 693
 694 /**
 695  * Whether this title exists on the wiki.
 696  *
 697  * @static
 698  * @param {string|mw.Title} title prefixed db-key name (string) or instance of Title
 699  * @return {boolean|null} Boolean if the information is available, otherwise null
 700  * @throws {Error} If title is not a string or mw.Title
 701  */
 702 Title.exists = function ( title ) {
 703         var match,
 704                 obj = Title.exist.pages;
 705
 706         if ( typeof title === 'string' ) {
 707                 match = obj[ title ];
 708         } else if ( title instanceof Title ) {
 709                 match = obj[ title.toString() ];
 710         } else {
 711                 throw new Error( 'mw.Title.exists: title must be a string or an instance of Title' );
 712         }
 713
 714         if ( typeof match !== 'boolean' ) {
 715                 return null;
 716         }
 717
 718         return match;
 719 };
 720
 721 /**
 722  * Store page existence
 723  *
 724  * @static
 725  * @property {Object} exist
 726  * @property {Object} exist.pages Keyed by title. Boolean true value indicates page does exist.
 727  *
 728  * @property {Function} exist.set The setter function.
 729  *
 730  *  Example to declare existing titles:
 731  *
 732  *     Title.exist.set( ['User:John_Doe', ...] );
 733  *
 734  *  Example to declare titles nonexistent:
 735  *
 736  *     Title.exist.set( ['File:Foo_bar.jpg', ...], false );
 737  *
 738  * @property {string|Array} exist.set.titles Title(s) in strict prefixedDb title form
 739  * @property {boolean} [exist.set.state=true] State of the given titles
 740  * @return {boolean}
 741  */
 742 Title.exist = {
 743         pages: {},
 744
 745         set: function ( titles, state ) {
 746                 var i, len,
 747                         pages = this.pages;
 748
 749                 titles = Array.isArray( titles ) ? titles : [ titles ];
 750                 state = state === undefined ? true : !!state;
 751
 752                 for ( i = 0, len = titles.length; i < len; i++ ) {
 753                         pages[ titles[ i ] ] = state;
 754                 }
 755                 return true;
 756         }
 757 };
 758
 759 /**
 760  * Normalize a file extension to the common form, making it lowercase and checking some synonyms,
 761  * and ensure it's clean. Extensions with non-alphanumeric characters will be discarded.
 762  * Keep in sync with File::normalizeExtension() in PHP.
 763  *
 764  * @param {string} extension File extension (without the leading dot)
 765  * @return {string} File extension in canonical form
 766  */
 767 Title.normalizeExtension = function ( extension ) {
 768         var
 769                 lower = extension.toLowerCase(),
 770                 squish = {
 771                         htm: 'html',
 772                         jpeg: 'jpg',
 773                         mpeg: 'mpg',
 774                         tiff: 'tif',
 775                         ogv: 'ogg'
 776                 };
 777         if ( Object.prototype.hasOwnProperty.call( squish, lower ) ) {
 778                 return squish[ lower ];
 779         } else if ( /^[0-9a-z]+$/.test( lower ) ) {
 780                 return lower;
 781         } else {
 782                 return '';
 783         }
 784 };
 785
 786 /**
 787  * PHP's strtoupper differs from String.toUpperCase in a number of cases (T147646).
 788  *
 789  * @param {string} chr Unicode character
 790  * @return {string} Unicode character, in upper case, according to the same rules as in PHP
 791  */
 792 Title.phpCharToUpper = function ( chr ) {
 793         var mapped = toUpperMapping[ chr ];
 794         return mapped || chr.toUpperCase();
 795 };
 796
 797 /* Public members */
 798
 799 Title.prototype = {
 800         constructor: Title,
 801
 802         /**
 803          * Get the namespace number
 804          *
 805          * Example: 6 for "File:Example_image.svg".
 806          *
 807          * @return {number}
 808          */
 809         getNamespaceId: function () {
 810                 return this.namespace;
 811         },
 812
 813         /**
 814          * Get the namespace prefix (in the content language)
 815          *
 816          * Example: "File:" for "File:Example_image.svg".
 817          * In #NS_MAIN this is '', otherwise namespace name plus ':'
 818          *
 819          * @return {string}
 820          */
 821         getNamespacePrefix: function () {
 822                 return getNamespacePrefix( this.namespace );
 823         },
 824
 825         /**
 826          * Get the page name without extension or namespace prefix
 827          *
 828          * Example: "Example_image" for "File:Example_image.svg".
 829          *
 830          * For the page title (full page name without namespace prefix), see #getMain.
 831          *
 832          * @return {string}
 833          */
 834         getName: function () {
 835                 if (
 836                         mw.config.get( 'wgCaseSensitiveNamespaces' ).indexOf( this.namespace ) !== -1 ||
 837                         !this.title.length
 838                 ) {
 839                         return this.title;
 840                 }
 841                 return mw.Title.phpCharToUpper( this.title[ 0 ] ) + this.title.slice( 1 );
 842         },
 843
 844         /**
 845          * Get the page name (transformed by #text)
 846          *
 847          * Example: "Example image" for "File:Example_image.svg".
 848          *
 849          * For the page title (full page name without namespace prefix), see #getMainText.
 850          *
 851          * @return {string}
 852          */
 853         getNameText: function () {
 854                 return text( this.getName() );
 855         },
 856
 857         /**
 858          * Get the extension of the page name (if any)
 859          *
 860          * @return {string|null} Name extension or null if there is none
 861          */
 862         getExtension: function () {
 863                 return this.ext;
 864         },
 865
 866         /**
 867          * Shortcut for appendable string to form the main page name.
 868          *
 869          * Returns a string like ".json", or "" if no extension.
 870          *
 871          * @return {string}
 872          */
 873         getDotExtension: function () {
 874                 return this.ext === null ? '' : '.' + this.ext;
 875         },
 876
 877         /**
 878          * Get the main page name
 879          *
 880          * Example: "Example_image.svg" for "File:Example_image.svg".
 881          *
 882          * @return {string}
 883          */
 884         getMain: function () {
 885                 return this.getName() + this.getDotExtension();
 886         },
 887
 888         /**
 889          * Get the main page name (transformed by #text)
 890          *
 891          * Example: "Example image.svg" for "File:Example_image.svg".
 892          *
 893          * @return {string}
 894          */
 895         getMainText: function () {
 896                 return text( this.getMain() );
 897         },
 898
 899         /**
 900          * Get the full page name
 901          *
 902          * Example: "File:Example_image.svg".
 903          * Most useful for API calls, anything that must identify the "title".
 904          *
 905          * @return {string}
 906          */
 907         getPrefixedDb: function () {
 908                 return this.getNamespacePrefix() + this.getMain();
 909         },
 910
 911         /**
 912          * Get the full page name (transformed by #text)
 913          *
 914          * Example: "File:Example image.svg" for "File:Example_image.svg".
 915          *
 916          * @return {string}
 917          */
 918         getPrefixedText: function () {
 919                 return text( this.getPrefixedDb() );
 920         },
 921
 922         /**
 923          * Get the page name relative to a namespace
 924          *
 925          * Example:
 926          *
 927          * - "Foo:Bar" relative to the Foo namespace becomes "Bar".
 928          * - "Bar" relative to any non-main namespace becomes ":Bar".
 929          * - "Foo:Bar" relative to any namespace other than Foo stays "Foo:Bar".
 930          *
 931          * @param {number} namespace The namespace to be relative to
 932          * @return {string}
 933          */
 934         getRelativeText: function ( namespace ) {
 935                 if ( this.getNamespaceId() === namespace ) {
 936                         return this.getMainText();
 937                 } else if ( this.getNamespaceId() === NS_MAIN ) {
 938                         return ':' + this.getPrefixedText();
 939                 } else {
 940                         return this.getPrefixedText();
 941                 }
 942         },
 943
 944         /**
 945          * Get the fragment (if any).
 946          *
 947          * Note that this method (by design) does not include the hash character and
 948          * the value is not url encoded.
 949          *
 950          * @return {string|null}
 951          */
 952         getFragment: function () {
 953                 return this.fragment;
 954         },
 955
 956         /**
 957          * Get the URL to this title
 958          *
 959          * @see mw.util#getUrl
 960          * @param {Object} [params] A mapping of query parameter names to values,
 961          *     e.g. `{ action: 'edit' }`.
 962          * @return {string}
 963          */
 964         getUrl: function ( params ) {
 965                 var fragment = this.getFragment();
 966                 if ( fragment ) {
 967                         return mw.util.getUrl( this.toString() + '#' + fragment, params );
 968                 } else {
 969                         return mw.util.getUrl( this.toString(), params );
 970                 }
 971         },
 972
 973         /**
 974          * Check if the title is in a talk namespace
 975          *
 976          * @return {boolean} The title is in a talk namespace
 977          */
 978         isTalkPage: function () {
 979                 return Title.isTalkNamespace( this.getNamespaceId() );
 980         },
 981
 982         /**
 983          * Get the title for the associated talk page
 984          *
 985          * @return {mw.Title|null} The title for the associated talk page, null if not available
 986          */
 987         getTalkPage: function () {
 988                 if ( !this.canHaveTalkPage() ) {
 989                         return null;
 990                 }
 991                 return this.isTalkPage() ?
 992                         this :
 993                         Title.makeTitle( this.getNamespaceId() + 1, this.getMainText() );
 994         },
 995
 996         /**
 997          * Get the title for the subject page of a talk page
 998          *
 999          * @return {mw.Title|null} The title for the subject page of a talk page, null if not available
1000          */
1001         getSubjectPage: function () {
1002                 return this.isTalkPage() ?
1003                         Title.makeTitle( this.getNamespaceId() - 1, this.getMainText() ) :
1004                         this;
1005         },
1006
1007         /**
1008          * Check the the title can have an associated talk page
1009          *
1010          * @return {boolean} The title can have an associated talk page
1011          */
1012         canHaveTalkPage: function () {
1013                 return this.getNamespaceId() >= NS_MAIN;
1014         },
1015
1016         /**
1017          * Whether this title exists on the wiki.
1018          *
1019          * @see #static-method-exists
1020          * @return {boolean|null} Boolean if the information is available, otherwise null
1021          */
1022         exists: function () {
1023                 return Title.exists( this );
1024         }
1025 };
1026
1027 /**
1028  * @alias #getPrefixedDb
1029  * @method
1030  */
1031 Title.prototype.toString = Title.prototype.getPrefixedDb;
1032
1033 /**
1034  * @alias #getPrefixedText
1035  * @method
1036  */
1037 Title.prototype.toText = Title.prototype.getPrefixedText;
1038
1039 // Expose
1040 mw.Title = Title;