module Phony
Phony
is the main module and is generally used to process E164 phone numbers directly.
Constants
- EMPTY_STRING
Public Class Methods
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 15 def self.define dsl = DSL.new dsl.instance_eval(&Proc.new) if block_given? dsl end
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 206 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
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 232 def format! phone_number, options = {} @codes.format phone_number, options end
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 122 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
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 143 def normalize! phone_number, options = {} @codes.normalize phone_number, options rescue raise NormalizationError.new end
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 244 def plausible? number, hints = {} @codes.plausible? number, hints end
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 163 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 end
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 181 def split! phone_number @codes.split phone_number end
Returns true if there is a character in the number after the first four numbers.
# File lib/phony.rb, line 251 def vanity? phone_number @codes.vanity? phone_number.dup end
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 265 def vanity_to_number vanity_number @codes.vanity_to_number vanity_number.dup end