module Geocoder

def self.configure(&block)


Provides convenient access to the Configuration singleton.
# 
def self.configure(&block)
  if block_given?
    block.call(Configuration.instance)
  else
    Configuration.instance
  end
end

def address(query)


or IP address (string).
Look up the address of the given coordinates ([lat,lon])
# 
def address(query)
  if (results = search(query)).size > 0
    results.first.address
  end
end

def blank_query?(value)


Is the given search query blank? (ie, should we not bother searching?)
# 
def blank_query?(value)
  !!value.to_s.match(/^\s*$/)
end

def cache


The working Cache object, or +nil+ if none configured.
# 
def cache
  if @cache.nil? and store = Configuration.cache
    @cache = Cache.new(store, Configuration.cache_prefix)
  end
  @cache
end

def coordinates(address)


Look up the coordinates of the given street or IP address.
# 
def coordinates(address)
  if (results = search(address)).size > 0
    results.first.coordinates
  end
end

def get_lookup(name)


Retrieve a Lookup object from the store.
# 
def get_lookup(name)
  @lookups = {} unless defined?(@lookups)
  @lookups[name] = spawn_lookup(name) unless @lookups.include?(name)
  @lookups[name]
end

def ip_address?(value)


dot-delimited numbers.
Does not check for actual validity, just the appearance of four

Does the given value look like an IP address?
# 
def ip_address?(value)
  !!value.to_s.match(/^(::ffff:)?(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/)
end

def ip_lookups


All IP address lookups, default first.
# 
def ip_lookups
  [:freegeoip]
end

def lookup(query)


depending on the query contents.
Takes a search query and returns an IP or street address Lookup
Get a Lookup object (which communicates with the remote geocoding API).
# 
def lookup(query)
  if ip_address?(query)
    get_lookup(ip_lookups.first)
  else
    get_lookup(Configuration.lookup || street_lookups.first)
  end
end

def search(query)


Search for information about an address or a set of coordinates.
# 
def search(query)
  blank_query?(query) ? [] : lookup(query).search(query)
end

def spawn_lookup(name)


Spawn a Lookup of the given name.
# 
def spawn_lookup(name)
  if valid_lookups.include?(name)
    name = name.to_s
    require "geocoder/lookups/#{name}"
    klass = name.split("_").map{ |i| i[0...1].upcase + i[1..-1] }.join
    Geocoder::Lookup.const_get(klass).new
  else
    valids = valid_lookups.map(&:inspect).join(", ")
    raise ConfigurationError, "Please specify a valid lookup for Geocoder " +
      "(#{name.inspect} is not one of: #{valids})."
  end
end

def street_lookups


All street address lookups, default first.
# 
def street_lookups
  [:google, :google_premier, :yahoo, :bing, :geocoder_ca, :yandex, :nominatim, :mapquest, :test]
end

def valid_lookups


Array of valid Lookup names.
# 
def valid_lookups
  street_lookups + ip_lookups
end