cep_facil 0.1.2 → 1.0.0

data/.gitignore

@@ -1,3 +1,4 @@
+.DS_Store
 *.gem
 .bundle
 Gemfile.lock

data/README.md

@@ -1,117 +1,110 @@
-CepFácil
-===========
+# CepFacil
 
-Wrapper Ruby for the service at cepfacil.com.br
+Ruby wrapper para o serviço em cepfacil.com.br
 
-Installation
-------------
+## Instalação
 
-In the `Gemfile`
+NOTA: Esse projeto encontra-se na versão 1.x, cuja API difere completamente das versões 0.x. Se você está procurando a versão mais antiga, veja a branch [0x], que se mantém intacta.
+
+No `Gemfile`:
 
 ```ruby
 gem "cep_facil"
+
 ```
 
-Or via RubyGems, directly:
+Ou via RubyGems, diretamente:
 
-  `gem install cep_facil`
+  `$ gem install cep_facil`
 
-CepFacil works only in Ruby 1.9.2 by default. If you need it to work with 1.8.7 you must do the following:
+## Uso
 
-In the `Gemfile`
+### Obtendo um endereço pelo CEP
+
+Para usar a API do [CepFácil], você precisa obter um token do serviço. Você obtém esse token gratuitamente em cepfacil.com.br
 
 ```ruby
-gem "cep_facil", :git => "git://github.com/rodrigoalvesvieira/cep_facil.git", :branch => "1.8.7"
+
+require "cep_facil"
+
+cep = "53417-540"
+
+token = "1234567890"
+
+address = CepFacil::API.new(cep, token)
+
 ```
 
-Usage
------
+#### Retorna o endereço referente àquele CEP
 
-### Fetching an address by zip code
+O retorno é um objeto `CepFacil::API` que contem 6 métodos (propriedades): cep, type, state, city, neighborhood, street. Assim você os acessa:
 
 ```ruby
-require "cep_facil"
-cep = "53417-540"
-token = "1234567890" # get yours at cepfacil.com.br
-address = CepFacil.get_address(cep, token)
-# Returns the address referent to that zip code.
-address[:city]
-# Returns the city referent to that zip code.
+
+address.cep # => "53417540"
+
+address.type # => "Rua"
+
+address.state # => "PE"
+
+address.city # => "Paulista"
+
+address.neighborhood # => "Artur Lundgren II"
+
+address.street # => "Panelas"
+
 ```
 
-Alternatively, you can do:
+Embora isso deva parecer óbvio, informo que essas propriedades são todas **READONLY**.
+
+Adicionalmente, seu objeto `CepFacil::API` possui um método `full` que o descreve por extenso:
 
 ```ruby
-require "cep_facil"
-include CepFacil
-address = get_address cep, token
-```
 
-The response is a Hash object that contains 6 keys: cep, type, state, city, neighborhood, description.
+address.full_format # => "Rua Panelas, Paulista - PE, Brasil"
+
+```
 
-There are three formats for one to store Brazilian zip codes (CEPs):
+Existem três formatos possíveis para se armazenar CEPs:
 
 ```ruby
 "12345-678"
 "12345678"
-12345678   # I wouldn't use this one, really.
+12345678   # Eu realmente não usaria esse
 ```
 
-CepFácil works with the three of them.
+CepFacil funciona com esses três formatos.
 
-### Displaying an address in full mode
+## Integração com a gem Geocoder
 
-```ruby
-address = CepFacil.get_address(cep, token)
-CepFacil.full address
-```
+A gem [Geocoder] é ótima para uso e manipulação de dados geográficos em projetos Ruby. Para integrá-la com o CepFacil, faça assim:
 
-Or:
+```ruby
 
-````ruby
-require "cep_facil"
-include CepFacil
+geocoded_by address.full_format
 
