rats 0.1.0

data/.document

@@ -0,0 +1,5 @@
+README.rdoc
+lib/**/*.rb
+bin/*
+features/**/*.feature
+LICENSE

data/.gitignore

@@ -0,0 +1,22 @@
+## MAC OS
+.DS_Store
+
+## TEXTMATE
+*.tmproj
+tmtags
+
+## EMACS
+*~
+\#*
+.\#*
+
+## VIM
+*.swp
+
+## PROJECT::GENERAL
+coverage
+rdoc
+pkg
+
+## PROJECT::SPECIFIC
+docs

data/LICENSE

@@ -0,0 +1,20 @@
+Copyright (c) 2009 Mark
+
+Permission is hereby granted, free of charge, to any person obtaining
+a copy of this software and associated documentation files (the
+"Software"), to deal in the Software without restriction, including
+without limitation the rights to use, copy, modify, merge, publish,
+distribute, sublicense, and/or sell copies of the Software, and to
+permit persons to whom the Software is furnished to do so, subject to
+the following conditions:
+
+The above copyright notice and this permission notice shall be
+included in all copies or substantial portions of the Software.
+
+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.

data/README.rdoc

@@ -0,0 +1,181 @@
+= rats
+
+a.k.a. Ruby Alberta Township System
+
+A ruby class to help with using the Alberta Township System
+
+You may find it amusing that Alberta was Rat-free ... until now.
+
+== ATS
+
+Alberta Township system is a land survey grid used in Alberta, Canada that
+divides the whole province into addressable locations.
+
+A typical location looks like: NE 1-2-3 W4
+
+Which can be broken down as follows ...
+
+=== Meridian
+
+from above example: [W4] West of the 4th Meridian
+
+The Meridian is a constant line running perpendicular to the line of longitude,
+and increments approx. every 4th line of longitude, from East to West.
+
+Alberta contains 3 of these Meridians, W4 through W6.
+
+=== Range
+a.k.a Range Lines
+
+from above example: [3]
+
+The Range is the x-axis within the given Meridian.  It increases East to West and
+resets at the next Meridian.  Each increase is approx. every 6 miles.
+
+NOTE: The longitude lines are closer together the further North you get, so as
+you go North, there is less Ranges from East to West.
+
+=== Township
+a.k.a. Township Lines
+
+from above example: [2]
+
+The Township is the y-axis with the Meridian.  It increases South to North and
+never resets, running from the Alberta-US border to the Northern border of Alberta.
+Each increase is approx. every 6 miles.
+
+NOTE: The 6x6 mile "square" indicated by the Township (line) + Range (line) +
+Meridian is confusingly called a Township.  So you have the Township line and
+the 6x6 mile Township "square".
+
+NOTE: Due to the longitude lines getting closer as you go North, there are small
+correction made South to North which results in a non-uniform stacking of Townships.
+Therefore you can not assume that going straight North from one Township to another
+will result in a Township with the same Township-line number.
+
+=== Section
+
+from above example: [1]
+
+The Section represents a number 1x1 miles "square" within the 6x6 mile Township.
+There can be up to a maximum of 36 Sections in a township.  The number starts with
+1 in the South-East corner and travels West to number 6.  It then increases to 7
+North of number 6 and counts up West-to-East until the number 12.  It snakes back
+and forth until it finishes at number 36 in the North-East corner.
+
+=== Quarter
+a.k.a. Quarter Section
+
+from above example: [NE]
+
+The Quarter represents a 1/2 x 1/2 mile square within the 1x1 mile Section.
+There can be 4 Quarters in a Section.  They are identified by "NE", "NW", "SE"
+and "SW".
+
+== Purpose
+
+The purpose of Rats is to make it easier to deal with location described using
+the Alberta Township System, at the Quarter, Section or Township level.
+
+=== Validation
+
+Included is validations, only allowing you to describe locations that actually
+exist. 
+
+For example, Range-line 30 is valid for Township-lines 1-18, but not 18-126.
+
+=== Parsing
+
+Included is string parsing, allowing you to extract and separate the different
+fields from multiple string representations of the location.
+
+For example, NE 1-2-3 W4 and 40300201NE are both recognized and parsed.
+
+=== Display
+
+Included is string creation that can create common representations of the
+location.
+
+=== Traversing
+
+NOTE: This is experimental and can probably be improved and made more exact.
+See 'Assumptions' to see where possible errors may exist.
+
+In this case, traverse means go North, South, East or West of a given location
+and know what the new location is.
+
+Within a Township you can traverse any direction from:
+- quarter to quarter
+- quarter to section
+- section to section
+
+When leaving a Township, you can only traverse West and East from:
+- quarter to quarter
+- quarter to section
+- quarter to township
+- section to section
+- section to township
+- township to township
+
+NOTE: The limitation in traversing from one Township to another is
+due to correction lines and the nature that Townships due no run vertical
+from North to South.  It might be possible to include a way to allow this
+but I do not currently need it.
+
+= Usage
+
+TODO: show examples
+
+= Information
+
+== links
+
+http://en.wikipedia.org/wiki/Alberta_Township_System
+
+== Road Map
+
+Future:
+- add support for Saskatchewan (no timeline)
+- address bugs, if any
+
+Except for the above, once this gem is finalized, I do not see future
+development happening unless the North-South Township traversing needs
+to be addressed or I want to add ATS to other-system conversions
+(ie: latitude/longitude).  Nothing else is planned.
+
+Currently this point has not been reached and this gem is still in development.
+
+== Assumptions
+
+The only assumptions made are in respects to traversing.  I do assume that
+traversing within a township, that all sections and quarter sections are
+perfectly aligned.  If this is not correct, it must be pretty close, and
+is close enough for my purpose.
+
+I also assume that all townships are perfectly aligned from East to West.
+
+Lastly, I assume that within every valid section, all four quarters are valid.
+This may be the false.  Even so, I do not have a list of which sections do not
+have four quarters (let alone which ones are missing), so I couldn't do anything
+about it anyway.
+
+== Environment
+
+This gem was created using:
+- ruby 1.9.1-p378
+- rspec 1.3.0
+- rake 0.8.7
+
+== Note on Patches/Pull Requests
+ 
+* Fork the project.
+* Make your feature addition or bug fix.
+* Add tests for it. This is important so I don't break it in a
+  future version unintentionally.
+* Commit, do not mess with rakefile, version, or history.
+  (if you want to have your own version, that is fine but bump version in a commit by itself I can ignore when I pull)
+* Send me a pull request. Bonus points for topic branches.
+
+== Copyright
+
+Copyright (c) 2010 Mark. See LICENSE for details.

