From f342099b3c63a2a591454a21a7a425bc28e7bd4e Mon Sep 17 00:00:00 2001 From: Abijeet Date: Thu, 14 May 2020 02:22:02 +0530 Subject: [PATCH] Rename class from LanguageData to LanguageUtil to have better namespacing Update the documentation also --- README.md | 2 +- docs/api.rst | 3 +- docs/api/languagedata.rst | 172 ------------------ docs/index.rst | 12 +- src/{LanguageData.php => LanguageUtil.php} | 14 +- ...guageDataTest.php => LanguageUtilTest.php} | 90 ++++----- 6 files changed, 60 insertions(+), 233 deletions(-) delete mode 100644 docs/api/languagedata.rst rename src/{LanguageData.php => LanguageUtil.php} (97%) rename tests/php/{LanguageDataTest.php => LanguageUtilTest.php} (63%) diff --git a/README.md b/README.md index 2840320..a994f87 100644 --- a/README.md +++ b/README.md @@ -23,7 +23,7 @@ This data is populated from the current version of 1. [Full documentation](https://language-data.readthedocs.io/en/latest/index.html) 2. [Using the PHP library](https://language-data.readthedocs.io/en/latest/index.html#using-the-php-library) - * [PHP API documentation](https://language-data.readthedocs.io/en/latest/api/languagedata.html) + * [PHP API documentation](https://language-data.readthedocs.io/en/latest/api/languageutil.html) 3. [Using the Node.js library](https://language-data.readthedocs.io/en/latest/index.html#using-the-node-js-library) 4. [Adding Languages](https://language-data.readthedocs.io/en/latest/user/adding_new_language.html) diff --git a/docs/api.rst b/docs/api.rst index fabd0d0..b3dadb3 100644 --- a/docs/api.rst +++ b/docs/api.rst @@ -5,6 +5,5 @@ API documentation :glob: api/* + api/languagedata/* - - diff --git a/docs/api/languagedata.rst b/docs/api/languagedata.rst deleted file mode 100644 index 6551137..0000000 --- a/docs/api/languagedata.rst +++ /dev/null @@ -1,172 +0,0 @@ -LanguageData -============ - -A singleton utility class to query the language data. - -:Qualified name: ``Wikimedia\LanguageData`` - -.. php:class:: LanguageData - - .. php:method:: addLanguage (string $languageCode, array $options) - - Adds a language in run time and sets its options as provided. If the target option is provided, the language is defined as a redirect. Other possible options are script (string), regions (array) and autonym (string). - - :param string $languageCode: - New language code. - :param array $options: - Language properties. - - .. php:method:: getAutonym (string $languageCode) - - Returns the autonym of the language - - :param string $languageCode: - Language code - :returns: string|bool Autonym of the language or false if the language is unknown - - .. php:method:: getAutonyms () -> array - - Returns all language codes and corresponding autonyms - - :returns: array -- The key is the language code, and the values are corresponding autonym - - .. php:method:: getDir (string $languageCode) - - Return the direction of the language - - :param string $languageCode: - Language code - :returns: string|bool Returns 'rtl' or 'ltr'. If the language code is unknown, returns false. - - .. php:method:: getGroupOfScript (string $script) -> string - - Returns the script group of a script or "Other" if it doesn't belong to any group - - :param string $script: - Name of the script - :returns: string -- Script group name or "Other" if the script doesn't belong to any group - - .. php:method:: getLanguages () - - Get all the languages. The properties in the returned object are ISO 639 language codes The value of each property is an array that has, [writing system code, [regions list], autonym] - - :returns: object - - .. php:method:: getLanguagesByScriptGroup (array $languageCodes) -> array - - Return the list of languages passed, grouped by their script group - - :param array $languageCodes: - List of language codes to group - :returns: array -- List of language codes grouped by script group - - .. php:method:: getLanguagesByScriptGroupInRegion (string $region) -> LanguageData::getLanguagesByScriptGroupInRegions - - Returns an associative array of languages in a region, grouped by their script - - :param string $region: - Region code - :returns: :class:`LanguageData::getLanguagesByScriptGroupInRegions` -- - - .. php:method:: getLanguagesByScriptGroupInRegions (array $regions) -> array - - Returns an associative array of languages in several regions, grouped by script group - - :param array $regions: - List of strings representing region codes - :returns: array -- Returns an associative array. They key is the script group name, and the value is a list of language codes in that region. - - .. php:method:: getLanguagesInScript (string $script) -> array - - Returns all languages written in the given script - - :param string $script: - Name of the script - :returns: array -- - - .. php:method:: getLanguagesInScripts (array $scripts) -> array - - Returns all languages written in the given scripts - - :param array $scripts: - List of strings, each being the name of a script - :returns: array -- - - .. php:method:: getLanguagesInTerritory (string $territory) - - Returns the languages spoken in a territory - - :param string $territory: - Territory code - :returns: array|bool List of language codes in the territory, or else false if invalid territory is passed - - .. php:method:: getRegions (string $languageCode) - - Returns the regions in which a language is spoken - - :param string $languageCode: - Language code - :returns: array|bool List of regions or false if language is unknown - - .. php:method:: getScript (string $languageCode) - - Returns the script of the language - - :param string $languageCode: - Language code - :returns: string|bool Language script or false if the language is unknown - - .. php:method:: getScriptGroupOfLanguage (string $languageCode) -> string - - Returns the script group of a language. Language belongs to a script, and the script belongs to a script group - - :param string $languageCode: - Language code - :returns: string -- script group name - - .. php:method:: isKnown (string $languageCode) -> bool - - Checks if a language code is valid - - :param string $languageCode: - Language code - :returns: bool -- - - .. php:method:: isRedirect (string $languageCode) - - Checks if the language is a redirect and returns the target language code - - :param string $languageCode: - Language code - :returns: string|bool Target language code if it's a redirect or false if it's not - - .. php:method:: isRtl (string $languageCode) -> bool - - Check if a language is right-to-left - - :param string $languageCode: - Language code - :returns: bool -- true if it is an RTL language, else false. Returns false if an unknown language code is passed. - - .. php:method:: sortByAutonym (array $languageCodes) -> array - - Sort languages by their autonym - - :param array $languageCodes: - List of language codes to sort - :returns: array -- List of sorted language codes returned by their autonym - - .. php:method:: sortByScriptGroup (array $languageCodes) -> array - - Return the list of languages sorted by their script groups - - :param array $languageCodes: - List of language codes to sort - :returns: array -- Sorted list of strings containing language codes - - .. php:staticmethod:: get () -> LanguageData - - Returns an instance of the class that can be used to then call the other methods in the class. - - :returns: :class:`LanguageData` -- - diff --git a/docs/index.rst b/docs/index.rst index 59e0d54..4594f6f 100644 --- a/docs/index.rst +++ b/docs/index.rst @@ -43,13 +43,13 @@ The basic usage is like this: .. code-block:: php getAutonym( 'en' ); + $languageUtil->getAutonym( 'en' ); -For a full list of methods see the documentation for the `LanguageData `_ class. +For a full list of methods see the documentation for the `LanguageUtil `_ class. Using the Node.js library ------------------------------ @@ -82,7 +82,7 @@ The basic usage is like this: // Returns English languageData.getAutonym( 'en'); -The exposed methods are similar to the methods present in the PHP `LanguageData `_ class. +The exposed methods are similar to the methods present in the PHP `LanguageUtil `_ class. Contribute ---------- @@ -103,7 +103,7 @@ Navigation :maxdepth: 2 :caption: PHP API Documentation - LanguageData class + LanguageUtil Indices and tables diff --git a/src/LanguageData.php b/src/LanguageUtil.php similarity index 97% rename from src/LanguageData.php rename to src/LanguageUtil.php index ebe1c7c..733f6a7 100644 --- a/src/LanguageData.php +++ b/src/LanguageUtil.php @@ -5,15 +5,15 @@ * @license GPL-2.0-or-later */ -namespace Wikimedia; +namespace Wikimedia\LanguageData; /** * A singleton utility class to query the language data. */ -class LanguageData { +class LanguageUtil { /** * Instance of the class. - * @var LanguageData + * @var self */ private static $instance; @@ -38,11 +38,11 @@ class LanguageData { /** * Returns an instance of the class that can be used to then call the other methods in the * class. - * @return LanguageData + * @return self */ - public static function get(): LanguageData { + public static function get(): LanguageUtil { if ( self::$instance === null ) { - self::$instance = new LanguageData(); + self::$instance = new LanguageUtil(); self::$instance->loadData(); } @@ -283,7 +283,7 @@ class LanguageData { /** * Returns an associative array of languages in a region, grouped by their script - * @see LanguageData#getLanguagesByScriptGroupInRegions + * @see LanguageUtil#getLanguagesByScriptGroupInRegions * @param string $region Region code * @return array */ diff --git a/tests/php/LanguageDataTest.php b/tests/php/LanguageUtilTest.php similarity index 63% rename from tests/php/LanguageDataTest.php rename to tests/php/LanguageUtilTest.php index c66bd9d..09c490e 100644 --- a/tests/php/LanguageDataTest.php +++ b/tests/php/LanguageUtilTest.php @@ -1,58 +1,58 @@ languageData = LanguageData::get(); + $this->languageUtil = LanguageUtil::get(); } /** * @covers isKnown */ public function testIsKnown() { - $this->assertTrue( $this->languageData->isKnown( 'en' ) ); - $this->assertFalse( $this->languageData->isKnown( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertTrue( $this->languageUtil->isKnown( 'en' ) ); + $this->assertFalse( $this->languageUtil->isKnown( self::UNKNOWN_LANGUAGE_CODE ) ); } /** * @covers isRedirect */ public function testIsRedirect() { - $this->assertFalse( $this->languageData->isRedirect( 'en' ) ); - $this->assertEquals( $this->languageData->isRedirect( 'aeb' ), 'aeb-arab' ); + $this->assertFalse( $this->languageUtil->isRedirect( 'en' ) ); + $this->assertEquals( $this->languageUtil->isRedirect( 'aeb' ), 'aeb-arab' ); } /** * @covers getScript */ public function testGetScript() { - $this->assertEquals( $this->languageData->getScript( 'en' ), 'Latn' ); - $this->assertFalse( $this->languageData->getScript( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertEquals( $this->languageUtil->getScript( 'en' ), 'Latn' ); + $this->assertFalse( $this->languageUtil->getScript( self::UNKNOWN_LANGUAGE_CODE ) ); } /** * @covers getRegions */ public function testGetRegions() { - $this->assertFalse( $this->languageData->getRegions( self::UNKNOWN_LANGUAGE_CODE ) ); - $this->assertEquals( [ 'AF' ], $this->languageData->getRegions( 'aeb' ) ); + $this->assertFalse( $this->languageUtil->getRegions( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertEquals( [ 'AF' ], $this->languageUtil->getRegions( 'aeb' ) ); $expected = [ 'EU', 'AM', 'AS' ]; - $regions = $this->languageData->getRegions( 'en' ); + $regions = $this->languageUtil->getRegions( 'en' ); foreach ( $expected as $region ) { $this->assertContains( $region, $regions ); } @@ -62,21 +62,21 @@ class LanguageDataTest extends TestCase { * @covers getAutonym */ public function testGetAutonym() { - $this->assertFalse( $this->languageData->getAutonym( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertFalse( $this->languageUtil->getAutonym( self::UNKNOWN_LANGUAGE_CODE ) ); $this->assertEquals( 'تونسي', - $this->languageData->getAutonym( 'aeb' ), + $this->languageUtil->getAutonym( 'aeb' ), 'Redirects return proper value in getAutonym.' ); - $this->assertEquals( 'English', $this->languageData->getAutonym( 'en' ) ); + $this->assertEquals( 'English', $this->languageUtil->getAutonym( 'en' ) ); } /** * @covers getAutonyms */ public function testGetAutonyms() { - $autonyms = $this->languageData->getAutonyms(); + $autonyms = $this->languageUtil->getAutonyms(); $this->assertEquals( 'English', $autonyms['en'] ); $this->assertFalse( isset( $autonyms['aeb'] ), @@ -89,10 +89,10 @@ class LanguageDataTest extends TestCase { */ public function testGetLanguagesInScripts() { $this->assertEmpty( - $this->languageData->getLanguagesInScripts( [ self::UNKNOWN_LANGUAGE_CODE ] ) + $this->languageUtil->getLanguagesInScripts( [ self::UNKNOWN_LANGUAGE_CODE ] ) ); - $expectedValues = $this->languageData->getLanguagesInScripts( [ 'Latn', 'Grek' ] ); + $expectedValues = $this->languageUtil->getLanguagesInScripts( [ 'Latn', 'Grek' ] ); $this->assertContains( 'zu', $expectedValues ); $this->assertContains( 'pnt', $expectedValues ); @@ -107,10 +107,10 @@ class LanguageDataTest extends TestCase { * @covers getGroupOfScript */ public function testGetGroupOfScript() { - $this->assertEquals( 'Latin', $this->languageData->getGroupOfScript( 'Latn' ) ); + $this->assertEquals( 'Latin', $this->languageUtil->getGroupOfScript( 'Latn' ) ); $this->assertEquals( - LanguageData::OTHER_SCRIPT_GROUP, - $this->languageData->getGroupOfScript( self::UNKNOWN_LANGUAGE_CODE ) + LanguageUtil::OTHER_SCRIPT_GROUP, + $this->languageUtil->getGroupOfScript( self::UNKNOWN_LANGUAGE_CODE ) ); } @@ -119,13 +119,13 @@ class LanguageDataTest extends TestCase { */ public function testGetScriptGroupOfLanguage() { $this->assertEquals( - LanguageData::OTHER_SCRIPT_GROUP, - $this->languageData->getScriptGroupOfLanguage( self::UNKNOWN_LANGUAGE_CODE ) + LanguageUtil::OTHER_SCRIPT_GROUP, + $this->languageUtil->getScriptGroupOfLanguage( self::UNKNOWN_LANGUAGE_CODE ) ); $this->assertEquals( 'Latin', - $this->languageData->getScriptGroupOfLanguage( 'en' ) + $this->languageUtil->getScriptGroupOfLanguage( 'en' ) ); } @@ -133,7 +133,7 @@ class LanguageDataTest extends TestCase { * @covers getLanguagesByScriptGroup */ public function testGetLanguagesByScriptGroup() { - $actuals = $this->languageData->getLanguagesByScriptGroup( [ 'en', 'sr-el', 'tt-cyrl' ] ); + $actuals = $this->languageUtil->getLanguagesByScriptGroup( [ 'en', 'sr-el', 'tt-cyrl' ] ); $this->assertContains( 'tt-cyrl', $actuals['Cyrillic'] ); $this->assertContains( 'en', $actuals['Latin'] ); @@ -144,7 +144,7 @@ class LanguageDataTest extends TestCase { * @covers getLanguagesByScriptGroupInRegions */ public function testGetLanguagesByScriptGroupInRegions() { - $actuals = $this->languageData->getLanguagesByScriptGroupInRegions( [ 'AS', 'PA' ] ); + $actuals = $this->languageUtil->getLanguagesByScriptGroupInRegions( [ 'AS', 'PA' ] ); $this->assertContains( 'tpi', $actuals['Latin'] ); $this->assertContains( 'ug-arab', $actuals['Arabic'] ); @@ -160,7 +160,7 @@ class LanguageDataTest extends TestCase { * @covers sortByAutonym */ public function testSortByAutonym() { - $sorted = $this->languageData->sortByAutonym( + $sorted = $this->languageUtil->sortByAutonym( [ 'atj', 'chr', 'chy', 'cr', 'en', 'es', @@ -188,8 +188,8 @@ class LanguageDataTest extends TestCase { * @covers sortByScriptGroup */ public function testSortByScriptGroup() { - $sorted = $this->languageData->sortByScriptGroup( - $this->languageData->sortByAutonym( + $sorted = $this->languageUtil->sortByScriptGroup( + $this->languageUtil->sortByAutonym( [ 'atj', 'chr', 'chy', 'cr', 'en', 'es', @@ -218,26 +218,26 @@ class LanguageDataTest extends TestCase { * @covers isRtl */ public function testIsRtl() { - $this->assertFalse( $this->languageData->isRtl( 'en' ) ); - $this->assertFalse( $this->languageData->isRtl( self::UNKNOWN_LANGUAGE_CODE ) ); - $this->assertTrue( $this->languageData->isRtl( 'he' ) ); + $this->assertFalse( $this->languageUtil->isRtl( 'en' ) ); + $this->assertFalse( $this->languageUtil->isRtl( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertTrue( $this->languageUtil->isRtl( 'he' ) ); } /** * @covers getDir */ public function testGetDir() { - $this->assertEquals( 'ltr', $this->languageData->getDir( 'en' ) ); - $this->assertEquals( 'rtl', $this->languageData->getDir( 'he' ) ); - $this->assertFalse( $this->languageData->getDir( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertEquals( 'ltr', $this->languageUtil->getDir( 'en' ) ); + $this->assertEquals( 'rtl', $this->languageUtil->getDir( 'he' ) ); + $this->assertFalse( $this->languageUtil->getDir( self::UNKNOWN_LANGUAGE_CODE ) ); } /** * @covers getLanguagesInTerritory */ public function testGetLanguagesInTerritory() { - $actualsAFG = $this->languageData->getLanguagesInTerritory( 'AF' ); - $actualsAT = $this->languageData->getLanguagesInTerritory( 'AT' ); + $actualsAFG = $this->languageUtil->getLanguagesInTerritory( 'AF' ); + $actualsAT = $this->languageUtil->getLanguagesInTerritory( 'AT' ); $this->assertContains( 'de', $actualsAT ); $this->assertContains( 'bar', $actualsAT ); @@ -252,13 +252,13 @@ class LanguageDataTest extends TestCase { * @covers addLanguage */ public function testAddLanguage() { - $this->assertFalse( $this->languageData->isKnown( 'xyz' ) ); + $this->assertFalse( $this->languageUtil->isKnown( 'xyz' ) ); $this->assertNotContains( 'xyz', - $this->languageData->getLanguagesByScriptGroupInRegion( 'AF' )['Latin'] + $this->languageUtil->getLanguagesByScriptGroupInRegion( 'AF' )['Latin'] ); - $this->languageData->addLanguage( self::UNKNOWN_LANGUAGE_CODE, [ + $this->languageUtil->addLanguage( self::UNKNOWN_LANGUAGE_CODE, [ 'script' => "Latn", 'regions' => [ "AF" @@ -266,10 +266,10 @@ class LanguageDataTest extends TestCase { 'autonym' => "Test Language" ] ); - $this->assertTrue( $this->languageData->isKnown( self::UNKNOWN_LANGUAGE_CODE ) ); + $this->assertTrue( $this->languageUtil->isKnown( self::UNKNOWN_LANGUAGE_CODE ) ); $this->assertContains( self::UNKNOWN_LANGUAGE_CODE, - $this->languageData->getLanguagesByScriptGroupInRegion( 'AF' )['Latin'] + $this->languageUtil->getLanguagesByScriptGroupInRegion( 'AF' )['Latin'] ); } }