clli 0.0.1

data/lib/clli/data/entity_types.yml

@@ -0,0 +1,71 @@
+---
+switching_types:
+  MGx: 'End Office Complete Switching System: Crossbar'
+  SGx: 'End Office Complete Switching System: Step-By-Step'
+  CGx: 'End Office Complete Switching System: Electonic-Analog'
+  DSx: 'End Office Complete Switching System: Electonic-Digital'
+  nnx: 'End Office: Single or Multiple Entity'
+  nnT: 'Tandem Office: Individual Tandem'
+  CnT: 'Tandem Office Combination: Tandem/Tandem'
+  BnT: 'Tandem Office Combination: Tandem/Switchboard'
+  nGT: 'Tandem Office Combination: Tandem/Marker or Control Group'
+  ZaZ: 'Common Control Switching Arrangement'
+  RSn: 'Remote Switching System'
+  XaX: 'Teletypewriter Switching System'
+  CTx: 'Concentrator'
+
+switchboard_and_desk:
+  C: 'Centralized Automatic Message Accounting (CAMA) Board'
+  D: 'Dial Service Assistance (DSA) Board'
+  B: 'Combined Toll, Dial Service Assistance (DSA), and Centralized Automatic Message Accounting (CAMA)'
+  I: 'Directory Assistance (Information)'
+  N: 'Intercept Board'
+  Q: 'Combined Directory Assistance and Intercept'
+  W: 'Inward Toll Board'
+  M: 'Manual Switchboard'
+  V: 'Overseas Toll Board'
+  R: 'Rate and Route Desk'
+  O: 'Service Observing Switchboard (Service Evaluation Center and Signal Converter Allotter Used for the Service Evaluation System)'
+  L: 'Special Boards (Conference, Mobile, Marine, Switchboard Converted to Special Operation Service Traffic (SOST))'
+  '0': 'Teleconference Board'
+  '1': 'Teleconference Board'
+  '2': 'Teleconference Board'
+  '3': 'Teleconference Board'
+  '4': 'Teleconference Board'
+  '5': 'Teleconference Board'
+  '6': 'Teleconference Board'
+  '7': 'Teleconference Board'
+  '8': 'Teleconference Board'
+  '9': 'Teleconference Board'
+  P: 'Telephone Company PBX (Offical)'
+  E: 'Traffic Service Position System (TSPS) Board'
+  U: 'Traffic Service Position (Universal TSP)'
+  T: 'Toll Board (Through, Outward)'
+  Z: 'Other Switchboard and Desk Entity'
+
+miscellaneous_switching_termination:
+  A: 'Announcement Machine (including Voice Storage System (VSS), Public Announcement System (PA), Mass Announcement Systems (MAS), Audio Response Units)'
+  X: 'Centrex (Central Office)'
+  C: 'Automatic Distributor'
+  T: 'Time Distributor'
+  W: 'Weather Distributor'
+  D: 'Other Distributor'
+  E: 'Emergency (911 Service)'
+  I: 'Automatic Intercept System: File Access System (FAS)'
+  N: 'Combined Operator, Trouble, and Machine Intercept'
+  P: 'Position Link Frame'
+  Q: 'Rate and Quote System'
+  U: 'TSPS Common Control Unit (Remote Trunking Arrangement)'
+  M: 'Other Switching Termination Entities (including Improved Mobile Telephone System (IMTS) and all other mobile control terminals Bellboy Control terminal Coin to Collect Verification Circuit Switchers at Other Common Carrier Locations)'
+
+nonswitching_types:
+  F: 'Frame (all types)'
+  A: 'Administrative Entity'
+  E: 'Exchange Switchroom'
+  K: 'Software Cross-connectable Entity'
+  M: 'Maintenance Group (including work centers, such as Switching Control Centers, and Operations Systems such as CAROT, CMS, CTMS)'
+  P: 'Test or Service Position'
+  Q: 'Radio Tower (collocated on building)'
+  S: 'Service Center'
+  T: 'Toll Test Room (or Board)'
+  W: 'Other Nonswitching Entity'

