ncs_mdes 0.2.0 → 0.3.0

data/CHANGELOG.md

@@ -1,3 +1,11 @@
+0.3.0
+=====
+
+- Add foreign key / table reference support, including explicit
+  mappings for all ambiguous or unguessable FKs.
+- Add Specification#[] for quicker access to a particular table or
+  tables.
+
 0.2.0
 =====
 

data/README.md

@@ -4,8 +4,8 @@ NCS Navigator MDES Module
 This gem provides a consistent computable interface to the National
 Children's Study Master Data Element Specification. All of the data it
 exposes is derived at runtime from the documents provided by the
-National Children's Study Program Office, which must be available on
-the system where it is running.
+National Children's Study Program Office, which are embedded in the
+distribution package.
 
 Use
 ---
@@ -16,7 +16,11 @@ Use
     mdes = NcsNavigator::Mdes('1.2')
     pp mdes.transmission_tables.collect(&:name)
 
-For more details see the API documentation, starting with {NcsNavigator::Mdes::Specification}.
+For more details see the API documentation, starting with
+{NcsNavigator::Mdes::Specification}. (If you're not looking at this
+document in the API documentation, try looking at [rubydoc.info][].)
+
+[rubydoc.info]: http://rubydoc.info/github/NUBIC/ncs_mdes/master/frames
 
 ### Examine
 

data/documents/1.2/heuristic_overrides.yml

@@ -0,0 +1,50 @@
+foreign_keys:
+  staff_exp_mngmnt_tasks:
+    staff_weekly_expense_id: staff_weekly_expense
+  staff_exp_data_cllctn_tasks:
+    staff_weekly_expense_id: staff_weekly_expense
+  participant_consent:
+    person_who_consented_id: person
+    person_wthdrw_consent_id: person
+  event:
+    participant_id: participant
+  participant_vis_consent:
+    vis_person_who_consented_id: person
+  link_contact:
+    specimen_id: false
+  birth_visit:
+    new_address_id: address
+    mail_address_id: address
+    new_address_b_id: address
+  household_enumeration_hidden_du:
+    hdu_address_id: address
+  pb_recruitment:
+    address_pb_id: address
+  pre_preg:
+    c_addr1_id: address
+    c_addr2_id: address
+  preg_screen_eh:
+    mail_address_id: address
+    new_address_id: address
+  preg_screen_hi:
+    mail_address_id: address
+    new_address_id: address
+  preg_screen_pb:
+    mail_address_id: address
+    new_address_id: address
+  preg_visit_1:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+  preg_visit_2:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+  preg_visit_li:
+    b_address_id: address
+  six_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address
+  twelve_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address

data/documents/2.0/heuristic_overrides.yml