data/Rakefile

@@ -0,0 +1,46 @@
+require 'rubygems'
+require 'rake'
+
+begin
+  require 'jeweler'
+  Jeweler::Tasks.new do |gem|
+    gem.name = "rats"
+    gem.summary = "A ruby class to help with using the Alberta Township System"
+    gem.description = "A ruby class to help with using the Alberta Township System"
+    gem.email = "rats@attackcorp.com"
+    gem.homepage = "http://github.com/attack/rats"
+    gem.authors = ["Mark G"]
+    #gem.add_development_dependency "rspec", ">= 1.2.9"
+    # gem is a Gem::Specification... see http://www.rubygems.org/read/chapter/20 for additional settings
+  end
+  Jeweler::GemcutterTasks.new
+rescue LoadError
+  puts "Jeweler (or a dependency) not available. Install it with: gem install jeweler"
+end
+
+require 'spec/rake/spectask'
+Spec::Rake::SpecTask.new(:spec) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.spec_files = FileList['spec/**/*_spec.rb']
+  spec.spec_opts = ["-c"]
+end
+
+Spec::Rake::SpecTask.new(:rcov) do |spec|
+  spec.libs << 'lib' << 'spec'
+  spec.pattern = 'spec/**/*_spec.rb'
+  spec.rcov = true
+end
+
+task :spec => :check_dependencies
+
+task :default => :spec
+
+require 'rake/rdoctask'
+Rake::RDocTask.new do |rdoc|
+  version = File.exist?('VERSION') ? File.read('VERSION') : ""
+
+  rdoc.rdoc_dir = 'rdoc'
+  rdoc.title = "rats #{version}"
+  rdoc.rdoc_files.include('README*')
+  rdoc.rdoc_files.include('lib/**/*.rb')
+end

