worlddb-models 2.2.2 → 2.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA1:
-  metadata.gz: e9b1bdb5484b5c74ef690b349dfd92dbb7fbd5d2
-  data.tar.gz: ed1e496ec5d29624d915dd9e93559eda99ead12e
+  metadata.gz: fe2b1dd265c24760835eeefbd445c3a8302eb554
+  data.tar.gz: 35aeaaac8672937b8388825aa4c36cc11ce4651b
 SHA512:
-  metadata.gz: 9ddd1c5c80416d77525a33cf1a54a79d953c2bc4303f7d305e0790b9d578990be7cfaf76576b5e2d9fc17ebc46f2bf3d353aa25d68771a8fb13a68f074a944e4
-  data.tar.gz: 8098bfbbbdaf6e23f47fe26a02315747581130c97455b2521cf4264d352c0d95f435dab6d8fe128b410ec1d839e6d423e1f937effef8a42771f51d7a72cadf68
+  metadata.gz: 60c27ed1d0fceebca6edef19c0a50a542dafdbd66b71bdf9ee0e84aa641de7569d856b9fae697ffb844428ee24b72c505e663dae1bd9b4bc8d8b54f66e9bef9c
+  data.tar.gz: 6acf8fcfe52845533582c7dbd010f17feb834beb0110c278e2cc72607d7240be894bff150facf73749f9f5419685e8216d05db6732c351fb44df209af52aec8f

data/Manifest.txt

@@ -3,22 +3,21 @@ Manifest.txt
 README.md
 Rakefile
 lib/worlddb/deleter.rb
+lib/worlddb/helpers/value_helper.rb
 lib/worlddb/matcher.rb
+lib/worlddb/matcher_adm.rb
 lib/worlddb/models.rb
 lib/worlddb/models/city.rb
-lib/worlddb/models/city_compat.rb
+lib/worlddb/models/city_base.rb
 lib/worlddb/models/continent.rb
-lib/worlddb/models/continent_compat.rb
 lib/worlddb/models/country.rb
 lib/worlddb/models/country_code.rb
-lib/worlddb/models/country_compat.rb
 lib/worlddb/models/forward.rb
 lib/worlddb/models/lang.rb
-lib/worlddb/models/lang_compat.rb
 lib/worlddb/models/name.rb
 lib/worlddb/models/place.rb
-lib/worlddb/models/region.rb
-lib/worlddb/models/region_compat.rb
+lib/worlddb/models/state.rb
+lib/worlddb/models/state_base.rb
 lib/worlddb/models/tagdb/tag.rb
 lib/worlddb/models/tagdb/tagging.rb
 lib/worlddb/models/usage.rb
@@ -26,32 +25,51 @@ lib/worlddb/patterns.rb
 lib/worlddb/reader.rb
 lib/worlddb/reader_file.rb
 lib/worlddb/reader_zip.rb
+lib/worlddb/readers/base.rb
 lib/worlddb/readers/city.rb
 lib/worlddb/readers/country.rb
 lib/worlddb/readers/lang.rb
-lib/worlddb/readers/region.rb
+lib/worlddb/readers/state.rb
+lib/worlddb/readers/state_tree.rb
 lib/worlddb/readers/usage.rb
 lib/worlddb/schema.rb
 lib/worlddb/stats.rb
+lib/worlddb/tree_reader.rb
 lib/worlddb/version.rb
+test/adm/test_fixture_matcher_adm2.rb
+test/adm/test_fixture_matcher_adm3.rb
+test/adm/test_fixture_matcher_tree.rb
+test/adm/test_read_adm.rb
+test/adm/test_read_tree.rb
 test/data/at-austria/1--b-burgenland/counties.txt
 test/data/at-austria/2--n-niederoesterreich/counties.txt
 test/data/at-austria/3--w-wien/counties.txt
+test/data/at-austria/orte.txt
 test/data/at-austria/setups/adm.txt
+test/data/at-austria/setups/tree.txt
 test/data/at-austria/states.txt
 test/data/de-deutschland/3--by-bayern/1--oberbayern/counties.txt
 test/data/de-deutschland/3--by-bayern/4--oberfranken/counties.txt
-test/data/de-deutschland/3--by-bayern/districts.txt
+test/data/de-deutschland/3--by-bayern/4--oberfranken/orte.txt
+test/data/de-deutschland/3--by-bayern/4--oberfranken/orte_ii.txt
+test/data/de-deutschland/3--by-bayern/parts.txt
+test/data/de-deutschland/orte.txt
 test/data/de-deutschland/setups/adm.txt