@@ -0,0 +1,405 @@
+foreign_keys:
+  birth_visit:
+    new_address_id: address
+    mail_address_id: address
+    new_address_b_id: address
+
+  birth_visit_2:
+    new_address_id: address
+    mail_address_id: address
+    new_address_b_id: address
+
+  birth_visit_baby_name:
+    bv_id: birth_visit
+
+  birth_visit_baby_name_2:
+    bv_id: birth_visit_2
+
+  birth_visit_decorate_room:
+    bv_id: birth_visit
+
+  birth_visit_decorate_room_2:
+    bv_id: birth_visit_2
+
+  birth_visit_li:
+    new_address_id: address
+    mail_address_id: address
+    new_address_b_id: address
+
+  birth_visit_renovate_room:
+    bv_id: birth_visit
+
+  birth_visit_renovate_room_2:
+    bv_id: birth_visit_2
+
+  drf_therm_verification:
+    equip_id: env_equipment
+
+  eighteen_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address
+
+  eighteen_mth_mother_cond:
+    eighteen_mth_habits_id: eighteen_mth_mother_habits
+
+  eighteen_mth_mother_saq:
+    asq18_address_id: address
+
+  env_equipment_prob_log:
+    equip_id: env_equipment
+    staff_id_reviewer: staff
+
+  event:
+    participant_id: participant
+
+  household_enumeration_hidden_du:
+    hdu_address_id: address
+
+  incident:
+    inc_staff_reporter_id: staff
+    inc_staff_supervisor_id: staff
+    inc_recip_is_participant: participant
+    inc_recip_is_du: dwelling_unit
+    inc_recip_is_staff: staff
+    inc_recip_is_family: person
+    inc_recip_is_acquaintance: person
+    inc_contact_person: person
+
+  participant_consent:
+    person_who_consented_id: person
+    person_wthdrw_consent_id: person
+
+  participant_vis_consent:
+    vis_person_who_consented_id: person
+
+  participant_rvis:
+    rvis_person: person
+
+  pb_recruitment:
+    address_pb_id: address
+
+  pb_recruitment_2:
+    address_pb_id: address
+
+  pb_recruitment_info_source:
+    pb_recruitment_id: pb_recruitment
+
+  pb_recruitment_info_source_2:
+    pb_recruitment_id: pb_recruitment_2
+
+  pb_recruitment_prov_source:
+    pb_recruitment_id: pb_recruitment
+
+  pb_recruitment_prov_source_2:
+    pb_recruitment_id: pb_recruitment_2
+
+  pb_recruitment_prov_svc:
+    pb_recruitment_id: pb_recruitment
+
+  pb_recruitment_prov_svc_2:
+    pb_recruitment_id: pb_recruitment_2
+
+  person:
+    new_address_id: address
+
+  prec_therm_cert:
+    equip_id: env_equipment
+
+  pre_preg:
+    c_addr1_id: address
+    c_addr2_id: address
+
+  preg_screen_eh:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_eh_2:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_eh_know_ncs:
+    ps_eh_id: preg_screen_eh
+
+  preg_screen_eh_know_ncs_2:
+    ps_eh_id: preg_screen_eh_2
+
+  preg_screen_eh_race:
+    ps_eh_id: preg_screen_eh
+
+  preg_screen_eh_race_2:
+    ps_eh_id: preg_screen_eh_2
+
+  preg_screen_hi:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_hi_2:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_hi_know_ncs:
+    ps_hi_id: preg_screen_hi
+
+  preg_screen_hi_know_ncs_2:
+    ps_hi_id: preg_screen_hi_2
+
+  preg_screen_hi_race:
+    ps_hi_id: preg_screen_hi
+
+  preg_screen_hi_race_2:
+    ps_hi_id: preg_screen_hi_2
+
+  preg_screen_pb:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_pb_2:
+    mail_address_id: address
+    new_address_id: address
+
+  preg_screen_pb_know_ncs:
+    ps_pb_id: preg_screen_pb
+
+  preg_screen_pb_know_ncs_2:
+    ps_pb_id: preg_screen_pb_2
+
+  preg_screen_pb_race:
+    ps_pb_id: preg_screen_pb
+
+  preg_screen_pb_race_2:
+    ps_pb_id: preg_screen_pb_2
+
+  preg_visit_1:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+
+  preg_visit_1_2:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+
+  preg_visit_1_commute:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_commute_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_cool:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_cool_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_diagnose_2:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_diagnose_2_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_heat2:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_heat2_2:
+    pv1_id: preg_visit_2
+
+  preg_visit_1_local_trav:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_local_trav_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_nonenglish2_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_pdecorate_room:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_pdecorate_room_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_pet_type:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_pet_type_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_prenovate2_room:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_prenovate_room:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_prenovate_room_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_room_mold:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_room_mold_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_1_saq_2:
+    f_addr_id: address
+
+  preg_visit_1_sp_race:
+    pv1_id: preg_visit_1
+
+  preg_visit_1_sp_race_2:
+    pv1_id: preg_visit_1_2
+
+  preg_visit_2:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+
+  preg_visit_2_2:
+    b_address_id: address
+    c_addr1_id: address
+    c_addr2_id: address
+
+  preg_visit_2_cool:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_cool_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_2_diagnose_2:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_diagnose_2_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_2_heat2:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_heat2_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_2_pdecorate2_room:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_pdecorate2_room_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_2_prenovate_room:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_prenovate_room_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_2_room_mold:
+    pv2_id: preg_visit_2
+
+  preg_visit_2_room_mold_2:
+    pv2_id: preg_visit_2_2
+
+  preg_visit_li:
+    b_address_id: address
+
+  preg_visit_li_2:
+    b_address_id: address
+
+  preg_visit_li_cool:
+    pv_li_id: preg_visit_li
+
+  preg_visit_li_cool_2:
+    pv_li_id: preg_visit_li_2
+
+  ref_freezer_verification:
+    equip_id: env_equipment
+
+  sample_receipt_store:
+    equip_id: env_equipment
+
+  sample_shipping:
+    staff_id_track: staff
+
+  six_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address
+
+  six_mth_saq_formula_type:
+    six_mth_saq_id: six_mth_saq
+
+  six_mth_saq_formula_type_2:
+    six_mth_saq_id: six_mth_saq_2
+
+  six_mth_saq_supp:
+    six_mth_saq_id: six_mth_saq
+
+  six_mth_saq_supp_2:
+    six_mth_saq_id: six_mth_saq_2
+
+  six_mth_saq_water:
+    six_mth_saq_id: six_mth_saq
+
+  six_mth_saq_water_2:
+    six_mth_saq_id: six_mth_saq_2
+
+  spec_blood:
+    equip_id: spec_equipment
+
+  spec_receipt:
+    # Insufficient info to determine what this is supposed to link to
+    storage_container_id: false
+    equip_id: spec_equipment
+
+  spec_shipping:
+    shipper_id: false
+
+  spec_storage:
+    equip_id: spec_equipment
+
+  staff_exp_mngmnt_tasks:
+    staff_weekly_expense_id: staff_weekly_expense
+
+  staff_exp_data_cllctn_tasks:
+    staff_weekly_expense_id: staff_weekly_expense
+
+  trh_meter_calibration:
+    equip_id: spec_equipment
+
+  twelve_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address
+
+  twelve_mth_saq_formula_brand:
+    twelve_mth_saq_id: twelve_mth_saq
+
+  twelve_mth_saq_formula_brand_2:
+    twelve_mth_saq_id: twelve_mth_saq_2
+
+  twelve_mth_saq_formula_type:
+    twelve_mth_saq_id: twelve_mth_saq
+
+  twelve_mth_saq_formula_type_2:
+    twelve_mth_saq_id: twelve_mth_saq_2
+
+  twelve_mth_saq_supplement:
+    twelve_mth_saq_id: twelve_mth_saq
+
+  twelve_mth_saq_supplement_2:
+    twelve_mth_saq_id: twelve_mth_saq_2
+
+  twelve_mth_saq_water:
+    twelve_mth_saq_id: twelve_mth_saq
+
+  twelve_mth_saq_water_2:
+    twelve_mth_saq_id: twelve_mth_saq_2
+
+  twenty_four_mth_mother:
+    c_addr1_id: address
+    c_addr2_id: address
+
+  twenty_four_mth_mother_otc:
+    twenty_four_mth_mother_id: twenty_four_mth_mother
+
+  twenty_four_mth_mother_prescr:
+    twenty_four_mth_mother_id: twenty_four_mth_mother
+
+  twenty_four_mth_mother_suppl:
+    twenty_four_mth_mother_id: twenty_four_mth_mother
+
+  twenty_four_mth_saq:
+    asq24_address_id: address

