geohash36 0.3.0

data/lib/geohash36/interface/thor/mixin/shell.rb

@@ -0,0 +1,225 @@
+#!/usr/bin/env ruby
+
+
+# System includes
+require 'andand'
+require 'ptools'
+require 'tempfile'
+
+# Custom includes
+require File.expand_path( File.dirname( __FILE__ ) + '/guess' )
+
+
+# @module     module Mixin
+# @brief      Mixin module contains various functions to be used in other components
+module Mixin
+
+  # @module   Shell Module
+  # @brief    Module wrapper around shell commands
+  module Shell
+
+    include ::Mixin::Guess
+
+    # @fn       def initialize *args {{{
+    # @brief    Default constructor
+    #
+    # @param    [Array]     args      Argument array
+    def initialize *args
+      super
+    end # }}}
+
+    ## Actions
+
+    # @fn       def run command {{{
+    # @brief    Run the given command gracefully (without throwing exceptions)
+    #
+    # @param    [String]        command         The command to run
+    # @param    [RegExp]        regexp          Optional regular expression used for matching output
+    #
+    # @return   [String]        Returns empty string if command not found or other problem,
+    #                           otherwise result of command.
+    def run command, regexp = nil
+
+      result      = ''
+
+      begin
+        if( regexp.nil? )
+          result  = execute( command ).strip
+        else
+          raise ArgumentError, 'Regular Expression input needs to be of type Regexp' unless( regexp.is_a?( Regexp ) )
+
+          result  = execute( command ).andand.send( :match, regexp ).andand.send( :to_s ).strip
+        end
+
+      rescue Exception => e
+        say '(EE) ' + e.message, :red
+        result    = ''
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def execute command {{{
+    # @brief    Execute single shell command
+    #
+    # @param    [String]          command         Shell command string with arguments
+    #
+    # @return   [String]          Returns result of command
+    #
+    # @throws   [ArgumentError]   Throws exception if command not found
+    def execute command
+
+      exists  = which( command )
+      raise ArgumentError, "Command not found" unless( exists )
+      result  = `#{command}`
+
+      return result
+    end # }}}
+
+    # @fn       def which command {{{
+    # @brief    Checks if command is available
+    #
+    # @param    [String]        command         Shell command string with or without arguments.
+    #                                           If arguments are given, they are split on first
+    #                                           whitespace and discarded
+    #
+    # @return   [Boolean]       Returns boolean true if command is available, false if not
+    #
+    #
+    # @info     Crude alternative: `#{command} 2>/dev/null`.strip.empty?
+    def which command
+      result      = false
+
+      begin
+        partial   = command.to_s
+        partial   = partial.split(' ').first.to_s if( partial =~ %r{ }i )
+        path      = File.which( partial )
+
+        result    = true unless( path.nil? )
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result    = false
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def version command {{{
+    # @brief    Prints the version of given command, if command exists
+    #
+    # @param    [String]        command         Command string to probe version for, e.g. ruby
+    #
+    # @return   [String]        Returns version string or empty if command not found / error
+    def version command
+
+      result      = ""
+
+      begin
+
+        # Sanity
+        raise ArgumentError, "Command not found" unless( which( command ) )
+
+        # Get usage help screen for command
+        help      = usage( command )
+
+        # Get version flag from help screen
+        flag      = version_flag( help )
+
+        return result if( flag.empty? ) # some stupid commands don't follow standard rules, e.g. bundle
+
+        # Get actual version string
+        banner    = run( command + " " + flag )
+
+        # Guess way to extract and extract semver
+        result    = guess_version( banner.to_s )
+
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result    = ""
+      end
+
+      return result
+    end # }}}
+
+
+    alias_method :exists?, :which
+
+    private
+
+    # @fn       def usage command {{{
+    # @brief    Extracts help/usage screen from command
+    #
+    # @param    [String]        command         Command string
+    #
+    # @return   [String         Result screen output string
+    def usage command
+
+      result        = ""
+
+      begin
+
+        # Some commands misbehave when using wrong arguments
+        # e.g. java
+        help        = []
+
+        # Collect all possible outputs
+        %w(--help -h -help).each do |argument|
+          tempfile  = Tempfile.new( "geohash36-" )
+          `#{command} #{argument} > #{tempfile.path.to_s} 2>&1`
+          help      <<  File.read( tempfile.path )
+        end
+
+        # Prune to relevent one
+        help.each do |h|
+
+          # Sanity
+          next if( h.strip.empty? )
+          next if( h.split( "\n" ).length < 4 )
+          next unless( h.match( /unknown/i ).to_s.empty? )           # does it contain unknown? (argument)
+          next unless( h.match( /unrecognized/i ).to_s.empty? )      # does it contain unrecognized? (argument)
+          next unless( h.match( /error/i ).to_s.empty? )             # does it contain error
+          next unless( h.match( /does not exist/i ).to_s.empty? )    # does not exist error
+          next unless( result.empty? )
+
+          result    = h
+
+        end # of help.each
+
+
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result      = ""
+      end
+
+      return result
+    end # }}}
+
+    # @fn       def version_flag usage {{{
+    # @brief    Extracts version flag from usage help screen of command
+    #
+    # @param    [String]        usage         Usage help screen output (string), e.g. ruby --help
+    #
+    # @return   [String]        Returns the string which according to help screen will print version
+    #                           e.g. -version for java
+    def version_flag usage
+
+      result        = ""
+
+      begin
+        result      = usage.match( /--version/i ).to_s
+        result      = usage.match( /-version/i ).to_s if( result.empty? )
+      rescue Exception => e
+        say "(EE) " + e.message, :red
+        result      = ""
+      end
+
+      return result
+    end # }}}
+
+  end # of Module Shell
+
+end # of module Mixin
+
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/geohash36/interface/thor/version.thor

@@ -0,0 +1,33 @@
+#!/usr/bin/env ruby
+
+
+# @class  Server command class
+# @brief  Implements the server command
+class Version < Thor
+
+  default_task :show
+
+  ## API
+
+  # @fn       def show {{{
+  # @brief    Show version string of app
+  desc 'show', 'Show version of this app'
+  def show
+    version = Geohash36::VERSION
+
+    puts version
+  end # }}}
+
+
+  private
+
+  no_tasks do
+
+    ## Actions
+
+  end # of no_tasks do
+
+end # of Class Version
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/geohash36/library/interval.rb

@@ -0,0 +1,130 @@
+# Designed to provide additional functionality for arrays
+# to handle geographical intervals.
+class Geohash36::Interval < Array
+
+  # @param array [Array<Fixnum, Float>] array with length 2.
+  # @param options [Hash]
+  #   options affects borders in interval. By default, all borders are included.
+  #   If you want to exclude left border, pass: `include_left: false`
+  #   If you want to exclude right border, pass: `include_right: false`
+  # @example With default args
+  #   Geohash36::Interval.new
+  # @example With array and options
+  #    Geohash36::Interval.new([0, 6], include_right: false)
+  def initialize array = [0, 0], options = {}
+    array.try(:compact!)
+    validate_array(array)
+    array.each{|element| self.push element}
+    defaults = {include_right: true, include_left: true }
+    @opts = defaults.merge options
+  end
+
+  # Replace old interval options with new one
+  #
+  # @param options [Hash] new options for interval
+  def configure options = {}
+    @opts.merge! options
+  end
+
+  # Check if `number` between left and right border.
+  #
+  # @param number [Float, Fixmum] number to check
+  def include? number
+    for_left_border  = (@opts[:include_left] == true)  ? first  <= number : first < number
+    for_right_number = (@opts[:include_right] == true) ? number <= last  : number < last
+    for_left_border && for_right_number
+  end
+
+  # Split interval into 6 parts
+  # @return array of 6 intervals
+  def split
+    split3.each_with_object([]){|interval, result| result.concat interval.split2}
+  end
+
+  # Change values of interval
+  # @example
+  #   my_interval = Geohash36::Interval.new([0, 1])
+  #   my_interval.update [0,6]
+  #   my_interval # => [0, 6]
+  def update array
+    array.try(:compact!)
+    validate_array(array)
+    self.clear
+    array.each{|element| self.push element}
+  end
+
+  # @return string representation of object
+  def inspect
+    left_br  = @opts[:include_left]  ? "[" : "("
+    right_br = @opts[:include_right] ? "]" : ")"
+    "#{left_br}#{first}, #{last}#{right_br}"
+  end
+
+  # @return string representation of object
+  def to_s
+    inspect
+  end
+
+  # @return middle of the interval
+  # @example
+  #   Geohash36::Interval.new([0, 6]).middle
+  #   # => 3.0
+  def middle
+    (first + last)/2.0
+  end
+
+  # @return third part of interval (only positive values)
+  # @example
+  #   Geohash36::Interval.new([-2, 4]).third
+  #   # => 2.0
+  def third
+    ((last - first)/3.0).abs
+  end
+
+  # Split interval into 2 parts
+  # @return array of 2 intervals
+  def split2
+    [[first, middle], [middle, last]].map{|interval| Geohash36::Interval.new interval}
+  end
+
+  # Split interval into 3 parts
+  # @return array of 3 intervals
+  def split3
+    result = [[self.first, self.first+third], [self.first+third, self.first+2*third], [self.first+2*third, self.last]]
+    result.map{|array| Geohash36::Interval.new array}
+  end
+
+  # Convert array of arrays to array of `Geohash36::Interval`s
+  #
+  # @param array [Array] array to convert
+  # @param options [Hash] options for `Geohash36::Interval` object
+  #   but it works a little different. It is not affect first\last elements in array.
+  #   For example, if we do not want to include left border, only first element
+  #   will include left border because this class designed to handle geographical coordinates.
+  #   It is not designed for abstract intervals.
+  # @example
+  #   # for example, we don't want to include left border of interval,
+  #   # so we will have array like `[[0, 0], [0, 0], [0, 0]] ->> [[0, 0], (0, 0], (0, 0]]`
+  #
+  #   my_array = [[0, 2], [2, 6], [6, 10]]
+  #   Geohash36.convert_array(my_array, include_left: false)
+  #   # => [[0, 2], (2, 6], (6, 10]]
+  def self.convert_array array, options = {}
+    intervals = array.map{|interval| Geohash36::Interval.new interval, options }
+    intervals.first.configure(include_left: true) unless options[:include_left]
+    intervals.last.configure(include_right: true) unless options[:include_right]
+    intervals
+  end
+
+  private
+    # Check if array has valid values
+    def validate_array(array)
+      unless array.length == 2 && ( array.try(:first) <= array.try(:last) )
+        raise ArgumentError, "Not valid array for geohash interval"
+      end
+    end
+
+end # of class Geohash36::Interval
+
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/geohash36/version.rb

@@ -0,0 +1,13 @@
+#!/usr/bin/env ruby
+
+
+# @module   Geohash36 Module
+# @brief    Implements the Geohash36 module wrapper around the Geohash36 API
+class Geohash36
+
+  # Version of gem
+  VERSION = `git describe --tags`.split("-").first || "0.1.0"
+
+end
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/lib/geohash36.rb

@@ -0,0 +1,164 @@
+#!/usr/bin/env ruby
+
+
+# Standard includes
+require 'bundler'
+require 'thor'
+require 'rake'
+require 'ruby-try'
+
+# Provides complete solution for geohashing
+class Geohash36
+
+  # Geocode-36 matrix for map
+  GEOCODE_MATRIX = [
+    ['2', '3', '4', '5', '6', '7'],
+    ['8', '9', 'b', 'B', 'C', 'd'],
+    ['D', 'F', 'g', 'G', 'h', 'H'],
+    ['j', 'J', 'K', 'l', 'L', 'M'],
+    ['n', 'N', 'P', 'q', 'Q', 'r'],
+    ['R', 't', 'T', 'V', 'W', 'X']
+  ]
+  # Needed for inversion direction of latitude
+  GEOMATRIX_MAX_INDEX = 5
+  # Standart length of geocode
+  GEOCODE_LENGTH = 10
+  # Accuracy for coordinates when converting from geohash
+  DEFAULT_ACCURACY = 6
+
+  attr_reader :coords
+  attr_reader :hash
+  attr_accessor :accuracy
+
+  # Create new Geohash object from geohash or coordinates.
+  #
+  # @param object [Hash, String]
+  # @example Pass geohash
+  #   Geohash36.new "l222222222222"
+  # @example Pass coordinates
+  #   Geohash36.new latitude: 80, longitude: 20
+  def initialize(obj = { latitude: 0, longitude: 0 })
+    @accuracy = DEFAULT_ACCURACY
+    if obj.kind_of? Hash
+      Geohash36.validate_coords(obj)
+      @hash = Geohash36.to_geohash(obj)
+      @coords = obj
+    elsif obj.kind_of? String
+      Geohash36.validate_geohash(obj)
+      @hash = obj
+      @coords = Geohash36.to_coords(obj, @accuracy)
+    else
+      raise ArgumentError, "Argument type should be hash or string"
+    end
+  end
+
+  # Update geohash value. Coordinates will update automatically
+  def hash=(geohash)
+    raise ArgumenError unless geohash.kind_of? String
+    @hash = geohash
+    @coords = Geohash36.to_coords(geohash, @accuracy)
+  end
+
+  # Update coordinates values. Geohash will update automatically
+  def coords=(coords)
+    raise ArgumenError unless coords.kind_of? Hash
+    @hash = Geohash36.to_geohash(coords)
+    @coords.merge! coords
+  end
+
+
+  # Convert coordinates pair to geohash without creating an object
+  #
+  # @param coords [Hash] coordinates to convert
+  # @return [String] geohash
+  # @example
+  #   Geohash36.to_geohash(latitude: 0, longitude: 0)
+  #   # => "l222222222"
+  def self.to_geohash(coords)
+    Geohash36.validate_coords(coords)
+    lon_interval = Geohash36.basic_lon_interval
+    lat_interval = Geohash36.basic_lat_interval
+
+    (0...GEOCODE_LENGTH).map{Geohash36.geohash_symbol!(lon_interval, lat_interval, coords)}.join
+  end
+
+  # Convert geohash to coords without creating an object.
+  #
+  # @param [String] geohash
+  # @param accuracy [Fuxnum] accuracy for coordinates values
+  # @return [Hash] coordinates
+  # @example With default accuracy
+  #   Geohash36.to_coords("l222222222")
+  #   # => {:latitude=>-1.0e-06, :longitude=>3.0e-06}
+  # @example With accuracy 3
+  #   Geohash36.to_coords("l222222222", 3)
+  #   # => {:latitude=>0.0, :longitude=>0.0}
+  def self.to_coords(geohash, accuracy = DEFAULT_ACCURACY)
+    Geohash36.validate_geohash(geohash)
+
+    lon_interval = Geohash36.basic_lon_interval
+    lat_interval = Geohash36.basic_lat_interval
+
+    geohash.each_char do |c|
+      lon_intervals = Geohash36::Interval.convert_array(lon_interval.split)
+      lat_intervals = Geohash36::Interval.convert_array(lat_interval.split)
+
+      lat_index, lon_index = 0, 0
+
+      GEOCODE_MATRIX.each_with_index do |row, row_index|
+        if row.include? c
+          lat_index = GEOMATRIX_MAX_INDEX-row_index
+          lon_index = row.index(c)
+          break
+        end
+      end
+
+      lon_interval.update lon_intervals[lon_index]
+      lat_interval.update lat_intervals[lat_index]
+    end
+
+    { latitude:  lat_interval.middle.round(accuracy) ,
+      longitude: lon_interval.middle.round(accuracy) }
+  end
+
+  private
+    def self.basic_lon_interval
+      Geohash36::Interval.new [-180, 180]
+    end
+
+    def self.basic_lat_interval
+      Geohash36::Interval.new [-90, 90]
+    end
+
+    def self.validate_geohash(geohash)
+      unless geohash =~ /\A[23456789bBCdDFgGhHjJKlLMnNPqQrRtTVWX]+{1,10}\z/
+        raise ArgumentError, "It is not Geohash-36."
+      end
+    end
+
+    def self.validate_coords(coords)
+      keys = coords.keys
+      raise ArgumentError, "Invalid hash" unless keys.length == 2 && keys.include?(:latitude) && keys.include?(:longitude)
+      lat_inclusion = Geohash36.basic_lat_interval.include? coords[:latitude]
+      lon_inclusion = Geohash36.basic_lon_interval.include? coords[:longitude]
+      raise ArgumentError, "Invalid hash values" unless lat_inclusion && lon_inclusion
+    end
+
+    def self.geohash_symbol!(lon_interval, lat_interval, coords)
+      lon_intervals = Geohash36::Interval.convert_array(lon_interval.split, include_right: false)
+      lat_intervals = Geohash36::Interval.convert_array(lat_interval.split, include_left: false)
+
+      lon_index = lon_intervals.index {|interval| interval.include? coords[:longitude] }
+      lat_index = lat_intervals.index {|interval| interval.include? coords[:latitude]  }
+
+      lon_interval.update lon_intervals[lon_index]
+      lat_interval.update lat_intervals[lat_index]
+
+      GEOCODE_MATRIX[GEOMATRIX_MAX_INDEX-lat_index][lon_index]
+    end
+
+end # of module Geohash36
+
+Dir[File.dirname(__FILE__) + '/geohash36/library/*.rb'].each {|file| require file }
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/spec/geohash36_spec.rb

@@ -0,0 +1,52 @@
+#!/usr/bin/env ruby
+
+# System include
+require 'spec_helper'
+
+
+describe Geohash36 do
+
+  it { expect{Geohash36.to_geohash(Hash.new)}.to raise_error(ArgumentError) }
+  it { expect{Geohash36.new 111 }.to raise_error(ArgumentError) }
+  it { expect{Geohash36.new Hash.new }.to raise_error(ArgumentError) }
+  it { expect{Geohash36.new "BB99999999"}.not_to raise_error }
+  it { expect{Geohash36.new latitude: 1, longitude: 2}.not_to raise_error }
+
+
+  context "when default args" do
+    context "coordinates" do
+      subject { Geohash36.new }
+
+      let(:default_coords)  { {latitude: 0, longitude: 0} }
+      let(:default_hash)    { 'l222222222' }
+      let(:some_coords)     { {latitude: 54, longitude: 32} }
+      let(:some_hash)       { 'BB99999999' }
+
+      its(:coords) { is_expected.to eq(default_coords)}
+      its(:hash)   { is_expected.to eq(default_hash)}
+
+      it "should change coords when hash updated" do
+        expect{subject.hash = some_hash}.to change{subject.coords}
+      end
+
+      it "should change hash when coords updated" do
+        expect{subject.coords = some_coords}.to change{subject.hash}
+      end
+
+      it "should give appropriate hash for coords" do
+        subject.coords = some_coords
+        expect(subject.hash).to eq(some_hash)
+      end
+
+      it "should give appropriate coords for hash" do
+        subject.accuracy = 2
+        subject.hash = some_hash
+        expect(subject.coords).to eq(some_coords)
+      end
+
+      it { expect{subject.hash = ""}.to raise_error(ArgumentError) }
+    end # of context
+  end # of context
+end # of describe
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby

data/spec/library/interval_spec.rb

@@ -0,0 +1,55 @@
+#!/usr/bin/env ruby
+
+# Custom include
+require 'spec_helper'
+
+describe Geohash36::Interval do
+  it { expect{Geohash36::Interval.new [0]}.to raise_error(ArgumentError) }
+
+  context "[0, 6]" do
+    subject { Geohash36::Interval.new([0, 6]) }
+
+    its(:middle) { should == 3.0 }
+    its(:third)  { should == 2.0 }
+    its(:split2) { should == [[0, 3.0], [3.0, 6]] }
+    its(:split3) { should == [[0, 2.0], [2.0, 4.0], [4.0, 6]] }
+    its(:split)  { should == [[0, 1.0], [1.0, 2.0], [2.0, 3.0], [3.0, 4.0], [4.0, 5.0], [5.0, 6]] }
+
+    context "when include all border" do
+      it { subject.to_s.should eq("[0, 6]")}
+      it { is_expected.to     include?(0) }
+      it { is_expected.to     include?(2) }
+      it { is_expected.to     include?(6) }
+      it { is_expected.to_not include?(9) }
+    end
+
+    context "when not include right border" do
+      subject { Geohash36::Interval.new([0, 6], include_right: false) }
+
+      it { subject.to_s.should eq("[0, 6)")}
+      it { is_expected.to     include?(0) }
+      it { is_expected.to     include?(2) }
+      it { is_expected.to_not include?(6) }
+      it { is_expected.to_not include?(9) }
+    end
+
+    context "when not include left border" do
+      subject { Geohash36::Interval.new([0, 6], include_left: false) }
+
+      it { subject.to_s.should eq("(0, 6]")}
+      it { is_expected.to_not include?(0) }
+      it { is_expected.to     include?(2) }
+      it { is_expected.to     include?(6) }
+      it { is_expected.to_not include?(9) }
+    end
+
+    describe "#update" do
+      it "should properly update interval" do
+        expect{subject.update [1, 3]}.to change{subject}.to([1,3])
+      end
+    end
+
+  end # of context
+end # of describe Geohash36::Interval
+
+# vim:ts=2:tw=100:wm=100:syntax=ruby