sportdb-structs 0.4.2 → 0.5.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4603607b4234fbe74e0b57ed548a61a7d899041497d2e0e7f3104396b00e943a
-  data.tar.gz: 24945611ea43fca109b2a4b993ad6bf913daee4e034762d3797799d5a8a7bea5
+  metadata.gz: 6f93a521b7edcab10afea6cb26770b1924b23cb0c8a1b1d25080c57132b0e21b
+  data.tar.gz: f0099bb428f29a92f1419096d0f693671d035718ec816dbca4a9d4ca5376e497
 SHA512:
-  metadata.gz: 236bb3e8ac4e58e16b398e2fd9bdceabbd74e527a4aa1ef2af823976f31ef7b63f7342b640829218a2c9c08effd060675db67c4ec24d17497cee8071db4df0db
-  data.tar.gz: 7bdc16e2b06599fad689166a06bcd6b9aa4ef9ba4ddd0bb6c47a0d6aa68f6b20d9e2184ba0f211d9d9d455da6a7832ec14e9b5455aafe0e3c2c2e0c43f14dd5c
+  metadata.gz: 6ee368ed13cfb5c2ea432404eb7a7171bbfb82a3d543773ff0ec66a5840f91301c719e9a373cb49826080e9c811f391566d2d5608fe4f8cb56d6a4f601babccc
+  data.tar.gz: d81f2090d34dc149a6667a09a89016d1c89a9b3f34b2876ce2b2f973843756102b1dfcfb275f0e0d0f4540dace8b0f6f5fe2b474764e5884eac9b0a3fb7ae719

data/CHANGELOG.md

@@ -1,5 +1,4 @@
-### 0.4.2
-
+### 0.5.1
 ### 0.0.1 / 2020-08-24
 
 * Everything is new. First release.

data/Manifest.txt

@@ -2,6 +2,10 @@ CHANGELOG.md
 Manifest.txt
 README.md
 Rakefile
+lib/sportdb/csv/goal.rb
+lib/sportdb/csv/goal_parser_csv.rb
+lib/sportdb/csv/match_parser_csv.rb
+lib/sportdb/csv/match_status_parser.rb
 lib/sportdb/structs.rb
 lib/sportdb/structs/country.rb
 lib/sportdb/structs/event_info.rb

data/Rakefile

