pinpoint 0.0.3 → 0.1.0

data/README.md

@@ -1,4 +1,182 @@
-pinpoint
-========
+<img align="right" width="400" src="http://cache.jezebel.com/assets/images/7/2009/07/custom_1245192016735_wargames_missle_locations.jpg" />
 
-(Un)conventional Address Composition for Ruby (and Rails)
+Pinpoint
+===============================================================================
+
+_(Un)conventional Address Composition for Ruby (and Rails)_
+
+Supported Rubies
+--------------------------------
+* MRI Ruby 1.9.2
+* MRI Ruby 1.9.3
+* JRuby (in 1.9 compat mode)
+
+<br/>
+<br/>
+
+Installation
+-------------------------------------------------------------------------------
+
+First:
+
+```ruby
+gem install pinpoint
+```
+
+Then in your script:
+
+```ruby
+require 'pinpoint'
+```
+
+or in your Gemfile
+
+```ruby
+gem 'pinpoint'
+```
+
+or from IRB
+
+```ruby
+irb -r 'pinpoint'
+```
+
+Usage
+-------------------------------------------------------------------------------
+
+### Direct ####################################################################
+
+Typically Pinpoint is used by requiring it and using the `Pinpoint::Address`
+class directly. Like so:
+
+```ruby
+class ThingWithAddress
+  attr_accessor :address
+end
+
+thing = ThingWithAddress.new
+thing.address = Pinpoint::Address.new(:foo => :bar)
+```
+
+### Composable ################################################################
+
+However it can also be included in the class when the class already has
+accessors for all of the different address attributes to generate a composed
+address.
+
+```ruby
+class ThingWithAddress
+  include Pinpoint::Composable
+
+  attr_accessor :street
+  attr_accessor :city
+  attr_accessor :state
+  attr_accessor :zip_code
+  attr_accessor :country
+
+  pinpoint :address
+end
+
+thing = ThingWithAddress.new
+
+# Set all address fields on `thing`
+
+thing.address # => Pinpoint::Address
+```
+
+#### Field Prefixes
+
+If your class has fields that are prefixed by a string (eg venue_city,
+venue_state, etc) you can pass `field_prefix` to the compose class method like
+so:
+
+```ruby
+class ThingWithAddress
+  # attr_accessors like:
+  attr_accessor :venue_street
+  attr_accessor :venue_city
+
+  pinpoint :venue, :field_prefix => 'venue'
+end
+```
+
+### Address Formatting ########################################################
+
+Pinpoint has an advanced address formatter which can output an address in
+multiple country formats.
+
+```ruby
+pinpoint_address.to_s(country:  :us,
+                      style:    :one_line)
+# => 'Kwik-E-Mart, 123 Apu Lane, Springfield, NW 12345, United States'
+
+pinpoint\_address.to\_s(country:  :ru,
+                      style:    :one_line)
+# => 'Kwik-E-Mart, ul. Apu Lane d. 123, pos. Springfield, NW obl, 12345, United States'
+```
+
+_Note: By default, Pinpoint will format addresses for the country that the
+address is located in._
+
+### Retrieving Address Information ############################################
+
+* `:name` - The name of the person or business this address is associated with
+* `:location_details` - Free form but typically describes the department, mail
+  stop, etc).
+* `:street` - The name of the street
+* `:street_number` - The number that corresponds to the place that the address
+  is associated with.
+* `:suite_number` - The number associated with the aparment, office or suite.
+* `:zip_code` - The postal code associated with the address
+* `:city` - The town/villiage/city associated with the address
+* `:state` - The state/department/province associated with the address
+* `:country` - The country associated with the address
+
+#### Aliases ####
+
+Some of the above attributes are aliased to some other common names:
+
+* `:name` => `:recipient`
+* `:name` => `:building_name`
+* `:location_details` => `:mail_stop`
+* `:zip_code` => `:postal_code`
+* `:city` => `:locality`
+* `:state` => `:province`
+
+### Geocoding #################################################################
+
+By default, Pinpoint uses [Geocoder]() to add latitude and longitude information
+to addresses.
+
+If a Pinpoint address is composed into your class, you can add a `:latitude` and
+`:longitude` attribute to it and it will be set/modified when the address is
+changed.
+
+Road Map
+--------------------------------
+
+* Advanced parsing support
+* SimpleForm inputs
+
+Issues
+--------------------------------
+
+If you have problems, please create a [Github issue](https://github.com/chirrpy/pinpoint/issues).
+
+Credits
+--------------------------------
+
+![](https://dl.dropbox.com/s/f9s2qd0kmbc8nwl/github_logo.png?dl=1)
+
+pinpoint is maintained by [Chrrpy, LLC](http://chirrpy.com)
+
+The names and logos for Chirrpy are trademarks of Chrrpy, LLC
+
+Contributors
+--------------------------------
+* [Jeff Felchner](https://github.com/jfelchner)
+
+License
+--------------------------------
+
+pinpoint is Copyright &copy; 2012 Chirrpy. It is free software, and may be redistributed under the terms specified in the LICENSE file.

data/lib/pinpoint/address.rb

@@ -1,3 +1,5 @@
+require 'pinpoint/formatter'
+
 module Pinpoint
   class Address
     attr_accessor :name,
@@ -10,6 +12,10 @@ module Pinpoint
                   :latitude,
                   :longitude
 
+    # City Aliases
+    alias :locality       :city
+    alias :locality=      :city=
+
     # State Aliases
     alias :region         :state
     alias :region=        :state=
@@ -52,6 +58,10 @@ module Pinpoint
       blank?(zip_code)
     end
 
+    def to_s(options = { :country => :us, :format => :one_line })
+      Formatter.format(self, options)
+    end
+
   private
     def present?(value)
       !blank?(value)

data/lib/pinpoint/config/formats/us.yml

@@ -0,0 +1,21 @@
+one_line_with_name:   '(%n, )(%s, )(%l, )(%p )%z(, %c)'
+one_line:             '(%s, )(%l, )(%p )%z(, %c)'
+multi_line:           "(%s\n)((%l, )(%p )%z\n)(%c\n)"
+multi_line_with_name: "(%n\n)(%s\n)((%l, )(%p )%z\n)(%c\n)"
+html:                 |
+                      <address>
+                        <span class="section">
+                          <span class="name">%n</span>
+                        </span>
+                        <span class="section">
+                          <span class="street">%s</span>
+                        </span>
+                        <span class="section">
+                          <span class="locality">%l</span>
+                          <span class="province">%p</span>
+                          <span class="postal_code">%z</span>
+                        </span>
+                        <span class="section">
+                          <span class="country">%c</span>
+                        </span>
+                      </address>

data/lib/pinpoint/format.rb

@@ -0,0 +1,61 @@
+require 'pinpoint/format/file'
+
+module Pinpoint
+  class Format
+    attr_accessor :styles
+
+    ##
+    # Public: Initialize an empty Format with no styles.
+    #
+    def initialize
+      styles = {}
+    end
+
+    ##
+    # Public: Attempts to find a format for a given country.
+    #
+    # country - A Symbol representing the lowercased two-character [ISO
+    #           3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for
+    #           the country you are trying to load a format for.
+    #
+    # Example
+    #
+    #   lookup_by_country(:us)
+    #   # => <Format styles: {one_line: <Format::Style>, ....}>
+    #
+    # Returns a Format loaded with all of the styles that it is capable of.
+    #
+    def self.lookup_by_country(country)
+      format = self.new
+      format.styles = Pinpoint::Format::File.styles_for(country)
+      format
+    end
+
+    ##
+    # Public: Will output any given address for the country defined in the
+    # Format.
+    #
+    # By default it will output in a 'one-line' style.
+    #
+    # address - The address that will be formatted (typically
+    #           a Pinpoint::Address).
+    #
+    # options - A Hash of options for the method
+    #
+    #           :style - The style to be applied to the address output
+    #                    (defaults to :one_line).
+    #
+    # Example
+    #
+    #   output my_address, :style => :one_line
+    #   # => 'Kwik-E-Mart, 123 Apu Lane, Springfield, NW 12345, United States'
+    #
+    # Returns a String representing the address in the specified style.
+    #
+    def output(address, options = {})
+      requested_style = options.fetch(:style, :one_line).to_sym
+
+      styles[requested_style].output(address)
+    end
+  end
+end

data/lib/pinpoint/format/file.rb

@@ -0,0 +1,45 @@
+require 'yaml'
+require 'pinpoint/format/style'
+
+module Pinpoint
+  class Format
+    class File
+
+      ##
+      # Public: Loads the format for the given country from the appropriate
+      # YAML file.
+      #
+      # It then converts the parsed YAML into Pinpoint::Format::Style objects which
+      # can be used to style something that quaks like an Address.
+      #
+      # country - A Symbol representing the lowercased two-character [ISO
+      #           3166-1](https://en.wikipedia.org/wiki/ISO_3166-1) country code for
+      #           the country you are trying to load a format for.
+      #
+      # Returns a Hash containing symbolized keys for the style names and values
+      # containing Styles.
+      #
+      def self.styles_for(country)
+        raw_style_data(country).each_with_object({}) do |style_definition, hash|
+          style_name = style_definition[0]
+          style      = style_definition[1]
+
+          hash[style_name.to_sym] = Format::Style.from_yaml(style)
+        end
+      end
+
+      private
+
+      def self.format_yaml_contents(country)
+        relative_path = "../../config/formats/#{country}.yml"
+        filename      = ::File.expand_path(relative_path, __FILE__)
+
+        ::File.read(filename)
+      end
+
+      def self.raw_style_data(country)
+        YAML::load(format_yaml_contents(country))
+      end
+    end
+  end
+end

data/lib/pinpoint/format/list.rb

@@ -0,0 +1,53 @@
+require 'pinpoint/format'
+
+module Pinpoint
+  class Format
+    class List
+      include Enumerable
+
+      ##
+      # Public: Initializes a new empty List
+      #
+      def initialize
+        self.formats = Hash.new
+      end
+
+      ##
+      # Public: Retrieves a Format for the given country.
+      #
+      # If the country's Format has already been retrieved, it is returned,
+      # otherwise it is looked up.
+      #
+      # country - The two letter ISO_3166-1 code for the country you're looking
+      #           up the format for.
+      #
+      # Example
+      #
+      #   [:us]
+      #   # => <Format>
+      #
+      # Returns a Format which corresponds to the given country.
+      #
+      def [](country)
+        country = country.to_sym
+
+        get(country) ||
+        set(country, Pinpoint::Format.lookup_by_country(country))
+      end
+
+      protected
+
+      attr_accessor :formats
+
+      private
+
+      def get(country)
+        self.formats[country]
+      end
+
+      def set(country, format)
+        self.formats[country] = format
+      end
+    end
+  end
+end

data/lib/pinpoint/format/parse_error.rb

@@ -0,0 +1,6 @@
+module Pinpoint
+  class Format
+    class ParseError          < StandardError; end
+    class UnevenNestingError  < ParseError; end
+  end
+end

data/lib/pinpoint/format/parser.rb

@@ -0,0 +1,94 @@
+require 'pinpoint/format/tokenizer'
+
+###
+# Private: Parses a set of Tokens into a parse tree that can be navigated by
+# a Style to render some output.
+#
+module Pinpoint
+  class Format
+    class Parser
+
+      ##
+      # Public: Initializes a Parser and converts the passed String into
+      # a TokenList that will be utilized when it is parsed.
+      #
+      # Raises a ParseError if the Tokenizer cannot tokenize the String
+      # Returns a Parser
+      #
+      def initialize(string)
+        self.tokens = Pinpoint::Format::Tokenizer.new(string).to_token_list
+      end
+
+      ##
+      # Public: Provides a way to convert a TokenList into a tree repersenting
+      # groups, message names, and String literals.
+      #
+      # If the TokenList is not valid, a form of ParseError is raised.
+      #
+      # Example
+      #
+      #   Parser.new('(%s, )((%l, )(%p )%z)(, %c)').parse
+      #   # =>  [
+      #   #       [
+      #   #         :street,
+      #   #         ', ',
+      #   #       ],
+      #   #       [
+      #   #         [
+      #   #           :locality,
+      #   #           ', '
+      #   #         ],
+      #   #         [
+      #   #           :province,
+      #   #           ' '
+      #   #         ],
+      #   #         :postal_code
+      #   #       ],
+      #   #       [
+      #   #         ', ',
+      #   #         :country
+      #   #       ]
+      #   #     ]
+      #
+      # Returns an Array containing the parse tree structure
+      #
+      def parse
+        process(tokens) if tokens.valid?
+      end
+
+      protected
+
+      ##
+      # Protected: Reads the TokenList associated with the Parser
+      #
+      attr_accessor :tokens
+
+      ##
+      # Protected: Can recursively process the TokenList into an Array containing
+      # the parse tree.
+      #
+      # See also Parser#parse
+      #
+      # Returns an Array containing the parse tree structure
+      #
+      def process(token_list)
+        result = []
+
+        token_list.process_each! do |token|
+          case token.processed_value
+          when :group_start
+            token_list, intermediate_result = process(token_list)
+
+            result << intermediate_result
+          when :group_end
+            return [token_list, result]
+          else
+            result << token.processed_value
+          end
+        end
+
+        result
+      end
+    end
+  end
+end