diff --git a/README.textile b/README.textile index 43078325..ad02b0c2 100644 --- a/README.textile +++ b/README.textile @@ -36,177 +36,34 @@ With Bundler: Append @gem 'phony'@ to your @Gemfile@ and @bundle install@ it. Without Bundler: Run @gem install phony@ from your command line. -h2(#usage). Usage +h2(#usage). Usage docs -h3(#normalizing). Normalizing +Phony uses "qed":https://github.com/rubyworks/qed as docs and to run its functional tests. Start here for usage docs: "Usage index":"./qed/index.md" -This will often raise an error if you try normalizing a non E164-izable number (a number that does not contain enough information to be normalized into an E164 conform number). Use @Phony.plausible?@ for checking if it can be normalized first. +h3(#normalizing). Phony.normalize(number) -Example: - -@Phony.normalize('364 35 33')@ No. Wrong. Nada. - -Always use it with a country code, as Phony needs it to know what country to normalize for: - -@Phony.normalize('41443643533').should == '41443643533'@ - -@Phony.normalize('+41 44 364 35 33').should == '41443643533'@ - -@Phony.normalize('+41 44 364 35 33').should == '41443643533'@ - -@Phony.normalize('+41 800 11 22 33').should == '41800112233'@ - -@Phony.normalize('John: +41 44 364 35 33').should == '41443643533'@ - -@Phony.normalize('1 (703) 451-5115').should == '17034515115'@ +"Phony.normalize docs":./qed/normalize.md @Phony.normalize('1-888-407-4747').should == '18884074747'@ -@Phony.normalize('1.906.387.1698').should == '19063871698'@ - -@Phony.normalize('+41 (044) 364 35 33').should == '41443643533'@ +h3(#formatting). Phony.format(number, options = {}) -h3(#formatting). Formatting - -Aliased as @Phony.formatted(number_string)@. - -You really need to give it a normalized phone number WITH country code, so: - -@Phony.format('3643532')@ This does not work. - -These, however, are splendid: +"Phony.format docs":./qed/format.md @Phony.format('41443643532').should == '+41 44 364 35 32'@ -@Phony.format('41800112233').should == '+41 800 11 22 33'@ - -@Phony.format('43198110').should == '+43 1 98110'@ - -@Phony.format('18705551122').should == '+1 870 555 1122'@ - -h4(#international). International - -@Phony.format('18091231234', :format => :international).should == '+1 (809) 123-1234'@ - -@Phony.format('43198110', :format => :international).should == '+43 1 98110'@ - -@Phony.format('43198110', :format => :international_absolute).should == '+43 1 98110'@ - -@Phony.format('33142278186', :format => :+).should == '+33 1 42 27 81 86'@ - -@Phony.format('43198110', :format => :international_relative).should == '0043 1 98110'@ - -@Phony.format('4233841148', :format => :international_relative).should == '00423 384 11 48'@ - -h4(#national). National - -@Phony.format('41443643532', :format => :national).should == '044 364 35 32'@ - -@Phony.format('41800112233', :format => :national).should == '0800 11 22 33'@ - -@Phony.format('43198110', :format => :national).should == '01 98110'@ - -h4(#local). Local - -@Phony.format('41443643532', :format => :local).should == '364 35 32'@ - -@Phony.format('493038625454', :format => :local).should == '386 25454'@ - -h4(#spaces). With spaces - -Option @spaces@: - -@Phony.format('18091231234', :format => :international, :spaces => '').should == '+1(809)1231234'@ - -@Phony.format('43198110', :format => :international, :spaces => '').should == '+43198110'@ - -@Phony.format('43198110', :format => :international_absolute, :spaces => '').should == '+43198110'@ - -@Phony.format('33142278186', :format => :+, :spaces => '').should == '+33142278186'@ +h3(#plausibility). Phony.plausible?(number, options = {}) -@Phony.format('43198110', :format => :international_relative, :spaces => '').should == '0043198110'@ - -@Phony.format('4233841148', :format => :international_relative, :spaces => '').should == '004233841148'@ - -@Phony.format('18091231234', :format => :international, :spaces => :-).should == '+1-(809)-123-1234'@ - -@Phony.format('43198110', :format => :international, :spaces => :-).should == '+43-1-98110'@ - -@Phony.format('43198110', :format => :international_absolute, :spaces => :-).should == '+43-1-98110'@ - -@Phony.format('33142278186', :format => :+, :spaces => :-).should == '+33-1-42-27-81-86'@ - -@Phony.format('43198110', :format => :international_relative, :spaces => :-).should == '0043-1-98110'@ - -@Phony.format('4233841148', :format => :international_relative, :spaces => :-).should == '00423-384-11-48'@ - -Option @local_spaces@: - -@Phony.format("33142278186", :format => :international, :local_spaces => :-).should == '+33 1 42-27-81-86'@ - -h3(#plausibility). Plausibility - -"Plausible" means "seems reasonable or probable", not implying 100% correctness on a @true@ or @false@ return value. A @false@ value is usually closer to the truth. - -Use this method in combination with @normalize@ for saving it into the database. Also see https://github.com/floere/phony/issues/35 for a discussion on the topic. - -Note that you can add constraints to the plausibility check like the country code, @cc@, and the national destination code, @ndc@. Use the options to further limit the plausibility range. For example, only allow a small number of countries. - -Examples: +"Phony.plausible? docs":./qed/plausibility.md @Phony.plausible?('+41 44 111 22 33').should be_true@ -@Phony.plausible?('0000000').should be_false@ - -@Phony.plausible?('hello').should be_false@ - -With options: - -@Phony.plausible?('+41 44 111 22 33', cc: '41').should be_true@ - -@Phony.plausible?('+41 44 111 22 33', ndc: '44').should be_true@ +h3(#splitting). Phony.split(number) -@Phony.plausible?('+41 44 111 22 33', cc: '1').should be_false@ - -@Phony.plausible?('+41 44 111 22 33', ndc: '43').should be_false@ - -@Phony.plausible?('+41 44 111 22 33', cc: '41', ndc: '44').should be_true@ - -@Phony.plausible?('+41 44 111 22 33', cc: /4(0|2)/, ndc: /4(4|5)/).should be_false@ - -@Phony.plausible?('+41 44 111 22 33', cc: /4(0|1)/, ndc: /4(4|5)/).should be_true@ - -h3(#splitting). Splitting - -@Phony.split(international_number)@ splits a normalised int'l number into its components, like so: -[CC, NDC, LOCAL1, LOCAL2, …, LOCALN]. - -You really need to give it a normalized phone number WITH a country code, so: - -@Phony.split('3643532')@ This … no. - -Phony is happy with these: - -@Phony.split('43198110').should == ['43', '1', '98110']@ - -@Phony.split('33112345678').should == ['33', '1', '12','34','56','78']@ - -@Phony.split('4976112345').should == ['49', '761', '123', '45']@ +"Phony.split docs":./qed/split.md @Phony.split('3928061371').should == ['39', '2', '806', '1371']@ -@Phony.split('41443643532').should == ['41', '44', '364', '35', '32']@ - -@Phony.split('15551115511').should == ['1', '555', '111', '5511']@ - -@Phony.split('6491234567').should == ['64', '9', '123', '4567']@ - -@Phony.split('41800334455').should == ['41', '800', '33', '44', '55']@ - -Note: There is also a ! version of each of these methods which - will destroy the original string and return a new (or old) one. - Just work only with the returned value, and you will be fine. - h2. List of Handled Countries Currently handles Abhas, Afghan, Algerian, Argentinan, Austrian, Australian, Azerbaijani, Belgian, Brazilian, Cambodian, Chilean, Chinese, Croatian, Cuban, Cypriot, Czech, Danish, Dutch, Egyptian, El Salvadorian, Estonian, French, German, Ghanan, Gibraltar, Greek, Haiti, Hong Kong, Hungarian, Indian, Iran, Irish, Israel, Italian, Kazakh, Liberian, Lithuanian, Luxembourgian, Malaysian, Malta, Mexican, Monaco, Morocco, New Zealand, Nigerian, Norwegian, Peruvian, Polish, Romanian, Russian, Rwandan, Seychelles, Singapore, Slovakian, South African, South Korean, South Osetian, Spanish, Sri Lankan, Sudan, Swedish, Swiss, Thailand, Tunisian, Turkish, Liechtenstein, UK, US, Venezuelan, Vietnamese, and Zambian numbers. \ No newline at end of file