season-formats 0.0.1

checksums.yaml

@@ -0,0 +1,7 @@
+---
+SHA1:
+  metadata.gz: 3edf7f8a24831832e08bcabae591f569f7ef9891
+  data.tar.gz: 020f1325519b1406904320bb3027cc0ec9dccc98
+SHA512:
+  metadata.gz: 3a184826449d5adf254f059ad1b3b2a103356cf2c69676976ae349690407da0a53f01a0ed81ebfd8a490c38ffae32951e56005cf50484c2e08cec723233d7216
+  data.tar.gz: 6f2d7c7822729d1fb2eba10804b5a7474dbdea1ee27a83c9b64df29b3ecd228811a655938f8bf307584645e03920a09a855fb4e0d44ccb6f03ebb9138ea1754b

data/CHANGELOG.md

@@ -0,0 +1,3 @@
+### 0.0.1 / 2020-11-22
+
+* Everything is new. First release.

data/Manifest.txt

@@ -0,0 +1,11 @@
+CHANGELOG.md
+Manifest.txt
+README.md
+Rakefile
+lib/season-formats.rb
+lib/season-formats/season.rb
+lib/season-formats/version.rb
+lib/season.rb
+lib/season/formats.rb
+test/helper.rb
+test/test_season.rb

data/README.md