+test/data/de-deutschland/setups/tree.txt
 test/data/de-deutschland/states.txt
 test/helper.rb
-test/test_fixture_matcher_adm2.rb
-test/test_fixture_matcher_adm3.rb
 test/test_fixture_matchers.rb
 test/test_fixture_matchers_ii.rb
 test/test_model_city.rb
-test/test_model_comp.rb
+test/test_model_compat.rb
 test/test_model_country.rb
-test/test_model_region.rb
+test/test_model_state.rb
+test/test_model_states_at.rb
+test/test_model_states_de.rb
 test/test_models.rb
-test/test_read_adm.rb
+test/test_parse_city.rb
+test/test_parse_country.rb
+test/test_parse_state.rb
+test/test_state_tree_reader_at.rb
+test/test_state_tree_reader_de.rb
+test/test_tree_reader.rb

data/README.md

@@ -30,9 +30,9 @@ Everything is a place.
     at.area
     # => 83_871
     
-    at.regions.count
+    at.states.count
     # => 9
-    at.regions
+    at.states
     # => [ 'Wien', 'Niederösterreich', 'Oberösterreich', ... ]
 
     at.cities.by_pop
@@ -52,9 +52,9 @@ Everything is a place.
     la = City.find_by! key: 'losangeles'
     la.name
     # => 'Los Angeles'
-    la.region.name
+    la.state.name
     # => 'California'
-    la.region.key
+    la.state.key
     # => 'ca'
     la.country.name
     # => 'United States'
@@ -73,11 +73,11 @@ Everything is a place.
     # => ['Austria, 'Belgium', 'Cyprus', ... ]
     
     flanders = Tag.find_by! key: 'flanders'
-    flanders.regions.count
+    flanders.states.count
     # => 5
-    flanders.regions
+    flanders.states
     # => ['Antwerpen', 'Brabant Wallon', 'Limburg', 'Oost-Vlaanderen', 'West-Vlaanderen']
-    flanders.regions.first.country.name
+    flanders.states.first.country.name
     # => 'Belgium'
 
 and so on.

data/Rakefile

