season-formats gem - read / parse and print seasons (using an academic e.g. 2020/21 or calendar year e.g. 2020)

ruby-talk
1

Hello,

   I have put together (extracted really) a little helper class
for seasons and bundled up in the season-formats gem / library [1]
for easy (re)use.

From the readme:
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

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).

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.:

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:

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:

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`.

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     # or
Season( '2019' ).next     #=>  2020

That's all for now. Cheers. Prost.

[1] https://github.com/sportdb/sport.db/tree/master/season-formats