data/lib/ncs_navigator/mdes/source_documents.rb

@@ -55,6 +55,7 @@ module NcsNavigator::Mdes
         self.new.tap do |sd|
           sd.version = version
           sd.schema = schema
+          sd.heuristic_overrides = "#{version}/heuristic_overrides.yml"
         end
       end
       private :create
@@ -86,7 +87,7 @@ module NcsNavigator::Mdes
     #
     # @return [String]
     def schema
-      @schema[0, 1] == '/' ? @schema : File.join(base, @schema)
+      absolutize(@schema)
     end
 
     ##
@@ -99,5 +100,37 @@ module NcsNavigator::Mdes
     def schema=(path)
       @schema = path
     end
+
+    ##
+    # The absolute path to a YAML-formatted document defining
+    # overrides of heuristics this library uses to do mapping when
+    # there is insufficient computable information in the other source
+    # documents.
+    #
+    # This is path is optional; if one is not provided no overrides
+    # will be attempted.
+    #
+    # @return [String]
+    def heuristic_overrides
+      absolutize(@heuristic_overrides)
+    end
+
+    ##
+    # Set the path to the heuristics override document.
+    # If the path is relative (i.e., it does not begin with `/`), it
+    # will be interpreted relative to {#base}.
+    #
+    # @param [String] path
+    # @return [String] the provided path
+    def heuristic_overrides=(path)
+      @heuristic_overrides = path
+    end
+
+    private
+
+    def absolutize(path)
+      return nil unless path
+      path[0, 1] == '/' ? path : File.join(base, path)
+    end
   end
 end

