From bcb9e68f553d1d75d63eeb00d99c66d8908b652f Mon Sep 17 00:00:00 2001 From: Wilson Mun <30316250+wmundev@users.noreply.github.com> Date: Tue, 26 Mar 2024 10:38:14 +1100 Subject: [PATCH] docs: update with concrete examples on how to use the library and various readme updates (#238) * docs: update with concrete examples on how to use the library * docs: add contributing guide --- .../default_pull_request_template.md | 2 + CONTRIBUTING.md | 32 +++++ README.md | 130 +++++++++++++++--- 3 files changed, 142 insertions(+), 22 deletions(-) create mode 100644 .github/PULL_REQUEST_TEMPLATE/default_pull_request_template.md create mode 100644 CONTRIBUTING.md diff --git a/.github/PULL_REQUEST_TEMPLATE/default_pull_request_template.md b/.github/PULL_REQUEST_TEMPLATE/default_pull_request_template.md new file mode 100644 index 000000000..6868bc9a7 --- /dev/null +++ b/.github/PULL_REQUEST_TEMPLATE/default_pull_request_template.md @@ -0,0 +1,2 @@ +## Changes +- diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 000000000..f919d5fb1 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,32 @@ +# Contributing to libphonenumber-csharp + +Thank you for considering contributing to libphonenumber-csharp! You can contribute to libphonenumber-csharp with issues and PRs. + +Simply filing issues for problems you encounter or contributing any implementation of an issue is greatly appreciated. + +### Suggested Workflow + +We use and recommend the following workflow: + +1. Create an issue for your work. + - You can skip this step for trivial changes. + - Reuse an existing issue on the topic, if there is one. + - For trivial changes, feel free to start work without an agreement from the maintainers. + - For slightly larger changes, you can reach out to the maintainers to discuss the change. + - Clearly state that you are going to take on implementing it if you are planning to, you can request that the issue be assigned to you. +2. Create a personal fork of the repository on GitHub (if you don't already have one). +3. In your fork, create a branch off of main (`git checkout -b mybranch`). + - Name the branch so that it clearly communicates your intentions, such as issue-123 or githubhandle-issue. +4. Make and commit your changes to your branch. +5. Add new tests corresponding to your change, if applicable. +6. Build the repository with your changes. + - Make sure that the builds are clean. + - Make sure that the tests are all passing, including your new tests. +7. Create a pull request (PR) against the **main** branch. + - State in the description what issue or improvement your change is addressing. + - Check if all the Continuous Integration checks are passing. +8. Wait for feedback or approval of your changes from the maintainers +9. Maintainers will merge once all checks are green and they are happy with the change + - The next official build will automatically include your change. + +Essentially, we are following trunk based development diff --git a/README.md b/README.md index 6b5fadd30..aab9a85de 100644 --- a/README.md +++ b/README.md @@ -12,38 +12,124 @@ See [this](csharp/README.md) for details about the port. Phone number metadata is updated in the Google repo approximately every two weeks. This library is automatically updated by a [scheduled github action](https://github.com/twcclegg/libphonenumber-csharp/actions/workflows/create_new_release_on_new_metadata_update.yml) to include the latest metadata, usually within a day. -## Example +## Installation -```cs - var phoneNumberUtil = PhoneNumbers.PhoneNumberUtil.GetInstance(); - var e164PhoneNumber = "+44 117 496 0123"; - var nationalPhoneNumber = "2024561111"; - var smsShortNumber = "83835"; - var phoneNumber = phoneNumberUtil.Parse(e164PhoneNumber, null); - phoneNumber = phoneNumberUtil.Parse(nationalPhoneNumber, "US"); - phoneNumber = phoneNumberUtil.Parse(smsShortNumber, "US"); +Run the following command to add this library to your project + +``` +dotnet add package libphonenumber-csharp +``` + +Available on NuGet as package [`libphonenumber-csharp`](https://www.nuget.org/packages/libphonenumber-csharp). + +## Examples + +### Parsing a phone number +```csharp +using PhoneNumbers; + +var phoneNumberUtil = PhoneNumberUtil.GetInstance(); +var e164PhoneNumber = "+44 117 496 0123"; +var nationalPhoneNumber = "2024561111"; +var smsShortNumber = "83835"; +var phoneNumber = phoneNumberUtil.Parse(e164PhoneNumber, null); +phoneNumber = phoneNumberUtil.Parse(nationalPhoneNumber, "US"); +phoneNumber = phoneNumberUtil.Parse(smsShortNumber, "US"); +``` + +### Formatting a phone number +```csharp +using PhoneNumbers; + +var phoneNumberUtil = PhoneNumberUtil.GetInstance(); +var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US"); +var formattedPhoneNumber = phoneNumberUtil.Format(phoneNumber, PhoneNumberFormat.INTERNATIONAL); +var formattedPhoneNumberNational = phoneNumberUtil.Format(phoneNumber, PhoneNumberFormat.NATIONAL); + +Console.WriteLine(formattedPhoneNumber.ToString()); // +1 415-666-7777 +Console.WriteLine(formattedPhoneNumberNational.ToString()); // (415) 666-7777 +``` + +### Check if a phone number is valid +```csharp +using PhoneNumbers; + +var phoneNumberUtil = PhoneNumberUtil.GetInstance(); +var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US"); +var isValid = phoneNumberUtil.IsValidNumber(phoneNumber); + +Console.WriteLine(isValid); // true +``` + +### Get the type of a phone number +```csharp +using PhoneNumbers; + +var phoneNumberUtil = PhoneNumberUtil.GetInstance(); +var phoneNumber = phoneNumberUtil.Parse("+14156667777", "US"); +var numberType = phoneNumberUtil.GetNumberType(phoneNumber); + +Console.WriteLine(numberType); // PhoneNumberType.FIXED_LINE_OR_MOBILE +``` + +See [PhoneNumberType.cs](csharp/PhoneNumbers/PhoneNumberType.cs) for the various possible types of phone numbers + +### Get the region code for a phone number +```csharp +using PhoneNumbers; + +var phoneNumberUtil = PhoneNumberUtil.GetInstance(); +var phoneNumber = phoneNumberUtil.Parse("+14156667777", null); +var regionCode = phoneNumberUtil.GetRegionCodeForNumber(phoneNumber); + +Console.WriteLine(regionCode); // US ``` ## Features - * Parsing/formatting/validating phone numbers for all countries/regions of the world. - * GetNumberType - gets the type of the number based on the number itself; able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers (whenever feasible). - * IsNumberMatch - gets a confidence level on whether two numbers could be the same. - * GetExampleNumber/GetExampleNumberByType - provides valid example numbers for 218 countries/regions, with the option of specifying which type of example phone number is needed. - * IsPossibleNumber - quickly guessing whether a number is a possible phonenumber by using only the length information, much faster than a full validation. - * AsYouTypeFormatter - formats phone numbers on-the-fly when users enter each digit. - * FindNumbers - finds numbers in text input +* Parsing/formatting/validating phone numbers for all countries/regions of the world. +* GetNumberType - gets the type of the number based on the number itself; able to distinguish Fixed-line, Mobile, Toll-free, Premium Rate, Shared Cost, VoIP and Personal Numbers (whenever feasible). +* IsNumberMatch - gets a confidence level on whether two numbers could be the same. +* GetExampleNumber/GetExampleNumberByType - provides valid example numbers for 218 countries/regions, with the option of specifying which type of example phone number is needed. +* IsPossibleNumber - quickly guessing whether a number is a possible phone number by using only the length information, much faster than a full validation. +* AsYouTypeFormatter - formats phone numbers on-the-fly when users enter each digit. +* FindNumbers - finds numbers in text input + +See [PhoneNumberUtil.cs](csharp/PhoneNumbers/PhoneNumberUtil.cs) for the various methods and properties available. ## ToDo - * port read/write source xml data to binary for better performance and smaller .nupkg size (WIP) - * update / add / port new unit tests and logging from java source +* port read / write source xml data to binary for better performance and smaller .nupkg size (WIP) +* update / add / port new unit tests and logging from java source ## How to unfold automatic generated files - * Install Jetbrains - Resharper for Visual Studio - * File by file, right click and "Cleanup code" - * Check the unfolded file -Available on NuGet as package [`libphonenumber-csharp`](https://www.nuget.org/packages/libphonenumber-csharp). +* Install Jetbrains - Resharper for Visual Studio +* File by file, right click and "Cleanup code" +* Check the unfolded file + +## Running tests locally + +To run tests locally, you will need a zip version of the `geocoding.zip` file stored in the `resources` folder +and `testgeocoding.zip` file stored in the `resources/test` folder. + +On linux, you can run the following commands to generate the zip accordingly + +```bash +(cd resources/geocoding; zip -r ../../resources/geocoding.zip *) +(cd resources/test/geocoding; zip -r ../../../resources/test/testgeocoding.zip *) +``` + +For windows, you can use the following powershell script + +```powershell +Compress-Archive -Path "resources\geocoding\*" -DestinationPath "resources\geocoding.zip" +Compress-Archive -Path "resources\test\geocoding\*" -DestinationPath "resources\test\testgeocoding.zip" +``` + +## Contributing +See [CONTRIBUTING.md](CONTRIBUTING.md) + +## Donations [![Buy me a beer](https://raw.githubusercontent.com/twcclegg/libphonenumber-csharp/main/bmacButton.png)](https://www.buymeacoffee.com/tclegg)