@@ -17,7 +17,7 @@ Hoe.spec 'worlddb-models' do
   self.extra_deps = [
     ['props',     '>= 1.1.2'],         # settings / prop(ertie)s / env / INI
     ['logutils',  '>= 0.6.1'],     # logging
-    ['textutils', '>= 0.10.0'], 
+    ['textutils', '>= 1.2.2'], 
 
     ['tagutils',              '>= 0.3.0'],  # tags n categories for activerecord
     ['activerecord-utils',    '>= 0.2.0'],

data/lib/worlddb/deleter.rb

@@ -18,7 +18,12 @@ module WorldDb
       Name.delete_all
       Place.delete_all
       City.delete_all
-      Region.delete_all
+      Metro.delete_all
+      District.delete_all
+      State.delete_all
+      Part.delete_all
+      County.delete_all
+      Muni.delete_all
       Country.delete_all
       Continent.delete_all
       Usage.delete_all

data/lib/worlddb/helpers/value_helper.rb

@@ -0,0 +1,117 @@
+# encoding: utf-8
+
+
+## NOTE:
+##   add helpers to textutils(!!) valuehelper
+##   do NOT create worlddb module
+
+module TextUtils
+  module ValueHelper
+
+  ## todo/check: add to pair of matchers??
+  # e.g. match_country and match_country!
+  #  - match_country will use find_by_key and match_country will use find_by_key! - why? why not?
+
+  def match_country( value )
+    if value =~ /^country:/       # country:
+      country_key = value[8..-1]  # cut off country: prefix
+      country = WorldDb::Model::Country.find_by_key!( country_key )
+      yield( country )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  def match_supra( value )
+    if value =~ /^supra:/         # supra:
+      country_key = value[6..-1]  # cut off supra: prefix
+      country = WorldDb::Model::Country.find_by_key!( country_key )
+      yield( country )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  def match_supra_flag( value )  # supranational (country)
+    if value =~ /^supra$/   # supra(national)
+      yield( true )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+
+  def is_state?( value )   # note: was is_region? (use new name only)
+    # assume state code e.g. TX or N
+    #
+    # fix: allow three letter states too e.g. BRU (brussels)
+    match_result =  value =~ /^[A-Z]{1,2}$/
+    # match found if 0,1,2,3 etc or no match if nil
+    # note: return bool e.g. false|true  (not 0,1,2,3 etc. and nil)
+    match_result != nil
+  end
+
+  ## fix/todo: use match_state_for_country! w/ !!! why? why not?
+  def match_state_for_country( value, country_id )  ## NB: required country_id 
+    if value =~ /^state:/   ## state:
+      state_key = value[6..-1]  ## cut off state: prefix
+      state = WorldDb::Model::State.find_by_key_and_country_id!( state_key, country_id )
+      yield( state )
+      true  # bingo - match found
+    elsif is_state?( value )  ## assume state code e.g. TX or N
+      state = WorldDb::Model::State.find_by_key_and_country_id!( value.downcase, country_id )
+      yield( state )
+      true  # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+
+  def match_city( value )  # NB: might be nil (city not found)
+    if value =~ /^city:/   ## city:
+      city_key = value[5..-1]  ## cut off city: prefix
+      city = WorldDb::Model::City.find_by_key( city_key )
+      yield( city )  # NB: might be nil (city not found)
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  def match_metro( value )
+    if value =~ /^metro:/   ## metro:
+      metro_key = value[6..-1]  ## cut off metro: prefix
+      metro = WorldDb::Model::Metro.find_by_key!( metro_key )
+      yield( metro )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  def match_metro_flag( value )
+    if value =~ /^metro$/   # metro(politan area)
+      yield( true )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  def match_metro_pop( value )
+    if value =~ /^m:/   # m:
+      num = value[2..-1].gsub(/[ _]/, '').to_i   # cut off m: prefix; allow space and _ in number
+      yield( num )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+  end # module ValueHelper
+end # module TextUtils
+

data/lib/worlddb/matcher.rb

@@ -4,26 +4,88 @@ module WorldDb
 
 module Matcher
 
+  def match_tree_for_country( name, &blk )  ## rename to state_tree ?? why? why not??
+    ## match state_tree (for now use orte.txt for austria, deutschland etc.)
+    ##   todo/fix: add more "generic" names
+    
+    simple_match_xxx_for_country( name, 'orte', &blk )  ## note: uses special **simple**_match_xxx_...
+  end
+
+
+  def match_cities_for_country( name, &blk )
+    ## todo: check if there's a better (more ruby way) to pass along code block ??
+    ## e.g. try
+    ##   match_xxx_for_country( name, 'cities') { |country_key| yield(country_key) }
+
+    match_xxx_for_country( name, 'cities', &blk )
+  end
+
+
+
+  def match_states_for_country( name, &blk )
+    ## todo/fix: remove regions (obsolete) - no longer supported
+    ## also try synonyms e.g. old regions (if not match for states)
+    found = match_xxx_for_country( name, 'states', &blk )
+    found = match_xxx_for_country( name, 'regions', &blk ) unless found
+    found
+  end
+
+  def match_states_abbr_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
+    ## also try synonyms e.g. old regions (if not match for states)
+    found = match_xxx_for_country( name, 'states\.abbr', &blk )
+    found = match_xxx_for_country( name, 'regions\.abbr', &blk ) unless found
+    found
+  end
+
+  def match_states_iso_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
+    ## also try synonyms e.g. old regions (if not match for states)
+    found = match_xxx_for_country( name, 'states\.iso', &blk )
+    found = match_xxx_for_country( name, 'regions\.iso', &blk ) unless found
+    found 
+  end
+
+  def match_states_nuts_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
+    ## also try synonyms e.g. old regions (if not match for states)
+    found = match_xxx_for_country( name, 'states\.nuts', &blk )
+    found = match_xxx_for_country( name, 'regions\.nuts', &blk ) unless found
+    found
+  end
+
+
+  def match_countries_for_continent( name )
+    if name =~ /^([a-z][a-z\-_]+[a-z])\/countries/     # e.g. africa/countries or america/countries
+      ### NB: continent changed to regions (e.g. middle-east, caribbean, north-america, etc.)
+      ## auto-add continent (from folder structure) as tag
+      ## fix: allow dash/hyphen/minus in tag
+      continent = $1.dup
+      yield( continent )
+      true
+    else
+      false # no match found
+    end
+  end
+
+
+private
+
   # note: returns code as capture
   WORLD_COUNTRY_CODE_PATTERN    = '([a-z]{2,3})'
   WORLD_COUNTRY_CLASSIC_PATTERN = "#{WORLD_COUNTRY_CODE_PATTERN}-[^\\/]+"          ## note: if you use "" need to double escape backslash!!!
   WORLD_COUNTRY_MODERN_PATTERN  = "[0-9]+--#{WORLD_COUNTRY_CODE_PATTERN}-[^\\/]+"  ## note: if you use "" need to double escape backslash!!!
 
   # note: returns code as capture
-  WORLD_REGION_CODE_PATTERN     = '([a-z]{1,3})'
-  WORLD_REGION_CLASSIC_PATTERN  = "#{WORLD_REGION_CODE_PATTERN}-[^\\/]+"
-  WORLD_REGION_MODERN_PATTERN   = "[0-9]+--#{WORLD_REGION_CODE_PATTERN}-[^\\/]+"
-
-  # note: returns name as capture (no code required)
-  WORLD_ADMIN_MODERN_PATTERN    = "[0-9]+--([^\\/]+)"
+  WORLD_STATE_CODE_PATTERN     = '([a-z]{1,3})'
+  WORLD_STATE_CLASSIC_PATTERN  = "#{WORLD_STATE_CODE_PATTERN}-[^\\/]+"
+  WORLD_STATE_MODERN_PATTERN   = "[0-9]+--#{WORLD_STATE_CODE_PATTERN}-[^\\/]+"
 
-    ## allow optional folders -- TODO: add restriction ?? e.g. must be 4+ alphas ???
+  ## allow optional folders -- TODO: add restriction ?? e.g. must be 4+ alphas ???
   WORLD_OPT_FOLDERS_PATTERN      = "(?:\\/[^\\/]+)*"     ## check: use double \\ or just \ ??
 
 
-  def match_xxx_for_country( name, xxx )  # xxx e.g. cities|regions|beers|breweries
+
+  def match_xxx_for_country( name, xxx )  # xxx e.g. cities|states|beers|breweries
     #      auto-add required country code (from folder structure)
-    #  note: always let match_xxx_for_country_n_region go first
+    #  note: always let match_xxx_for_country_n_state go first
 
     # note: allow  /cities and /1--hokkaido--cities
     xxx_pattern = "(?:#{xxx}|[0-9]+--[^\\/]+?--#{xxx})"    # note: double escape \\ required for backslash
@@ -48,7 +110,7 @@ module Matcher
       #
       # (3)  classic style: e.g. /at/beers (europe/at/cities)
       #
-      # (4) new style w/ region w/o abbrev/code e.g. /ja-japon/1--hokkaido/cities
+      # (4) new style w/ state w/o abbrev/code e.g. /ja-japon/1--hokkaido/cities
       #
       # (5)  compact style (country part of filename):
       #   e.g. /at-austria--cities or /europe/at-austria--cities
@@ -57,12 +119,27 @@ module Matcher
     end
   end
 
+  def simple_match_xxx_for_country( name, xxx )
+    xxx_pattern           = "(?:#{xxx})"    ## just xxx for now
+
+    ## used for state tree (e.g. orte.txt)
+    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/ ||
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_MODERN_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/
+
+      country_key = $1.dup
+      yield( country_key )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
 
-  def match_xxx_for_country_n_region( name, xxx ) # xxx e.g. wine|wineries
+  def match_xxx_for_country_n_state( name, xxx ) # xxx e.g. wine|wineries
 
-    # auto-add required country n region code (from folder structure)
+    # auto-add required country n state code (from folder structure)
 
-    ## -- allow opt_folders after long regions (e.g. additional subregion/zone)
+    ## -- allow opt_folders after long states (e.g. additional substate/zone)
     ## -- allow anything (prefixes) before -- for xxx
     #       e.g.  at-austria!/1--n-niederoesterreich--eastern/wagram--wines
     #             at-austria!/1--n-niederoesterreich--eastern/wagram--wagram--wines
@@ -72,12 +149,12 @@ module Matcher
     oldoldold_xxx_pattern = "(?:#{xxx}|[^\\/]+--#{xxx})"
     xxx_pattern           = "(?:#{xxx}|[^\\/]+#{xxx})"   # note: double escape \\ required for backslash
 
-    ## note: for now only (style #2) n (style #3)  that is long region allow opt folders
+    ## note: for now only (style #2) n (style #3)  that is long state allow opt folders
 
-    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_CLASSIC_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/  ||                # (1)
-       name =~ /(?:^|\/)#{WORLD_COUNTRY_MODERN_PATTERN}\/#{WORLD_REGION_MODERN_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/   || # (2)
-       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_MODERN_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/  || # (3)
-       name =~ /(?:^|\/)#{WORLD_COUNTRY_MODERN_PATTERN}\/#{WORLD_REGION_CLASSIC_PATTERN}\/#{xxx_pattern}/            # (4)
+    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_CLASSIC_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/  ||                # (1)
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_MODERN_PATTERN}\/#{WORLD_STATE_MODERN_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/   || # (2)
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_MODERN_PATTERN}#{WORLD_OPT_FOLDERS_PATTERN}\/#{xxx_pattern}/  || # (3)
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_MODERN_PATTERN}\/#{WORLD_STATE_CLASSIC_PATTERN}\/#{xxx_pattern}/            # (4)
 
       #######
       # nb: country must start name (^) or coming after / e.g. europe/at-austria/...