data/VERSION

@@ -0,0 +1 @@
+0.1.0

data/lib/rats/base.rb

@@ -0,0 +1,264 @@
+module Rats
+  class Base
+    
+    def initialize(*args)
+      return unless args.flatten!
+      @quarter = Rats::Quarter.new
+      @section = Rats::Section.new
+      @township = Rats::Township.new
+      @range = Rats::Range.new
+      @meridian = Rats::Meridian.new
+      if args.size == 1
+        parse_string(args.pop)
+      else
+        set_values(args)
+      end
+    end
+    
+    def q; @quarter; end
+    def s; @section; end
+    def t; @township; end
+    def r; @range; end
+    def m; @meridian; end
+    
+    def q=(v); @quarter = v; end
+    def s=(v); @section = v; end
+    def t=(v); @township = v; end
+    def r=(v); @range = v; end
+    def m=(v); @meridian = v ; end
+
+    def quarter; @quarter.v; end
+    def section; @section.v; end
+    def township; @township.v; end
+    def range; @range.v; end
+    def meridian; @meridian.v; end
+
+    def quarter=(v); @quarter.v = v; end
+    def section=(v); @section.v = v; end
+    def township=(v); @township.v = v; end
+    def range=(v); @range.v = v; end
+    def meridian=(v); @meridian.v = v; end
+
+    def location(format = :long)
+      case format
+      when :short
+        short_location
+      when :long
+        long_location
+      else
+        long_location
+      end
+    end
+
+    def location=(value)
+      return unless value
+      if value.is_a?(Array)
+        set_values(value)
+      else  
+        parse_string(value)
+      end
+    end
+    
+    def to_s
+      long_location
+    end
+
+    def scope
+      if self.meridian && self.range && self.township
+        if self.section
+          if self.quarter
+            :quarter
+          else
+            :section
+          end
+        else
+          :township
+        end
+      else
+        :unknown
+      end
+    end
+
+    def valid?
+      self.meridian && self.range && self.township && self.exists?
+    end
+    
+    # test that a location actually exists
+    #
+    def exists?
+      # make sure meridian exists
+      return false unless TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian]
+      
+      # make sure range exists
+      return false unless TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian][self.range]
+      
+      # make sure township exists
+      return false unless TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian][self.range][:townships].include?(self.township)
+      
+      # make sure section exists
+      
+      # it is possible all sections exists for all townships
+      if TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian][self.range].has_key?(:sections)
+        # NO, now see if this township has valid sections
+        if TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian][self.range][:sections].has_key?(self.township)
+          # YES, check further to see that this section is listed          
+          return TOWNSHIPS_BY_RANGE_AND_MERIDIAN[self.meridian][self.range][:sections][self.township].include?(self.section)
+        else
+          # the township isn't listed, therefore it has all sections
+          return true
+        end
+      else
+        # looks like we exist
+        return true
+      end
+    end
+    
+    def up(level=nil); self.traverse(:up, level); end
+    def down(level=nil); self.traverse(:down, level); end
+    def left(level=nil); self.traverse(:left, level); end
+    def right(level=nil); self.traverse(:right, level); end
+    alias north up
+    alias south down
+    alias west left
+    alias east right
+    
+    # this just walks from location to location in the given direction until
+    # it finds the next valid location.
+    #
+    def traverse(direction, level=nil)
+      return unless direction
+      
+      new_location = self.dup
+      # change the scope of the traverse
+      # eg. allow quarter section to traverse to a section
+      #
+      case level
+      when :section
+        # we are traversing by section, remove quarter
+        new_location.q.nil!
+      when :township
+        # we are traversing by section, remove quarter & section
+        new_location.q.nil!
+        new_location.s.nil!
+      end
+
+      the_scope = new_location.scope
+      begin
+        case the_scope
+        when :quarter
+          new_location._traverse_quarter(direction)
+        when :section
+          new_location._traverse_section(direction)
+        when :township
+          new_location._traverse_range(direction)
+        end
+      end until new_location.valid?
+      new_location
+    end
+     
+    def _traverse_quarter(direction)
+      begin
+        self.q = self.q.send(direction)
+      rescue OutOfSection
+        self.q = self.q.send(direction.to_s + '!')
+        self._traverse_section(direction)
+      end
+    end
+  
+    def _traverse_section(direction)
+      begin
+        self.s = self.s.send(direction)
+      rescue OutOfTownship
+        self.s = self.s.send(direction.to_s + '!')
+        self._traverse_range(direction)
+      end
+    end
+  
+    def _traverse_range(direction)
+      begin
+        self.r = self.r.send(direction)
+      rescue OutOfMeridian
+        self.r = self.r.send(direction.to_s + '!')
+        self._traverse_meridian(direction)
+      end
+    end
+  
+    def _traverse_meridian(direction)
+      begin
+        self.m = self.m.send(direction)
+      rescue
+        raise OutOfAlberta
+      end
+    end
+    
+    def to_a
+      [self.quarter, self.section, self.township, self.range, self.meridian].compact
+    end
+       
+    private
+
+    def parse_string(location)
+      return unless location.respond_to?('to_s')
+
+      case location_type?(location)
+      when :description
+        parse_description(location)
+      when :parcel_id
+        parse_parcel_id(location)
+      end
+    end
+
+    def location_type?(location)
+      location.to_s.match(/^\d{8}\D{2}/) ? :parcel_id : :description
+    end
+
+    def parse_description(description)
+      quarter = description.to_s.scan(/^\D{2}/)
+      self.quarter = quarter[0].upcase if quarter && quarter.size > 0
+
+      numbers = description.to_s.scan(/\d{1,3}/)
+      if numbers
+        self.meridian = numbers.pop.to_i if numbers.size > 0
+        self.range = numbers.pop.to_i if numbers.size > 0
+        self.township = numbers.pop.to_i if numbers.size > 0
+        self.section = numbers.pop.to_i if numbers.size > 0
+      end
+      true
+    end
+
+    def parse_parcel_id(parcel_id)
+      result = parcel_id.to_s.scan(/^(\d{1})(\d{2})(\d{3})(\d{2})(\D{2})/)
+      return unless result && result.size > 0
+      numbers = result.pop
+      self.meridian = numbers.shift.to_i if numbers.size > 0
+      self.range = numbers.shift.to_i if numbers.size > 0
+      self.township = numbers.shift.to_i if numbers.size > 0
+      self.section = numbers.shift.to_i if numbers.size > 0
+      self.quarter = numbers.shift.to_s if numbers.size > 0
+      true
+    end
+
+    def set_values(values)
+      #self.quarter = values.shift
+      self.quarter = values.shift.to_s if values.size > 0
+      self.section = values.shift.to_i if values.size > 0
+      self.township = values.shift.to_i if values.size > 0
+      self.range = values.shift.to_i if values.size > 0
+      self.meridian = values.shift.to_i if values.size > 0
+    end
+    
+
+    def long_location
+      if self.quarter
+        "#{@quarter.to_s} #{[@section.to_s,@township.to_s,@range.to_s].compact.join('-')} #{@meridian.to_s}".strip
+      else
+        "#{[@section.to_s,@township.to_s,@range.to_s].compact.join('-')} #{@meridian.to_s}".strip
+      end
+    end
+
+    def short_location
+      [@quarter.to_p,@section.to_p,@township.to_p,@range.to_p,@meridian.to_p].compact.join('').strip
+    end
+    
+  end
+end