{"id":16958452,"url":"https://github.com/dohliam/pingyam-rb","last_synced_at":"2025-03-21T14:30:18.132Z","repository":{"id":88992069,"uuid":"347816491","full_name":"dohliam/pingyam-rb","owner":"dohliam","description":"Cantonese romanization converter in Ruby","archived":false,"fork":false,"pushed_at":"2021-03-24T00:42:12.000Z","size":17,"stargazers_count":3,"open_issues_count":0,"forks_count":0,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-01-26T10:08:43.322Z","etag":null,"topics":["cantonese","cantonese-language","cantonese-romanization","chinese-romanization","conversion","ipa","jyutping","pingyam","pinyin-conversion","romanization-systems","yale-transcription"],"latest_commit_sha":null,"homepage":"","language":"Ruby","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/dohliam.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-03-15T02:49:19.000Z","updated_at":"2023-03-28T15:41:32.000Z","dependencies_parsed_at":"2023-06-13T11:15:32.672Z","dependency_job_id":null,"html_url":"https://github.com/dohliam/pingyam-rb","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Fpingyam-rb","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Fpingyam-rb/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Fpingyam-rb/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/dohliam%2Fpingyam-rb/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/dohliam","download_url":"https://codeload.github.com/dohliam/pingyam-rb/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244814976,"owners_count":20514859,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cantonese","cantonese-language","cantonese-romanization","chinese-romanization","conversion","ipa","jyutping","pingyam","pinyin-conversion","romanization-systems","yale-transcription"],"created_at":"2024-10-13T22:42:38.285Z","updated_at":"2025-03-21T14:30:18.103Z","avatar_url":"https://github.com/dohliam.png","language":"Ruby","funding_links":[],"categories":[],"sub_categories":[],"readme":"# pingyam-rb - Cantonese romanization conversion in Ruby\n\nThis repository contains a Ruby library and example conversion tool that makes use of the open-licensed [Pingyam Database](https://github.com/kfcd/pingyam) to convert between 11 different Cantonese romanization systems and variants.\n\n* [1 Features](#features)\n* [2 Included romanization systems](#included-romanization-systems)\n* [3 Requirements](#requirements)\n* [4 Usage](#usage)\n  * [4.1 lib_pingyam](#lib_pingyam)\n    * [4.1.1 converting syllables](#converting-syllables)\n  * [4.2 convert_pingyam](#convert_pingyam)\n    * [4.2.1 Basic usage](#basic-usage)\n    * [4.2.2 Checking input validity](#checking-input-validity)\n    * [4.2.3 Modifying the output](#modifying-the-output)\n    * [4.2.4 Options](#options)\n* [5 To do](#to-do)\n* [6 See also](#see-also)\n* [7 License](#license)\n\n## Features\n\n* Converts to and from any Cantonese romanization scheme (including IPA)\n* Can convert single and multiple words / whole lines of romanized text\n* Handles mixed input (non-Cantonese text is ignored)\n* Converter script ready to use on the command-line -- or include the library in your own code\n\n## Included romanization systems\n\nIn total 11 Cantonese romanization systems are available for conversion using this library. Each variant is identified by a number (`0-10`); this number is also used for identifying the \"to\" and \"from\" romanizations to use while converting text.\n\nIndex | Name | Chinese | Variant\n----- | ---- | ------- | -------\n`0` | [Yale](https://en.wikipedia.org/wiki/Yale_romanization_of_Cantonese) | 耶魯拼音 | Tone numbers\n`1` | Yale | | Tone diacritics\n`2` | [Cantonese Pinyin](https://en.wikipedia.org/wiki/Cantonese_Pinyin) | 教院拼音\n`3` | [S.L. Wong](https://en.wikipedia.org/wiki/S._L._Wong_(romanisation)) | 黃錫凌 | Tone numbers\n`4` | S.L. Wong | | Tone diacritics\n`5` | [International Phonetic Alphabet](https://en.wikipedia.org/wiki/International_Phonetic_Alphabet) | 國際音標\n`6` | [Jyutping](https://en.wikipedia.org/wiki/Jyutping) | 粵拼\n`7` | [Canton](https://en.wikipedia.org/wiki/Guangdong_Romanization#Cantonese) | 廣州拼音\n`8` | [Sidney Lau](https://en.wikipedia.org/wiki/Sidney_Lau_romanisation) | 劉錫祥\n`9` | [Penkyamp](http://cantonese.wikia.com/wiki/Penkyamp) | 粵語拼音字 | Tone numbers\n`10` | Penkyamp | | Tone diacritics\n\nNote: A modified 9-tone Yale system is used by default. However, this library includes a method to convert the Yale transcription to the more traditional 6-tone system (see [below](#modifying-the-output) for details).\n\n## Requirements\n\nThis library makes use of the latest version of the [Pingyam database](https://github.com/kfcd/pingyam), and expects a file called `pingyambiu` containing the conversion data to be located in a `pingyam` folder in the project root directory. There a number of ways to do this:\n\n* _Easiest method_: Run the `update_database.rb` script to get the latest version of the script\n  * Instructions: In the project root directory, enter the following command: `./update_database.rb`\n  * If the current version of the database is different than the one on your machine, your local copy will be updated\n* Download the file directly from the Pingyam project [here](https://github.com/kfcd/pingyam/blob/master/pingyambiu).\n  * Make sure to create a directory called `pingyam` in the project root and copy the file to that directory\n* If you have `git` installed, you can clone the database into the root project folder using the following command: `git clone https://github.com/kfcd/pingyam.git\n* Download the Pingyam project into a separate location and create a symlink in the current project directory\n\nThere are no other special requirements other than a working version of Ruby.\n\n## Usage\n\nThis project can be used either as a library (`lib_pingyam.rb`) or as a command-line script (`convert_pingyam.rb`). Details for both types of usage can be found below.\n\n### lib_pingyam\n\nTo use the library, make sure to `require` the library file, e.g.:\n\n```ruby\nrequire_relative 'lib_pingyam.rb'\n```\n\nBefore you can convert text, you need to initialize a `Converter` object:\n\n```ruby\nconv = Converter.new\n```\n\nBy default, this initializes a conversion dictionary that works from Yale to any other romanization system.\n\nTo use a different source romanization system, just specify the corresponding index number as an argument when initializing the `Converter` object, e.g.:\n\n```ruby\nconv = Converter.new(6)\n# =\u003e This converts from Jyutping to any other system\n```\n\nYou can then convert any string of text using the `convert_line` method, which takes a string and an integer representing the target romanization system as arguments:\n\n```ruby\npingyam = \"Yale to Jyutping conversion: yut9 yu5 jyun2 wun6\"\nputs conv.convert_line(pingyam, 6)\n# =\u003e Yale to Jyutping conversion: jyut6 jyu5 zyun2 wun6\n```\n\nTip: If you provide `11` as the index number when converting, the string will be translated into all of the available systems sequentially, e.g.:\n\n```ruby\npingyam = \"yut9 yu5 ping3 yam1 fong1 on3 yat7 laam4\"\nputs conv.convert_line(pingyam, 11)\n# =\u003e yut9 yu5 ping3 yam1 fong1 on3 yat7 laam4 \n# =\u003e yuht yúh ping yām fōng on yāt làahm \n# =\u003e jyt9 jy5 ping3 jam1 fong1 on3 jat7 laam4 \n# =\u003e jyt⁹ jy⁵ pɪŋ³ jɐm¹ fɔŋ¹ ɔn³ jɐt⁷ lam⁴ \n# =\u003e _jyt ˏjy ¯pɪŋ 'jɐm 'fɔŋ ¯ɔn 'jɐt ˌlam \n# =\u003e jyːt˨ jyː˩˧ pʰɪŋ˧ jɐm˥ fɔːŋ˥ ɔːn˧ jɐt˥ laːm˨˩ \n# =\u003e jyut6 jyu5 ping3 jam1 fong1 on3 jat1 laam4 \n# =\u003e yud6 yu5 ping3 yem1 fong1 on3 yed1 lam4 \n# =\u003e yuet⁶ yue⁵ ping³ yam¹ fong¹ on³ yat¹ laam⁴ \n# =\u003e yeud6 yeu5 penk3 yamp1 fong1 on3 yat1 lam4 \n# =\u003e yeùd yeú pênk yämp föng ôn yät lam\n```\n\nThe `Converter` class has a built-in method for checking if a given string is a valid syllable in any of the available Cantonese romanization systems:\n\n```ruby\nconv = Converter.new\n# checks against syllables in Yale (numerals) by default\n\nword = \"heung1\"\nputs conv.check_syllable(word)\n# =\u003e true\n\nword = \"heungg1\"\nputs conv.check_syllable(word)\n# =\u003e false\n```\n\nTo check syllables in any other romanization system, just specify it when initializing the `Converter` class:\n\n```ruby\nconv = Converter.new(6)\n# checks valid Jyutping syllables\n\nword = \"heung1\"\nputs conv.check_syllable(word)\n# =\u003e false\n\nword = \"hoeng1\"\nputs conv.check_syllable(word)\n# =\u003e true\n```\n\n#### converting syllables\n\nYou can convert individual syllables using the `convert_syllable` method of the `Converter` class. This method requires two arguments: a string consisting of a single romanized syllable and an integer representing the index number of the target romanization system.\n\nFor example, to convert a syllable in Yale into IPA:\n\n```ruby\nconv = Converter.new\np conv.convert_syllable(\"heung1\", 5)\n# =\u003e \"hœːŋ˥\"\n```\n\nTo convert from a different source transcription system, just provide the corresponding index number when initializing the Converter object.\n\nFor example, to convert Jyutping into IPA:\n\n```ruby\n@conv = Converter.new(6)\np @conv.convert_syllable(\"hoeng1\", 5)\n# =\u003e \"hœːŋ˥\"\n```\n\nIf `11` is passed as the final argument to the `convert_syllable` method, it will return an array containing all of the possible transcriptions of the given syllable:\n\n```ruby\nconv = Converter.new\np conv.convert_syllable(\"heung1\", 11)\n# =\u003e [\"heung1\", \"heūng\", \"hoeng1\", \"hœŋ¹\", \"'hœŋ\", \"hœːŋ˥\", \"hoeng1\", \"hêng1\", \"heung¹\", \"heong1\", \"heöng\"]\n```\n\n### convert_pingyam\n\nThe `convert_pingyam.rb` file found in the root directory is a simple script that demonstrates the use of the `lib_pingyam` library. It allows for quick and easy conversion between arbitrary Cantonese romanization systems on the command-line.\n\n#### Basic usage\n\n```bash\n./convert_pingyam.rb -i \"This is a test: Yut9 yu5 ping3 yam1 jyun2 wun6\"\n# =\u003e This is a test: yuht yúh ping yām jyún wuhn\n```\n\nThe above example converts the Cantonese romanization in the provided sentence from Yale (with numerals) into Yale with diacritics. All of the text that is not recognizable as Cantonese romanization (e.g., all of the English text before the colon in the provided sentence) is ignored.\n\nTo convert the text into Jyutping instead, just provide the index number for Jyutping (i.e., `6` -- see [list above](#included-romanization-systems)) using the `-t` (`--target`) option:\n\n```bash\n./convert_pingyam.rb -i \"This is a test: Yut9 yu5 ping3 yam1 jyun2 wun6\" -t 6\n# =\u003e This is a test: jyut6 jyu5 ping3 jam1 zyun2 wun6\n```\n\nAs can be seen, the text has now been converted into Jyutping romanization. Conversion into other systems is equally easy -- just replace `6` above with the index number of the system you wish to use for output.\n\nTo convert from a different source romanization system (e.g., to convert from Jyutping to Yale, or from S.L. Wong to Jyutping), provide the source system index number as a parameter using the `-s` (`--source`) option. The example below converts from Jyutping to Yale with diacritics:\n\n```bash\n./convert_pingyam.rb -i \"This is a test: jyut6 jyu5 ping3 jam1 zyun2 wun6\" -s 6 -t 1\n# =\u003e This is a test: yuht yúh ping yām jyún wuhn\n```\n\n#### Checking input validity\n\nInvalid romanization syllables can be identified using the `-c` (`--check`) option. This checks each word in the input string and outputs a list of words that are not recognizable as valid Cantonese syllables in the given romanization system:\n\n```bash\n./convert_pingyam.rb -i \"This is a test: Yut9 yu5 ping3 yam1 jyun2 wun6\" -c\n# =\u003e This\n# =\u003e is\n# =\u003e a\n# =\u003e test:\n```\n\nThe output in the above example contains words that are not valid syllables in Yale romanization (the default, since no other system was specified). To use a different romanization system just provide the appropriate index number using the `-s` option. For example, the command below checks for invalid syllables in Jyutping:\n\n```bash\n./convert_pingyam.rb -i \"This is a test: Yut9 yu5 ping3 yam1 jyun2 wun6\" -c -s 6\n# =\u003e This\n# =\u003e is\n# =\u003e a\n# =\u003e test:\n# =\u003e Yut9\n# =\u003e yu5\n# =\u003e yam1\n```\n\nIn the example above, the output contains apart from English the Yale syllables `Yut9`, `yu5`, and `yam1`, because these are not valid syllables in Jyutping.\n\n#### Modifying the output\n\nThe output transcription can be further modified using optional command-line flags, for example to convert regular tone numerals to superscript numerals (Unicode), or to revert to the traditional 6-tone Yale system.\n\n* **Superscript numerals**: Several romanization systems use numerals to indicate tones in Cantonese. These are often represented in superscript form to increase readability of romanized text. To use superscript numerals, use the `-S` (`--superscript`) option with any numeral-using transcription system. For example, this will convert `siu2 chak7 si3` to `siu² chak⁷ si³`.\n* **Yale normalization**: To use the older 6-tone Yale transcription instead of the default 9-tone modified version, use the `-Y` (`--yale`) option. For example, this will convert `yat7 jek8 kek9` to `yat1 jek3 kek6`.\n\nThese modifications can be combined -- the example below both normalizes the Yale transcription and converts the numerals to superscript:\n\n```bash\n./convert_pingyam.rb -i \"yat7 jek8 kek9\" -t 0 -YS\n# =\u003e yat¹ jek³ kek⁶\n```\n\n#### Options\n\nThe following options can be provided to `convert_pingyam.rb` to control the conversion process:\n\n* `-c`, `--check`: _Check if input contains invalid Cantonese romanization_\n* `-i`, `--input STRING`: _Input string to be converted_\n* `-f`, `--filename FILE`: _Provide file for conversion_\n* `-s`, `--source INDEX`: _Provide index number of romanization to convert from_\n* `-S`, `--superscript`: _Print tone numerals as superscript_\n* `-t`, `--target INDEX`: _Provide index number of romanization to convert into_\n* `-Y`, `--yale`: _Normalize Yale to 6-tone traditional system_\n\n## To do\n\n* ~~Support for traditional 6-tone Yale (with numerals)~~\n* ~~Conversion of tone numbers to superscript~~\n* Optional HTML output\n* Handle ~~files and~~ pipes as input\n\n## See also\n\n* [Pingyam database](https://github.com/kfcd/pingyam)\n* [pingyam-js](https://github.com/dohliam/pingyam-js) - Online Cantonese Romanization Converter\n* [pinyin-rb](https://github.com/dohliam/pinyin-rb) - Mandarin Chinese transcription conversion in Ruby\n\n## License\n\n* Romanization data: [CC BY](https://github.com/kfcd/pingyam/blob/master/LICENSE)\n* All other code: [MIT](LICENSE)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdohliam%2Fpingyam-rb","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdohliam%2Fpingyam-rb","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdohliam%2Fpingyam-rb/lists"}