@@ -89,134 +166,21 @@ module Matcher
       #
       # (3)
       #  new new mixed style e.g.  /at-austria/1--w-wien--eastern/cities
-      #      "classic" country plus new new region
+      #      "classic" country plus new new state
       #
       # (4)
       #  new new mixed style e.g.  /1--at-austria--central/w-wien/cities
-      #      new new country plus "classic" region
-
-      country_key = $1.dup
-      region_key  = $2.dup
-      yield( country_key, region_key )
-      true # bingo - match found
-    else
-      false # no match found
-    end
-  end
-
-
-
-  def match_xxx_for_country_n_adm1( name, xxx ) # xxx e.g. districts|counties|etc.
-
-    # auto-add required country n regions (from folder structure)
-    #
-    #  e.g.  de-deutschland!/3--by-bayern/districts  (regierungsbezirke)
-    #        europe/de-deutschland!/3--by-bayern/districts
-    #
-    #    at-austria!/1--n-niederoesterreich/counties  (bezirke)
-
-    xxx_pattern           = "#{xxx}"
-
-    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_MODERN_PATTERN}\/#{xxx_pattern}/  ||
-       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_CLASSIC_PATTERN}\/#{xxx_pattern}/
-
-      country_key = $1.dup
-      region_key  = $2.dup
-      yield( country_key, region_key )
-      true # bingo - match found
-    else
-      false # no match found
-    end
-  end
-
-
-  def match_xxx_for_country_n_adm1_n_adm2( name, xxx ) # xxx e.g. districts|counties|etc.
-
-    # auto-add required country n regions (from folder structure)
-    #
-    #  e.g.  de-deutschland!/3--by-bayern/4--oberfranken/counties  (landkreise)
-    #        europe/de-deutschland!/3--by-bayern/4--oberfranken/counties
-
-    xxx_pattern           = "#{xxx}"
-
-    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_MODERN_PATTERN}\/#{WORLD_ADMIN_MODERN_PATTERN}\/#{xxx_pattern}/  ||
-       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_REGION_CLASSIC_PATTERN}\/#{WORLD_ADMIN_MODERN_PATTERN}\/#{xxx_pattern}/
+      #      new new country plus "classic" state
 
       country_key = $1.dup