data/lib/ncs_navigator/mdes/specification.rb

@@ -3,6 +3,7 @@ require 'ncs_navigator/mdes'
 require 'forwardable'
 require 'logger'
 require 'nokogiri'
+require 'yaml'
 
 module NcsNavigator::Mdes
   class Specification
@@ -42,6 +43,27 @@ module NcsNavigator::Mdes
       @xsd ||= Nokogiri::XML(File.read source_documents.schema)
     end
 
+    ##
+    # @return [Hash] the loaded heuristic overrides, or a default
+    #   (empty) set
+    def heuristic_overrides
+      @heuristic_overrides ||=
+        begin
+          if File.exist?(source_documents.heuristic_overrides)
+            empty_overrides.merge(YAML.load(File.read source_documents.heuristic_overrides))
+          else
+            empty_overrides
+          end
+        end
+    end
+
+    def empty_overrides
+      {
+        'foreign_keys' => { }
+      }
+    end
+    private :empty_overrides
+
     ##
     # @return [Array<TransmissionTable>] all the transmission tables
     #   in this version of the MDES.
@@ -57,10 +79,42 @@ module NcsNavigator::Mdes
         TransmissionTable.from_element(table_elt, :log => @log)
       }.tap { |tables|
         tables.each { |t| t.variables.each { |v| v.resolve_type!(types, :log => @log) } }
+        # All types must be resolved before doing FK resolution or
+        # forward refs are missed.
+        tables.each { |t|
+          fk_overrides = heuristic_overrides['foreign_keys'][t.name] || { }
+          t.variables.each { |v|
+            v.resolve_foreign_key!(tables, fk_overrides[v.name], :log => @log)
+          }
+        }
       }
     end
     private :read_transmission_tables
 
+    ##
+    # A shortcut for accessing particular {#transmission_tables}.
+    #
+    # @overload [](table_name)
+    #   Retrieves a single table by name.
+    #   @param [String] table_name the transmission table to return.
+    #   @return [TransmissionTable,nil] the matching table or nothing.
+    #
+    # @overload [](pattern)
+    #   Searches the transmission tables by name.
+    #   @param [Regexp] pattern the pattern to match the name against.
+    #   @return [Array<TransmissionTable>] the matching tables (or an
+    #     empty array).
+    def [](criterion)
+      case criterion
+      when Regexp
+        transmission_tables.select { |t| t.name =~ criterion }
+      when String
+        transmission_tables.detect { |t| t.name == criterion }
+      else
+        fail "Unexpected criterion #{criterion.inspect}"
+      end
+    end
+
     ##
     # @return [Array<VariableType>] all the named types in the
     #   MDES. This includes all the code lists.

