sportdb-search 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA256:
+  metadata.gz: a675e2ad48a651c6b31ccc0f68f838907384a93078269dff90c87e5424472a56
+  data.tar.gz: 8abf21926e4e3924ef71df5da72330c834fe0a54679efffdb6657e90361e4bac
+SHA512:
+  metadata.gz: db536b42aabda47e6a6eb7b2da08a7454f91c017801948a86ee7207762a5ffc9ebc5eb7a32e65378aeea4ad8a93af7c0db390458e667dd6cc350c2d3e9dfa24e
+  data.tar.gz: 5b69bf93a1dd374d2dcf50907c26aeaf7781af34ba127d91830f09d8e9406dfcf1345b806222258ba6da7d7bf2df8590790d8f3763298c9a1909ca536a02097a

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2024-08-25
+
+* Everything is new. First release.

data/Manifest.txt

@@ -0,0 +1,9 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/sportdb/search.rb
+lib/sportdb/search/sport.rb
+lib/sportdb/search/structs.rb
+lib/sportdb/search/version.rb
+lib/sportdb/search/world.rb

data/README.md

@@ -0,0 +1,28 @@
+# sportdb-search - find national teams, clubs, leagues & more
+
+* home  :: [github.com/sportdb/sport.db](https://github.com/sportdb/sport.db)
+* bugs  :: [github.com/sportdb/sport.db/issues](https://github.com/sportdb/sport.db/issues)
+* gem   :: [rubygems.org/gems/sportdb-search](https://rubygems.org/gems/sportdb-search)
+* rdoc  :: [rubydoc.info/gems/sportdb-search](http://rubydoc.info/gems/sportdb-search)
+
+
+
+## Usage
+
+
+to be done
+
+
+## License
+
+The `sportdb-search` scripts are dedicated to the public domain.
+Use it as you please with no restrictions whatsoever.
+
+
+## Questions? Comments?
+
+Yes, you can. More than welcome.
+See [Help & Support »](https://github.com/openfootball/help)
+
+
+

data/Rakefile

@@ -0,0 +1,29 @@
+require 'hoe'
+require './lib/sportdb/search/version.rb'
+
+Hoe.spec 'sportdb-search' do
+
+  self.version = SportDb::Module::Search::VERSION
+
+  self.summary = "sportdb-search - find national teams, clubs, leagues & more"
+  self.description = summary
+
+  self.urls = { home: 'https://github.com/sportdb/sport.db' }
+
+  self.author = 'Gerald Bauer'
+  self.email = 'gerald.bauer@gmail.com'
+
+  # switch extension to .markdown for gihub formatting
+  self.readme_file  = 'README.md'
+  self.history_file = 'CHANGELOG.md'
+
+  self.licenses = ['Public Domain']
+
+  self.extra_deps = [
+    ['sportdb-catalogs',   '>= 1.2.3'],
+  ]
+
+  self.spec_extras = {
+   required_ruby_version: '>= 3.1.0'
+  }
+end

data/lib/sportdb/search/sport.rb

@@ -0,0 +1,323 @@
+###
+#  sport search service api for leagues, clubs and more
+#
+# core api is:
+
+
+class SportSearch
+
+class PlayerSearch < Search
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+  def match_by( name:, country: nil, year: nil )
+    @service.match_by( name:    name,
+                       country: country,
+                       year:    year )
+  end
+
+  ###############
+  ### more deriv support functions / helpers
+  def match( name ) match_by( name: name ); end
+  ## add more here - why? why not?
+end   # class PlayerSearch
+
+
+class LeagueSearch < Search
+
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+  def match_by( name: nil, code: nil, country: nil )
+     ## todo/fix upstream - remove "generic" match_by() - why? why not?
+     ###
+     if code && name.nil?
+      @service.match_by_code( code, country: country )
+    elsif name && code.nil?
+      @service.match_by_name( name, country: country )
+    else
+      raise ArgumentError, "LeagueSearch#match_by - one (and only one arg) required - code: or name:"
+    end
+    ## @service.match_by( name: name,
+    ##                   country: country )
+  end
+
+  ## all-in-one query (name or code)
+  def match( q, country: nil )
+     @service.match_by_name_or_code( q, country: country )
+  end
+
+
+  ###############
+  ### more deriv support functions / helpers
+  def find!( q )
+    league = find( q )
+    if league.nil?
+      puts "** !!! ERROR - no league match found for >#{q}<, add to leagues table; sorry"
+      exit 1
+    end
+    league
+  end
+
+  def find( q )
+    league = nil
+    recs = match( q )
+    # pp m
+
+    if recs.empty?
+      ## fall through/do nothing
+    elsif recs.size > 1
+      puts "** !!! ERROR - ambigious league query; too many leagues (#{recs.size}) found:"
+      pp recs
+      exit 1
+    else
+      league = recs[0]
+    end
+
+    league
+  end
+end # class LeagueSearch
+
+
+
+class GroundSearch  < Search
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+  def match_by( name:, country: nil, city: nil )
+    @service.match_by( name:    name,
+                       country: country,
+                       city:    city )
+  end
+
+  ###############
+  ### more deriv support functions / helpers
+  def match( name ) match_by( name: name ); end
+  ## add more here - why? why not?
+end  # class GroundSearch
+
+
+
+class NationalTeamSearch  < Search
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+
+  ## changle core api to match( q ) only - why? why not?
+  ##   and make find and find! derivs???
+  def find( q )    @service.find( q ); end
+  def find!( q )   @service.find!( q ); end
+end # class NationalTeamSearch
+
+
+class ClubSearch  < Search
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+
+  ## add mods here - why? why not?
+
+  def match_by( name:, country: nil,
+                       league:  nil,
+                       mods:    nil )
+    ## for now assume "global" mods  - checks only for name
+    ##
+    if mods && mods[ name ]
+      club = mods[ name ]
+      return [club]   # note: wrap (single record) in array
+    end
+
+    ## note: add "auto-magic" country calculation via league record
+    ##            if league is a national league for football clubs
+    if league
+        raise ArgumentError, "match_by - league AND country NOT supported; sorry"  if country
+### find countries via league
+###     support league.intl? too - why? why not?
+###       or only nationa league
+        raise ArgumentError, "match_by - league - only national club leagues supported (not int'l or national teams for now); sorry"   unless league.national? && league.clubs?
+
+        ### calc countries
+        ### uses "global" func in sports-catalogs for now
+        ##   move code here - why? why not?
+        country = find_countries_for_league( league )
+        @service.match_by( name:    name,
+                           country: country )
+    else
+        @service.match_by( name:    name,
+                           country: country )
+    end
+  end
+
+
+  ## todo/fix/check: use rename to find_canon  or find_canonical() or something??
+  ##  remove (getting used?) - why? why not?
+  # def []( name )    ## lookup by canoncial name only;  todo/fix: add find alias why? why not?
+  #  puts "WARN!! do not use ClubIndex#[] for lookup >#{name}< - will get removed!!!"
+  #  @clubs[ name ]
+  # end
+
+
+  ###############
+  ### more deriv support functions / helpers
+  def match( name ) match_by( name: name ); end
+
+  ##########
+  #  "legacy" finders - return zero or one club
+  ##    (if more than one match, exit/raise error/exception)
+  def find( name )   find_by( name: name ); end
+  def find!( name )  find_by!( name: name ); end
+
+  ## find - always returns a single record / match or nil
+  ##   if there is more than one match than find aborts / fails
+  def find_by!( name:, country: nil,
+                       league:  nil )    ## todo/fix: add international or league flag?
+    club = find_by( name:    name,
+                    country: country,
+                    league:  league )
+
+    if club.nil?
+      puts "** !!! ERROR - no match for club >#{name}<"
+      exit 1
+    end
+
+    club
+  end
+
+
+  def find_by( name:, country: nil,
+                      league:  nil )    ## todo/fix: add international or league flag?
+    ## note: allow passing in of country key too (auto-counvert)
+    ##       and country struct too
+    ##     - country assumes / allows the country key or fifa code for now
+    recs = match_by( name:    name,
+                     country: country,
+                     league:  league )
+
+    club = nil
+    if recs.empty?
+      ## puts "** !!! WARN !!! no match for club >#{name}<"
+    elsif recs.size > 1
+      puts "** !!! ERROR - too many matches (#{recs.size}) for club >#{name}<:"
+      pp recs
+      exit 1
+    else   # bingo; match - assume size == 1
+      club = recs[0]
+    end
+
+    club
+  end
+
+
+#######
+# more support methods
+  def build_mods( mods )
+    ## e.g.
+    ##  { 'Arsenal   | Arsenal FC'    => 'Arsenal, ENG',
+    ##    'Liverpool | Liverpool FC'  => 'Liverpool, ENG',
+    ##    'Barcelona'                 => 'Barcelona, ESP',
+    ##    'Valencia'                  => 'Valencia, ESP' }
+
+    mods.reduce({}) do |h,(club_names, club_line)|
+
+      values = club_line.split( ',' )
+      values = values.map { |value| value.strip }  ## strip all spaces
+
+      ## todo/fix: make sure country is present !!!!
+      club_name, country_name = values
+      club = find_by!( name: club_name, country: country_name )
+
+      values = club_names.split( '|' )
+      values = values.map { |value| value.strip }  ## strip all spaces
+
+      values.each do |club_name|
+        h[club_name] = club
+      end
+      h
+    end
+  end
+end # class ClubSearch
+
+
+
+## todo/check - change to EventInfoSearch - why? why not?
+class EventSearch < Search
+  ##
+  ## todo - eventinfo search still open / up for change
+
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+  def seasons( league )
+      @service.seasons( league )
+  end
+  def find_by( league:, season: )
+      @service.find_by( league: league,
+                        season: season )
+  end
+end # class EventSearch
+
+
+####
+## virtual table for season lookup
+##   note - use EventSeaon  to avoid name conflict with (global) Season class
+##      find a better name SeasonInfo or SeasonFinder or SeasonStore
+##                       or SeasonQ or ??
+class EventSeasonSearch
+    def initialize( events: )
+        @events = events
+    end
+
+  ###############
+  ## todo/fix:  find a better algo to guess season for date!!!
+  ##
+  def find_by( date:, league: )
+    date = Date.strptime( date, '%Y-%m-%d' )   if date.is_a?( String )
+
+    infos = @events.seasons( league )
+
+    infos.each do |info|
+       return info.season   if info.include?( date )
+    end
+    nil
+  end
+end # class EventSeasonSearch
+
+
+######
+### add virtual team search ( clubs + national teams)
+##   note: no record base!!!!!
+class TeamSearch
+    ## note: "virtual" index lets you search clubs and/or national_teams (don't care)
+
+  def initialize( clubs:, national_teams: )
+    @clubs          = clubs
+    @national_teams = national_teams
+  end
+
+    ## todo/check: rename to/use map_by! for array version - why? why not?
+    def find_by!( name:, league:, mods: nil )
+      if name.is_a?( Array )
+        recs = []
+        name.each do |q|
+          recs << _find_by!( name: q, league: league, mods: mods )
+        end
+        recs
+      else  ## assume single name
+        _find_by!( name: name, league: league, mods: mods )
+      end
+    end
+
+
+    def _find_by!( name:, league:, mods: nil )
+      if mods && mods[ league.key ] && mods[ league.key ][ name ]
+        mods[ league.key ][ name ]
+      else
+        if league.clubs?
+          if league.intl?    ## todo/fix: add intl? to ActiveRecord league!!!
+            @clubs.find!( name )
+          else  ## assume clubs in domestic/national league tournament
+             ## note - search by league countries (may incl. more than one country
+             ##             e.g. us incl. ca, fr incl. mc, ch incl. li, etc.
+            @clubs.find_by!( name: name, league: league )
+          end
+        else   ## assume national teams (not clubs)
+          @national_teams.find!( name )
+        end
+      end
+    end # method _find_by!
+  end  # class TeamSearch
+end  # class SportSearch

data/lib/sportdb/search/structs.rb

@@ -0,0 +1,132 @@
+###
+#  note - extend all structs for with search api
+#
+#  todo - add more helpers!!!!
+#
+#
+#  todo - fix - move all non-core search functionality/machinery
+#                  over here - why? why not?
+
+
+
+module Sports
+
+class Country
+    def self._search #### use service/api or such - why? why not?
+        SportDb::Import.world.countries
+    end
+   def self.find_by( code: nil, name: nil )
+        _search.find_by( code: code, name: name )
+   end
+
+   def self.find( q )   ## find by code (first) or name (second)
+       _search.find( q )
+   end
+
+   def self.parse_heading( line )
+      ## fix - move parse code here from search - why? why not?
+      _search.parse( line )
+   end
+
+   ## add alternate names/aliases
+   class << self
+    alias_method :[],      :find    ### keep shortcut - why? why not?
+    alias_method :heading, :parse_heading
+   end
+
+
+# open question - what name to use build or  parse_line or ?
+#                              or   parse_recs for CountryReader?
+#          remove CountryReader helper methods - why? why not?
+#   use parse_heading/heading for now !!!
+#
+#   def self.parse( line )  or build( line ) ??
+#      SportDb::Import.world.countries.parse( line )
+#   end
+#
+# !!!! note - conflict with
+#     def self.read( path )  CountryReader.read( path ); end
+#     def self.parse( txt )  CountryReader.parse( txt ); end
+#
+end # class Country
+
+
+###
+## todo/fix - add find_by( code: ), find_by( name: )
+##                   split - why? why not?
+
+
+class League
+    def self._search #### use service/api or such - why? why not?
+        SportDb::Import.catalog.leagues
+    end
+    def self.match_by( name: nil, code: nil,
+                        country: nil )
+       _search.match_by( name: name, code: code,
+                         country: country )
+    end
+    def self.match( q, country: nil )
+        _search.match( q, country: country )
+    end
+
+    def self.find!( q ) _search.find!( q ); end
+    def self.find( q )  _search_find( q ); end
+end # class League
+
+
+class NationalTeam
+    def self._search #### use service/api or such - why? why not?
+        SportDb::Import.catalog.national_teams
+    end
+
+    def self.find( q )   _search.find( q ); end
+    def self.find!( q )  _search_find!( q ); end
+end # class NationalTeam
+
+
+
+class Club
+    def self._search #### use service/api or such - why? why not?
+        SportDb::Import.catalog.clubs
+    end
+
+    def self.match_by( name:, country: nil,
+                         league:  nil,
+                         mods:    nil )
+        _search.match_by( name: name, country: country,
+                          league: league, mods: mods )
+    end
+    def self.match( name ) match_by( name: name ); end
+
+    def self.find( name )   _search.find_by( name: name ); end
+    def self.find!( name )  _search.find_by!( name: name ); end
+
+    def self.find_by!( name:, country: nil,
+                              league:  nil )
+       _search.find_by!( name: name, country: country,
+                                     league: league )
+    end
+    def self.find_by( name:, country: nil,
+                             league:  nil )
+       _search.find_by( name: name, country: country,
+                                    league: league )
+    end
+
+   def self.build_mods( mods )
+       _search_build_mods( mods )
+    end
+  end # class Club
+
+
+  class Ground
+    def self._search
+        SportDb::Import.catalog.grounds
+    end
+
+    def self.match_by( name:, country: nil, city: nil )
+      _search.match_by( name:    name,
+                        country: country,
+                        city:    city )
+    end
+  end # class Ground
+end   # module Sports

data/lib/sportdb/search/version.rb

@@ -0,0 +1,24 @@
+module SportDb
+module Module
+module Search
+
+  MAJOR = 0    ## todo: namespace inside version or something - why? why not??
+  MINOR = 0
+  PATCH = 1
+  VERSION = [MAJOR,MINOR,PATCH].join('.')
+
+  def self.version
+    VERSION
+  end
+
+  def self.banner
+    "sportdb-search/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}] in (#{root})"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(File.dirname(__FILE__)))) )
+  end
+
+end # module Search
+end # module Module
+end # module SportDb

data/lib/sportdb/search/world.rb

@@ -0,0 +1,127 @@
+###
+#  world search service api for countries and more
+#
+# core api is:
+# -  world.countries.find_by_code
+# -                 .find_by_name
+
+
+class WorldSearch
+
+class CitySearch < Search
+  ###################
+  ## core required delegates  - use delegate generator - why? why not?
+  def match_by( name: )
+    @service.match_by( name: name )
+  end
+end  # class CitySearch
+
+
+class CountrySearch < Search
+    ###################
+    ## core required delegates  - use delegate generator - why? why not?
+    def find_by_code( code )
+      puts "!! DEPRECATED - use CountrySearch#find_by( code: )"
+      @service.find_by_code( code )
+    end
+    def find_by_name( name )
+      puts "!! DEPRECATED - use CountrySearch#find_by( name: )"
+      @service.find_by_name( name )
+    end
+
+    def find_by( code: nil, name: nil )
+      ## todo/fix upstream - change to find_by( code:, name:, ) too
+      if code && name.nil?
+        @service.find_by_code( code )
+      elsif name && code.nil?
+        @service.find_by_name( name )
+      else
+        raise ArgumentError, "CountrySearch#find_by - one (and only one arg) required - code: or name:"
+      end
+    end
+
+    def find( q )
+      @service.find_by_name_or_code( q )
+    end
+    alias_method :[], :find    ### keep shortcut - why? why not?
+
+
+    ###############
+    ### more deriv support functions / helpers
+
+ ###
+ ##   split/parse country line
+ ##
+ ##  split on bullet e.g.
+ ##   split into name and code with regex - make code optional
+ ##
+ ##  Examples:
+ ##    Österreich • Austria (at)
+ ##    Österreich • Austria
+ ##    Austria
+ ##    Deutschland (de) • Germany
+ ##
+ ##   todo/check: support more formats - why? why not?
+ ##       e.g.  Austria, AUT  (e.g. with comma - why? why not?)
+ def parse( line )
+   values = line.split( '•' )   ## use/support multi-lingual separator
+   country = nil
+   values.each do |value|
+      value = value.strip
+      ## check for trailing country code e.g. (at), (eng), etc
+      ##   allow code 1 to 5 for now - northern cyprus(fifa) with 5 letters?.
+      ##     add/allow  gb-eng, gb-wal (official iso2!!), in the future too - why? why not?
+      if value =~ /[ ]+\((?<code>[A-Za-z]{1,5})\)$/  ## e.g. Austria (at)
+        code =  $~[:code]
+        name = value[0...(value.size-code.size-2)].strip  ## note: add -2 for brackets
+        candidates = [ find_by( code: code ), find_by( name: name ) ]
+        if candidates[0].nil?
+          puts "** !!! ERROR Country.parse_heading - unknown code >#{code}< in line: #{line}"
+          pp line
+          exit 1
+        end
+        if candidates[1].nil?
+          puts "** !!! ERROR Country.parse_heading - unknown name >#{code}< in line: #{line}"
+          pp line
+          exit 1
+        end
+        if candidates[0] != candidates[1]
+          puts "** !!! ERROR Country.parse_heading - name and code do NOT match the same country:"
+          pp line
+          pp candidates
+          exit 1
+        end
+        if country && country != candidates[0]
+          puts "** !!! ERROR Country.parse_heading - names do NOT match the same country:"
+          pp line
+          pp country
+          pp candidates
+          exit 1
+        end
+        country = candidates[0]
+      else
+        ## just assume value is name or code
+        candidate = find( value )
+        if candidate.nil?
+          puts "** !!! ERROR Country.parse_heading - unknown name or code >#{value}< in line: #{line}"
+          pp line
+          exit 1
+        end
+        if country && country != candidate
+          puts "** !!! ERROR Country.parse_heading - names do NOT match the same country:"
+          pp line
+          pp country
+          pp candidate
+          exit 1
+        end
+        country = candidate
+      end
+   end
+   country
+ end # method parse
+end  # class CountrySearch
+end  # class WorldSearch
+
+
+
+

data/lib/sportdb/search.rb

@@ -0,0 +1,223 @@
+## note: sportdb/catalogs pulls in sportdb/structs and footballdb/data
+require 'sportdb/catalogs'
+
+
+
+## move to base?
+###  shared basics for search
+class SportSearch
+  class Search    ## base search service - use/keep - why? why not?
+    def initialize( service ) @service = service; end
+  end  # class Search
+end
+
+class WorldSearch
+  class Search    ## base search service - use/keep - why? why not?
+    def initialize( service ) @service = service; end
+  end  # class Search
+end
+
+
+
+## our own code
+require_relative 'search/version'
+require_relative 'search/sport'
+require_relative 'search/world'
+
+
+########
+###  setup sport search apis
+class SportSearch
+   def initialize( leagues:,
+                   national_teams:,
+                   clubs:,
+                   grounds:,
+                   events:,
+                   players:
+                   )
+       @leagues        = LeagueSearch.new( leagues )
+       @national_teams = NationalTeamSearch.new( national_teams )
+       @clubs          = ClubSearch.new( clubs )
+       @events         = EventSearch.new( events )
+
+       @grounds        = GroundSearch.new( grounds )
+
+       @players        = PlayerSearch.new( players )
+
+       ## virtual deriv ("composite") search services
+       @teams          = TeamSearch.new( clubs:          @clubs,
+                                         national_teams: @national_teams )
+       @event_seasons  = EventSeasonSearch.new( events: @events )
+
+   end
+
+ def leagues()        @leagues; end
+ def national_teams() @national_teams; end
+ def clubs()          @clubs; end
+ def events()         @events; end
+ def grounds()         @grounds; end
+
+ def players()        @players; end
+
+ def teams()          @teams; end         ## note - virtual table
+ def seasons()        @event_seasons; end ## note - virtual table
+
+ def countries
+    puts
+    puts "[WARN] do NOT use catalog.countries, deprecated!!!"
+    puts "   please, switch to new world.countries search service"
+    puts
+    exit 1
+ end
+end # class SportSearch
+
+
+class WorldSearch
+    def initialize( countries:, cities: )
+        ## change service to country_service or such - why? why not?
+        ##  add city_service and such later
+        @countries = CountrySearch.new( countries )
+        @cities    = CitySearch.new( cities )
+    end
+
+    ####
+    #  note: for now setup only for countries & cities
+    def countries() @countries;  end
+    def cities()    @cities;  end
+end  # class WorldSearch
+
+
+#######
+## add configuration
+
+module SportDb
+module Import
+class Configuration
+  def world
+    @world ||= WorldSearch.new(
+                      countries: CatalogDb::Metal::Country,
+                      cities:    CatalogDb::Metal::City,
+                   )
+  end
+
+  def catalog
+    @catalog ||= SportSearch.new(
+                        leagues:        CatalogDb::Metal::League,
+                        national_teams: CatalogDb::Metal::NationalTeam,
+                        clubs:          CatalogDb::Metal::Club,
+                        grounds:        CatalogDb::Metal::Ground,
+                        events:         CatalogDb::Metal::EventInfo,
+                        players:        CatalogDb::Metal::Player,    # note - via players.db !!!
+                     )
+  end
+
+  ###
+  #  find a better name for setting - why? why not?
+  #     how about catalogdb or ???
+  attr_reader   :catalog_path
+  def catalog_path=(path)
+      @catalog_path = path
+      ########
+      # reset database here to new path
+      CatalogDb::Metal::Record.database = path
+      @catalog_path
+  end
+
+  ###
+  #  find a better name for setting - why? why not?
+  #     how about playersdb or ???
+  attr_reader   :players_path
+  def players_path=(path)
+      @players_path = path
+      ########
+      # reset database here to new path
+      CatalogDb::Metal::PlayerRecord.database = path
+
+      @players_path
+  end
+
+
+end # class Configuration
+
+    ##  e.g. use config.catalog  -- keep Import.catalog as a shortcut (for "read-only" access)
+    def self.world()   config.world;    end
+    def self.catalog() config.catalog;  end
+
+      ## lets you use
+      ##   SportDb::Import.configure do |config|
+      ##      config.catalog_path = './catalog.db'
+      ##   end
+    def self.configure()  yield( config ); end
+    def self.config()  @config ||= Configuration.new;  end
+end   # module Import
+end   # module SportDb
+
+
+module Sports
+    ## note: just forward to SportDb::Import configuration!!!!!
+    ##  keep Sports module / namespace "clean" - why? why not?
+    ##    that is, only include data structures (e.g. Match,League,etc) for now - why? why not?
+    def self.configure()  yield( config ); end
+    def self.config()  SportDb::Import.config; end
+end   # module Sports
+
+
+
+
+
+###
+##   add/augment core classes with search services
+require_relative 'search/structs'
+
+
+
+module SportDb
+  module Import
+    Season = ::Season   ## add a convenience alias for top-level Season class
+
+    ## add "old" convenience aliases for structs - why? why not?
+    ##   todo/check: just use include Sports !!!!
+    Country      = ::Sports::Country
+    League       = ::Sports::League
+    Group        = ::Sports::Group
+    Round        = ::Sports::Round
+    Match        = ::Sports::Match
+    Matchlist    = ::Sports::Matchlist
+    Goal         = ::Sports::Goal
+    Team         = ::Sports::Team
+    NationalTeam = ::Sports::NationalTeam
+    Club         = ::Sports::Club
+    Standings    = ::Sports::Standings
+    TeamUsage    = ::Sports::TeamUsage
+
+    Ground       = ::Sports::Ground
+
+    Player       = ::Sports::Player
+
+    EventInfo    = ::Sports::EventInfo
+
+
+    class Team
+      ## add convenience lookup helper / method for name by season for now
+      ##   use clubs history - for now kept separate from struct - why? why not?
+      def name_by_season( season )
+        ## note: returns / fallback to "regular" name if no records found in history
+        SportDb::Import.catalog.clubs_history.find_name_by( name: name, season: season ) || name
+      end
+    end  # class Team
+
+  end   # module Import
+end     # module SportDb
+
+
+###
+## add default/built-in catalog here - why? why not?
+##  todo/fix  - set catalog_path on demand
+##   note:  for now required for world search setup etc.
+## SportDb::Import.config.catalog_path = "#{FootballDb::Data.data_dir}/catalog.db"
+##
+##  note - for now set as default upstream in sportdb-catalogs!!!
+
+
+puts SportDb::Module::Search.banner   # say hello
+

metadata

@@ -0,0 +1,104 @@
+--- !ruby/object:Gem::Specification
+name: sportdb-search
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Gerald Bauer
+autorequire:
+bindir: bin
+cert_chain: []
+date: 2024-08-25 00:00:00.000000000 Z
+dependencies:
+- !ruby/object:Gem::Dependency
+  name: sportdb-catalogs
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 1.2.3
+- !ruby/object:Gem::Dependency
+  name: rdoc
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: '4.0'
+    - - "<"
+      - !ruby/object:Gem::Version
+        version: '7'
+- !ruby/object:Gem::Dependency
+  name: hoe
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '4.1'
+description: sportdb-search - find national teams, clubs, leagues & more
+email: gerald.bauer@gmail.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/sportdb/search.rb
+- lib/sportdb/search/sport.rb
+- lib/sportdb/search/structs.rb
+- lib/sportdb/search/version.rb
+- lib/sportdb/search/world.rb
+homepage: https://github.com/sportdb/sport.db
+licenses:
+- Public Domain
+metadata: {}
+post_install_message:
+rdoc_options:
+- "--main"
+- README.md
+require_paths:
+- lib
+required_ruby_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: 3.1.0
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubygems_version: 3.4.10
+signing_key:
+specification_version: 4
+summary: sportdb-search - find national teams, clubs, leagues & more
+test_files: []