-      region_key  = $2.dup
-      adm2        = $3.dup   # lowercase name e.g. oberfranken, oberbayern, etc.
-      yield( country_key, region_key, adm2 )
+      state_key  = $2.dup
+      yield( country_key, state_key )
       true # bingo - match found
     else
       false # no match found
     end
   end
 
-
-  def match_adm2_for_country( name, &blk )
-    ## note: also try synonyms e.g. districts|counties
-    ## note: counties might also be an adm3 match
-    found = match_xxx_for_country_n_adm1( name, 'districts', &blk )
-    found = match_xxx_for_country_n_adm1( name, 'counties', &blk ) unless found
-    found
-  end
-
-  def match_adm3_for_country( name, &blk )
-    match_xxx_for_country_n_adm1_n_adm2( name, 'counties', &blk )
-  end
-
-
-
-  def match_cities_for_country( name, &blk )
-    ## todo: check if there's a better (more ruby way) to pass along code block ??
-    ## e.g. try
-    ##   match_xxx_for_country( name, 'cities') { |country_key| yield(country_key) }
-
-    match_xxx_for_country( name, 'cities', &blk )
-  end
-
-  def match_regions_for_country( name, &blk )
-    ## also try synonyms e.g. old regions (if not match for states)
-    found = match_xxx_for_country( name, 'states', &blk )
-    found = match_xxx_for_country( name, 'regions', &blk ) unless found
-    found
-  end
-
-  def match_regions_abbr_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
-    ## also try synonyms e.g. old regions (if not match for states)
-    found = match_xxx_for_country( name, 'states\.abbr', &blk )
-    found = match_xxx_for_country( name, 'regions\.abbr', &blk ) unless found
-    found
-  end
-
-  def match_regions_iso_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
-    ## also try synonyms e.g. old regions (if not match for states)
-    found = match_xxx_for_country( name, 'states\.iso', &blk )
-    found = match_xxx_for_country( name, 'regions\.iso', &blk ) unless found
-    found 
-  end
-
-  def match_regions_nuts_for_country( name, &blk )  # NB: . gets escaped for regex, that is, \.
-    ## also try synonyms e.g. old regions (if not match for states)
-    found = match_xxx_for_country( name, 'states\.nuts', &blk )
-    found = match_xxx_for_country( name, 'regions\.nuts', &blk ) unless found
-    found
-  end
-
-
-  def match_countries_for_continent( name )
-    if name =~ /^([a-z][a-z\-_]+[a-z])\/countries/     # e.g. africa/countries or america/countries
-      ### NB: continent changed to regions (e.g. middle-east, caribbean, north-america, etc.)
-      ## auto-add continent (from folder structure) as tag
-      ## fix: allow dash/hyphen/minus in tag
-      continent = $1.dup
-      yield( continent )
-      true
-    else
-      false # no match found
-    end
-  end
-
 end # module Matcher
 
 end # module WorldDb