data/lib/clli/data/location_types.yml

@@ -0,0 +1,37 @@
+---
+A: 'Bell Operating Company Nonbuilding Location'
+B: 'International Boundary Crossing Point'
+C: 'Bell Operating Company Nonbuilding Location'
+D: 'Bell Operating Company Nonbuilding Location'
+E: 'End Point'
+F: 'Bell Operating Company Nonbuilding Location'
+G: 'Bell Operating Company Nonbuilding Location'
+H: 'Bell Operating Company Nonbuilding Location'
+I: 'Bell Operating Company Nonbuilding Location'
+J: 'Junction'
+K: 'Bell Operating Company Nonbuilding Location'
+L: 'Bell Operating Company Nonbuilding Location'
+M: 'Manhole'
+N: 'Bell Operating Company Nonbuilding Location'
+O: 'Bell Operating Company Nonbuilding Location'
+P: 'Pole'
+Q: 'Radio'
+R: 'Repeater'
+S: 'Toll Station'
+T: 'Bell Operating Company Nonbuilding Location'
+U: 'Other'
+V: 'Bell Operating Company Nonbuilding Location'
+W: 'Bell Operating Company Nonbuilding Location'
+X: 'Independent Telephone Company Nonbuilding Location'
+Y: 'Bell Operating Company Nonbuilding Location'
+Z: 'Bell Operating Company Nonbuilding Location'
+'0': 'Customer Location'
+'1': 'Customer Location'
+'2': 'Customer Location'
+'3': 'Customer Location'
+'4': 'Customer Location'
+'5': 'Customer Location'
+'6': 'Customer Location'
+'7': 'Customer Location'
+'8': 'Customer Location'
+'9': 'Customer Location'

data/lib/clli/data/region_conversions.yml

@@ -0,0 +1,25 @@
+---
+# Quebec, Canada
+PQ:
+  state: QC
+  country: CA
+
+# Nunavut, Canada
+VU:
+  state: NU
+  country: CA
+
+# Newfoundland and Labrador, Canada
+NF:
+  state: NL
+  country: CA
+
+# High Seas / International Waters
+HS:
+  state:
+  country: XZ
+
+# Earth Orbit / Satellite
+EO:
+  state:
+  country: XS

data/lib/clli/entity_type.rb

@@ -0,0 +1,59 @@
+class CLLI
+  ##
+  # This module provides methods to lookup the entity code description for a
+  # parsed +CLLI+ string.
+  module EntityType
+    ##
+    # When this modeule is included then extend the including class with the
+    # methods defined in +ClassMethods+.
+    def self.included(o)
+      o.extend(ClassMethods)
+    end
+
+    ##
+    # These methods will be available in the +CLLI+ class.
+    module ClassMethods
+      include Pattern
+
+      @entity_type_data = nil
+
+      ##
+      # Lookup the entity code description for a parsed +CLLI+ string.
+      #
+      # Params:
+      # +code+:: the +CLLI+ +:entity_code+ attribute value.
+      def entity_type(code)
+        @entity_type_data ||= YAMLData.new(%w(clli data entity_types.yml))
+        @entity_type_data.get(*code_keys(code))
+      end
+
+      private
+
+      ##
+      # Determine which key to use for the parsed entity code.
+      #
+      # Params:
+      # +code+:: the +CLLI+ +:entity_code+ attribute value.
+      def code_keys(code)
+        case code
+        when Regexp.new("MG[#{x1}]") then %w(switching_types MGx)
+        when Regexp.new("SG[#{x1}]") then %w(switching_types SGx)
+        when Regexp.new("CG[#{x1}]") then %w(switching_types CGx)
+        when Regexp.new("DS[#{x1}]") then %w(switching_types DSx)
+        when Regexp.new("[#{n}]{2}[#{x1}]") then %w(switching_types nnx)
+        when Regexp.new("[#{n}]{2}T") then %w(switching_types nnT)
+        when Regexp.new("C[#{n}]T") then %w(switching_types CnT)
+        when Regexp.new("B[#{n}]T") then %w(switching_types BnT)
+        when Regexp.new("[#{n}]GT") then %w(switching_types nGT)
+        when Regexp.new("Z[#{a}]Z") then %w(switching_types ZaZ)
+        when Regexp.new("RS[#{n}]") then %w(switching_types RSn)
+        when Regexp.new("X[#{a}]X") then %w(switching_types XaX)
+        when Regexp.new("CT[#{x1}]") then %w(switching_types CTx)
+        when Regexp.new(switchboard_and_desk_entity_code_pattern) then ['switchboard_and_desk', code[1]]
+        when Regexp.new(miscellaneous_switching_termination_entity_code_pattern) then ['miscellaneous_switching_termination', code[1]]
+        when Regexp.new(nonswitching_entity_code_pattern) then ['nonswitching_types', code[0]]
+        end
+      end
+    end
+  end
+end

