pinpoint 0.0.3 → 0.1.0

data/lib/pinpoint/format/style.rb

@@ -0,0 +1,81 @@
+require 'pinpoint/format/parser'
+require 'active_support/core_ext/string/output_safety'
+
+module Pinpoint
+  class Format
+    class Style
+
+      ##
+      # Public: Processes the style information gleaned from the Pinpoint YAML
+      # format and generates a Style from it.
+      #
+      # style - The style information from the Pinpoint YAML format file. For
+      #         example:
+      #
+      #             (%s, )(%l, )(%p )%z(, %c)
+      #
+      # Returns a Pinpoint::Format::Style based on the information passed in.
+      #
+      def self.from_yaml(style_definition)
+        style = self.new
+        style.send(:structure=, Format::Parser.new(style_definition).parse)
+        style
+      end
+
+      ##
+      # Public: Can take an address-like object and output it in the style
+      # specified by the structure.
+      #
+      # Example
+      #
+      #   # Assuming address is an address-like object and Style was
+      #   # instantiated with '(%s, )(%l, )(%p )%z(, %c)'
+      #   output address
+      #   # => '123 First Street, Nashville, TN 37033, United States'
+      #
+      def output(address)
+        process(structure, address)
+      end
+
+      protected
+
+      ##
+      # Protected: Access to the underlying structure of the Style (typically is
+      # a result of calling Pinpoint::Format::Parser#parse.
+      #
+      attr_accessor :structure
+
+      private
+
+      ##
+      # Private: Can take a Style structure and assemble a String from data from
+      # a context.
+      #
+      # When finishing with a grouping, if there is no alphanumeric content
+      # within a grouping, it will be discarded.
+      #
+      # Returns a String containing data from the context and String literals
+      #
+      def process(structure, context)
+        processed = "".html_safe
+
+        structure.each_with_object(processed) do |token, result|
+          result << case token
+                    when Array
+                      process(token, context)
+                    when Symbol
+                      context.public_send(token)
+                    when String
+                      token.html_safe
+                    end
+        end
+
+        processed.match(no_alphanumerics) ? "".html_safe : processed
+      end
+
+      def no_alphanumerics
+        /\A[^A-Za-z0-9]*\z/
+      end
+    end
+  end
+end

data/lib/pinpoint/format/token.rb

@@ -0,0 +1,47 @@
+require 'ostruct'
+
+module Pinpoint
+  class Format
+    class Token < Struct.new(:type, :value)
+      def initialize(*args)
+        args[0] = args[0].to_sym
+
+        super
+      end
+
+      def processed_value
+        case type
+        when :group_start
+          :group_start
+        when :group_end
+          :group_end
+        when :literal
+          value
+        else
+          message
+        end
+      end
+
+      def to_ary
+        [type, value]
+      end
+
+      private
+
+      def message
+        type_to_message_map[type]
+      end
+
+      def type_to_message_map
+        {
+          name:        :name,
+          street:      :street,
+          locality:    :locality,
+          province:    :province,
+          postal_code: :postal_code,
+          country:     :country
+        }
+      end
+    end
+  end
+end

data/lib/pinpoint/format/token_list.rb

@@ -0,0 +1,49 @@
+require 'pinpoint/format/parse_error'
+
+module Pinpoint
+  class Format
+    class TokenList < Array
+
+      ##
+      # Public: Processes each item in the list by removing it and passing it to
+      # the block.
+      #
+      # At the end of the call, the list will be empty.
+      #
+      # Yields the Token of the iteration
+      #
+      # Returns nothing
+      #
+      def process_each!
+        while size > 0 do
+          token = delete_at(0)
+
+          yield token
+        end
+      end
+
+      ##
+      # Public: Verifies that the tokens in the list are in good form.
+      #
+      # Returns TrueClass if the tokens in the list are valid
+      # Raises Pinpoint::Format::UnevenNestingError if the number of
+      #   'group_start' tokens does not match the number of 'group_end' tokens.
+      #
+      def valid?
+        raise Pinpoint::Format::UnevenNestingError if group_start_count != group_end_count
+
+        true
+      end
+
+      private
+
+      def group_start_count
+        count { |token| token.type == :group_start }
+      end
+
+      def group_end_count
+        count { |token| token.type == :group_end }
+      end
+    end
+  end
+end

