module Phony

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

Constants

EMPTY_STRING

Attributes

config[W]

Public Class Methods

[](cc) click to toggle source

Get the Country for the given CC.

@param [String] cc A valid country code.

@return [Country] for the given CC.

@example Country for the NANP (includes the US)

nanp = Phony['1']
normalized_number = nanp.normalize number
# File lib/phony.rb, line 126
def [](cc)
  @codes[cc]
end
config() click to toggle source
# File lib/phony/config.rb, line 8
def config
  # Default config includes all CCs.
  @config ||= Config.new([], [])
end
define(&block) click to toggle source

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 …

# File lib/phony/dsl.rb, line 16
def self.define(&block)
  dsl = DSL.new
  dsl.instance_eval(&block) if block_given?
  dsl
end
format(phone_number, options = {}) click to toggle source

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

Absolutely needs a normalized E164 number.

@param [String] phone_number A normalized E164 number. @param [Hash] options See the README for a list of options.

@return [Array<String>] The pieces of a phone number.

@example Format a Swiss number.

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

@example Format a NANP number.

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

@example Format a NANP number in local format.

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

@example Format a NANP number in a specific format.

Phony.format("13015550100", :format => '%{cc} (%{trunk}%{ndc}) %{local}') # => "555 0100"
# 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
Also aliased as: formatted
format!(phone_number, options = {}) click to toggle source

A destructive version of {#format}.

@see format

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

Absolutely needs a normalized E164 number.

@param [String] phone_number A normalized E164 number. @param [Hash] options See the README for a list of options.

@return [Array<String>] The pieces of the phone number.

@example Format a Swiss number.

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

@example Format a NANP number.

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

@example Format a NANP number in local format.

Phony.format!("13015550100", :format => :local) # => "555 0100"
# File lib/phony.rb, line 266
def format!(phone_number, options = {})
  @codes.format phone_number, options
rescue
  raise FormattingError.new
end
Also aliased as: formatted!
formatted(phone_number, options = {})
Alias for: format
formatted!(phone_number, options = {})
Alias for: format!
normalize(phone_number, options = {}) click to toggle source

Normalizes the given number into a digits-only String.

Useful before inserting the number into a database.

@param [String] phone_number An E164 number. @param [Hash] options An options hash (With :cc as the only used key).

@return [String] A normalized E164 number.

@raise [Phony::NormalizationError] If phony can’t normalize the given number.

@example Normalize a Swiss number.

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

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

Phony.normalize("301 555 0100", cc: '1') # => "13015550100"
# File lib/phony.rb, line 147
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 = {}) click to toggle source

A destructive version of {#normalize}.

@see normalize

@param [String] phone_number An E164 number. @param [Hash] options An options hash (With :cc as the only used key).

@return [String] The normalized E164 number.

@raise [Phony::NormalizationError] If phony can’t normalize the given number.

@example Normalize a Swiss number.

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

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

Phony.normalize!("301 555 0100", cc: '1') # => "13015550100"
# File lib/phony.rb, line 170
def normalize!(phone_number, options = {})
  @codes.normalize phone_number, options
rescue
  raise NormalizationError.new
end
plausible?(number, hints = {}) click to toggle source

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.

# File lib/phony.rb, line 280
def plausible?(number, hints = {})
  @codes.plausible? number, hints
end
split(phone_number) click to toggle source

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

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

@param [String] phone_number An E164 number.

@return [Array<String>] The pieces of a phone number.

@example Split a Swiss number.

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

@example Split a NANP number.

Phony.split("13015550100") # => ["1", "301", "555", "0100"]
# File lib/phony.rb, line 190
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) click to toggle source

A destructive version of {#split}.

@see split

@param [String] phone_number An E164 number.

@return [Array<String>] The pieces of the phone number.

@example Split a Swiss number.

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

@example Split a NANP number.

Phony.split!("13015550100") # => ["1", "301", "555", "0100"]
# 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) click to toggle source

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

# File lib/phony.rb, line 287
def vanity?(phone_number)
  @codes.vanity? phone_number.dup
end
vanity_to_number(vanity_number) click to toggle source

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.

@param [String] vanity_number A vanity number.

@return [String] The de-vanitized phone number.

@example De-vanitize a number.

Phony.vanity_to_number("1-800-HELLOTHERE") # => "1-800-4355684373"
# File lib/phony.rb, line 301
def vanity_to_number(vanity_number)
  @codes.vanity_to_number vanity_number.dup
end