data/lib/clli/iso3166.rb

@@ -0,0 +1,104 @@
+class CLLI
+  # This module is used to convert CLLI region codes into ISO 3166 codes.
+  module ISO3166
+    ##
+    # When this modeule is included then extend the including class with the
+    # methods defined in +ClassMethods+.
+    def self.included(o)
+      o.extend(ClassMethods)
+    end
+
+    ##
+    # These methods will be available in the CLLI class.
+    module ClassMethods
+      @region_conversion_data = nil
+
+      ##
+      # Convert the +CLLI+ region code into an ISO 3166 country code.
+      #
+      # Params:
+      # +region-code+:: the +CLLI+ +:region+ attribute value.
+      def iso_country(region_code)
+        load_data
+        return @region_conversion_data[region_code]['country'] if @region_conversion_data.key?(region_code)
+        country = ::ISO3166::Country.new(region_code)
+        country.nil? ? 'ZZ' : country.alpha2
+      end
+
+      ##
+      # Lookup the name of the country for the specified +region_code+.
+      #
+      # Params:
+      # +region-code+:: the +CLLI+ +:region+ attribute value.
+      def country_name(region_code)
+        country_code = iso_country(region_code)
+        country = ::ISO3166::Country.new(country_code)
+        return if country.nil?
+        country.name
+      end
+
+      ##
+      # Convert the +CLLI+ region code into an ISO 3166 state code.
+      #
+      # Params:
+      # +region-code+:: the +CLLI+ +:region+ attribute value.
+      def iso_state(region_code)
+        load_data
+        return @region_conversion_data[region_code]['state'] if @region_conversion_data.key?(region_code)
+      end
+
+      ##
+      # Lookup the name of the state for the specified +region_code+.
+      #
+      # Params:
+      # +region-code+:: the +CLLI+ +:region+ attribute value.
+      def state_name(region_code)
+        state_code = iso_state(region_code)
+        return unless state_code
+        country_code = iso_country(region_code)
+        return unless country_code
+        country = ::ISO3166::Country.new(country_code)
+        return unless country
+        state_data = country.states[state_code]
+        return unless state_data
+        state_data['name']
+      end
+
+      private
+
+      ##
+      # Get an array of all the state codes in the specified country.
+      #
+      # Params:
+      # +iso_country+:: the ISO 3166 country code.
+      def state_codes(iso_country)
+        country = ::ISO3166::Country.new(iso_country)
+        return [] unless country
+        country.states.keys
+      end
+
+      ##
+      # Load the region code conversion data.
+      def load_data
+        return unless @region_conversion_data.nil?
+        data = {}
+        # Load the YAML region code conversion data.
+        data.merge!(YAMLData.new(%w(clli data region_conversions.yml)).data)
+
+        # load the US & Canadian state conversions.
+        data.merge!(us_ca_state_conversions)
+        @region_conversion_data = data
+      end
+
+      ##
+      # load the US & Canadian state conversions.
+      def us_ca_state_conversions
+        %w(US CA).each_with_object({}) do |country, data|
+          state_codes(country).each do |state|
+            data[state] = { 'state' => state, 'country' => country }
+          end
+        end
+      end
+    end
+  end
+end

