happy_phone_number 0.0.1 → 0.0.2

data/README.markdown

@@ -3,15 +3,24 @@ Happy Phone Number [![Build Status](https://travis-ci.org/lkdjiin/happy_phone_nu
 
 Description
 ----------------------
-A rails plugin to happily format phone numbers.
 
-**Early stage. Work in progress.**
+*Happy Phone Number* provides easy methods to format phone
+numbers from your Rails models. Virtually any country specific
+format or convention could be supported, including national and international
+format. For the not (yet) supported countries, a general method
+using a simple mask is also provided.
 
 Overview
 -----------------------
 
-Let's say you have a `Contact` model with a `phone` attribute. The phone number
-**must be save** without spaces, or hyphen, or dots...
+### Prerequisite
+
+  * Phone number **must be save** with digits only. So, without spaces, hyphens,
+    or dots. Just digits.
+
+### Demonstration
+
+Let's say you have a `Contact` model with a `phone` attribute.
 
 To display the phone number you could do this:
 
@@ -30,7 +39,7 @@ Or in uppercase if you prefer:
 
 If you want an international format:
 
-    <%= @contact.happy_phone(:international) %>
+    <%= @contact.happy_inter_phone(:fr) %>
     #=> "+33 1 23 45 67 89"
 
 What if you want dots as separator?
@@ -49,6 +58,29 @@ and `mobile`, or maybe `portable`?
     #=> "33 33 33 33 33"
     ...
 
+Now, imagine you live in Belgium, where phone numbers could have 2 formats:
+
+    <%= @contact.happy_phone(:be) %>
+    #=> "03 111 22 33"
+
+    <%= @contact.happy_phone2(:be) %>
+    #=> "063 11 22 33"
+
+    <%= @contact.happy_inter_phone(:be) %>
+    #=> "+32 3 111 22 33"
+
+    <%= @contact.happy_inter_phone2(:be) %>
+    #=> "+32 63 11 22 33"
+
+And if *Happy Phone Number* don't know your country, you could use a
+**mask formatting**:
+
+    <%= @contact.happy_phone("#### ###-###") %>
+    #=> "0123 456-789"
+
+### Caveats
+
+*Mask formatting* doesn't work for international phone number format.
 
 Install
 -------------------------
@@ -72,12 +104,80 @@ Now, in your views, you can use:
 
     happy_phone(:fr)
     happy_fax(:fr)
+    ...
+
+Supported Countries
+--------------------------
+
+<table>
+<tr>
+  <th>Name</th>
+  <th>Symbol</th>
+</tr>
+<tr>
+  <td>Belgium</td>
+  <td>:be</td>
+</tr>
+<tr>
+  <td>Denmark</td>
+  <td>:dk</td>
+</tr>
+<tr>
+  <td>France</td>
+  <td>:fr</td>
+</tr>
+<tr>
+  <td>Iceland</td>
+  <td>:is</td>
+</tr>
+</table>
 
 Dependencies
 --------------------------
 
-ruby >= 1.9.2
-rails >= 3.2
+  * ruby >= 1.9.2
+  * rails >= 3.2
+
+Contributing
+-------------------------
+
+*I don't know much about format and convention for every possible country.
+Feel free to send me documentation for the phone number formatting and
+convention for your country. Or contribute to the code by adding any
+missing formatter.*
+
+1. Fork it
+2. Create your feature branch (`git checkout -b my-new-feature`)
+3. Commit your changes (`git commit -am 'Add some feature'`)
+4. Push to the branch (`git push origin my-new-feature`)
+5. Create new Pull Request
+
+### How to add a formatter for your country
+
+Name the file as follow:
+
+    aa_format.rb
+
+where "aa" is the ISO code of the country.
+See [ISO country codes] [1].
+
+Put this file in the lib/happy_phone_number/ folder. Then follow the structure of
+an existed formatter:
+
+  * fr_format.rb is a good starting point
+  * dk_format.rb is the simplest one
+  * be_format.rb is a little more complex
+
+Feel free to ask for help if you have any troubles.
+
+
+### There is many other ways to contibute to FIXME
+
+1. Report any bug
+2. Give me ideas
+3. Correct my poor english syntax
+4. Blog about *Happy Phone Number*
+5. Tell *Happy Phone Number* to your friends and colleagues
 
 License
 --------------------------
@@ -89,4 +189,6 @@ Questions and/or Comments
 --------------------------
 
 Feel free to email [Xavier Nayrac](mailto:xavier.nayrac@gmail.com)
-with any questions.
+with any questions, or contact me on [twitter](https://twitter.com/lkdjiin).
+
+[1]: http://en.wikipedia.org/wiki/ISO_3166-1 "ISO country codes on wikipedia"

data/lib/happy_phone_number.rb

@@ -1,24 +1,69 @@
+require 'happy_phone_number/formatter'
+require 'happy_phone_number/mask'
+require 'happy_phone_number/base_format'
+
+# Public: Happy Phone Number provides easy methods to format phone
+# numbers from your Rails models. Virtually any country specific
+# format could be supported, including national and international
+# format. For the not (yet) supported countries, a general method
+# using a simple mask is also provided.
+#
+# Examples
+#
+#   class Contact < ActiveRecord::Base
+#     attr_accessible :email, :name, :phone, :fax
+#     happy_phone_number
+#   end
+#
+#   <%= @contact.happy_phone(:fr) %>
+#   # => "01 23 45 67 89"
+#
+#   <%= @contact.happy_inter_phone(:fr) %>
+#   # => "+33 1 23 45 67 89"
+#
+#   <%= @contact.happy_phone(:be) %>
+#   # => "03 111 22 33"
+#
+#   <%= @contact.happy_phone("#### ###-###") %>
+#   # => "0123 456-789"
 module HappyPhoneNumber
   extend ActiveSupport::Concern
 
   included do
-
   end
 
   module ClassMethods
     def happy_phone_number(options = {})
-      # your code will go here
     end
   end
 
+  # Public: Format a phone number from a model.
+  #
+  # args[0] - Either a Symbol country or a String formatting mask.
+  #           A country symbol must be in ISO 3166-1-alpha-2 format,
+  #           both lower and upper case are valids.
+  # block   - Not used.
+  #
+  # Signature
+  #
+  #   happy_<field>(country_or_mask, separator)
+  #   happy_inter_<field>(country_or_mask, separator)
+  #
+  # field - A field name of the model that holds a phone number as a
+  #         string.
+  #
+  # Returns the String formatted phone number.
   def method_missing(meth, *args, &block)
-    if meth.to_s =~ /^happy_(.+)$/
-      run_happy($1, *args, &block)
+    if meth.to_s =~ /^happy_inter_(.+)$/
+      happy_format(:international, $1, *args)
+    elsif meth.to_s =~ /^happy_(.+)$/
+      happy_format(:national, $1, *args)
     else
       super
     end
   end
 
+  # Public: Make the happy_* methods respond to respond_to?.
   def respond_to?(meth, include_private = false)
     if meth.to_s =~ /^happy_.*$/
       true
@@ -29,16 +74,16 @@ module HappyPhoneNumber
 
   private
 
-  def run_happy(meth, *args, &block)
-    type = args[0]
-    separator = args[1] || ' '
-    if (type == :fr) || (type == :FR)
-      send(meth.to_sym).unpack('A2A2A2A2A2').join(separator)
-    elsif type == :international
-      "+33#{send(meth.to_sym)[1, 9]}".unpack('A3A1A2A2A2A2').join(separator)
-    else
-      send(meth.to_sym)
-    end
+  # Launch the formatting process.
+  #
+  # type - Either :national or :international.
+  # meth - The String field from the model.
+  # args - Argument(s) passed to the formatting method, like a country,
+  #        a mask string, the separator.
+  #
+  # Returns the String formatted phone number.
+  def happy_format(type, meth, *args)
+    Formatter.new(send(meth.to_sym), type, args[0], args[1]).format
   end
 
 end

data/lib/happy_phone_number/base_format.rb

@@ -0,0 +1,67 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Internal: Base class for specific country formatter.
+  class BaseFormat
+
+    # Internal: Initialize a new base formatter.
+    #
+    # phone     - A String phone number to format.
+    # type      - Either :national or :international.
+    # separator - A String separator to put into each groups of digit.
+    def initialize phone, type, separator
+      @phone = phone
+      @type = type
+      @separator = separator
+    end
+
+    private
+
+    # Internal: Format the phone number using specified grouping.
+    #
+    # groups - A String set of digits.
+    #
+    # Examples
+    #
+    #   @phone = "123456"
+    #   make_happy "222"
+    #   # => "12 34 56"
+    #
+    #   @phone = "+33123456789"
+    #   @separator = "."
+    #   make_happy "312222"
+    #   # => "+33.1.23.45.67.89"
+    #
+    # Returns the String formatted phone number.
+    def make_happy groups
+      unpack_string = "A#{groups.split('').join('A')}"
+      @phone.unpack(unpack_string).join(@separator)
+    end
+
+    # Internal: Internationalize a phone number with a given prefix.
+    #
+    # prefix - A String.
+    # block  - Optional, a block to call before we add the prefix.
+    #
+    # Examples
+    #
+    #   puts @phone
+    #   # => "12345678"
+    #   internationalize_with("45")
+    #   # => "+4512345678"
+    #
+    #   puts @phone
+    #   # => "0123456789"
+    #   internationalize_with("33") { @phone.slice!(0) }
+    #   # => "+33123456789"
+    #
+    # Returns nothing.
+    def internationalize_with prefix, &block
+      block.call if block
+      @phone = "+#{prefix}#{@phone}"
+    end
+
+  end
+end
+

data/lib/happy_phone_number/be_format.rb

@@ -0,0 +1,38 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Format for belgian phone numbers.
+  class BeFormat < BaseFormat
+
+    # Format the phone number given belgian convention.
+    #
+    # Returns the String formatted phone number.
+    def format
+      case @phone[0, 2]
+      when "02", "03", "04", "08", "09"
+        if @type == :national
+          make_happy '2322'
+        else
+          internationalize
+          make_happy '31322'
+        end
+      else
+        if @type == :national
+          make_happy '3222'
+        else
+          internationalize
+          make_happy '32222'
+        end
+      end
+    end
+
+    private
+
+    def internationalize
+      internationalize_with('32') { @phone.slice!(0) }
+    end
+
+  end
+end
+

data/lib/happy_phone_number/dk_format.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Format phone numbers from Denmark.
+  class DkFormat < BaseFormat
+
+    # Format the phone number given danish convention.
+    #
+    # Returns the String formatted phone number.
+    def format
+      if @type == :national
+        make_happy '2222'
+      else
+        internationalize_with '45'
+        make_happy '32222'
+      end
+    end
+  end
+end
+

data/lib/happy_phone_number/formatter.rb

@@ -0,0 +1,81 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Internal: A simple facade which call the real formatter.
+  class Formatter
+
+    # Internal: Initialize the formatter facade.
+    #
+    # phone           - A String phone number to format.
+    # type            - Either :national or :international.
+    # country_or_mask - If it's a country, must be a two-letters Symbol.
+    #                   If it's a String, it is considered as a mask.
+    # separator       - Optional, a String to separate groups of digits
+    #                   the final result.
+    def initialize phone, type, country_or_mask, separator
+      @phone = phone
+      @type = type
+      @country_or_mask = country_or_mask
+      @separator = separator || ' '
+    end
+
+    # Internal: Call the real formatter.
+    #
+    # Returns the String formatted phone number.
+    def format
+      if @country_or_mask.class == String
+        use_mask
+      else
+        use_formatter
+      end
+    end
+
+    private
+
+    # Format phone using a mask.
+    #
+    # Returns the String formatted phone number.
+    def use_mask
+      Mask.new(@phone, @country_or_mask).format
+    end
+
+    # Format phone using a country formatter.
+    #
+    # Returns the String formatted phone number.
+    def use_formatter
+      begin
+        require "happy_phone_number/#{formatter_filename}"
+        HappyPhoneNumber.const_get(formatter_classname).new(
+          @phone, @type, @separator).format
+      rescue LoadError
+        return @phone
+      end
+    end
+
+    # Get the formatter classname.
+    #
+    # Examples
+    #
+    #   @country_or_mask = :fr
+    #   formatter_classname # => "FrFormat"
+    #
+    # Returns the String formatter classname.
+    def formatter_classname
+      "#{@country_or_mask.to_s.capitalize}Format"
+    end
+
+    # Get the formatter filename.
+    #
+    # Examples
+    #
+    #   @country_or_mask = :fr
+    #   formatter_classname # => "fr_format"
+    #
+    # Returns the String formatter filename.
+    def formatter_filename
+      "#{@country_or_mask.to_s.downcase}_format"
+    end
+  end
+end
+

data/lib/happy_phone_number/fr_format.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Format for french phone numbers.
+  class FrFormat < BaseFormat
+
+    # Format the phone number given french convention.
+    #
+    # Returns the String formatted phone number.
+    def format
+      if @type == :national
+        make_happy '22222'
+      else
+        internationalize_with('33') { @phone.slice!(0) }
+        make_happy '312222'
+      end
+    end
+  end
+end
+

data/lib/happy_phone_number/is_format.rb

@@ -0,0 +1,21 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Format phone numbers from Iceland.
+  class IsFormat < BaseFormat
+
+    # Format the phone number given convention for Iceland.
+    #
+    # Returns the String formatted phone number.
+    def format
+      if @type == :national
+        make_happy '34'
+      else
+        internationalize_with '354'
+        make_happy '434'
+      end
+    end
+  end
+end
+

data/lib/happy_phone_number/mask.rb

@@ -0,0 +1,85 @@
+# -*- encoding: utf-8 -*-
+
+module HappyPhoneNumber
+
+  # Internal: Phone number formatting using a mask.
+  #
+  # Examples
+  #
+  #   Mask.new("123456", "### ###").format
+  #   # => "123 456"
+  #
+  #   Mask.new("123456", "## ##-##").format
+  #   # => "12 34-56"
+  #
+  #   Mask.new("123456", "##.####").format
+  #   # => "12.3456"
+  class Mask
+
+    # Internal: Initialize a new mask formatter.
+    #
+    # phone - A String phone number.
+    # mask  - A String mask.
+    def initialize phone, mask
+      @phone = phone
+      @mask = mask
+    end
+
+    # Internal: Format the phone number. If the mask is too long for the
+    # phone number, it will be truncated (the mask). If the mask is too
+    # short, the returned phone number will be left untouched.
+    #
+    # Examples
+    #
+    #   Mask.new("1234", "### ###").format
+    #   # => "123 4"
+    #
+    #   Mask.new("1234", "#").format
+    #   # => "1234"
+    #
+    # Returns the String formatted phone number.
+    def format
+      return @phone if mask_too_short?
+      mask_array.map do |item|
+        if item == "#"
+          next_digit
+        else
+          item
+        end
+      end.join
+    end
+
+    private
+
+    # Check if the mask is too short for the phone number.
+    #
+    # Returns true or false.
+    def mask_too_short?
+      @mask.split('').select {|i| i == "#" }.size < @phone.size
+    end
+
+    # Split the mask into single characters.
+    #
+    # Returns an Array.
+    def mask_array
+      @mask.split('')
+    end
+
+    # Get the next digit of the phone number.
+    #
+    # Examples
+    #
+    #   @phone = "123"
+    #   next_digit
+    #   # => "1"
+    #   next_digit
+    #   # => "2"
+    #
+    # Returns a String.
+    def next_digit
+      @phone.slice!(0)
+    end
+
+  end
+end
+

data/lib/happy_phone_number/version.rb

@@ -1,3 +1,3 @@
 module HappyPhoneNumber
-  VERSION = "0.0.1"
+  VERSION = "0.0.2"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: happy_phone_number
 version: !ruby/object:Gem::Version
-  version: 0.0.1
+  version: 0.0.2
   prerelease: 
 platform: ruby
 authors:
@@ -9,7 +9,7 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2013-05-03 00:00:00.000000000 Z
+date: 2013-05-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rails
@@ -59,14 +59,31 @@ dependencies:
     - - ! '>='
       - !ruby/object:Gem::Version
         version: '0'
-description: Rails plugin to format phone number.
+description: ! 'Happy Phone Number provides easy methods to format phone
+
+  numbers from your Rails models. Virtually any country specific
+
+  format could be supported, including national and international
+
+  format. For the not (yet) supported countries, a general method
+
+  using a simple mask is also provided.
+
+'
 email:
 - xavier.nayrac@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- lib/happy_phone_number/dk_format.rb
 - lib/happy_phone_number/version.rb
+- lib/happy_phone_number/fr_format.rb
+- lib/happy_phone_number/mask.rb
+- lib/happy_phone_number/is_format.rb
+- lib/happy_phone_number/be_format.rb
+- lib/happy_phone_number/base_format.rb
+- lib/happy_phone_number/formatter.rb
 - lib/tasks/happy_phone_number_tasks.rake
 - lib/happy_phone_number.rb
 - MIT-LICENSE