myl-fech 1.0.3

data/lib/fech/filing.rb

@@ -0,0 +1,341 @@
+require 'tmpdir'
+require 'open-uri'
+
+module Fech
+  
+  # Fech::Filing downloads an Electronic Filing given its ID, and will search
+  # rows by row type. Using a child Translator object, the data in each row
+  # is automatically mapped at runtime into a labeled Hash. Additional
+  # Translations may be added to change the way that data is mapped and cleaned.
+  class Filing
+    # first filing number using the version >=3.00 format
+    # note that there are plenty of <v3 filings after this, so readable? still needs to be checked
+    FIRST_V3_FILING = 11850 
+    
+    attr_accessor :filing_id, :download_dir, :translator
+
+    # Create a new Filing object, assign the download directory to system's
+    # temp folder by default.
+    # @param [String] download_dir override the directory where files should
+    #   be downloaded.
+    # @param [Symbol,Array] translate a list of built-in translation sets to use
+    def initialize(filing_id, opts={})
+      @filing_id    = filing_id
+      @download_dir = opts[:download_dir] || Dir.tmpdir
+      @translator   = Fech::Translator.new(:include => opts[:translate])
+      @quote_char   = opts[:quote_char] || '"'
+      @csv_parser   = opts[:csv_parser] || Fech::Csv
+      @resaved      = false
+      @customized   = false
+    end
+
+    # Saves the filing data from the FEC website into the default download
+    # directory.
+    def download
+      File.open(file_path, 'w') do |file|
+        file << open(filing_url).read
+      end
+      self
+    end
+    
+    # This downloads ALL the filings.
+    #
+    # Because this trashes the zip files after extraction (to save space), while it is safe to rerun, it has to do the whole thing over again.
+    # Update operations should just iterate single file downloads starting from the current+1th filing number.
+    # 
+    # This takes a very long time to run - on the order of an hour or two, depending on your bandwidth.
+    #
+    # WARNING: As of July 9, 2012, this downloads 536964 files (25.8 GB), into one directory. 
+    # This means that the download directory will break bash file globbing (so e.g. ls and rm *.fec will not work).
+    # If you want to get all of it, make sure to download only to a dedicated FEC filings directory.
+    def self.download_all download_dir
+      `cd #{download_dir} && ftp -a ftp.fec.gov:/FEC/electronic/*.zip`
+      `cd #{download_dir} && for z in *.zip; do unzip -o $z && rm $z; done`
+      Dir[File.join(download_dir, '*.fec')].count
+    end
+
+    # Runs the passed block on every downloaded .fec file. Pass the same options hash as you would to Fech::Filing.new.
+    # E.g. for_all(:download_dir => Rails.root.join('db', 'data', 'fec', 'filings', :csv_parser => Fech::CsvDoctor, ...) {|filing| ... }
+    # filing.download is of course unnecessary.
+    #
+    # note that if there are a lot of files (e.g. after download_all), just listing them to prepare for this will take several seconds
+    def self.for_all options = {}
+      options[:download_dir] ||= Dir.tmpdir
+      # .sort{|x| x.scan/\d+/.to_i } # should be no need to spend time on sort, since the file system should already do that
+      Dir[File.join(options[:download_dir], '*.fec')].each do |file|
+        yield Fech::Filing.new(file.scan(/(\d+)\.fec/)[0][0].to_i, options)
+      end
+    end
+    
+    # Access the header (first) line of the filing, containing information
+    # about the filing's version and metadata about the software used to file it.
+    # @return [Hash] a hash that assigns labels to the values of the filing's header row
+    def header(opts={})
+      each_row do |row|
+        return parse_row?(row)
+      end
+    end
+    
+    # Access the summary (second) line of the filing, containing aggregate and
+    # top-level information about the filing.
+    # @return [Hash] a hash that assigns labels to the values of the filing's summary row
+    def summary
+      each_row_with_index do |row, index|
+        next if index == 0
+        return parse_row?(row)
+      end
+    end
+    
+    # Access all lines of the filing that match a given row type. Will return an
+    # Array of all available lines if called directly, or will yield the mapped
+    # rows one by one if a block is passed.
+    #
+    # @param [String, Regexp] row_type a partial or complete name of the type of row desired
+    # @option opts [Boolean] :raw should the function return the data as an array
+    #   that has not been mapped to column names
+    # @option opts [Array] :include list of field names that should be included
+    #   in the returned hash
+    # @yield [Hash] each matched row's data, as either a mapped hash or raw array
+    # @return [Array] the complete set of mapped hashes for matched lines
+    def rows_like(row_type, opts={}, &block)
+      data = []
+      each_row do |row|
+        value = parse_row?(row, opts.merge(:parse_if => row_type))
+        next if value == false
+        if block_given?
+          yield value
+        else
+          data << value if value
+        end
+      end
+      block_given? ? nil : data
+    end
+    
+    # Decides what to do with a given row. If the row's type matches the desired
+    # type, or if no type was specified, it will run the row through #map.
+    # If :raw was passed true, a flat, unmapped data array will be returned.
+    #
+    # @param [String, Regexp] row a partial or complete name of the type of row desired
+    # @option opts [Array] :include list of field names that should be included
+    #   in the returned hash
+    def parse_row?(row, opts={})
+      # Always parse, unless :parse_if is given and does not match row
+      if opts[:parse_if].nil? || \
+          Fech.regexify(opts[:parse_if]).match(row.first.downcase)
+        opts[:raw] ? row : map(row, opts)
+      else
+        false
+      end
+    end
+
+    # Maps a raw row to a labeled hash following any rules given in the filing's
+    # Translator based on its version and row type.
+    # Finds the correct map for a given row, performs any matching Translations
+    # on the individual values, and returns either the entire dataset, or just
+    # those fields requested.
+    # @param [String, Regexp] row a partial or complete name of the type of row desired
+    # @option opts [Array] :include list of field names that should be included
+    #   in the returned hash
+    def map(row, opts={})
+      data = Fech::Mapped.new(self, row.first)
+      full_row_map = map_for(row.first)
+      
+      # If specific fields were asked for, return only those
+      if opts[:include]
+        row_map = full_row_map.select { |k| opts[:include].include?(k) }
+      else
+        row_map = full_row_map
+      end
+      
+      # Inserts the row into data, performing any specified preprocessing
+      # on individual cells along the way
+      row_map.each_with_index do |field, index|
+        value = row[full_row_map.index(field)]
+        translator.get_translations(:row => row.first,
+            :version => filing_version, :action => :convert,
+            :field => field).each do |translation|
+          # User's Procs should be given each field's value as context
+          value = translation[:proc].call(value)
+        end
+        data[field] = value
+      end
+      
+      # Performs any specified group preprocessing / combinations
+      combinations = translator.get_translations(:row => row.first,
+            :version => filing_version, :action => :combine)
+      row_hash = hash_zip(row_map, row) if combinations
+      combinations.each do |translation|
+        # User's Procs should be given the entire row as context
+        value = translation[:proc].call(row_hash)
+        field = translation[:field].source.gsub(/[\^\$]*/, "").to_sym
+        data[field] = value
+      end
+      
+      data
+    end
+    
+    # Returns the column names for given row type and the filing's version
+    # in the order they appear in row data.
+    # @param [String, Regexp] row_type representation of the row desired
+    def map_for(row_type)
+      mappings.for_row(row_type)
+    end
+    
+    # Returns the column names for given row type and version in the order
+    # they appear in row data.
+    # @param [String, Regexp] row_type representation of the row desired
+    # @option opts [String, Regexp] :version representation of the version desired
+    def self.map_for(row_type, opts={})
+      Fech::Mappings.for_row(row_type, opts)
+    end
+    
+    # @yield [t] returns a reference to the filing's Translator
+    # @yieldparam [Translator] the filing's Translator
+    def translate(&block)
+      if block_given?
+        yield translator
+      else
+        translator
+      end
+    end
+    
+    # Whether this filing amends a previous filing or not.
+    def amendment?
+      !amends.nil?
+    end
+    
+    # Returns the filing ID of the past filing this one amends,
+    # nil if this is a first-draft filing.
+    # :report_id in the HDR line references the amended filing
+    def amends
+      header[:report_id]
+    end
+    
+    # Combines an array of keys and values into an Fech::Mapped object,
+    # a type of Hash.
+    # @param [Array] keys the desired keys for the new hash
+    # @param [Array] values the desired values for the new hash
+    # @return [Fech::Mapped, Hash]
+    def hash_zip(keys, values)
+      Fech::Mapped.new(self, values.first).merge(Hash[*keys.zip(values).flatten])
+    end
+    
+    # The version of the FEC software used to generate this Filing
+    def filing_version
+      @filing_version ||= parse_filing_version
+    end
+    
+    # Pulls out the version number from the header line.
+    # Must parse this line manually, since we don't know the version yet, and
+    # thus the delimiter type is still a mystery.
+    def parse_filing_version
+      first = File.open(file_path).first
+      if first.index("\034").nil?
+        @csv_parser.parse(first).flatten[2]
+      else
+        @csv_parser.parse(first, :col_sep => "\034").flatten[2]
+      end
+    end
+    
+    # Only FEC format 3.00 + is supported
+    def readable?
+      filing_version.to_i >= 3
+    end
+    
+    # Gets or creats the Mappings instance for this filing_version
+    def mappings
+      @mapping ||= Fech::Mappings.new(filing_version)
+    end
+
+    # The location of the Filing on the file system
+    def file_path
+      File.join(download_dir, file_name)
+    end
+
+    # The raw contents of the Filing
+    def file_contents
+      File.open(file_path, 'r')
+    end
+
+    # Determine the form type of the filing
+    # before it's been parsed. This is needed
+    # for the F99 special case.
+    def form_type
+      file_contents.lines.each_with_index do |row, index|
+        next if index == 0
+        return row.split(delimiter).first
+      end
+    end
+
+    # The file path where custom versions
+    # of a filing are to be saved.
+    def custom_file_path
+      File.join(download_dir, "fech_#{file_name}")
+    end
+
+    # Handle the contents of F99s by removing the
+    # [BEGINTEXT] and [ENDTEXT] delimiters and
+    # putting the text content onto the same
+    # line as the summary.
+    def fix_f99_contents
+      @customized = true
+      content = file_contents.read
+      regex = /\n\[BEGINTEXT\]\n(.*?)\[ENDTEXT\]\n/mi # some use eg [EndText]
+      match = content.match(regex)
+      if match
+        repl = match[1].gsub(/"/, '""')
+        content.gsub(regex, "#{delimiter}\"#{repl}\"")
+      else
+        content
+      end
+    end
+
+    # Resave the "fixed" version of an F99
+    def resave_f99_contents
+      return true if @resaved
+      File.open(custom_file_path, 'w') { |f| f.write(fix_f99_contents) }
+      @resaved = true
+    end
+
+    def file_name
+      "#{filing_id}.fec"
+    end
+
+    def filing_url
+      "http://query.nictusa.com/dcdev/posted/#{filing_id}.fec"
+    end
+
+    # Iterates over and yields the Filing's lines
+    # @option opts [Boolean] :with_index yield both the item and its index
+    # @yield [Array] a row of the filing, split by the delimiter from #delimiter
+    def each_row(opts={}, &block)
+      unless File.exists?(file_path)
+        raise "File #{file_path} does not exist. Try invoking the .download method on this Filing object."
+      end
+
+      # If this is an F99, we need to parse it differently.
+      resave_f99_contents if form_type == 'F99'
+
+      c = 0
+      @csv_parser.parse_row(@customized ? custom_file_path : file_path, :col_sep => delimiter, :quote_char => @quote_char, :skip_blanks => true) do |row|
+        if opts[:with_index]
+          yield [row, c]
+          c += 1
+        else
+          yield row
+        end
+      end
+    end
+
+    # Wrapper around .each_row to include indexes
+    def each_row_with_index(&block)
+      each_row(:with_index => true, &block)
+    end
+    
+    # @return [String] the delimiter used in the filing's version
+    def delimiter
+      filing_version.to_f < 6 ? "," : "\034"
+    end
+    
+  end
+end

data/lib/fech/map_generator.rb

@@ -0,0 +1,233 @@
+module Fech
+  
+  # Helper class to generate mapping hashes from source csv data.
+  # Needed to rebuild rendered_maps.rb with new source data, not used
+  # in main gem.
+  #   rake fech:maps
+  class MapGenerator
+    
+    attr_accessor :map
+    FILING_VERSIONS   = ["8.0", "7.0", "6.4", "6.3", "6.2", "6.1",
+                         "5.3", "5.2", "5.1", "5.0", "3"]
+    BASE_ROW_TYPES    = ["HDR", "F1", "F1M", "F2", "F24", "F3", "F3L", "F3P", "F3P31", "F3PS", "F3S", "F3X", 
+                         "F4", "F5", "F56", "F57", "F6", "F65", "F7", "F76", "F9", "F91", "F92", "F93", "F94", "F99",
+                         "H1", "H2", "H3", "H4", "H5", "H6",
+                         "SchA", "SchB", "SchC", "SchC1", "SchC2", "SchD", "SchE", "SchF", "SchL", "TEXT"]
+    ROW_TYPE_MATCHERS = {
+      "HDR"    => FechUtils::ROW_TYPES[:hdr],
+      "F1"     => FechUtils::ROW_TYPES[:f1],
+      "F1M"    => FechUtils::ROW_TYPES[:f1m],
+      "F2"     => FechUtils::ROW_TYPES[:f2],
+      "F24"    => FechUtils::ROW_TYPES[:f24],
+      "F3"     => FechUtils::ROW_TYPES[:f3],
+      "F3L"    => FechUtils::ROW_TYPES[:f3l],
+      "F3P"    => FechUtils::ROW_TYPES[:f3p],
+      "F3S"    => FechUtils::ROW_TYPES[:f3s],
+      "F3P31"  => FechUtils::ROW_TYPES[:f3p31],
+      "F3PS"   => FechUtils::ROW_TYPES[:f3ps],
+      "F3X"    => FechUtils::ROW_TYPES[:f3x],
+      "F4"     => FechUtils::ROW_TYPES[:f4],
+      "F5"     => FechUtils::ROW_TYPES[:f5],
+      "F56"    => FechUtils::ROW_TYPES[:f56],
+      "F57"    => FechUtils::ROW_TYPES[:f57],
+      "F6"     => FechUtils::ROW_TYPES[:f6],
+      "F65"    => FechUtils::ROW_TYPES[:f65],
+      "F7"     => FechUtils::ROW_TYPES[:f7],
+      "F76"    => FechUtils::ROW_TYPES[:f76],
+      "F9"     => FechUtils::ROW_TYPES[:f9],
+      "F91"    => FechUtils::ROW_TYPES[:f91],
+      "F92"    => FechUtils::ROW_TYPES[:f92],
+      "F93"    => FechUtils::ROW_TYPES[:f93],
+      "F94"    => FechUtils::ROW_TYPES[:f94],
+      "F99"    => FechUtils::ROW_TYPES[:f99],
+      "H1"     => FechUtils::ROW_TYPES[:h1],
+      "H2"     => FechUtils::ROW_TYPES[:h2],
+      "H3"     => FechUtils::ROW_TYPES[:h3],
+      "H4"     => FechUtils::ROW_TYPES[:h4],
+      "H5"     => FechUtils::ROW_TYPES[:h5],
+      "H6"     => FechUtils::ROW_TYPES[:h6],
+      "SchA"   => FechUtils::ROW_TYPES[:sa],
+      "SchB"   => FechUtils::ROW_TYPES[:sb],
+      "SchC"   => FechUtils::ROW_TYPES[:sc],
+      "SchC1"  => FechUtils::ROW_TYPES[:sc1],
+      "SchC2"  => FechUtils::ROW_TYPES[:sc2],
+      "SchD"   => FechUtils::ROW_TYPES[:sd],
+      "SchE"   => FechUtils::ROW_TYPES[:se],
+      "SchF"   => FechUtils::ROW_TYPES[:sf],
+      "SchL"   => FechUtils::ROW_TYPES[:sl],
+      "TEXT"   => FechUtils::ROW_TYPES[:text],
+    }
+    
+    # Goes through all version header summary files and generates
+    # row map files for each type of row inside them.
+    def self.convert_header_file_to_row_files(source_dir)
+      data = {}
+      hybrid_data = {}
+      
+      ignored_fields = File.open(ignored_fields_file(source_dir)).readlines.map { |l| l.strip }
+      
+      # Create a hash of data with an entry for each row type found in the source
+      # version summary files. Each row has an entry for each version map that
+      # exists for it. If maps for two different versions are identical, they
+      # are combined.
+      FILING_VERSIONS.each do |version|
+        filepath = version_summary_file(source_dir, version)
+
+        # Clean the source files by removing unparseable characters
+        if RUBY_VERSION < "1.9.3"
+          require 'iconv'
+          ic = Iconv.new('UTF-8//IGNORE', 'UTF-8')
+          valid_string = ic.iconv(open(filepath).read << ' ')[0..-2]
+        else
+          valid_string = (open(filepath).read << ' ')[0..-2].encode!('UTF-16', 'UTF-8', :invalid => :replace, :replace => '')
+          valid_string = valid_string.encode!('UTF-8', 'UTF-16')
+        end
+        open(filepath, 'w').write(valid_string)
+
+        Fech::Csv.foreach(filepath) do |row|
+          # Each row of a version summary file contains the ordered list of
+          # column names.
+          data[row.first] ||= {}
+          hybrid_data[row.first] ||= {}
+          row_version_data = remove_ignored_fields(row, ignored_fields)
+
+          # Check the maps for this row type in already-processed versions.
+          # If this map is identical to a previous map, tack this version on to
+          # to it instead of creating a new one.
+          data[row.first][version] = row_version_data
+          data[row.first].each do |k, v|
+            # skip the row we just added
+            
+            next if k == version
+            if v == row_version_data
+              # Create the new hybrid entry
+              hybrid_data[row.first]["#{k}|#{version}"] = row_version_data
+              
+              # Delete the old entry, and the one for this version only
+              data[row.first].delete(k)
+              data[row.first].delete(version)
+            end
+          end
+          data[row.first].update(hybrid_data[row.first])
+        end
+      end
+      
+      # Go through each row type and create a base map management file that
+      # will serve as a template for organizing which fields are the same
+      # between versions. This file will need to then be arranged by hand to
+      # clean up the data. Each row will represent a column across versions,
+      # each column a unique map for that row for one or more versions.
+      data.each do |row_type, row_data|
+        file_path = write_row_map_file(source_dir, row_type)
+        next unless File.exists?(file_path)
+        File.open(file_path, 'w') do |f|
+          f.write('canonical')
+          
+          to_transpose = []
+          row_data.sort.reverse.each do |version, version_data|
+            to_transpose << ["^#{version}", version_data.each_with_index.collect {|x, idx| idx+1}].flatten
+            to_transpose << [nil, version_data].flatten
+          end
+          
+          # standardize row size
+          max_size = to_transpose.max { |r1, r2| r1.size <=> r2.size }.size
+          to_transpose.each { |r| r[max_size - 1] ||= nil }
+          transposed = to_transpose.transpose
+          
+          transposed.each do |transposed_data|
+            transposed_data.collect! {|x| x.to_s.gsub(/\r/, ' ')}
+            canonical = transposed_data[1] # first description
+            if canonical
+              canonical = canonical.gsub(/\{.*\}/, "").gsub(/[ -\.\/\(\)]/, "_").gsub(/_+/, "_").gsub(/(_$)|(^_)/, "").downcase
+              transposed_data = [canonical, transposed_data].flatten
+            end
+            f.write(transposed_data.join(','))
+            f.write("\n")
+          end
+        end
+      end
+
+    end
+    
+    # Generates the mapping for each row type in BASE_ROW_TYPES, writes them out
+    # to file for inclusion in the gem.
+    def self.dump_row_maps_to_ruby(source_dir, file_path)
+      File.open(file_path, 'w') do |f|
+        f.write("# Generated automatically by Fech::MapGenerator.\n\n")
+        f.write("# RENDERED_MAPS contains an entry for each supported row type, which in turn:\n")
+        f.write("#   contain an entry for each distinct map between a row's labels and the\n")
+        f.write("#   indexes where their values can be found.\n")
+        f.write("module Fech\n")
+        f.write("  RENDERED_MAPS = {\n")
+        BASE_ROW_TYPES.each do |row_type|
+          f.write("    \"#{ROW_TYPE_MATCHERS[row_type].source}\" => {\n")
+          generate_row_map_from_file(source_dir, row_type).sort_by(&:first).reverse.each do |k, v|
+            f.write("      \'#{k}' => [#{v.map {|x| x.to_s.gsub(/^\d+_?/, "") }.collect {|x| (x.nil? || x == "") ? "nil" : ":#{x}" }.join(', ') }],\n")
+          end
+          f.write("    },\n")
+        end
+        f.write("  }\n")
+        f.write("end")
+      end
+    end
+
+    # For a given row type, parses its source file and returns
+    # a mapping object for it.
+    def self.generate_row_map_from_file(source_dir, row_type)
+      versions = []
+      version_indexes = []
+      data = {}
+      text = open(row_map_file(source_dir, row_type)).read
+      split_char = text.index(/\r/) ? /\r/ : /\n/
+      rows = text.split(split_char).collect {|x| x.split(',')}
+      rows.each do |row|
+        row = row.collect {|x| x.gsub("\n", "")}
+        if row.first.nil?
+          require 'ruby-debug'; debugger
+        end
+        if row.first.downcase == "canonical"
+          versions = row[1..-1].uniq.collect {|x| x unless (x.nil? || x.empty?)}.compact
+          row.each_with_index {|x, ind| version_indexes << ind unless (x.nil? || x.empty?)}.slice!(1)
+          version_indexes.slice!(0, 1)
+          versions.each {|x| data[x] = [] }
+          
+        elsif row.first.size > 0
+          canonical = row.first
+          
+          versions.zip(version_indexes).each do |version, row_index|
+            index = row[row_index]
+            data[version][index.to_i - 1] = canonical.to_sym if index.to_i > 0
+          end
+        end
+      end
+    
+      row_map = {}
+      data.each {|key, value| row_map[key] = value}
+      row_map
+    end
+    
+    # Remove both the row type from the beginning of the row,
+    # and any fields marked as "ignore" in sources/headers/ignore.csv
+    def self.remove_ignored_fields(row, ignore)
+      data = row[1..-1].compact # strip off the row type
+      data.reject { |f| ignore.include?(f) }
+    end
+    
+    def self.row_map_file(source_dir, row_type)
+      File.join(source_dir, row_type + '.csv')
+    end
+    
+    def self.ignored_fields_file(source_dir)
+      File.join(source_dir, 'headers', 'ignore.csv')
+    end
+    
+    def self.version_summary_file(source_dir, version)
+      File.join(source_dir, 'headers', version + '.csv')
+    end
+    
+    def self.write_row_map_file(source_dir, row_type)
+      File.join(source_dir, 'rows', row_type + '.csv')
+    end
+  
+  end
+end

data/lib/fech/mapped.rb

@@ -0,0 +1,38 @@
+module Fech
+  
+  # Fech::Mapped is a thin wrapper around Hash which allows values to be
+  # referenced either by key or by an alias specified in the associated
+  # Filing's Translations.
+  class Mapped < Hash
+    
+    attr_accessor :filing, :row_type
+    alias :old_bracket :[]
+    
+    def initialize(filing, row_type)
+      @filing   = filing
+      @row_type = row_type
+    end
+    
+    # Just calls Hash's [] method, unless the specified key doesn't
+    # exist, in which case it checks for any aliases on the filing's
+    # translator.
+    def [](key, &block)
+      if has_key?(key)
+        old_bracket(key, &block)
+      else
+        # Look up aliases in reverse, to find the most recent one
+        # Does not allow (obvious) recursion
+        aliias = filing.translator.aliases.reverse.detect do |a|
+          a[:alias] == key && a[:row].match(row_type) && a[:alias] != a[:for]
+        end
+        # Pass the key this alias references back to this function
+        aliias ? old_bracket(aliias[:for], &block) : nil
+      end
+    end
+    
+    def method_missing(method, *args, &block)
+      self[method]
+    end
+    
+  end
+end

data/lib/fech/mappings.rb

@@ -0,0 +1,67 @@
+module Fech
+  class VersionError < RuntimeError; end
+  
+  # Fech::Mappings loads a set of master mappings between labels and where
+  # their values can be found in Electronic Filings for various row types
+  # and versions.
+  # To access a map, call Mappings.for_row with the row_type,
+  # and optionally the version:
+  #   Mappings.for_row("SA", :version => 6.1)
+  class Mappings
+    
+    attr_accessor :map, :version
+    
+    def initialize(ver = Fech::DEFAULT_VERSION)
+      @version  = ver
+      @map      = load_map
+      @cache    = {}
+    end
+    
+    # Returns a hash of mappings for row with given row_type
+    #
+    # @param [String,Symbol] row_type the row type whose map to find
+    def for_row(row_type)
+      @cache[row_type] ||= self.class.for_row(row_type, :version => @version)
+    end
+    
+    # Returns the basic, default mappings hash by reading in a mappings
+    # file and saving the variable to the class's context.
+    def load_map
+      self.class.load_map
+    end
+    
+    def self.load_map
+      Fech::RENDERED_MAPS
+    end
+    
+    # Given a row type, first find the entire block of maps for that row type.
+    # Then, use the filing's version to choose which specific map set to use,
+    # and return it.
+    #
+    # @param [Symbol,String,Regex] row_type the row whose map to find
+    def self.for_row(row_type, opts={})
+      opts[:version] ||= Fech::DEFAULT_VERSION
+      map = key_by_regex(load_map, row_type)
+      key_by_regex(map, opts[:version])
+    end
+    
+    # Given a Hash whose keys are string representations of regular expressions,
+    # return the value whose key best matches the given label.
+    #
+    # @param [Hash] hash a Hash with string regular expressions for keys
+    # @param [String,Symbol,Regexp] label return the key that best matches this
+    def self.key_by_regex(hash, label)
+      label = label.source if label.is_a?(Regexp)
+      
+      # Try matching longer keys first, to ensure more accurate keys are
+      # prioritized over less accurate ones.
+      hash.keys.sort { |x, y| x.length <=> y.length }.reverse.each do |key|
+        return hash[key] if Regexp.new(key, Regexp::IGNORECASE).match(label.to_s)
+      end
+      
+      raise VersionError, "Attempted to access mapping that has not been generated (#{label}). " +
+            "Supported keys match the format: #{hash.keys.join(', ')}"
+    end
+    
+  end
+end