-address = get_address("50050-000", token)
-full(address) # => Rua da Aurora, Boa Vista, Recife-PE, Brasil.
 ```
 
-Author
-------
+## Autor
 
-* Rodrigo Vieira - rodrigovieira1994@gmail.com - http://www.rodrigoalvesvieira.com
+* Rodrigo Alves Vieira - rodrigovieira1994@gmail.com - http://www.rodrigoalvesvieira.com
 
-Contributors
-------------
+## Contribuidores
 
 * Adriano Bacha - abacha@gmail.com
 
-Thanks
--------
-
-Huge thanks and cheers to CépFácil (http://cepfacil.com.br) of course. Thanks for the great service that you provide!
-
-Also, thanks to the [Contributors] of this project.
-
-Licence
--------
+## Agradecimentos
 
-Copyright (c) 2012 Rodrigo Vieira. http://www.rodrigoalvesvieira.com/
+Obrigado pelas pessoas que oferecem o serviço [CepFácil], sem o qual esse projeto não seria possível.
 
-Permission is hereby granted, free of charge, to any person obtaining
-a copy of this software and associated documentation files (the
-"Software"), to use, copy and modify copies of the Software, subject
-to the following conditions:
+Obrigado também aos [Contribuidores] desse projeto.
 
-The above copyright notice and this permission notice shall be
-included in all copies or substantial portions of the Software.
+## Licença
 
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
-EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
-MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND
-NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE
-LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION
-OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION
-WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+CepFacil é liberado sob a [licença do MIT] com atribuições a Rodrigo Alves Vieira.
 
-[Contributors]: #ontributors
+[0x]: https://github.com/rodrigoalvesvieira/cep_facil/tree/0x
+[Geocoder]: https://github.com/alexreisner/geocoder
+[CepFácil]: http://cepfacil.com.br
+[Contribuidores]: #contribuidores
+[licença do MIT]: http://pt.wikipedia.org/wiki/Licen%C3%A7a_MIT#Texto_da_licen.C3.A7a

data/Rakefile

@@ -5,9 +5,9 @@ require 'rake'
 require 'rdoc/task'
 require 'fileutils'
 
-task :test => :spec
+task test: :spec
 
-task :default => :spec
+task default: :spec
 
 require "rspec/core/rake_task"
 RSpec::Core::RakeTask.new(:spec) do |t|

data/cep_facil.gemspec

@@ -7,7 +7,7 @@ Gem::Specification.new do |s|
   s.version     = CepFacil::VERSION
   s.authors     = ["Rodrigo Alves Vieira"]
   s.email       = ["rodrigovieira1994@gmail.com"]
-  s.homepage    = "https://github.com/rodrigoalvesvieira/cep_facil"
+  s.homepage    = "http://github.com/rodrigoalvesvieira/cep_facil"
   s.summary     = %q{Wrapper para o serviço cepfacil.com.br}
   s.description = %q{Wrapper Ruby para o serviço cepfacil.com.br}
   s.rubyforge_project = "cep_facil"
@@ -15,5 +15,5 @@ Gem::Specification.new do |s|
   s.test_files    = `git ls-files -- {test,spec,features}/*`.split("\n")
   s.executables   = `git ls-files -- bin/*`.split("\n").map{ |f| File.basename(f) }
   s.require_paths = ["lib"]
-  s.add_dependency("rspec", ">=2")
+  s.add_dependency("rspec", "~> 2.11.0")
 end

data/lib/cep_facil/api.rb

@@ -0,0 +1,53 @@
+# coding: utf-8
+
+require "cgi"
+require "net/http"
+
+module CepFacil
+  class API
+    attr_reader :cep, :type, :state, :city, :neighborhood, :street
+    ## Obtenção de endereço atráves do CEP
+    # retorna um objeto `CepFacil::API` que contem 6 métodos (propriedades):
+    # cep, type, state, city, neighborhood e street.
+
+    def initialize(cep, token)
+      @cep = cep
+      @token = token
+
+      zip_code = @cep.to_s
+
+      if zip_code.match(/^[0-9]{5}[-]?[0-9]{3}/)
+        zip_code.gsub!("-", "")
+        @uri = URI.parse "http://www.cepfacil.com.br/service/?filiacao=#{token}&cep=#{zip_code}&formato=texto"
+      else
+        @uri = URI.parse "http://www.cepfacil.com.br/service/?filiacao=#{token}&cep=#{zip_code}&formato=texto"
+      end
+
+      http = Net::HTTP.new(@uri.host, @uri.port)
+      call = Net::HTTP::Get.new(@uri.request_uri)
+
+      response = http.request(call)
+
+      pattern = /^([a-z]+)\=/
+
+      result = response.body.split("&")
+
+      if result[2]
+        @type = result[2].gsub!(pattern, "")
+        @state = result[3].gsub!(pattern, "")
+        @city = result[4].gsub!(pattern, "")
+        @neighborhood = result[5].gsub!(pattern, "")
+        @street = result[6].gsub!(pattern, "")
+      else
+        return false
+      end
+    end
+
+    ##
+    # Descreve o endereço obtido, por extenso. i.e: "Rua Panelas, Paulista - PE, Brasil"
+    #
+    def full_format
+      "#{self.type} #{self.street}, #{self.city} - #{self.state}, Brasil"
+    end
+  end
+end

data/lib/cep_facil/version.rb

@@ -1,3 +1,3 @@
 module CepFacil
-  VERSION = "0.1.2" #:nodoc:
+  VERSION = "1.0.0" #:nodoc:
 end

data/lib/cep_facil.rb

@@ -1,75 +1,6 @@
-# coding: utf-8
-require "cgi"
+require "cep_facil/api"
 require "cep_facil/version"
-require "net/http"
 
 module CepFacil
-  
-  module_function
-
-  # Receives the zip code (CEP) and the Token (get yours at http://cepfacil.com.br) and
-  # returns the address referent to that zip code as a hash object.
-  #
-  # == Example 
-  #   require "cep_facil"
-  #   cep = "5417-540"
-  #   token = "1234567890"
-  #   address = CepFacil.get_address(cep, token)
-  #
-  # == You can also do:
-  #   require "cep_facil"
-  #   include CepFacil
-  #   get_address cep, token
-  #
-  #   # address is a hash with 6 keys: cep, type, state, city, neighborhood, description
-  #
-  # Reading them: 
-  #   address[:city]
-  #   address[:state]
-  #
-  # Some applications store Brazilian zip codes (CEPs) in formats like "22222222", or "22222-222"
-  # or even as an integer. This method accept these three possible formats so you don´t need to format it yourself.
-  
-  def get_address(zip_code, token, dictionary = {})
-    dictionary = {
-      "tipo" => :type,
-      "cidade" => :city,
-      "bairro" => :neighborhood,
-      "cep" => :cep,
-      "descricao" => :description,
-      "uf" => :state
-    }.merge(dictionary)
-
-    zip_code = zip_code.to_s
-    
-    if zip_code.match(/^[0-9]{5}[-]?[0-9]{3}/)
-      zip_code.gsub!("-", "")
-      @uri = URI.parse "http://www.cepfacil.com.br/service/?filiacao=#{token}&cep=#{zip_code}&formato=texto"
-    else
-      @uri = URI.parse "http://www.cepfacil.com.br/service/?filiacao=#{token}&cep=#{zip_code}&formato=texto"
-    end
-    
-    http = Net::HTTP.new(@uri.host, @uri.port)
-    call = Net::HTTP::Get.new(@uri.request_uri)
-    
-    response = http.request(call)
-    address = Hash[* CGI::parse(response.body).map {|key, value| [dictionary[key],value[0]]}.flatten]
-  end
-  
-  # Receives and address hash and returns its extense version
-  # == Example
-  #   address = CepFacil.get_address "53417-540", "1234456677886545"
-  #   CepFacil.full address
-  #   # => Rua Panelas, Artur Lundgren II, Paulista-PE, Brasil.
-  #
-  # == You can also do:
-  #   require "cep_facil"
-  #   include CepFacil
-  #   address = CepFacil.get_address "53417-540", "1234456677886545"
-  #   full address
-   
-  def full(address)
-    "#{address[:type]} #{address[:description]}, #{address[:neighborhood]}, #{address[:city]}-#{address[:state]}, Brasil."
-  end
-
+  autoload :API, "cep_facil/api"
 end

data/spec/cep_facil_spec.rb

@@ -13,80 +13,55 @@ describe CepFacil do
   it "can fetch an address from a CEP" do
     cep = "53417-540"
 
-    address = CepFacil.get_address cep, @token
+    address = CepFacil::API.new(cep, @token)
     address.should_not be_nil
 
-    address[:type].should eql("Rua")
-    address[:city].should eql("Paulista")
+    address.type.should eql("Rua")
+    address.city.should eql("Paulista")
   end
 
   it "works with non formatted zip codes (CEPs)" do
     cep = "53417540"
-    address = CepFacil.get_address cep, @token
+    address = CepFacil::API.new(cep, @token)
     address.should_not be_nil
   end
 
   it "works even with zip codes (CEPs) stored as integers" do
     cep = 53417540
-    address = CepFacil.get_address cep, @token
+    address = CepFacil::API.new(cep, @token)
     address.should_not be_nil
   end
 
-  it "can get all 6 attributes (cep, type, state, city, neighborhood, description) from a given CEP" do
+  it "can get all 6 attributes (cep, type, state, city, neighborhood, street) from a given CEP" do
     cep = "52060-010"
-    address = CepFacil.get_address cep, @token
-
-    address[:cep].should eql("52060010")
-    address[:type].should eql("Rua")
-    address[:state].should eql("PE")
-    address[:city].should eql("Recife")
-    address[:neighborhood].should eql("Parnamirim")
-    address[:description].should include("Tude de Melo")
-
-    address[:cep].should_not be_nil
-    address[:type].should_not be_nil
-    address[:state].should_not be_nil
-    address[:city].should_not be_nil
-    address[:neighborhood].should_not be_nil
-    address[:description].should_not be_nil
-
-    address.should have_key(:cep)
-    address.should have_key(:type)
-    address.should have_key(:state)
-    address.should have_key(:city)
-    address.should have_key(:neighborhood)
-    address.should have_key(:description)
+    address = CepFacil::API.new(cep, @token)
+
+    address.cep.should eql("52060010")
+    address.type.should eql("Rua")
+    address.state.should eql("PE")
+    address.city.should eql("Recife")
+    address.neighborhood.should eql("Parnamirim")
+    address.street.should include("Tude de Melo")
   end
 
   it "can return a string with the full address" do
     cep = "53417-540"
-    address = CepFacil.get_address cep, @token
-    full_version = CepFacil.full address
+
+    address = CepFacil::API.new(cep, @token)
+
+    full_version = address.full_format
+
     full_version.should_not be_nil
-    full_version.should eql("Rua Panelas, Artur Lundgren II, Paulista-PE, Brasil.")
+    full_version.should eql("Rua Panelas, Paulista - PE, Brasil")
   end
 
   it "handles correct encoding" do
     cep = "79005-340"
-    address = CepFacil.get_address cep, @token
-    address[:neighborhood].should eql("Amambaí")
-    address[:description].should eql("Coronel Camisão")
-  end
 
-  it "support a different dictionary" do
-    cep = "79005-340"
-    dictionary = {
-      "tipo" => :type,
-      "cidade" => :city,
-      "bairro" => :district,
-      "cep" => :zipcode,
-      "descricao" => :street,
-      "uf" => :uf
-    }
-    address = CepFacil.get_address cep, @token, dictionary
-    address[:zipcode].should eql("79005340")
-    address[:uf].should eql("MS")
-    address[:district].should eql("Amambaí")
+    address = CepFacil::API.new(cep, @token)
+
+    address.neighborhood.should eql("Amambaí")
+    address.street.should eql("Coronel Camisão")
   end
 
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: cep_facil
 version: !ruby/object:Gem::Version
-  version: 0.1.2
+  version: 1.0.0
   prerelease: 
 platform: ruby
 authors:
@@ -9,24 +9,24 @@ authors:
 autorequire: 
 bindir: bin
 cert_chain: []
-date: 2012-06-13 00:00:00.000000000 Z
+date: 2012-08-05 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec
   requirement: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 2.11.0
   type: :runtime
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     none: false
     requirements:
-    - - ! '>='
+    - - ~>
       - !ruby/object:Gem::Version
-        version: '2'
+        version: 2.11.0
 description: Wrapper Ruby para o serviço cepfacil.com.br
 email:
 - rodrigovieira1994@gmail.com
@@ -40,10 +40,11 @@ files:
 - Rakefile
 - cep_facil.gemspec
 - lib/cep_facil.rb
+- lib/cep_facil/api.rb
 - lib/cep_facil/version.rb
 - spec/cep_facil_spec.rb
 - spec/spec_helper.rb
-homepage: https://github.com/rodrigoalvesvieira/cep_facil
+homepage: http://github.com/rodrigoalvesvieira/cep_facil
 licenses: []
 post_install_message: 
 rdoc_options: []