data/lib/pinpoint/format/tokenizer.rb

@@ -0,0 +1,172 @@
+require 'pinpoint/format/parse_error'
+require 'pinpoint/format/token_list'
+require 'pinpoint/format/token'
+
+###
+# Public: Has the ability to parse a String for specific token identifiers and
+# can process the resulting Tokens using any of the standard Enumerable messages.
+#
+module Pinpoint
+  class Format
+    class Tokenizer
+      include Enumerable
+
+      ##
+      # Public: Initializes a Tokenizer with a given String
+      #
+      def initialize(string_with_tokens)
+        self.tokenable = string_with_tokens
+      end
+
+      ##
+      # Public: From the beginning of the tokenable String, it reads each token
+      # and passes it to the block.
+      #
+      # Yields each successive Token to the given block
+      #
+      # Raises subclasses of Pinpoint::Format::ParseError upon various syntax
+      #   errors
+      #
+      # Returns nothing
+      #
+      def each
+        self.tokenable.reset
+
+        while current_token = next_token
+          yield current_token
+        end
+      end
+
+      ##
+      # Public: Wraps the Array of Tokens in a TokenList
+      #
+      # Returns a TokenList
+      #
+      def to_token_list
+        TokenList.new(self.to_a)
+      end
+
+      protected
+
+      # Protected: Reader for tokenable
+      attr_reader :tokenable
+
+      ##
+      # Protected: Sets tokenable but first checks to see if it needs to be
+      # wrapped in an IO object and does so if necessary.
+      #
+      def tokenable=(value)
+        io         = wrap_in_io_if_needed(value)
+
+        @tokenable = StringScanner.new(io.read)
+      end
+
+      ##
+      # Public: Allows the tokens used for the Tokenizer to be overridden.
+      #
+      # The value passed must be a Hash with keys representing the title of the
+      # token and values containing the Regex which represents a match for that
+      # Token.
+      #
+      # Example
+      #
+      #   token_map = { alphanumeric: /[A-Za-z0-9]/
+      #
+      attr_writer :token_map
+
+      ##
+      # Protected: Reads the token_map for the Tokenizer
+      #
+      # Returns the token_map if it is set, otherwise sets the token_map to the
+      # default and returns it.
+      #
+      def token_map
+        @token_map ||= {
+          literal:     /[^\(\)%]+/,
+          name:        /%n/,
+          street:      /%s/,
+          locality:    /%l/,
+          province:    /%p/,
+          postal_code: /%z/,
+          country:     /%c/,
+          percent:     /%%/,
+          left_paren:  /%\(/,
+          right_paren: /%\)/,
+          group_start: /\(/,
+          group_end:   /\)/
+        }
+      end
+
+      private
+
+      ##
+      # Private: Checks to see if the value passed in is an IO or something
+      # else.  If it's an IO, it remains unmodified, otherwise the value is
+      # converted to a StringIO.
+      #
+      # Example
+      #
+      #   wrap_in_io_if_needed(my_io_object)
+      #   # => my_io_object
+      #
+      #   wrap_in_io_if_needed('my_string')
+      #   # => <StringIO contents: 'my_string'>
+      #
+      #   wrap_in_io_if_needed(1)
+      #   # => <StringIO contents: '1'>
+      #
+      # Returns an IO object.
+      #
+      def wrap_in_io_if_needed(value)
+        case value
+        when IO
+          value
+        else
+          StringIO.new value.to_s
+        end
+      end
+
+      ##
+      # Private: Can locate the next token in the tokenable String
+      #
+      # Example
+      #
+      #   # When a Token can be found
+      #   next_token
+      #   # => <Token type: :token_type, value: 'my_token'>
+      #
+      #   # When a Token cannot be found
+      #   next_token
+      #   # => Pinpoint::Format::ParseError
+      #
+      #   # When there is nothing left to process
+      #   next_token
+      #   # => false
+      #
+      # Returns a Token if a match is found
+      # Returns FalseClass if there is nothing left to process
+      # Raises Pinpoint::Format::ParseError if an unknown Token is encountered
+      #
+      def next_token
+        return if tokenable.eos?
+
+        case
+        when text = tokenable.scan(token_map[:literal]);     Token.new(:literal,     text)
+        when text = tokenable.scan(token_map[:name]);        Token.new(:name,        text)
+        when text = tokenable.scan(token_map[:street]);      Token.new(:street,      text)
+        when text = tokenable.scan(token_map[:locality]);    Token.new(:locality,    text)
+        when text = tokenable.scan(token_map[:province]);    Token.new(:province,    text)
+        when text = tokenable.scan(token_map[:postal_code]); Token.new(:postal_code, text)
+        when text = tokenable.scan(token_map[:country]);     Token.new(:country,     text)
+        when text = tokenable.scan(token_map[:percent]);     Token.new(:literal,     '%')
+        when text = tokenable.scan(token_map[:left_paren]);  Token.new(:literal,     '(')
+        when text = tokenable.scan(token_map[:right_paren]); Token.new(:literal,     ')')
+        when text = tokenable.scan(token_map[:group_start]); Token.new(:group_start, text)
+        when text = tokenable.scan(token_map[:group_end]);   Token.new(:group_end,   text)
+        else
+          raise ParseError, "Cannot parse the remainder of the tokenable string: '#{tokenable.rest}'"
+        end
+      end
+    end
+  end
+end