data/lib/clli/location_type.rb

@@ -0,0 +1,31 @@
+class CLLI
+  ##
+  # This module provides methods to lookup the location code description for a
+  # parsed +CLLI+ string.
+  module LocationType
+    ##
+    # When this modeule is included then extend the including class with the
+    # methods defined in +ClassMethods+.
+    def self.included(o)
+      o.extend(ClassMethods)
+    end
+
+    ##
+    # These methods will be available in the CLLI class.
+    module ClassMethods
+      include Pattern
+
+      @location_type_data = nil
+
+      ##
+      # Lookup the entity code description for a parsed +CLLI+ string.
+      #
+      # Params:
+      # +code+:: the +CLLI+ +:location_code+ or +:customer_code+ attribute value.
+      def location_type(code)
+        @location_type_data ||= YAMLData.new(%w(clli data location_types.yml))
+        @location_type_data.get(code)
+      end
+    end
+  end
+end

data/lib/clli/pattern.rb

@@ -0,0 +1,203 @@
+class CLLI
+  ##
+  # This module provides the various patterns used for parsing +CLLI+ strings.
+  module Pattern
+    ##
+    # When this modeule is included then extend the including class with the
+    # methods defined in +ClassMethods+.
+    def self.included(o)
+      o.extend(ClassMethods)
+    end
+
+    ##
+    # These methods will be available in the CLLI class.
+    module ClassMethods
+      DEFAULT_PATTERN_OPTIONS = {
+        strict: true,
+        place_group: 'place',
+        region_group: 'region',
+        network_site_group: 'network_site',
+        entity_code_group: 'entity_code',
+        nonbuilding_code_group: 'location_code',
+        nonbuilding_id_group: 'location_id',
+        customer_code_group: 'customer_code',
+        customer_id_group: 'customer_id'
+      }
+
+      ##
+      # Get the complete +CLLI+ pattern.
+      #
+      # Params:
+      # +options+:: the following options are supported.
+      # [:strict]                 whether or not the rules in section
+      #                           +795-100-100+ are enforced for all fields.
+      # [:place_group]            the name to use for the place abbreviation.
+      # [:region_group]           the name to use for the region code.
+      # [:network_site_group]     the name to use for the network site code.
+      # [:entity_code_group]      the name to use for the entity code.
+      # [:nonbuilding_code_group] the name to use for the nonbuilding code.
+      # [:nonbuilding_id_group]   the name to use for the nonbuilding ID.
+      # [:customer_code_group]    the name to use for the customer code.
+      # [:customer_id_group]      the name to use for the customer ID.
+      def pattern(**options)
+        place = place_pattern(options)
+        network_site = network_site_pattern(options)
+        entity_code = entity_code_pattern(options)
+        nonbuilding_location = nonbuilding_location_pattern(options)
+        customer_location = customer_location_pattern(options)
+        "#{place}(?:#{network_site}(?:#{entity_code})?|#{nonbuilding_location}|#{customer_location})"
+      end
+
+      ##
+      # Get the complete +CLLI+ pattern as a compiled +Regexp+.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def regexp(**options)
+        Regexp.new(pattern(options))
+      end
+
+      ##
+      # Get the place abbreviation and region code pattern.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def place_pattern(**options)
+        options = DEFAULT_PATTERN_OPTIONS.merge(options)
+        pattern = named_group(options[:place_group], options[:strict] ? "[#{a}]{4}|[#{a}]{3}[ ]|[#{a}]{2}[ ]{2}" : "[#{x}\s]{4}")
+        pattern << named_group(options[:region_group], '[A-Z]{2}')
+      end
+
+      ##
+      # Get the network site code pattern.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def network_site_pattern(**options)
+        options = DEFAULT_PATTERN_OPTIONS.merge(options)
+        named_group(options[:network_site_group], options[:strict] ? "(?:[#{a}]{2}|[#{n}]{2})" : "(?:[#{a}#{n}]{2})")
+      end
+
+      ##
+      # Get the entity code pattern.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def entity_code_pattern(**options)
+        options = DEFAULT_PATTERN_OPTIONS.merge(options)
+        named_group(options[:entity_code_group], [
+          switching_entity_code_pattern, # (Table B)
+          switchboard_and_desk_entity_code_pattern, # (Table C)
+          miscellaneous_switching_termination_entity_code_pattern, # (Table D)
+          nonswitching_entity_code_pattern # (Table E)
+        ].join('|'))
+      end
+
+      # Switching Entities (Table B)
+      def switching_entity_code_pattern
+        [
+          "(?:MG|SG|CG|DS|[#{n}][#{n}])[#{x1}]",
+          "[CB#{n}][#{n}]T",
+          "[#{n}]GT",
+          "Z[#{a}]Z",
+          "RS[#{n}]",
+          "X[#{a}]X",
+          "CT[#{x1}]"
+        ].join('|')
+      end
+
+      # Switchboard and Desk Termination Entities (Table C)
+      def switchboard_and_desk_entity_code_pattern
+        "[#{n}][CDBINQWMVROLPEUTZ#{n}]B"
+      end
+
+      # Miscellaneous switching termination entities (Table D)
+      def miscellaneous_switching_termination_entity_code_pattern
+        ["[#{n}][AXCTWDEINPQ]D", "[#{x}][UM]D"].join('|')
+      end
+
+      # Non-Switching Entities (Table E)
+      def nonswitching_entity_code_pattern
+        ["[FAEKMPSTW][#{x2}][#{x1}]", "Q[#{n}][#{n}]"].join('|')
+      end
+
+      ##
+      # Get the non-building location code pattern.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def nonbuilding_location_pattern(**options)
+        options = DEFAULT_PATTERN_OPTIONS.merge(options)
+        pattern = named_group(options[:nonbuilding_code_group], "[#{a}]")
+        pattern << named_group(options[:nonbuilding_id_group], "[#{n}]{4}")
+      end
+
+      ##
+      # Get the customer non-building location pattern.
+      #
+      # Params:
+      # +options+:: see #pattern for more details.
+      def customer_location_pattern(**options)
+        options = DEFAULT_PATTERN_OPTIONS.merge(options)
+        pattern = named_group(options[:customer_code_group], "[#{n}]")
+        pattern << named_group(options[:customer_id_group], "[#{a}][#{n}]{3}")
+      end
+
+      ##
+      # A character group excluding B, D, I, O, T, U, W, and Y.
+      def a1
+        'ACE-HJ-NP-SVXZ'
+      end
+
+      ##
+      # A character group excluding G.
+      def a2
+        'A-FH-Z'
+      end
+
+      ##
+      # A character group containing all alpha characters.
+      def a
+        'A-Z'
+      end
+
+      ##
+      # A character group containing all digit characters.
+      def n
+        '0-9'
+      end
+
+      ##
+      # A character group containing all alpha and digit characters.
+      def x
+        a + n
+      end
+
+      ##
+      # A character group containing both +a1+ and all digit characters.
+      def x1
+        a1 + n
+      end
+
+      ##
+      # A character group containing both +a2+ and all digit characters.
+      def x2
+        a2 + n
+      end
+
+      private
+
+      ##
+      # Generate a named group using the specified +name+ and +pattern+. If the
+      # +name+ is +nil+ then just the +pattern+ will be returned.
+      #
+      # Params:
+      # +name+::    the name of the group.
+      # +pattern+:: the pattern inside the group.
+      def named_group(name, pattern)
+        return pattern if name.nil? || name.respond_to?(:empty?) && name.empty?
+        "(?<#{name}>#{pattern})"
+      end
+    end
+  end
+end