Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Newer
Older
100644 117 lines (88 sloc) 3.984 kb
eb6e6e8 Tomislav Car Renamed library to 'Phone'. Updated Readme and all
authored
1 = Phone
d0145f5 Tomislav Car Expanded to cover all countries
authored
2 Parsing, validating and creating phone numbers
1dcc706 Tomislav Car Initial commit
authored
3
b86aca8 Tomislav Car Readme and license updates
authored
4 == Install
5 You can install the phone library as a gem
6 gem sources -a http://gemcutter.org
6e91504 Tomislav Car Instructions for pulling and installing carr/phone gem and plugin
authored
7 gem install phone
b86aca8 Tomislav Car Readme and license updates
authored
8
9 Or as a Rails plugin
6e91504 Tomislav Car Instructions for pulling and installing carr/phone gem and plugin
authored
10 script/plugin install git://github.com/carr/phone.git
1dcc706 Tomislav Car Initial commit
authored
11
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
12 == Updates in v 1.0
13
14 The biggest updating is the namespacing problem fixed that a lot of people were having. You now use phone by refering to
15
16 Phoner::Phone
17
1dcc706 Tomislav Car Initial commit
authored
18 == Initializing
714590c [Enhancement] Support for extensions
Michael Lee Squires authored
19 You can initialize a new phone object with the number, area code, country code and extension number
d0145f5 Tomislav Car Expanded to cover all countries
authored
20
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
21 Phoner::Phone.new('5125486', '91', '385')
1dcc706 Tomislav Car Initial commit
authored
22 or
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
23 Phoner::Phone.new(:number => '5125486', :area_code => '91', :country_code => '385', :extension => '143')
1dcc706 Tomislav Car Initial commit
authored
24
25 == Parsing
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
26 You can create a new phone object by parsing from a string. Phoner::Phone does it's best to detect the country and area codes:
27 Phoner::Phone.parse '+385915125486'
28 Phoner::Phone.parse '00385915125486'
1dcc706 Tomislav Car Initial commit
authored
29
d0145f5 Tomislav Car Expanded to cover all countries
authored
30 If the country or area code isn't given in the string, you must set it, otherwise it doesn't work:
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
31 Phoner::Phone.parse '091/512-5486', :country_code => '385'
32 Phoner::Phone.parse '(091) 512 5486', :country_code => '385'
1dcc706 Tomislav Car Initial commit
authored
33
b86aca8 Tomislav Car Readme and license updates
authored
34 If you feel that it's tedious, set the default country code once (in your config/environment.rb):
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
35 Phoner::Phone.default_country_code = '385'
36 Phoner::Phone.parse '091/512-5486'
37 Phoner::Phone.parse '(091) 512 5486'
1dcc706 Tomislav Car Initial commit
authored
38
39 Same goes for the area code:
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
40 Phoner::Phone.parse '451-588', :country_code => '385', :area_code => '47'
1dcc706 Tomislav Car Initial commit
authored
41 or
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
42 Phoner::Phone.default_country_code = '385'
43 Phoner::Phone.default_area_code = '47'
1dcc706 Tomislav Car Initial commit
authored
44
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
45 Phoner::Phone.parse '451-588'
1dcc706 Tomislav Car Initial commit
authored
46
d0145f5 Tomislav Car Expanded to cover all countries
authored
47 === Automatic country and area code detection
48 Like it's stated above, Phone does it's best to automatically detect the country and area code while parsing. Do do this,
0cc6414 Tomislav Car Updated Readme
authored
49 phone uses data stored in <tt>data/countries.yml</tt>.
d0145f5 Tomislav Car Expanded to cover all countries
authored
50
51 Each country code can have a regular expression named <tt>area_code</tt> that describes how the area code for that
52 particular country looks like.
53
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
54 If an <tt>area_code</tt> regular expression isn't specified, the default, <tt>Phoner::Phone::DEFAULT_AREA_CODE</tt> (correct for
d0145f5 Tomislav Car Expanded to cover all countries
authored
55 the US) is used.
56
1dcc706 Tomislav Car Initial commit
authored
57 == Validating
b86aca8 Tomislav Car Readme and license updates
authored
58 Validating is very relaxed, basically it strips out everything that's not a number or '+' character:
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
59 Phoner::Phone.valid? 'blabla 091/512-5486 blabla'
1dcc706 Tomislav Car Initial commit
authored
60
61 == Formatting
d0145f5 Tomislav Car Expanded to cover all countries
authored
62 Formating is done via the <tt>format</tt> method. The method accepts a <tt>Symbol</tt> or a <tt>String</tt>.
63
64 When given a string, it interpolates the string with the following fields:
1dcc706 Tomislav Car Initial commit
authored
65
66 * %c - country_code (385)
67 * %a - area_code (91)
68 * %A - area_code with leading zero (091)
69 * %n - number (5125486)
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
70 * %f - first @@n1_length characters of number (configured through Phoner::Phone.n1_length), default is 3 (512)
714590c [Enhancement] Support for extensions
Michael Lee Squires authored
71 * %l - last characters of number (5486)
72 * %x - the extension number
1dcc706 Tomislav Car Initial commit
authored
73
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
74 pn = Phoner::Phone.parse('+385915125486')
1dcc706 Tomislav Car Initial commit
authored
75 pn.to_s # => "+385915125486"
76 pn.format("%A/%f-%l") # => "091/512-5486"
77 pn.format("+ %c (%a) %n") # => "+ 385 (91) 5125486"
d0145f5 Tomislav Car Expanded to cover all countries
authored
78
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
79 When given a symbol it is used as a lookup for the format in the <tt>Phoner::Phone.named_formats</tt> hash.
f923cce Tomislav Car Update for US format. Updated Readme. Hungary number bug fix
authored
80 pn.format(:europe) # => "+385 (0) 91 512 5486"
81 pn.format(:us) # => "(234) 123 4567"
714590c [Enhancement] Support for extensions
Michael Lee Squires authored
82 pn.format(:default_with_extension) # => "+3851234567x143"
d0145f5 Tomislav Car Expanded to cover all countries
authored
83
84 You can add your own custom named formats like so:
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
85 Phoner::Phone.named_formats[:short] = '%A/%n1-%n2'
f923cce Tomislav Car Update for US format. Updated Readme. Hungary number bug fix
authored
86 pn.format(:short) # => 091/512-5486
d0145f5 Tomislav Car Expanded to cover all countries
authored
87
88 = TODO
acd893e Don Morrison Update README to reflect current state of country tests
elskwid authored
89 Parse testing for different countries.
90
91 Currently tested on:
7d3e997 Don Morrison Add Australia area code formatting and tests
elskwid authored
92 [AU] Australia
acd893e Don Morrison Update README to reflect current state of country tests
elskwid authored
93 [BA] Bosnia and Herzegovina
d868d6f Don Morrison Add Belgium area code formatting and tests
elskwid authored
94 [BE] Belgium
acd893e Don Morrison Update README to reflect current state of country tests
elskwid authored
95 [DE] Germany
96 [FR] France
97 [GB] United Kingdom
98 [HR] Croatia
99 [HU] Hungary
b7dbe9d Don Morrison Add Netherlands area code formatting and tests
elskwid authored
100 [NL] Netherlands
acd893e Don Morrison Update README to reflect current state of country tests
elskwid authored
101 [RS] Serbia
102 [SE] Sweden
103 [SI] Slovenia
104 [UA] Ukraine
105 [US] United States
106 [ZA] South Africa
107
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
108 = Known issues
109 There's an issue with Germany and area codes.
110
b86aca8 Tomislav Car Readme and license updates
authored
111 = Author
4592f04 Tomislav Car Version 1.0 - fixed namespacing
authored
112 Copyright © 2010 Tomislav Car, {Infinum}[http://www.infinumdigital.com]
9a8c3d0 Todd Eichel Give myself some credit in the readme, and change gemspec references.
tfe authored
113
7403710 Tomislav Car Updated readme with contributors
authored
114 = Contributors
33fa139 Tomislav Car Updated Readme with credits to elskwid and bumped up gem version
authored
115 Don Morrison, Michael Squires, Todd Eichel (Fooala, Inc.), chipiga, Etienne Samson, Luke Randall
9a8c3d0 Todd Eichel Give myself some credit in the readme, and change gemspec references.
tfe authored
116
Something went wrong with that request. Please try again.