data/lib/pinpoint/formatter.rb

@@ -0,0 +1,86 @@
+require 'pinpoint/format/list'
+
+module Pinpoint
+  class Formatter
+
+    ##
+    # Public: Is able to process an Address into numerous formats based on the
+    # country and style, or a completely custom format.
+    #
+    # address - An Object that responds to #name, #street, #city, #state,
+    #           #county, #country, #zip_code and #country.
+    # options - A Hash of options describing how the address should be formatted
+    #
+    #           :country - Each country displays its addresses in a specific
+    #                      format. Pinpoint knows about these. Passing in two
+    #                      letter ISO code as a Symbol for a country will use
+    #                      that country's format. (defaults to :us)
+    #           :style   - Can be a Symbol which relates to any style in the
+    #                      format file that is loaded. Default formats are:
+    #
+    #                        * :one_line
+    #                        * :one_line_with_name
+    #                        * :multi_line
+    #                        * :multi_line_with_name
+    #                        * :html
+    #
+    #                      All but the 'html' style is standard text.
+    #
+    #                      The :html option wraps each piece of the address as
+    #                      well as the entire address in HTML tags to which CSS
+    #                      can be applied for either a single-line or multi-line
+    #                      layout.
+    #
+    #                      Additionally :html will append classes to the
+    #                      different pieces of the address which correspond to
+    #                      both the globally generic name (eg 'locality').
+    #
+    # Example
+    #
+    #   format(address, :country => :us, :style => :one_line)
+    #   # => 'Kwik-E-Mart, 123 Apu Lane, Springfield, NW 12345, United States'
+    #
+    #
+    #   format(address, :country => :us, :style => :multi_line)
+    #   # => 'Kwik-E-Mart
+    #   #     123 Apu Lane
+    #   #     Springfield, NW 12345
+    #   #     United States'
+    #
+    #
+    #   format(address, country:  :us,
+    #                   style:    :html)
+    #
+    #   # => '<address>
+    #   #       <span class="section">
+    #   #         <span class="name">Kwik-E-Mart</span>
+    #   #       </span>
+    #   #       <span class="section">
+    #   #         <span class="street">123 Apu Lane</span>
+    #   #       </span>
+    #   #       <span class="section">
+    #   #         <span class="city locality">Springfield</span>
+    #   #         <span class="state state_or_province">NW</span>
+    #   #         <span class="zip_code postal_code">12345</span>
+    #   #       </span>
+    #   #       <span class="section">
+    #   #         <span class="country">United States</span>
+    #   #       </span>
+    #   #     </address>'
+    #
+    def self.format(address, options = {})
+      country = options.fetch(:country, :us)
+      style   = options.fetch(:style,   :one_line)
+
+      format  = formats[country]
+
+      format.output address, :style => style
+    end
+
+    private
+
+    def self.formats
+      @formats ||= Pinpoint::Format::List.new
+    end
+  end
+end

data/lib/pinpoint/validations.rb

@@ -1,5 +1,5 @@
-require 'pinpoint/us_states'
-require 'pinpoint/formats'
+require 'pinpoint/config/us_states'
+require 'pinpoint/config/patterns'
 
 module Pinpoint
   module Validations