data/lib/ncs_navigator/mdes/variable.rb

@@ -37,6 +37,13 @@ module NcsNavigator::Mdes
     attr_accessor :required
     alias :required? :required
 
+    ##
+    # If this variable is a foreign key, this is the {table
+    # TransmissionTable} to which it refers.
+    #
+    # @return [TransmissionTable,nil] the parent table.
+    attr_accessor :table_reference
+
     class << self
       ##
       # Examines the given parsed element and creates a new
@@ -115,5 +122,57 @@ module NcsNavigator::Mdes
         log.warn("Undefined type #{type.name} for #{name}.") if log
       end
     end
+
+    ##
+    # Attempts to resolve this variable as a {reference to another
+    # table #table_reference}. There are two mechanisms for performing
+    # the resolution:
+    #
+    # 1. If an `override_name` is provided, that table will be looked
+    #    up in the provided table list. If it exists, it will be used,
+    #    otherwise nothing will be set.
+    # 2. If the type of this variable is one of the NCS FK types and
+    #    there exists exactly one table in `tables` whose primary key
+    #    has the same name as this variable, that table will be used.
+    #
+    # Alternatively, to suppress the heuristics without providing a
+    # replacement, pass `false` as the `override_name`
+    #
+    # @param [Array<TransmissionTable>] tables the tables to search
+    #   for a parent.
+    # @param [String,nil] override_name the name of a table to use as
+    #   the parent. Supplying a value in this parameter bypasses the
+    #   search heuristic.
+    # @return [void]
+    def resolve_foreign_key!(tables, override_name=nil, options={})
+      log = options[:log] || NcsNavigator::Mdes.default_logger
+
+      case override_name
+      when String
+        self.table_reference = tables.detect { |t| t.name == override_name }
+        unless table_reference
+          log.warn("Foreign key #{name.inspect} explicitly mapped " <<
+            "to unknown table #{override_name.inspect}.")
+        end
+      when nil
+        return unless (self.type && self.type.name =~ /^foreignKey/)
+
+        candidates = tables.select do |t|
+          t.variables.detect { |v| (v.name == name) && (v.type && (v.type.name =~ /^primaryKey/)) }
+        end
+
+        case candidates.size
+        when 0
+          log.warn("Foreign key not resolvable: " <<
+            "no tables have a primary key named #{name.inspect}.")
+        when 1
+          self.table_reference = candidates.first
+        else
+          log.warn(
+            "#{candidates.size} possible parent tables found for foreign key #{name.inspect}: " <<
+            "#{candidates.collect { |c| c.name.inspect }.join(', ')}. None used due to ambiguity.")
+        end
+      end
+    end
   end
 end

data/lib/ncs_navigator/mdes/version.rb

@@ -1,5 +1,5 @@
 module NcsNavigator
   module Mdes
-    VERSION = "0.2.0"
+    VERSION = "0.3.0"
   end
 end

data/spec/ncs_navigator/mdes/source_documents_spec.rb

@@ -23,21 +23,41 @@ module NcsNavigator::Mdes
       end
     end
 
-    describe '#schema' do
-      let(:docs) { SourceDocuments.new }
+    shared_examples 'an absolutizing path accessor' do
+      let(:docs) { SourceDocuments.new.tap { |d| d.base = '/baz' } }
+
+      def set(value)
+        docs.send("#{property}=", value)
+      end
 
-      before do
-        docs.base = '/baz'
+      def actual
+        docs.send(property)
       end
 
       it 'absolutizes a relative path against the base' do
-        docs.schema = '1.3/bar.xsd'
-        docs.schema.should == '/baz/1.3/bar.xsd'
+        set('1.3/bar.foo')
+        actual.should == '/baz/1.3/bar.foo'
       end
 
       it 'leaves an absolute path alone' do