data/lib/worlddb/matcher_adm.rb

@@ -0,0 +1,82 @@
+# encoding: UTF-8
+
+####
+## matchers for adm2,adm3,etc
+##   e.g. parts (regierungsbezirke)
+##        counties (kreise,bezirke)
+
+module WorldDb
+
+module Matcher
+
+  def match_adm2_parts_for_country( name, &blk )
+    match_xxx_for_country_n_adm1( name, 'parts', &blk )
+  end
+
+  def match_adm2_counties_for_country( name, &blk )
+    ## note: counties might also be an adm3 match
+    match_xxx_for_country_n_adm1( name, 'counties', &blk )
+  end
+
+  def match_adm3_counties_for_country( name, &blk )
+    match_xxx_for_country_n_adm1_n_adm2( name, 'counties', &blk )
+  end
+
+
+private
+  # note: returns name as capture (no code required)
+  WORLD_ADMIN_MODERN_PATTERN    = "[0-9]+--([^\\/]+)"
+
+  ###
+  ## todo/check: adm1 => state
+  ##   why use adm1 and not state ??  duplicate of match___country_n_state ??
+  def match_xxx_for_country_n_adm1( name, xxx ) # xxx e.g. parts|counties|etc.
+
+    # auto-add required country n states (from folder structure)
+    #
+    #  e.g.  de-deutschland!/3--by-bayern/parts  (regierungsbezirke)
+    #        europe/de-deutschland!/3--by-bayern/parts
+    #
+    #    at-austria!/1--n-niederoesterreich/counties  (bezirke)
+
+    xxx_pattern           = "#{xxx}"
+
+    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_MODERN_PATTERN}\/#{xxx_pattern}/  ||
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_CLASSIC_PATTERN}\/#{xxx_pattern}/
+
+      country_key = $1.dup
+      state_key  = $2.dup
+      yield( country_key, state_key )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+
+  def match_xxx_for_country_n_adm1_n_adm2( name, xxx ) # xxx e.g. parts|counties|etc.
+
+    # auto-add required country n states (from folder structure)
+    #
+    #  e.g.  de-deutschland!/3--by-bayern/4--oberfranken/counties  (landkreise)
+    #        europe/de-deutschland!/3--by-bayern/4--oberfranken/counties
+
+    xxx_pattern           = "#{xxx}"
+
+    if name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_MODERN_PATTERN}\/#{WORLD_ADMIN_MODERN_PATTERN}\/#{xxx_pattern}/  ||
+       name =~ /(?:^|\/)#{WORLD_COUNTRY_CLASSIC_PATTERN}\/#{WORLD_STATE_CLASSIC_PATTERN}\/#{WORLD_ADMIN_MODERN_PATTERN}\/#{xxx_pattern}/
+
+      country_key = $1.dup
+      state_key  = $2.dup
+      adm2        = $3.dup   # lowercase name e.g. oberfranken, oberbayern, etc.
+      yield( country_key, state_key, adm2 )
+      true # bingo - match found
+    else
+      false # no match found
+    end
+  end
+
+end # module Matcher
+
+end # module WorldDb
+