README.md

# Phone
[![Build Status](https://travis-ci.org/fcevado/phone.svg?branch=master)](https://travis-ci.org/fcevado/phone)
[![Phone version](https://img.shields.io/hexpm/v/phone.svg)](https://hex.pm/packages/phone)
[![Inline docs](http://inch-ci.org/github/fcevado/phone.svg?branch=master)](http://inch-ci.org/github/fcevado/phone)
[![Hex.pm](https://img.shields.io/hexpm/dt/phone.svg)](https://hex.pm/packages/phone)
[![GitHub issues](https://img.shields.io/github/issues/fcevado/phone.svg)](https://github.com/fcevado/phone/issues)
[![GitHub license](https://img.shields.io/badge/license-Apache%202-blue.svg)](https://raw.githubusercontent.com/fcevado/phone/master/LICENSE)

Phone number parser for numbers in international standard for Elixir.

## About
What is, what isnt and what will be about Phone:
  1. It isnt:
    * Intended to work as libphonenumber.
    * Prepared to format numbers.
    * Necessary any information about the number if in international standard.
  2. It is:
    * A real parser, created to extract information based only in the number.
  3. It will be:
    * Prepared to work with numbers not only in the international standard.
    * Prepared for internationalization.

  * Patterns:
    * Countries without area code info:
        ```
        %{
          country: "Country Name",
          a2: "Alpha-2",
          a3: "Alpha-3",
          international_code: "1",
          area_code: "yyy",
          number: "xxxxxxx"
        }
        ```

    * Countries with area code info:
        ```
        %{
          country: "Country Name",
          a2: "Alpha-2 code",
          a3: "Alpha-3 code",
          international_code: "1",
          number: "xxxxxxx",
          area_code: "yyy",
          area_name: "Area Name",
          area_type: "state",
          area_abbreviation: "AN"
        }
        ```

## Vocabulary
  * a2: Alpha-2, two letters code for country names.
  * a3: Alpha-3, three letters code for country names.
  * NANP: North American Numbering Plan, numbering plan for countries with international code number 1.
  * Numbering Plan: The rules and specifications of how telephone numbers works in a given country.

## Installation
Add to your depencies like any other hex package.
```
{:phone, "0.1.1"}
```

## Contributing
There are may ways you can help this project grow, like:
  * Create an issue if you find any inconsistency with our parsing. If possible give us official information about the numbering plan of your country.
  * Create a PR adding area code info for a country that is missing.

Since for this project that would be a lot of repeating code, there is some helpers for creating a country module and a area.

Required fields for an area module:
  * regex, with the full regex for identifing that area number.
  * area_name, with the full area name.
  * area_type, the kind of area in that given country, it could be a state, province, territory, etc.
  * area_abbreviation, the abbreviation for the area name.
```
  defmodule Phone.NANP.CA.AB do
    use Helper.Area
    field :regex, ~r/^(1)(403|780|587)([2-9].{6})/
    field :area_name, "Alberta"
    field :area_type, "province"
    field :area_abbreviation, "AB"
    builder
  end
```

Required fields for an country module:
  * regex, with the full regex for identifing that country. Not needed if has area modules.
  * country, with the full country name.
  * a2, two letter code for that country.
  * a3, three letter code for that country.
  * modules, list of area modules for that country.
  * match, a macro to say if that country should match against regex or the list of area modules.
```
  defmodule Phone.NANP.AG do
    use Helper.Country
    field :regex, ~r/^(1)(268)([2-9].{6})/
    field :country, "Antigua and Barbuda"
    field :a2, "AG"
    field :a3, "ATG"
    match :regex
  end
```
```
  defmodule Phone.NANP.CA do
    use Helper.Country
    field :country, "Canada"
    field :a2, "CA"
    field :a3, "CAN"
    field :modules, [
      Phone.NANP.CA.AB,
      Phone.NANP.CA.BC,
      Phone.NANP.CA.MB,
      Phone.NANP.CA.NB,
      Phone.NANP.CA.NL,
      Phone.NANP.CA.NS_PE,
      Phone.NANP.CA.ON,
      Phone.NANP.CA.QC,
      Phone.NANP.CA.SK,
      Phone.NANP.CA.Territory
    ]
    match :modules
  end
```


##[Changelog](./CHANGELOG.md)

##[Code of Conduct](./CODE_OF_CONDUCT.md)

## License
Phone is under Apache v2.0 license. Check the [LICENSE](./LICENSE) file for more details.