@@ -20,6 +20,7 @@ Hoe.spec 'sportdb-structs' do
   self.licenses = ['Public Domain']
 
   self.extra_deps = [
+    ['cocos',          '>= 0.4.0'],
     ['alphabets',      '>= 1.0.2'],
     ['score-formats',  '>= 0.1.1'],
     ['season-formats', '>= 0.0.1'],

data/lib/sportdb/csv/goal.rb

@@ -0,0 +1,192 @@
+
+module Sports
+
+## "free-standing" goal event - for import/export  in separate event / goal datafiles
+##   returned by CsvGoalParser and others
+class GoalEvent
+
+  def self.build( row )  ## rename to parse or such - why? why not?
+
+  ## split match_id
+  team_str, more_str   = row['Match'].split( '|' )
+  team1_str, team2_str = team_str.split( ' - ' )
+
+  more_str  = more_str.strip
+  team1_str = team1_str.strip
+  team2_str = team2_str.strip
+
+   # check if more_str is a date otherwise assume round
+   date_fmt = if more_str =~ /^[A-Z]{3} [0-9]{1,2}$/i  ## Apr 4
+                '%b %d'
+              elsif more_str =~ /^[A-Z]{3} [0-9]{1,2} [0-9]{4}$/i  ## Apr 4 2019
+                '%b %d %Y'
+             else
+                nil
+             end
+
+   if date_fmt
+    date  = Date.strptime( more_str, date_fmt )
+    round = nil
+   else
+    date  = nil
+    round = more_str
+   end
+
+
+    values = row['Score'].split('-')
+    values = values.map { |value| value.strip }
+    score1 = values[0].to_i
+    score2 = values[1].to_i
+
+    minute = nil
+    offset = nil
+    if m=%r{([0-9]+)
+              (?:[ ]+
+                   \+([0-9]+)
+                )?
+                ['.]
+          $}x.match( row['Minute'])
+      minute = m[1].to_i
+      offset = m[2] ? m[2].to_i : nil
+    else
+      puts "!! ERROR - unsupported minute (goal) format >#{row['Minute']}<"
+      exit 1
+    end
+
+    attributes = {
+          team1:  team1_str,
+          team2:  team2_str,
+          date:   date,
+          round:  round,
+          score1: score1,
+          score2: score2,
+          minute: minute,
+          offset: offset,
+          player: row['Player'],
+          owngoal: ['(og)', '(o.g.)'].include?( row['Extra']),
+          penalty: ['(pen)', '(pen.)'].include?( row['Extra']),
+          notes:   (row['Notes'].nil? || row['Notes'].empty?) ? nil : row['Notes']
+        }
+
+    new( **attributes )
+  end
+
+
+  ## match id
+  attr_reader  :team1,
+               :team2,
+               :round,  ## optional
+               :date   ## optional
+
+  ## main attributes
+  attr_reader :score1,
+              :score2,
+              :player,
+              :minute,
+              :offset,
+              :owngoal,
+              :penalty,
+              :notes
+
+
+  ## todo/check: or just use match.hash or such if match mapping known - why? why not?
+  def match_id
+    if round
+      "#{@team1} - #{@team2} | #{@round}"
+    else
+      "#{@team1} - #{@team2} | #{@date}"
+    end
+  end
+
+
+  def owngoal?() @owngoal==true; end
+  def penalty?() @penalty==true; end
+
+  def initialize( team1:,
+                  team2:,
+                  round:   nil,
+                  date:    nil,
+                  score1:,
+                  score2:,
+                  player:,
+                  minute:,
+                  offset:  nil,
+                  owngoal: false,
+                  penalty: false,
+                  notes:   nil
+                )
+    @team1   = team1
+    @team2   = team2
+    @round   = round
+    @date    = date
+
+    @score1  = score1
+    @score2  = score2
+    @player  = player
+    @minute  = minute
+    @offset  = offset
+    @owngoal = owngoal
+    @penalty = penalty
+    @notes   = notes
+  end
+
+
+  ## note: lets you use normalize teams or such acts like a Match struct
+  def update( **kwargs )
+    ## todo/fix: use team1_name, team2_name or similar - for compat with db activerecord version? why? why not?
+    @team1 = kwargs[:team1]    if kwargs.has_key? :team1
+    @team2 = kwargs[:team2]    if kwargs.has_key? :team2
+  end
+end  # class GoalEvent
+
+
+### extend "basic" goal struct with goal event build
+class Goal  ### nested (non-freestanding) inside match (match is parent)
+
+  def self.build( events )  ## check/todo - rename to build_from_event/row or such - why? why not?
+    ## build an array of goal structs from (csv) recs
+    recs = []
+
+    last_score1 = 0
+    last_score2 = 0
+
+    events.each do |event|
+
+      if last_score1+1 == event.score1 && last_score2 == event.score2
+        team = 1
+      elsif last_score2+1 == event.score2 && last_score1 == event.score1
+        team = 2
+      else
+        puts "!! ERROR - unexpected score advance (one goal at a time expected):"
+        puts "  #{last_score1}-#{last_score2}=> #{event.score1}-#{event.score2}"
+        exit 1
+      end
+
+      last_score1 = event.score1
+      last_score2 = event.score2
+
+
+      attributes = {
+        score1:  event.score1,
+        score2:  event.score2,
+        team:    team,
+        minute:  event.minute,
+        offset:  event.offset,
+        player:  event.player,
+        owngoal: event.owngoal,
+        penalty: event.penalty,
+        notes:   event.notes
+      }
+
+      recs << new( **attributes )
+    end
+
+    recs
+  end
+end  # class Goal
+
+
+end # module Sports
+
+
+

data/lib/sportdb/csv/goal_parser_csv.rb

@@ -0,0 +1,28 @@
+
+module SportDb
+  class CsvGoalParser
+
+
+  def self.read( path )
+     txt = File.open( path, 'r:utf-8' ) {|f| f.read }   ## note: make sure to use (assume) utf-8
+     parse( txt )
+  end
+
+  def self.parse( txt )
+     new( txt ).parse
+  end
+
+
+  def initialize( txt )
+    @txt = txt
+  end
+
+  def parse
+    rows = parse_csv( @txt )
+    recs = rows.map { |row| Sports::GoalEvent.build( row ) }
+    ## pp recs[0]
+    recs
+  end
+
+  end # class CsvGoalParser
+end # module Sports

data/lib/sportdb/csv/match_parser_csv.rb

@@ -0,0 +1,490 @@
+
+module SportDb
+  class CsvMatchParser
+
+  #############
+  # helpers
+  def self.find_seasons( path, col: 'Season', sep: nil, headers: nil )
+
+    ## check if headers incl. season if yes,has priority over col mapping
+    ##  e.g. no need to specify twice (if using headers)
+    col = headers[:season]    if headers && headers[:season]
+
+    seasons = Hash.new( 0 )   ## default value is 0
+
+    ## todo/fix: yes, use CsvHash.foreach  - why? why not?
+    ##                    use read_csv with block  to switch to foreach!!!!
+    rows = read_csv( path, sep: sep )
+
+    rows.each_with_index do |row,i|
+      puts "[#{i}] " + row.inspect  if i < 2
+
+      season = row[ col ]   ## column name defaults to 'Season'
+      seasons[ season ] += 1
+    end
+
+    pp seasons
+
+    ## note: only return season keys/names (not hash with usage counter)
+    seasons.keys
+  end
+
+
+  ##########
+  # main machinery
+
+  ##  todo/fix: use a generic "global" parse_csv method - why? why not?
+  ## def self.parse_csv( text, sep: ',' )    ## helper -lets you change the csv library in one place if needed/desired
+  ##   ## note:  do NOT symbolize keys - keep them as is!!!!!!
+  ##  ##   todo/fix: move "upstream" and remove symbolize keys too!!! - why? why not?
+  ##   CsvHash.parse( text, sep: sep )
+  ## end
+
+  def self.read( path, headers: nil, filters: nil, converters: nil, sep: nil )
+     txt = File.open( path, 'r:utf-8' ) {|f| f.read }   ## note: make sure to use (assume) utf-8
+     parse( txt, headers: headers,
+                 filters: filters,
+                 converters: converters,
+                 sep: sep )
+  end
+
+  def self.parse( txt, headers: nil, filters: nil, converters: nil, sep: nil )
+     new( txt ).parse( headers: headers,
+                        filters: filters,
+                        converters: converters,
+                        sep: sep )
+  end
+
+
+  def initialize( txt )
+    @txt = txt
+  end
+
+  def parse( headers: nil, filters: nil, converters: nil, sep: nil )
+
+    headers_mapping = {}
+
+    rows = parse_csv( @txt, sep: sep )
+
+    return []   if rows.empty?      ## no rows / empty?
+
+
+    ## fix/todo: use logger!!!!
+    ## pp csv
+
+    if headers   ## use user supplied headers if present
+      headers_mapping = headers_mapping.merge( headers )
+    else
+
+      ## note: returns an array of strings (header names)  - assume all rows have the same columns/fields!!!
+      headers = rows[0].keys
+      pp headers
+
+      # note: greece 2001-02 etc. use HT  -  check CVS reader  row['HomeTeam'] may not be nil but an empty string?
+      #   e.g. row['HomeTeam'] || row['HT'] will NOT work for now
+
+      if find_header( headers, ['Team 1']) && find_header( headers, ['Team 2'])
+         ## assume our own football.csv format, see github.com/footballcsv
+         headers_mapping[:team1]  = find_header( headers, ['Team 1'] )
+         headers_mapping[:team2]  = find_header( headers, ['Team 2'] )
+         headers_mapping[:date]   = find_header( headers, ['Date'] )
+         headers_mapping[:time]   = find_header( headers, ['Time'] )
+
+         ## check for all-in-one full time (ft) and half time (ht9 scores?
+         headers_mapping[:score]  = find_header( headers, ['FT'] )
+         headers_mapping[:scorei] = find_header( headers, ['HT'] )
+
+         headers_mapping[:round]  = find_header( headers, ['Round', 'Matchday'] )
+
+         ## optional headers - note: find_header returns nil if header NOT found
+         header_stage = find_header( headers, ['Stage'] )
+         headers_mapping[:stage]  =  header_stage   if header_stage
+
+         header_group = find_header( headers, ['Group'] )
+         headers_mapping[:group]  =  header_group   if header_group
+
+
+         header_et = find_header( headers, ['ET', 'AET'] )   ## (after) extra time
+         headers_mapping[:score_et] = header_et   if header_et
+
+         header_p  = find_header( headers, ['P', 'PEN'] )    ## penalties
+         headers_mapping[:score_p] = header_p   if header_p
+
+         header_notes = find_header( headers, ['Notes', 'Comments'] )
+         headers_mapping[:notes]  =  header_notes   if header_notes
+
+
+         header_league = find_header( headers, ['League'] )
+         headers_mapping[:league] = header_league   if header_league
+      else
+         ## else try footballdata.uk and others
+         headers_mapping[:team1]  = find_header( headers, ['HomeTeam', 'HT', 'Home'] )
+         headers_mapping[:team2]  = find_header( headers, ['AwayTeam', 'AT', 'Away'] )
+         headers_mapping[:date]   = find_header( headers, ['Date'] )
+         headers_mapping[:time]   = find_header( headers, ['Time'] )
+
+         ## note: FT = Full Time, HG = Home Goal, AG = Away Goal
+         headers_mapping[:score1] = find_header( headers, ['FTHG', 'HG'] )
+         headers_mapping[:score2] = find_header( headers, ['FTAG', 'AG'] )
+
+         ## check for half time scores ?
+         ##  note: HT = Half Time
+         headers_mapping[:score1i] = find_header( headers, ['HTHG'] )
+         headers_mapping[:score2i] = find_header( headers, ['HTAG'] )
+      end
+    end
+
+    pp headers_mapping
+
+    ### todo/fix: check headers - how?
+    ##  if present HomeTeam or HT required etc.
+    ##   issue error/warn is not present
+    ##
+    ## puts "*** !!! wrong (unknown) headers format; cannot continue; fix it; sorry"
+    ##    exit 1
+    ##
+
+    matches = []
+
+    rows.each_with_index do |row,i|
+
+      ## fix/todo: use logger!!!!
+      ## puts "[#{i}] " + row.inspect  if i < 2
+
+
+      ## todo/fix: move to its own (helper) method - filter or such!!!!
+       if filters    ## filter MUST match if present e.g. row['Season'] == '2017/2018'
+         skip = false
+         filters.each do |header, value|
+           if row[ header ] != value   ## e.g. row['Season']
+             skip = true
+             break
+           end
+         end
+         next if skip   ## if header values NOT matching
+       end
+
+
+      ## note:
+      ##   add converters after filters for now (why not before filters?)
+      if converters   ## any converters defined?
+        ## convert single proc shortcut to array with single converter
+        converters = [converters]    if converters.is_a?( Proc )
+
+        ## assumes array of procs
+        converters.each do |converter|
+          row = converter.call( row )
+        end
+      end
+
+
+
+      team1 = row[ headers_mapping[ :team1 ]]
+      team2 = row[ headers_mapping[ :team2 ]]
+
+
+      ## check if data present - if not skip (might be empty row)
+      ##  note:  (old classic) csv reader returns nil for empty fields
+      ##         new modern csv reader ALWAYS returns strings (and empty strings for data not available (n/a))
+      if (team1.nil? || team1.empty?) &&
+         (team2.nil? || team2.empty?)
+        puts "*** WARN: skipping empty? row[#{i}] - no teams found:"
+        pp row
+        next
+      end
+
+      ## remove possible match played counters e.g. (4) (11) etc.
+      team1 = team1.sub( /\(\d+\)/, '' ).strip
+      team2 = team2.sub( /\(\d+\)/, '' ).strip
+
+
+
+      col = row[ headers_mapping[ :time ]]
+
+      if col.nil?
+        time = nil
+      else
+        col = col.strip     # make sure not leading or trailing spaces left over
+
+        if col.empty?
+          col =~ /^-{1,}$/ ||      # e.g.  - or ---
+          col =~ /^\?{1,}$/        # e.g. ? or ???
+          ## note: allow missing / unknown date for match
+          time = nil
+        else
+          if col =~ /^\d{1,2}:\d{2}$/
+            time_fmt = '%H:%M'   # e.g. 17:00 or 3:00
+          elsif col =~ /^\d{1,2}.\d{2}$/
+            time_fmt = '%H.%M'   # e.g. 17:00 or 3:00
+          else
+            puts "*** !!! wrong (unknown) time format >>#{col}<<; cannot continue; fix it; sorry"
+            ## todo/fix: add to errors/warns list - why? why not?
+            exit 1
+          end
+
+          ## todo/check: use date object (keep string?) - why? why not?
+          ##  todo/fix: yes!! use date object!!!! do NOT use string
+          time = Time.strptime( col, time_fmt ).strftime( '%H:%M' )
+        end
+      end
+
+
+
+      col = row[ headers_mapping[ :date ]]
+      col = col.strip   # make sure not leading or trailing spaces left over
+
+      if col.empty? ||
+         col =~ /^-{1,}$/ ||      # e.g.  - or ---
+         col =~ /^\?{1,}$/        # e.g. ? or ???
+          ## note: allow missing / unknown date for match
+          date = nil
+      else
+        ## remove possible weekday or weeknumber  e.g. (Fri) (4) etc.
+        col = col.sub( /\(W?\d{1,2}\)/, '' )  ## e.g. (W11), (4), (21) etc.
+        col = col.sub( /\(\w+\)/, '' )  ## e.g. (Fri), (Fr) etc.
+        col = col.strip   # make sure not leading or trailing spaces left over
+
+        if col =~ /^\d{2}\/\d{2}\/\d{4}$/
+          date_fmt = '%d/%m/%Y'   # e.g. 17/08/2002
+        elsif col =~ /^\d{2}\/\d{2}\/\d{2}$/
+          date_fmt = '%d/%m/%y'   # e.g. 17/08/02
+        elsif col =~ /^\d{4}-\d{1,2}-\d{1,2}$/      ## "standard" / default date format
+          date_fmt = '%Y-%m-%d'   # e.g. 1995-08-04
+        elsif col =~ /^\d{1,2} \w{3} \d{4}$/
+          date_fmt = '%d %b %Y'   # e.g. 8 Jul 2017
+        elsif col =~ /^\w{3} \w{3} \d{1,2} \d{4}$/
+          date_fmt = '%a %b %d %Y'   # e.g. Sat Aug 7 1993
+        else
+          puts "*** !!! wrong (unknown) date format >>#{col}<<; cannot continue; fix it; sorry"
+          ## todo/fix: add to errors/warns list - why? why not?
+          exit 1
+        end
+
+        ## todo/check: use date object (keep string?) - why? why not?
+        ##  todo/fix: yes!! use date object!!!! do NOT use string
+        date = Date.strptime( col, date_fmt ).strftime( '%Y-%m-%d' )
+      end
+
+
+      ##
+      ## todo/fix:  round might not always be just a simple integer number!!!
+      ##             might be text such as Final | Leg 1 or such!!!!
+      round   = nil
+      ## check for (optional) round / matchday
+      if headers_mapping[ :round ]
+        col = row[ headers_mapping[ :round ]]
+        ## todo: issue warning if not ? or - (and just empty string) why? why not
+        ## (old attic) was: round = col.to_i  if col =~ /^\d{1,2}$/     # check format - e.g. ignore ? or - or such non-numbers for now
+
+        ## note: make round always a string for now!!!! e.g. "1", "2" too!!
+        round = if col.nil? || col.empty? || col == '-' || col == 'n/a'
+                 ## note: allow missing round for match / defaults to nil
+                 nil
+                else
+                  col
+                end
+      end
+
+
+      score1  = nil
+      score2  = nil
+      score1i = nil
+      score2i = nil
+
+      ## check for full time scores ?
+      if headers_mapping[ :score1 ] && headers_mapping[ :score2 ]
+        ft = [ row[ headers_mapping[ :score1 ]],
+               row[ headers_mapping[ :score2 ]] ]
+
+        ## todo/fix: issue warning if not ? or - (and just empty string) why? why not
+        score1 = ft[0].to_i  if ft[0] =~ /^\d{1,2}$/
+        score2 = ft[1].to_i  if ft[1] =~ /^\d{1,2}$/
+      end
+
+      ## check for half time scores ?
+      if headers_mapping[ :score1i ] && headers_mapping[ :score2i ]
+        ht = [ row[ headers_mapping[ :score1i ]],
+               row[ headers_mapping[ :score2i ]] ]
+
+        ## todo/fix: issue warning if not ? or - (and just empty string) why? why not
+        score1i = ht[0].to_i  if ht[0] =~ /^\d{1,2}$/
+        score2i = ht[1].to_i  if ht[1] =~ /^\d{1,2}$/
+      end
+
+
+      ## check for all-in-one full time scores?
+      if headers_mapping[ :score ]
+        col = row[ headers_mapping[ :score ]]
+        score = parse_score( col )
+        if score
+          score1 = score[0]
+          score2 = score[1]
+        else
+          puts "!! ERROR - invalid score (ft) format >#{col}<:"
+          pp row
+          exit 1
+        end
+      end
+
+      if headers_mapping[ :scorei ]
+        col = row[ headers_mapping[ :scorei ]]
+        score = parse_score( col )
+        if score
+          score1i = score[0]
+          score2i = score[1]
+        else
+          puts "!! ERROR - invalid score (ht) format >#{col}<:"
+          pp row
+          exit 1
+        end
+      end
+
+      ####
+      ## try optional score - extra time (et) and penalities (p/pen)
+      score1et  = nil
+      score2et  = nil
+      score1p   = nil
+      score2p   = nil
+
+      if headers_mapping[ :score_et ]
+        col = row[ headers_mapping[ :score_et ]]
+        score = parse_score( col )
+        if score
+          score1et = score[0]
+          score2et = score[1]
+        else
+          puts "!! ERROR - invalid score (et) format >#{col}<:"
+          pp row
+          exit 1
+        end
+      end
+
+      if headers_mapping[ :score_p ]
+        col = row[ headers_mapping[ :score_p ]]
+        score = parse_score( col )
+        if score
+          score1p = score[0]
+          score2p = score[1]
+        else
+          puts "!! ERROR - invalid score (p) format >#{col}<:"
+          pp row
+          exit 1
+        end
+      end
+
+
+      ## try some optional headings / columns
+      stage = nil
+      if headers_mapping[ :stage ]
+        col = row[ headers_mapping[ :stage ]]
+        ## todo/fix: check can col be nil e.g. col.nil? possible?
+        stage =  if col.nil? || col.empty? || col == '-' || col == 'n/a'
+                    ## note: allow missing stage for match / defaults to "regular"
+                    nil
+                 elsif col == '?'
+                     ## note: default explicit unknown to unknown for now AND not regular - why? why not?
+                    '?'   ## todo/check: use unkown and NOT ?  - why? why not?
+                 else
+                    col
+                 end
+      end
+
+      group = nil
+      if headers_mapping[ :group ]
+        col = row[ headers_mapping[ :group ]]
+        ## todo/fix: check can col be nil e.g. col.nil? possible?
+        group =  if col.nil? || col.empty? || col == '-' || col == 'n/a'
+                    ## note: allow missing stage for match / defaults to "regular"
+                    nil
+                 else
+                    col
+                 end
+      end
+
+      status = nil    ## e.g. AWARDED, CANCELLED, POSTPONED, etc.
+      if headers_mapping[ :notes ]
+        col = row[ headers_mapping[ :notes ]]
+        ## check for optional (match) status in notes / comments
+        status = if col.nil? || col.empty? || col == '-' || col == 'n/a'
+                   nil
+                 else
+                   StatusParser.parse( col )  # note: returns nil if no (match) status found
+                 end
+      end
+
+
+      league = nil
+      league = row[ headers_mapping[ :league ]]   if headers_mapping[ :league ]
+
+
+      ## puts 'match attributes:'
+      attributes = {
+        date:     date,
+        time:     time,
+        team1:    team1,    team2:    team2,
+        score1:   score1,   score2:   score2,
+        score1i:  score1i,  score2i:  score2i,
+        score1et: score1et, score2et: score2et,
+        score1p:  score1p,  score2p:  score2p,
+        round:    round,
+        stage:    stage,
+        group:    group,
+        status:   status,
+        league:   league
+      }
+      ## pp attributes
+
+      match = Sports::Match.new( **attributes )
+      matches << match
+    end
+
+    ## pp matches
+    matches
+  end
+
+
+  private
+
+  def find_header( headers, candidates )
+     ## todo/fix: use find_first from enumare of similar ?! - why? more idiomatic code?
+
+    candidates.each do |candidate|
+       return candidate   if headers.include?( candidate ) ## bingo!!!
+    end
+    nil  ## no matching header  found!!!
+  end
+
+########
+# more helpers
+#
+
+def parse_score( str )
+  if str.nil?    ## todo/check: remove nil case - possible? - why? why not?
+    [nil,nil]
+  else
+    ## remove (optional single) note/footnote/endnote markers
+    ##  e.g. (*) or (a), (b),
+    ##    or [*], [A], [1], etc.
+    ##  - allow (1) or maybe (*1) in the future - why? why not?
+    str = str.sub( /\( [a-z*] \)
+                        |
+                    \[ [1-9a-z*] \]
+                   /ix, '' ).strip
+
+    if str.empty? || str == '?' || str == '-' || str == 'n/a'
+      [nil,nil]
+    ### todo/check: use regex with named capture groups here - why? why not?
+    elsif str =~ /^\d{1,2}[:-]\d{1,2}$/   ## sanity check scores format
+      score  = str.split( /[:-]/ )
+      [score[0].to_i, score[1].to_i]
+    else
+      nil  ## note: returns nil if invalid / unparseable format!!!
+    end
+  end
+end # method parse_score
+
+
+
+  end # class CsvMatchParser
+end # module Sports
+

data/lib/sportdb/csv/match_status_parser.rb

@@ -0,0 +1,63 @@
+#####################
+# helpers for parsing & finding match status e.g.
+#    - cancelled / canceled
+#    - awarded
+#    - abandoned
+#    - replay
+#    etc.
+
+
+module SportDb
+
+
+  ### todo/fix: move Status inside Match struct - why? why not?
+
+  class Status
+# note: use a class as an "enum"-like namespace for now - why? why not?
+#   move class into Match e.g. Match::Status  - why? why not?
+    CANCELLED = 'CANCELLED'   # canceled (US spelling), cancelled (UK spelling) - what to use?
+    AWARDED   = 'AWARDED'
+    POSTPONED = 'POSTPONED'
+    ABANDONED = 'ABANDONED'
+    REPLAY    = 'REPLAY'
+  end # class Status
+
+
+  
+  #
+  #  todo/fix - move self.parse to class Status e.g.
+  #    use Status.parse( str ) NOT StatusParser...
+
+  class StatusParser
+
+    def self.parse( str )
+      ## note: returns nil if no match found
+      ## note: english usage - cancelled (in UK), canceled (in US)
+      if str =~ /^(cancelled|
+                   canceled|
+                   can\.
+                  )/xi
+        Status::CANCELLED
+      elsif str =~ /^(awarded|
+                       awd\.
+                      )/xi
+        Status::AWARDED
+      elsif str =~ /^(postponed
+                      )/xi
+        Status::POSTPONED
+      elsif str =~ /^(abandoned|
+                       abd\.
+                      )/xi
+        Status::ABANDONED
+      elsif str =~ /^(replay
+                      )/xi
+        Status::REPLAY
+      else
+        # no match
+        nil
+      end
+    end
+
+  end # class StatusParser
+end # module SportDb
+

data/lib/sportdb/structs/league.rb

@@ -5,6 +5,9 @@ module Sports
 class LeaguePeriod
   attr_reader   :key, :name, :qname, :slug,
                 :prev_name,  :start_season, :end_season
+
+  attr_accessor :alt_names
+               
   def initialize( key:, name:, qname:, slug:,
                         prev_name: nil,
                         start_season: nil, end_season: nil )
@@ -15,10 +18,120 @@ class LeaguePeriod
     @prev_name = prev_name
     @start_season = start_season
     @end_season  = end_season
+
+    @alt_names = []
+  end
+
+
+####
+## todo/fix - share code for names and codes with League and LeaguePeriod!!!
+##         for now cut-n-paste copy
+
+ #############################
+  ### virtual helpers
+  ##    1) codes  (returns uniq array of all codes in lowercase
+  ##               incl. key, code and alt_codes in alt_names)
+  ##    2) names  (returns uniq array of all names - with language tags stripped)
+  ##
+
+## note: split names into names AND codes
+##      1)  key plus all lower case names are codes
+##      2)    all upper case names are names AND codes
+##      3)    all other names are names
+
+## only allow asci a to z (why? why not?)
+##  excludes Ö1 or such (what else?)
+##   allow space and dot - why? why not?
+##     e.g. HNL 1
+##          NB I or NB II etc.
+IS_CODE_N_NAME_RE = %r{^
+                           [\p{Lu}0-9. ]+
+                       $}x
+## add space (or /) - why? why not?
+IS_CODE_RE           = %r{^
+                            [\p{Ll}0-9.]+
+                        $}x
+
+
+  def codes
+       ## change/rename to more_codes - why? why?
+       ##    get reference (tier/canonicial) codes via periods!!!!
+
+       ## note - "auto-magically" downcase code (and code'n'name matches)!!
+      ##  note - do NOT include key as code for now!!!
+      ##
+      ## todo/check - auto-remove space from code - why? why not?
+      ##         e.g. NB I, NB II, HNL 1 => NBI, NBII, HBNL1, etc -
+      codes = []
+      alt_names.each do |name|
+        if IS_CODE_N_NAME_RE.match?( name )
+          codes << name.downcase
+        elsif IS_CODE_RE.match?( name )
+          codes << name
+        else ## assume name
+          ## do nothing - skip/ignore
+        end
+      end
+      codes.uniq
+  end
+
+
+  include SportDb::NameHelper   # pulls-in strip_lang
+
+  def names
+    names = [@name]
+    alt_names.each do |name|
+       if IS_CODE_N_NAME_RE.match?( name )
+         names << name
+       elsif IS_CODE_RE.match?( name )
+         ## do nothing - skip/ignore
+       else ## assume name
+         names <<  strip_lang( name )
+       end
+   end
+
+##  report duplicate names - why? why not
+     ## check for duplicates - simple check for now - fix/improve
+     ## todo/fix: (auto)remove duplicates - why? why not?
+     count      = names.size
+     count_uniq = names.uniq.size
+     if count != count_uniq
+       puts "** !!! ERROR !!! - #{count-count_uniq} duplicate name(s):"
+       pp names
+       pp self
+       exit 1
+     end
+
+   names.uniq
+  end
+
+
+  def pretty_print( printer )
+    buf = String.new
+    buf << "<LeaguePeriod"
+    buf << " #{@key}"
+    buf << " (#{@start_season}-#{@end_season})"  if @start_season || @end_season
+    buf << " -"
+    buf << " #{@name}"
+    if @name != @qname
+       buf << " | #{@qname}"
+    else
+       buf << "*"
+    end
+    buf << ">"
+
+    printer.text( buf )
   end
 end # class LeaguePeriod
 
 
+################
+# todo: add a type field -
+#       add a tier field - why? why not?
+#   e.g.  league/cup  (or national_league, national_cup, intl_cup, etc.?)
+#   e.g.  1st-tier, 2nd-tier, etc.
+
+
 class League
   attr_reader   :key, :name, :country, :intl
   attr_accessor :alt_names
@@ -48,6 +161,86 @@ class League
   alias_method   :club?,          :clubs?
   alias_method   :national_team?, :national_teams?
 
+
+  #############################
+  ### virtual helpers
+  ##    1) codes  (returns uniq array of all codes in lowercase
+  ##               incl. key, code and alt_codes in alt_names)
+  ##    2) names  (returns uniq array of all names - with language tags stripped)
+  ##
+
+## note: split names into names AND codes
+##      1)  key plus all lower case names are codes
+##      2)    all upper case names are names AND codes
+##      3)    all other names are names
+
+## only allow asci a to z (why? why not?)
+##  excludes Ö1 or such (what else?)
+##   allow space and dot - why? why not?
+##     e.g. HNL 1
+##          NB I or NB II etc.
+IS_CODE_N_NAME_RE = %r{^
+                           [\p{Lu}0-9. ]+
+                       $}x
+## add space (or /) - why? why not?
+IS_CODE_RE           = %r{^
+                            [\p{Ll}0-9.]+
+                        $}x
+
+
+  def codes
+       ## change/rename to more_codes - why? why?
+       ##    get reference (tier/canonicial) codes via periods!!!!
+
+       ## note - "auto-magically" downcase code (and code'n'name matches)!!
+      ##  note - do NOT include key as code for now!!!
+      ##
+      ## todo/check - auto-remove space from code - why? why not?
+      ##         e.g. NB I, NB II, HNL 1 => NBI, NBII, HBNL1, etc -
+      codes = []
+      alt_names.each do |name|
+        if IS_CODE_N_NAME_RE.match?( name )
+          codes << name.downcase
+        elsif IS_CODE_RE.match?( name )
+          codes << name
+        else ## assume name
+          ## do nothing - skip/ignore
+        end
+      end
+      codes.uniq
+  end
+
+
+  include SportDb::NameHelper   # pulls-in strip_lang
+
+  def names
+    names = [@name]
+    alt_names.each do |name|
+       if IS_CODE_N_NAME_RE.match?( name )
+         names << name
+       elsif IS_CODE_RE.match?( name )
+         ## do nothing - skip/ignore
+       else ## assume name
+         names <<  strip_lang( name )
+       end
+   end
+
+##  report duplicate names - why? why not
+     ## check for duplicates - simple check for now - fix/improve
+     ## todo/fix: (auto)remove duplicates - why? why not?
+     count      = names.size
+     count_uniq = names.uniq.size
+     if count != count_uniq
+       puts "** !!! ERROR !!! - #{count-count_uniq} duplicate name(s):"
+       pp names
+       pp self
+       exit 1
+     end
+
+   names.uniq
+  end
+
+
 =begin
  @alt_names=[],
   @clubs=true,
@@ -66,7 +259,7 @@ class League
              else
                  " NATIONAL TEAMS"
              end
-    buf << ": #{@key} - #{@name}"
+    buf << ": #{@name}"
 
     if @alt_names && !@alt_names.empty?
       buf << "|"
@@ -83,10 +276,7 @@ class League
 
     printer.text( buf )
   end
-
-
-
-
 end   # class League
 
+
 end   # module Sports

data/lib/sportdb/structs/match.rb

@@ -23,7 +23,8 @@ class Match
               :country1, :country2,    ## special case for champions league etc. - uses FIFA country code
               :comments,
               :league,      ## (optinal) added as text for now (use struct?)
-              :ground       ## (optional) add as text line for now (incl. city, timezone etc.)
+              :ground,       ## (optional) add as text line for now (incl. city, timezone etc.)
+              :timezone      ## (optional) as a string
 
   attr_accessor :goals  ## todo/fix: make goals like all other attribs!!
 
@@ -66,6 +67,7 @@ class Match
 
     @league   = kwargs[:league]   if kwargs.has_key?( :league )
     @ground   = kwargs[:ground]   if kwargs.has_key?( :ground )
+    @timezone = kwargs[:timezone] if kwargs.has_key?( :timezone )
 
 
     if kwargs.has_key?( :score )   ## check all-in-one score struct for convenience!!!
@@ -181,12 +183,14 @@ class Match
 
 
 def as_json
-  ##
+  #####
+  ##  note - use string keys (NOT symbol for data keys)
+  ##            for easier json compatibility
   data = {}
 
   ## check round
   if @round
-    data[:round ] = if round.is_a?( Integer )
+    data['round'] = if round.is_a?( Integer )
                       "Matchday #{@round}"
                     else ## assume string
                       @round
@@ -194,41 +198,58 @@ def as_json
   end
 
 
-  data[:num] = @num    if @num
+  data['num'] = @num    if @num
   if @date
     ## assume 2020-09-19 date format!!
-    data[:date]  = @date.is_a?( String ) ? @date : @date.strftime('%Y-%m-%d')
+    data['date']  = @date.is_a?( String ) ? @date : @date.strftime('%Y-%m-%d')
 
-    data[:time] = @time  if @time
+    data['time'] = @time  if @time
   end
 
-  data[:team1] =  @team1.is_a?( String ) ? @team1 : @team1.name
-  data[:team2] =  @team2.is_a?( String ) ? @team2 : @team2.name
-
-  data[:score] = {}
-
-  data[:score][:ht] = [@score1i,   @score2i]     if @score1i && @score2i
-  data[:score][:ft] = [@score1,    @score2]      if @score1 && @score2
-  data[:score][:et] = [@score1et,  @score2et]    if @score1et && @score2et
-  data[:score][:p]  = [@score1p,   @score2p]     if @score1p && @score2p
-
-  data[:status] = @status  if @status
-
-  data[:group]  = @group   if @group
-  data[:stage]  = @stage   if @stage
-
-=begin
-      "round": "Spieltag 1",
-      "date": "2020-09-19",
-      "team1": "Eintracht Frankfurt",
-      "team2": "Arminia Bielefeld",
-      "score": {
-        "ft": [
-          1,
-          1
-        ]
-      }
-=end
+  data['team1'] =  @team1.is_a?( String ) ? @team1 : @team1.name
+  data['team2'] =  @team2.is_a?( String ) ? @team2 : @team2.name
+
+  data['score'] = {}
+
+  data['score']['ht'] = [@score1i,   @score2i]     if @score1i && @score2i
+  data['score']['ft'] = [@score1,    @score2]      if @score1 && @score2
+  data['score']['et'] = [@score1et,  @score2et]    if @score1et && @score2et
+  data['score']['p']  = [@score1p,   @score2p]     if @score1p && @score2p
+
+  ### check for goals
+  if @goals && @goals.size > 0
+    data['goals1'] = []
+    data['goals2'] = []
+
+    @goals.each do |goal|
+          node = {}
+          node['name']    = goal.player
+          node['minute']  = goal.minute
+          node['offset']  = goal.offset  if goal.offset
+          node['owngoal'] = true         if goal.owngoal
+          node['penalty'] = true         if goal.penalty
+          
+          if goal.team == 1
+            data['goals1']  << node   
+          else  ## assume 2
+            data['goals2']  << node
+          end
+     end  # each goal
+  end
+
+
+  data['status'] = @status  if @status
+
+  data['group']  = @group   if @group
+  data['stage']  = @stage   if @stage
+
+  if @ground
+       ## note: might be array of string e.g. ['Wembley', 'London']
+       data['ground'] = {}
+       data['ground']['name']      = @ground
+       data['ground']['timezone']  = @timezone   if @timezone
+  end
+  
   data
 end
 

data/lib/sportdb/structs/round.rb

@@ -21,13 +21,14 @@ module Sports
       def pretty_print( printer )
         ## todo/check - how to display/format key - use () or not - why? why not?
         buf = String.new
-        buf << "<Round: "
+        buf << "<Round"
+        buf << " AUTO"    if @auto
+        buf << ": "
         buf << "(#{@num}) "  if @num
         buf << "#{@name}, "
         buf << "#{@start_date}"
         buf << " - #{@end_date}"  if @start_date != @end_date
         buf << "  (knockout)" if @knockout
-        buf << "  (auto)"     if @auto
         buf << ">"
 
         printer.text( buf )

data/lib/sportdb/structs/team.rb

@@ -64,7 +64,7 @@ class Team   # shared base for clubs AND natinal_teams
 
   def initialize( **kwargs )
     @alt_names      = []
- 
+
     update( **kwargs )  unless kwargs.empty?
   end
 
@@ -89,14 +89,14 @@ class NationalTeam < Team
     self   ## note - MUST return self for chaining
   end
 
-  def pretty_print( printer ) 
+  def pretty_print( printer )
     buf = String.new
     buf << "<NationalTeam: #{@name}"
     ## use code from country or from team ???
-    buf << " (#{@code})"  
+    buf << " (#{@code})"
     buf << ">"
 
-    printer.text( buf ) 
+    printer.text( buf )
   end
 end  # class NationalTeam
 
@@ -121,8 +121,9 @@ class Club < Team
   def geos()      @a == nil ?  @geos     : @a.geos;     end
 
 
-  def initialize( **kwargs )
-    super
+  def initialize( auto: false, **kwargs )
+    @auto = auto
+    super( **kwargs )   ## todo/check - use super only or super() - must it always come first?
   end
 
   def update( **kwargs )
@@ -135,13 +136,15 @@ class Club < Team
   end
 
 
-  def pretty_print( printer ) 
+  def pretty_print( printer )
     buf = String.new
-    buf << "<Club: #{@name}"
+    buf << "<Club"
+    buf << " AUTO"   if @auto
+    buf << ": #{@name}"
     buf << " (#{@country.code})"    if @country
     buf << ">"
 
-    printer.text( buf ) 
+    printer.text( buf )
   end
 end # class Club
 

data/lib/sportdb/structs/version.rb

@@ -3,8 +3,8 @@ module SportDb
   module Module
     module Structs
   MAJOR = 0    ## todo: namespace inside version or something - why? why not??
-  MINOR = 4
-  PATCH = 2
+  MINOR = 5
+  PATCH = 1
   VERSION = [MAJOR,MINOR,PATCH].join('.')
 
   def self.version

data/lib/sportdb/structs.rb

@@ -3,6 +3,8 @@ require 'alphabets'       # unaccent, downcase_i18n, variants, ...
 require 'season/formats'  # Season.parse, ...
 require 'score/formats'
 
+require 'cocos'    # pull-in for read_csv & more
+
 
 ###
 # our own code
@@ -102,6 +104,38 @@ end     # module SportDb
 
 
 
+###
+#  csv (tabular dataset) support / machinery
+require_relative 'csv/match_status_parser'
+require_relative 'csv/goal'
+require_relative 'csv/goal_parser_csv'
+require_relative 'csv/match_parser_csv'
+
+
+### add convenience shortcut helpers
+module Sports
+  class Match
+    def self.read_csv( path, headers: nil, filters: nil, converters: nil, sep: nil )
+       SportDb::CsvMatchParser.read( path,
+                                       headers:    headers,
+                                       filters:    filters,
+                                       converters: converters,
+                                       sep:        sep )
+    end
+
+    def self.parse_csv( txt, headers: nil, filters: nil, converters: nil, sep: nil )
+       SportDb::CsvMatchParser.parse( txt,
+                                        headers:    headers,
+                                        filters:    filters,
+                                        converters: converters,
+                                        sep:        sep )
+    end
+  end # class Match
+end # module Sports
+
+
+
+
 #####
 # note: add Sport and Football convenience alias - why? why not?
 Sport    = Sports

metadata

@@ -1,15 +1,29 @@
 --- !ruby/object:Gem::Specification
 name: sportdb-structs
 version: !ruby/object:Gem::Version
-  version: 0.4.2
+  version: 0.5.1
 platform: ruby
 authors:
 - Gerald Bauer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2024-10-17 00:00:00.000000000 Z
+date: 2025-01-19 00:00:00.000000000 Z
 dependencies:
+- !ruby/object:Gem::Dependency
+  name: cocos
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - ">="
+      - !ruby/object:Gem::Version
+        version: 0.4.0
 - !ruby/object:Gem::Dependency
   name: alphabets
   requirement: !ruby/object:Gem::Requirement
@@ -78,14 +92,14 @@ dependencies:
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.2'
   type: :development
   prerelease: false
   version_requirements: !ruby/object:Gem::Requirement
     requirements:
     - - "~>"
       - !ruby/object:Gem::Version
-        version: '4.1'
+        version: '4.2'
 description: sportdb-structs - sport data structures for matches, scores, leagues,
   seasons, rounds, groups, teams, clubs and more
 email: gerald.bauer@gmail.com
@@ -100,6 +114,10 @@ files:
 - Manifest.txt
 - README.md
 - Rakefile
+- lib/sportdb/csv/goal.rb
+- lib/sportdb/csv/goal_parser_csv.rb
+- lib/sportdb/csv/match_parser_csv.rb
+- lib/sportdb/csv/match_status_parser.rb
 - lib/sportdb/structs.rb
 - lib/sportdb/structs/country.rb
 - lib/sportdb/structs/event_info.rb
@@ -136,7 +154,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.4.10
+rubygems_version: 3.5.22
 signing_key:
 specification_version: 4
 summary: sportdb-structs - sport data structures for matches, scores, leagues, seasons,