@@ -0,0 +1,188 @@
+# season-formats - read / parse and print seasons (using an academic or calendar year)
+
+
+* 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/season-formats](https://rubygems.org/gems/season-formats)
+* rdoc  :: [rubydoc.info/gems/season-formats](http://rubydoc.info/gems/season-formats)
+* forum :: [opensport](http://groups.google.com/group/opensport)
+
+
+
+## Usage
+
+
+The idea is to follow the `Date` class and make `Season`
+into a top-level free-standing class. Let's say you have
+the season (using an academic year):
+
+```
+2020/21     # or
+2020/1      # or
+2020/2021   # or
+2020-21
+...
+```
+
+
+Using
+
+``` ruby
+require "season/formats"
+
+season = Season.parse( "2020/21" )    # or
+season = Season.parse( "2020/1" )     # or
+season = Season.parse( "2020/2021" )  # or
+season = Season.parse( "2020-21" )    # or
+
+season.start_year       #=> 2020
+season.end_year         #=> 2021
+
+season.academic?        # or
+season.academic_year?   #=> true
+
+season.to_s             #=> "2020/21"
+season.to_path          #=> "2020-21"
+```
+
+you can parse the season into its components, that is, the
+start year (`start_year`) and end year (`end year`).
+
+Using the `academic?` /  `academic_year?`
+or `calendar?` / `calendar_year?` / `year?`  helpers
+lets you check if the season uses an academic year (e.g. 2020/2021)
+or a calendar year (e.g. 2020).
+
+
+``` ruby
+season = Season.parse( "2020" )
+
+season.start_year       #=> 2020
+season.end_year         #=> 2020
+
+season.calendar?        # or
+season.calendar_year?   # or
+season.year?            #=> true
+
+season.to_s             #=> "2020"
+season.to_path          #=> "2020"
+```
+
+Using `to_s` gets you back a canonical / normalized name
+(e.g. 2020/21 or 2020). For use in file names / paths
+use `to_path` (2020-21 or 2020).
+
+
+
+
+Like `Date` you can initialize `Season` with a "to-the-metal"
+year or years as integer numbers e.g.:
+
+``` ruby
+season = Season.new( 2020, 2021 )
+
+season.start_year       #=> 2020
+season.end_year         #=> 2021
+
+season.academic?        # or
+season.academic_year?   #=> true
+
+season.to_s             #=> "2020/21"
+season.to_path          #=> "2020-21"
+
+# -or-
+
+season = Season.new( 2020 )
+
+season.start_year       #=> 2020
+season.end_year         #=> 2020
+
+season.calendar?        # or
+season.calendar_year?   # or
+season.year?            #=> true
+
+season.to_s             #=> "2020"
+season.to_path          #=> "2020"
+```
+
+
+If you want to support / allow both string and integers in your
+arguments, use the `Kernel#Season` method, that is,
+a shortcut for `Season.convert`. Example:
+
+``` ruby
+season = Season( "2020/21" )    # or
+season = Season( "2020/1" )     # or
+season = Season( "2020/2021" )  # or
+season = Season( "2020-21" )    # or
+season = Season( 2020, 2021 )   # or
+season = Season( 202021 )       # or
+season = Season( 20202021 )
+
+# -or-
+season = Season( "2020" )    # or
+season = Season( 2020 )
+```
+
+
+
+### Bonus: Using Ranges with Seasons
+
+Yes, you can use the Season class for ruby's built-in ranges.
+Example:
+
+``` ruby
+seasons = Season( '2010/11' )..Season( '2019/20' )
+seasons.to_a
+# => [2010/11, 2011/12, 2012/13, 2013/14, 2014/15,
+#     2015/16, 2016/17, 2017/18, 2018/19, 2019/20]
+
+seasons = Season( '2010' )..Season( '2019' )
+seasons.to_a
+# => [2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019]
+```
+
+The "magic" is possible thanks to `Season#succ / next`
+and `Season#prev`.
+
+``` ruby
+Season( '2019/20' ).succ        # or
+Season( '2019/20' ).next        #=>  2020/21
+
+Season( '2019/20' ).succ.succ   # or
+Season( '2019/20' ).next.next   #=>  2021/22
+
+# -or-
+
+Season( '2019' ).succ     #=>  2020
+Season( '2019' ).next     #=>  2020
+```
+
+
+That's all for now.
+
+
+
+## Installation
+
+Use
+
+    gem install season-formats
+
+or add the gem to your Gemfile
+
+    gem 'season-formats'
+
+
+
+## License
+
+The `season-formats` scripts are dedicated to the public domain.
+Use it as you please with no restrictions whatsoever.
+
+
+## Questions? Comments?
+
+Send them along to the
+[Open Sports & Friends Forum/Mailing List](http://groups.google.com/group/opensport).
+Thanks!

data/Rakefile

@@ -0,0 +1,27 @@
+require 'hoe'
+require './lib/season-formats/version.rb'
+
+Hoe.spec 'season-formats' do
+
+  self.version = SeasonFormats::VERSION
+
+  self.summary = "season-formats - read / parse and print seasons (using an academic or calendar year"
+  self.description = summary
+
+  self.urls = { home: 'https://github.com/sportdb/sport.db' }
+
+  self.author = 'Gerald Bauer'
+  self.email = 'opensport@googlegroups.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 = []
+
+  self.spec_extras = {
+    required_ruby_version: '>= 2.2.2'
+  }
+end

data/lib/season-formats.rb

@@ -0,0 +1,15 @@
+require 'pp'
+require 'date'
+require 'time'
+
+
+
+## our own code
+require 'season-formats/version'   ## let version go first
+require 'season-formats/season'
+
+
+
+
+
+puts SeasonFormats.banner   # say hello

data/lib/season-formats/season.rb

@@ -0,0 +1,209 @@
+
+### note: make Season like Date a "top-level" / "generic" class
+
+
+class Season
+  ##
+  ##  todo: add (optional) start_date and end_date - why? why not?
+
+  ## todo/todo/todo/check/check/check !!!
+  ## todo: add a kernel Seaons e.g. Season('2011/12')
+  ##    forward to Season.convert( *args )  - why? why not?
+
+  ## todo: add unicode - too - why? why not? see wikipedia pages, for example
+
+  YYYY_YYYY_RE  = %r{^      ## e.g. 2011-2012 or 2011/2012
+                    (\d{4})
+                      [/-]
+                    (\d{4})
+                   $
+                  }x
+  YYYY_YY_RE  = %r{^       ## e.g. 2011-12 or 2011/12
+                    (\d{4})
+                      [/-]
+                    (\d{2})
+                   $
+                  }x
+  YYYY_Y_RE  = %r{^       ## e.g. 2011-2 or 2011/2
+                  (\d{4})
+                    [/-]
+                  (\d{1})
+                 $
+                }x
+  YYYY_RE     = %r{^       ## e.g. 2011
+                    (\d{4})
+                   $
+                  }x
+
+
+  def self.parse( str )
+    new( *_parse( str ))
+  end
+
+  def self._parse( str )   ## "internal" parse helper
+    if str =~ YYYY_YYYY_RE    ## e.g. 2011/2012
+      [$1.to_i, $2.to_i]
+    elsif str =~ YYYY_YY_RE   ## e.g. 2011/12
+      fst = $1.to_i
+      snd = $2.to_i
+      snd_exp = '%02d' % [(fst+1) % 100]    ## double check: e.g 00 == 00, 01==01 etc.
+      raise ArgumentError, "[Season.parse] invalid year in season >>#{str}<<; expected #{snd_exp} but got #{$2}"   if snd_exp != $2
+      [fst, fst+1]
+    elsif str =~ YYYY_Y_RE    ## e.g. 2011/2
+      fst = $1.to_i
+      snd = $2.to_i
+      snd_exp = '%d' % [(fst+1) % 10]      ## double check: e.g 0 == 0, 1==1 etc.
+      raise ArgumentError, "[Season.parse] invalid year in season >>#{str}<<; expected #{snd_exp} but got #{$2}"   if snd_exp != $2
+      [fst, fst+1]
+    elsif str =~ YYYY_RE      ## e.g. 2011
+      [$1.to_i]
+    else
+      raise ArgumentError, "[Season.parse] unkown season format >>#{str}<<; sorry cannot parse"
+    end
+  end
+
+
+  def self.convert( *args )  ## note: used by Kernel method Season()
+    if args.size == 1 && args[0].is_a?( Season )
+      args[0]  # pass through / along as is 1:1
+    elsif args.size == 1 && args[0].is_a?( String )
+      parse( args[0] )
+    elsif args.size == 1 && args[0].is_a?( Integer ) && args[0] > 9999
+      ## note: allow convenience "hack" such as:
+      # 202021   or 2020_21   => '2020/21' or
+      # 2020_1   or 2020_1    => '2020/21' or
+      # 20202021 or 2020_2021 => '2020/21'
+      str = args[0].to_s
+      parse( "#{str[0..3]}/#{str[4..-1]}" )
+    else ## assume all integer args e.g.  2020 or 2020, 2021 and such
+      new( *args ) ## try conversion with new
+    end
+  end
+
+
+  attr_reader :start_year,
+              :end_year
+
+  def initialize( *args )   ## change args to years - why? why not?
+    if args.size == 1 && args[0].is_a?( Integer )
+      @start_year = args[0]
+      @end_year   = args[0]
+    elsif args.size == 2 && args[0].is_a?( Integer ) &&
+                            args[1].is_a?( Integer )
+      @start_year = args[0]
+      @end_year   = args[1]
+      end_year_exp = @start_year+1
+      raise ArgumentError, "[Season] invalid year in season >>#{to_s}<<; expected #{end_year_exp} but got #{@end_year}"   if end_year_exp != @end_year
+    else
+      pp args
+      raise ArgumentError, "[Season] expected season start year (integer) with opt. end year"
+    end
+  end
+
+
+
+  ## single-year season e.g. 2011 if start_year is end_year - todo - find a better name?
+  def calendar_year?()  @start_year == @end_year; end
+  alias_method :calendar?, :calendar_year?
+  alias_method :year?,     :calendar_year?
+
+  def academic_year?() !calenar_year?; end
+  alias_method :academic?, :academic_year?
+
+
+
+  def prev
+    if year?
+      Season.new( @start_year-1 )
+    else
+      Season.new( @start_year-1, @end_year-1 )
+    end
+  end
+
+  def next
+    if year?
+      Season.new( @start_year+1 )
+    else
+      Season.new( @start_year+1, @end_year+1 )
+    end
+  end
+  alias_method :succ, :next   ## add support for ranges
+
+
+  include Comparable
+  def <=>(other)
+    ## todo/fix/fix:  check if other is_a?( Season )!!!
+    ##  what to return if other type/class ??
+    ## note: check special edge case - year season and other e.g.
+    ##    2010 <=> 2010/2011
+
+    res = @start_year <=> other.start_year
+    res = @end_year   <=> other.end_year     if res == 0
+    res
+  end
+
+
+  def to_formatted_s( format=:default, sep: '/' )
+    if year?
+      '%d' % @start_year
+    else
+      case format
+      when :default, :short, :s   ## e.g. 1999/00 or 2019/20
+        "%d#{sep}%02d" % [@start_year, @end_year % 100]
+      when :long, :l              ## e.g. 1999/2000 or 2019/2020
+        "%d#{sep}%d" % [@start_year, @end_year]
+      else
+        raise ArgumentError, "[Season.to_s] unsupported format >#{format}<"
+      end
+    end
+  end
+  alias_method :to_s, :to_formatted_s
+
+  def key()  to_s( :short ); end
+  alias_method :to_key,  :key
+  alias_method :name,    :key
+  alias_method :title,   :key
+
+  alias_method :inspect, :key  ## note: add inspect debug support change debug output to string!!
+
+
+
+  def to_path( format=:default )
+    case format
+    when :default, :short, :s    ## e.g. 1999-00 or 2019-20
+      to_s( :short, sep: '-' )
+    when :long, :l                ## e.g. 1999-2000 or 2019-2000
+      to_s( :long, sep: '-' )
+    when :archive, :decade, :d    ## e.g. 1990s/1999-00 or 2010s/2019-20
+      "%3d0s/%s" % [@start_year / 10, to_s( :short, sep: '-' )]
+    when :century, :c             ## e.g. 1900s/1990-00 or 2000s/2019-20
+      "%2d00s/%s" % [@start_year / 100, to_s( :short, sep: '-' )]
+    else
+      raise ArgumentError, "[Season.to_path] unsupported format >#{format}<"
+    end
+  end # method to_path
+  alias_method :directory, :to_path   ## keep "legacy" directory alias - why? why not?
+  alias_method :path,      :to_path
+
+
+
+  #########################################
+  ## more convenience helper  - move to sportdb or such - remove - why - why not???
+  def start_date   ## generate "generic / syntetic start date" - keep helper - why? why not?
+    if year?
+      Date.new( start_year, 1, 1 )
+    else
+      Date.new( start_year 1, 7 )
+    end
+  end
+
+
+end # class Season
+
+
+
+### note: add a convenience "shortcut" season kernel method conversion method
+##  use like Season( '2012/3' )  or such
+module Kernel
+  def Season( *args ) Season.convert( *args ); end
+end

data/lib/season-formats/version.rb

@@ -0,0 +1,19 @@
+
+module SeasonFormats
+  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
+    "season-formats/#{VERSION} on Ruby #{RUBY_VERSION} (#{RUBY_RELEASE_DATE}) [#{RUBY_PLATFORM}]"
+  end
+
+  def self.root
+    File.expand_path( File.dirname(File.dirname(File.dirname(__FILE__))) )
+  end
+end   # module SeasonFormats

data/lib/season.rb

@@ -0,0 +1,4 @@
+# note: allow require simple 'season' too
+#       (in addition to require 'season-formats')
+
+require_relative 'season-formats'

data/lib/season/formats.rb

@@ -0,0 +1,7 @@
+# note: allow require 'season/formats' too
+#       (in addition to require 'season-formats')
+
+require_relative '../season-formats'
+
+
+

data/test/helper.rb

@@ -0,0 +1,8 @@
+## minitest setup
+require 'minitest/autorun'
+
+
+## our own code
+require 'season/formats'     ## or require 'season-formats'
+
+

data/test/test_season.rb

@@ -0,0 +1,141 @@
+###
+#  to run use
+#     ruby -I ./lib -I ./test test/test_season.rb
+
+
+require 'helper'
+
+class TestSeason < MiniTest::Test
+
+
+  def test_to_path
+    assert_equal '2010-11',       Season( '2010-11' ).to_path
+    assert_equal '2010-11',       Season( '2010-2011' ).to_path
+    assert_equal '2010-11',       Season( '2010/11' ).to_path
+    assert_equal '2010-11',       Season( '2010/1' ).to_path
+    assert_equal '2010-11',       Season( '2010/2011' ).to_path
+    assert_equal '2010',          Season( '2010' ).to_path
+
+    assert_equal '2010-11',       Season( 2010, 2011 ).to_path
+    assert_equal '2010-11',       Season( 2010_2011 ).to_path
+    assert_equal '2010-11',       Season( 20102011 ).to_path
+    assert_equal '2010-11',       Season( 201011 ).to_path
+    assert_equal '2010-11',       Season( 20101 ).to_path
+    assert_equal '2010',          Season( 2010 ).to_path
+
+    assert_equal '2010s/2010-11', Season( '2010-11' ).to_path( :decade )
+    assert_equal '2010s/2010-11', Season( '2010-2011' ).to_path( :decade )
+    assert_equal '2010s/2010',    Season( '2010' ).to_path( :decade )
+
+    assert_equal '1999-00',       Season( '1999-00' ).to_path
+    assert_equal '1999-00',       Season( '1999-2000' ).to_path
+    assert_equal '1990s/1999-00', Season( '1999-00' ).to_path( :decade )
+    assert_equal '1990s/1999-00', Season( '1999-2000' ).to_path( :decade )
+
+    assert_equal '2000s/2010-11', Season( '2010-11' ).to_path( :century )
+    assert_equal '2000s/2010-11', Season( '2010-2011' ).to_path( :century )
+    assert_equal '2000s/2010',    Season( '2010' ).to_path( :century )
+
+    assert_equal '1900s/1999-00', Season( '1999-00' ).to_path( :century )
+    assert_equal '1900s/1999-00', Season( '1999-2000' ).to_path( :century )
+  end  # method test_to_path
+
+
+  def test_key
+    assert_equal '2010/11',       Season( '2010-11' ).key
+    assert_equal '2010/11',       Season( '2010-2011' ).key
+    assert_equal '2010/11',       Season( '2010/11' ).key
+    assert_equal '2010/11',       Season( '2010/1' ).key
+    assert_equal '2010/11',       Season( '2010/2011' ).key
+    assert_equal '2010',          Season( '2010' ).key
+
+    assert_equal '1999/00',       Season( '1999-00' ).key
+    assert_equal '1999/00',       Season( '1999-2000' ).key
+  end  # method test_key
+
+
+  def test_years
+    [Season( '1999-00' ),
+     Season( '1999/00' ),
+     Season( '1999/2000' ),
+     Season( 1999, 2000 ),
+     Season( 1999_00 ),   ## allow "hacky" shortcuts - why? why not?
+     Season( 1999_2000 ),
+    ].each do |season|
+      assert_equal 1999, season.start_year
+      assert_equal 2000, season.end_year
+    end
+
+    [Season( '2010/1' ),
+     Season( '2010/11' ),
+     Season( 201011 ),    ## allow "hacky" shortcuts - why? why not?
+     Season( 20102011 ),
+    ].each do |season|
+      assert_equal 2010, season.start_year
+      assert_equal 2011, season.end_year
+    end
+
+    [Season( '1999' ),
+     Season( 1999 ),
+    ].each do |season|
+      assert_equal 1999, season.start_year
+      assert_equal 1999, season.end_year
+    end
+
+    [Season( '2010' ),
+     Season( 2010 ),
+    ].each do |season|
+      assert_equal 2010, season.start_year
+      assert_equal 2010, season.end_year
+    end
+  end
+
+
+  def test_prev
+    assert_equal '2009/10',       Season( '2010-11' ).prev.key
+    assert_equal '2009/10',       Season( '2010-2011' ).prev.key
+    assert_equal '2009',          Season( '2010' ).prev.key
+
+    assert_equal '1998/99',       Season( '1999-00' ).prev.key
+    assert_equal '1998/99',       Season( '1999-2000' ).prev.key
+  end
+
+  def test_next
+    assert_equal '2009/10',       Season( '2008-09' ).next.key
+    assert_equal '2009/10',       Season( '2008-2009' ).next.key
+    assert_equal '2009',          Season( '2008' ).next.key
+
+    assert_equal '1998/99',       Season( '1997-98' ).next.key
+    assert_equal '1998/99',       Season( '1997-1998' ).next.key
+  end
+
+
+  def test_range
+    s2010 = Season( '2010' )..Season( '2019' )
+    pp s2010.to_a
+# => [2010, 2011, 2012, 2013, 2014, 2015, 2016, 2017, 2018, 2019]
+
+    s2010 = Season( '2010-11')..Season( '2019-20')
+    pp s2010.to_a
+# => [2010/11, 2011/12, 2012/13, 2013/14, 2014/15,
+#     2015/16, 2016/17, 2017/18, 2018/19, 2019/20]
+
+    puts s2010 === Season( '2015-16' )  # true
+    puts s2010 === Season( '2015' )     # !!!! false  - why? if using >= <=
+    puts s2010 === Season( '1999-00' )  # false
+    puts s2010 === Season( '2020-21' )  # false
+
+    puts
+    puts s2010.include? Season( '2015-16' )  # true
+    puts s2010.include? Season( '2015' )     # !!! false
+    puts s2010.include? Season( '1999-00' )  # false
+
+    assert_equal true,  Season( '2010-11' ) < Season( '2015' )
+    assert_equal true,  Season( '2015' )    < Season( '2019-20' )
+
+    assert_equal false, Season( '2015' ) == Season( '2015-16' )
+    assert_equal true,  Season( '2015' ) <  Season( '2015-16' )
+    assert_equal true,  Season( '2015' ) == Season( '2015' )
+  end
+
+end # class TestSeason

metadata

@@ -0,0 +1,95 @@
+--- !ruby/object:Gem::Specification
+name: season-formats
+version: !ruby/object:Gem::Version
+  version: 0.0.1
+platform: ruby
+authors:
+- Gerald Bauer
+autorequire: 
+bindir: bin
+cert_chain: []
+date: 2020-11-22 00:00:00.000000000 Z
+dependencies:
+- !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: '3.22'
+  type: :development
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: '3.22'
+description: season-formats - read / parse and print seasons (using an academic or
+  calendar year
+email: opensport@googlegroups.com
+executables: []
+extensions: []
+extra_rdoc_files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+files:
+- CHANGELOG.md
+- Manifest.txt
+- README.md
+- Rakefile
+- lib/season-formats.rb
+- lib/season-formats/season.rb
+- lib/season-formats/version.rb
+- lib/season.rb
+- lib/season/formats.rb
+- test/helper.rb
+- test/test_season.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: 2.2.2
+required_rubygems_version: !ruby/object:Gem::Requirement
+  requirements:
+  - - ">="
+    - !ruby/object:Gem::Version
+      version: '0'
+requirements: []
+rubyforge_project: 
+rubygems_version: 2.5.2
+signing_key: 
+specification_version: 4
+summary: season-formats - read / parse and print seasons (using an academic or calendar
+  year
+test_files: []