-        docs.schema = '/somewhere/particular.xsd'
-        docs.schema.should == '/somewhere/particular.xsd'
+        set '/somewhere/particular.ext'
+        actual.should == '/somewhere/particular.ext'
+      end
+    end
+
+    describe '#schema' do
+      let(:property) { :schema }
+
+      it_behaves_like 'an absolutizing path accessor'
+    end
+
+    describe '#heuristic_overrides' do
+      let(:property) { :heuristic_overrides }
+
+      it_behaves_like 'an absolutizing path accessor'
+
+      it 'is optional' do
+        SourceDocuments.new.heuristic_overrides.should be_nil
       end
     end
 
@@ -49,6 +69,10 @@ module NcsNavigator::Mdes
           subject.schema.should =~ %r{1.2/Data_Transmission_Schema_V1.2.xsd$}
         end
 
+        it 'has the correct path for the overrides' do
+          subject.heuristic_overrides.should =~ %r{1.2/heuristic_overrides.yml$}
+        end
+
         it 'is of the specified version' do
           subject.version.should == '1.2'
         end
@@ -61,6 +85,10 @@ module NcsNavigator::Mdes
           subject.schema.should =~ %r{2.0/NCS_Transmission_Schema_2.0.01.02.xml$}
         end
 
+        it 'has the correct path for the overrides' do
+          subject.heuristic_overrides.should =~ %r{2.0/heuristic_overrides.yml$}
+        end
+
         it 'is of the specified version' do
           subject.version.should == '2.0'
         end

data/spec/ncs_navigator/mdes/specification_spec.rb

@@ -31,13 +31,7 @@ module NcsNavigator::Mdes
           should be_a TransmissionTable
       end
 
-      context 'in version 1.2' do
-        let!(:tables) { Specification.new('1.2', :log => logger).transmission_tables }
-
-        it 'has 124 tables' do
-          tables.size.should == 124
-        end
-
+      shared_examples 'tables fully resolved' do
         it 'emits no warnings' do
           logger[:warn].should == []
         end
@@ -49,6 +43,16 @@ module NcsNavigator::Mdes
         end
       end
 
+      context 'in version 1.2' do
+        let!(:tables) { Specification.new('1.2', :log => logger).transmission_tables }
+
+        it 'has 124 tables' do
+          tables.size.should == 124
+        end
+
+        include_examples 'tables fully resolved'
+      end
+
       context 'in version 2.0' do
         let!(:tables) { Specification.new('2.0', :log => logger).transmission_tables }
 
@@ -56,14 +60,26 @@ module NcsNavigator::Mdes
           tables.size.should == 264
         end
 
-        it 'emits no warnings' do
-          logger[:warn].should == []
+        include_examples 'tables fully resolved'
+      end
+    end
+
+    describe '#[]' do
+      let(:spec) { Specification.new('2.0') }
+
+      describe 'with a string' do
+        it 'returns a single table if there is a match by name' do
+          spec['listing_unit'].should be_a TransmissionTable
         end
 
-        it 'resolves all NCS type references' do
-          tables.collect { |table|
-            table.variables.collect { |v| v.type }.select { |t| t.reference? }
-          }.flatten.collect { |t| t.name }.select { |n| n =~ /^ncs:/ }.should == []
+        it 'returns nothing if there is no match' do
+          spec['fred'].should be_nil
+        end
+      end
+
+      describe 'with a regular expression' do
+        it 'returns a list of tables whose names match' do
+          spec[/^preg_visit_1.*2$/].should have(15).tables
         end
       end
     end

data/spec/ncs_navigator/mdes/variable_spec.rb

@@ -212,5 +212,191 @@ XSD
         end
       end
     end
