Module: Phony

Defined in:
lib/phony.rb,
lib/phony/dsl.rb,
lib/phony/config.rb,
lib/phony/vanity.rb,
lib/phony/country.rb,
lib/phony/trunk_code.rb,
lib/phony/country_codes.rb,
lib/phony/national_code.rb,
lib/phony/local_splitters/fixed.rb,
lib/phony/local_splitters/regex.rb,
lib/phony/national_splitters/dsl.rb,
lib/phony/national_splitters/none.rb,
lib/phony/national_splitters/fixed.rb,
lib/phony/national_splitters/regex.rb,
lib/phony/national_splitters/default.rb,
lib/phony/national_splitters/variable.rb

Overview

Phony is the main module and is generally used to process E164 phone numbers directly.

Defined Under Namespace

Modules: LocalSplitters, NationalSplitters, Vanity Classes: Config, Country, CountryCodes, DSL, FormattingError, NationalCode, NormalizationError, SplittingError, TrunkCode

Constant Summary collapse

EMPTY_STRING = 
''

Class Attribute Summary collapse

Class Method Summary collapse

Class Attribute Details

.config ⇒ Object 



9
10
11
12
 
# File 'lib/phony/config.rb', line 9

def config
  # Default config includes all CCs.
  @config ||= Config.new([], [])
end

Class Method Details

.[](cc) ⇒ Country

Get the Country for the given CC.

Examples:

Country for the NANP (includes the US)

nanp = Phony['1']
normalized_number = nanp.normalize number

Parameters:

  • cc (String) —

    A valid country code.

Returns:



128
129
130
 
# File 'lib/phony.rb', line 128

def [] cc
  @codes[cc]
end

.define(&block) ⇒ Object

For country definitions.

There are two styles: With or without block. Use the block if you have multiple.

Examples: Phony.define do

country ...

end

Phony.define.country …



15
16
17
18
19
 
# File 'lib/phony/dsl.rb', line 15

def self.define(&block)
  dsl = DSL.new
  dsl.instance_eval(&block) if block_given?
  dsl
end

.format(phone_number, options = {}) ⇒ Array<String> Also known as: formatted

Formats a normalized E164 number according to a country’s formatting scheme.

Absolutely needs a normalized E164 number.

Examples:

Format a Swiss number.

Phony.format("41441234567") # => "+41 44 123 45 67"

Format a NANP number.

Phony.format("13015550100") # => "+1 301 555 0100"

Format a NANP number in local format.

Phony.format("13015550100", :format => :local) # => "555 0100"

Format a NANP number in a specific format.

Phony.format("13015550100", :format => '%{cc} (%{trunk}%{ndc}) %{local}') # => "555 0100"

Parameters:

  • phone_number (String) —

    A normalized E164 number.

  • options (Hash) (defaults to: {}) —

    See the README for a list of options.

Returns:

  • (Array<String>) —

    The pieces of a phone number.

Raises:

  • (ArgumentError) 


238
239
240
241
 
# File 'lib/phony.rb', line 238

def format phone_number, options = {}
  raise ArgumentError, "Phone number cannot be nil. Use e.g. number && Phony.format(number)." unless phone_number
  format! phone_number.dup, options
end

.format!(phone_number, options = {}) ⇒ Array<String> Also known as: formatted!

A destructive version of #format.

Formats a normalized E164 number according to a country’s formatting scheme.

Absolutely needs a normalized E164 number.

Examples:

Format a Swiss number.

Phony.format!("41441234567") # => "+41 44 123 45 67"

Format a NANP number.

Phony.format!("13015550100") # => "+1 301 555 0100"

Format a NANP number in local format.

Phony.format!("13015550100", :format => :local) # => "555 0100"

Parameters:

  • phone_number (String) —

    A normalized E164 number.

  • options (Hash) (defaults to: {}) —

    See the README for a list of options.

Returns:

  • (Array<String>) —

    The pieces of the phone number.

See Also:

  • #format


264
265
266
267
268
 
# File 'lib/phony.rb', line 264

def format! phone_number, options = {}
  @codes.format phone_number, options
rescue
  raise FormattingError.new
end

.normalize(phone_number, options = {}) ⇒ String

Normalizes the given number into a digits-only String.

Useful before inserting the number into a database.

Examples:

Normalize a Swiss number.

Phony.normalize("+41 (044) 123 45 67") # => "41441234567"

Normalize a phone number assuming it’s a NANP number.

Phony.normalize("301 555 0100", cc: '1') # => "13015550100"

Parameters:

  • phone_number (String) —

    An E164 number.

  • options (Hash) (defaults to: {}) —

    An options hash (With :cc as the only used key).

Returns:

  • (String) —

    A normalized E164 number.

Raises:



149
150
151
152
153
 
# File 'lib/phony.rb', line 149

def normalize phone_number, options = {}
  raise ArgumentError, "Phone number cannot be nil. Use e.g. number && Phony.normalize(number)." unless phone_number
  
  normalize! phone_number.dup, options
end

.normalize!(phone_number, options = {}) ⇒ String

A destructive version of #normalize.

Examples:

Normalize a Swiss number.

Phony.normalize!("+41 (044) 123 45 67") # => "41441234567"

Normalize a phone number assuming it’s a NANP number.

Phony.normalize!("301 555 0100", cc: '1') # => "13015550100"

Parameters:

  • phone_number (String) —

    An E164 number.

  • options (Hash) (defaults to: {}) —

    An options hash (With :cc as the only used key).

Returns:

  • (String) —

    The normalized E164 number.

Raises:

See Also:

  • #normalize


171
172
173
174
175
 
# File 'lib/phony.rb', line 171

def normalize! phone_number, options = {}
  @codes.normalize phone_number, options
rescue
  raise NormalizationError.new
end

.plausible?(number, hints = {}) ⇒ Boolean

Makes a plausibility check.

If it returns false, it is not plausible. If it returns true, it is unclear whether it is plausible, leaning towards being plausible.

Returns:

  • (Boolean) 


278
279
280
 
# File 'lib/phony.rb', line 278

def plausible? number, hints = {}
  @codes.plausible? number, hints
end

.split(phone_number) ⇒ Array<String>

Splits the phone number into pieces according to the country codes.

Useful for manually processing the CC, NDC, and local pieces.

Examples:

Split a Swiss number.

Phony.split("41441234567") # => ["41", "44", "123", "45", "67"]

Split a NANP number.

Phony.split("13015550100") # => ["1", "301", "555", "0100"]

Parameters:

  • phone_number (String) —

    An E164 number.

Returns:

  • (Array<String>) —

    The pieces of a phone number.

Raises:

  • (ArgumentError) 


191
192
193
194
195
 
# File 'lib/phony.rb', line 191

def split phone_number
  raise ArgumentError, "Phone number cannot be nil. Use e.g. number && Phony.split(number)." unless phone_number
  
  split! phone_number.dup, phone_number
end

.split!(phone_number, error_number = nil) ⇒ Array<String>

A destructive version of #split.

Examples:

Split a Swiss number.

Phony.split!("41441234567") # => ["41", "44", "123", "45", "67"]

Split a NANP number.

Phony.split!("13015550100") # => ["1", "301", "555", "0100"]

Parameters:

  • phone_number (String) —

    An E164 number.

Returns:

  • (Array<String>) —

    The pieces of the phone number.

See Also:

  • #split


210
211
212
213
214
215
 
# File 'lib/phony.rb', line 210

def split! phone_number, error_number = nil
  @codes.split phone_number
rescue
  # NB The error_number (reference) is used because phone_number is destructively handled.
  raise SplittingError.new(error_number)
end

.vanity?(phone_number) ⇒ Boolean

Returns true if there is a character in the number after the first four numbers.

Returns:

  • (Boolean) 


285
286
287
 
# File 'lib/phony.rb', line 285

def vanity? phone_number
  @codes.vanity? phone_number.dup
end

.vanity_to_number(vanity_number) ⇒ String

Converts any character in the vanity_number to its numeric representation. Does not check if the passed number is a valid vanity_number, simply does replacement.

Examples:

De-vanitize a number.

Phony.vanity_to_number("1-800-HELLOTHERE") # => "1-800-4355684373"

Parameters:

  • vanity_number (String) —

    A vanity number.

Returns:

  • (String) —

    The de-vanitized phone number.



299
300
301
 
# File 'lib/phony.rb', line 299

def vanity_to_number vanity_number
  @codes.vanity_to_number vanity_number.dup
end