+
+    describe '#resolve_foreign_key!' do
+      let(:variable) {
+        Variable.new('helicopter_id').tap { |v| v.type = variable_type }
+      }
+
+      let(:table) {
+        TransmissionTable.new('flights').tap do |t|
+          t.variables = [ variable ]
+        end
+      }
+
+      let(:table_with_matching_pk) {
+        TransmissionTable.new('helicopters').tap do |t|
+          t.variables = [
+            Variable.new('helicopter_id').tap do |v|
+              v.type = VariableType.new('primaryKeyType')
+            end
+          ]
+        end
+      }
+
+      let(:table_with_nonmatching_pk) {
+        TransmissionTable.new('frogs').tap do |t|
+          t.variables = [
+            Variable.new('frog_id').tap do |v|
+              v.type = VariableType.new('primaryKeyType')
+            end
+          ]
+        end
+      }
+
+      let(:table_with_same_fk) {
+        TransmissionTable.new('autorotation_events').tap do |t|
+          t.variables = [
+            Variable.new('helicopter_id').tap do |v|
+              v.type = VariableType.new('foreignKeyTypeRequired')
+            end
+          ]
+        end
+      }
+
+      let(:all_tables) {
+        [table, table_with_matching_pk, table_with_nonmatching_pk, table_with_same_fk]
+      }
+
+      # These are overridden in nested contexts as necessary
+      let(:override) { nil }
+      let(:tables) { all_tables }
+
+      before do
+        variable.resolve_foreign_key!(tables, override, :log => logger)
+      end
+
+      shared_examples 'a foreign key' do
+        context 'when there is no table matching' do
+          context 'and there is no override' do
+            let(:tables) {
+              [table, table_with_same_fk, table_with_nonmatching_pk]
+            }
+
+            it 'does not set a table reference' do
+              variable.table_reference.should be_nil
+            end
+
+            it 'warns' do
+              logger[:warn].first.
+                should == 'Foreign key not resolvable: no tables have a primary key named "helicopter_id".'
+            end
+          end
+
+          include_examples 'for overrides'
+        end
+
+        context 'when there is exactly one matching table' do
+          let(:tables) { all_tables }
+
+          context 'and there is no override' do
+            it 'sets the table_reference to that matching table' do
+              variable.table_reference.should be table_with_matching_pk
+            end
+
+            it 'does not warn' do
+              logger[:warn].should be_empty
+            end
+          end
+
+          include_examples 'for overrides'
+        end
+
+        context 'when there is more than one matching table' do
+          let(:other_matches) {
+            [
+              TransmissionTable.new('helicopters_2').tap { |t|
+                t.variables = table_with_matching_pk.variables.dup
+              },
+              TransmissionTable.new('choppers').tap { |t|
+                t.variables = table_with_matching_pk.variables.dup
+              }
+            ]
+          }
+
+          let(:tables) { all_tables + other_matches }
+
+          context 'and there is no override' do
+            it 'does not set a table reference' do
+              variable.table_reference.should be_nil
+            end
+
+            it 'warns' do
+              logger[:warn].first.
+                should == '3 possible parent tables found for foreign key "helicopter_id": "helicopters", "helicopters_2", "choppers". None used due to ambiguity.'
+            end
+          end
+
+          include_examples 'for overrides'
+        end
+      end
+
+      shared_examples 'for overrides' do
+        context 'and there is an override' do
+          context 'and the override is to a known table' do
+            let(:override) { table_with_same_fk.name }
+
+            it 'sets the table reference to the override' do
+              variable.table_reference.should be table_with_same_fk
+            end
+
+            it 'does not warn' do
+              logger[:warn].should == []
+            end
+          end
+
+          context 'and the override is to an unknown table' do
+            let(:override) { 'aircraft' }
+
+            it 'does not set a table reference' do
+              variable.table_reference.should be_nil
+            end
+
+            it 'warns' do
+              logger[:warn].first.
+                should == 'Foreign key "helicopter_id" explicitly mapped to unknown table "aircraft".'
+            end
+          end
+
+          context 'and the override is false' do
+            let(:override) { false }
+
+            it 'does not set a table reference' do
+              variable.table_reference.should be_nil
+            end
+
+            it 'does not warn' do
+              logger[:warn].should == []
+            end
+          end
+        end
+      end
+
+      context 'when a nullable FK' do
+        let(:variable_type) { VariableType.new('foreignKeyTypeNullable') }
+
+        it_behaves_like 'a foreign key'
+      end
+
+      context 'when a required FK' do
+        let(:variable_type) { VariableType.new('foreignKeyTypeRequired') }
+
+        it_behaves_like 'a foreign key'
+      end
+
+      context 'when not an FK' do
+        let(:variable_type) { VariableType.new('confirm_cl7') }
+
+        it 'does nothing' do
+          variable.table_reference.should be_nil
+        end
+
+        it 'does not warn' do
+          logger[:warn].should be_empty
+        end
+
+        include_examples 'for overrides'
+      end
+    end
   end
 end

metadata

@@ -1,13 +1,13 @@
 --- !ruby/object:Gem::Specification 
 name: ncs_mdes
 version: !ruby/object:Gem::Version 
-  hash: 23
+  hash: 19
   prerelease: false
   segments: 
   - 0
-  - 2
+  - 3
   - 0
-  version: 0.2.0
+  version: 0.3.0
 platform: ruby
 authors: 
 - Rhett Sutphin
@@ -15,13 +15,11 @@ autorequire:
 bindir: bin
 cert_chain: []
 
-date: 2011-07-08 00:00:00 -05:00
+date: 2011-07-25 00:00:00 -05:00
 default_executable: 
 dependencies: 
 - !ruby/object:Gem::Dependency 
-  name: nokogiri
-  prerelease: false
-  requirement: &id001 !ruby/object:Gem::Requirement 
+  version_requirements: &id001 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -31,12 +29,12 @@ dependencies:
         - 1
         - 4
         version: "1.4"
+  requirement: *id001
   type: :runtime
-  version_requirements: *id001
-- !ruby/object:Gem::Dependency 
-  name: rspec
+  name: nokogiri
   prerelease: false
-  requirement: &id002 !ruby/object:Gem::Requirement 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id002 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -46,12 +44,12 @@ dependencies:
         - 2
         - 6
         version: "2.6"
+  requirement: *id002
   type: :development
-  version_requirements: *id002
-- !ruby/object:Gem::Dependency 
-  name: rake
+  name: rspec
   prerelease: false
-  requirement: &id003 !ruby/object:Gem::Requirement 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id003 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -62,12 +60,12 @@ dependencies:
         - 9
         - 2
         version: 0.9.2
+  requirement: *id003
   type: :development
-  version_requirements: *id003
-- !ruby/object:Gem::Dependency 
-  name: yard
+  name: rake
   prerelease: false
-  requirement: &id004 !ruby/object:Gem::Requirement 
+- !ruby/object:Gem::Dependency 
+  version_requirements: &id004 !ruby/object:Gem::Requirement 
     none: false
     requirements: 
     - - ~>
@@ -78,8 +76,10 @@ dependencies:
         - 7
         - 2
         version: 0.7.2
+  requirement: *id004
   type: :development
-  version_requirements: *id004
+  name: yard
+  prerelease: false
 description: |
   
   Provides a consistent ruby interface to the project metainformation in the
@@ -103,7 +103,9 @@ files:
 - Rakefile
 - bin/mdes-console
 - documents/1.2/Data_Transmission_Schema_V1.2.xsd
+- documents/1.2/heuristic_overrides.yml
 - documents/2.0/NCS_Transmission_Schema_2.0.01.02.xml
+- documents/2.0/heuristic_overrides.yml
 - lib/ncs_navigator/mdes.rb
 - lib/ncs_navigator/mdes/source_documents.rb
 - lib/ncs_navigator/mdes/specification.rb