nba 0.1.1 → 0.2.0

data/lib/nba/cli/formatters/team_formatters.rb

@@ -0,0 +1,67 @@
+module NBA
+  class CLI < Thor
+    module Formatters
+      # Formatters for team-related output
+      module TeamFormatters
+        # Eastern Conference team abbreviations
+        #
+        # @api private
+        # @return [Array<String>]
+        EAST = %w[ATL BOS BKN CHA CHI CLE DET IND MIA MIL NYK ORL PHI TOR WAS].freeze
+
+        # Division mappings by team abbreviation
+        #
+        # @api private
+        # @return [Hash]
+        DIVISIONS = {
+          %w[BOS BKN NYK PHI TOR] => "Atlantic", %w[CHI CLE DET IND MIL] => "Central",
+          %w[ATL CHA MIA ORL WAS] => "Southeast", %w[DEN MIN OKC POR UTA] => "Northwest",
+          %w[GSW LAC LAL PHX SAC] => "Pacific", %w[DAL HOU MEM NOP SAS] => "Southwest"
+        }.freeze
+
+        # Returns the team nickname for display
+        #
+        # @api private
+        # @return [String]
+        def team_nickname(team)
+          return "TBD" unless team
+
+          team.nickname || team.full_name&.split&.last || "TBD"
+        end
+
+        # Returns the conference name for a team
+        #
+        # @api private
+        # @return [String]
+        def conference_name(detail)
+          EAST.include?(detail.abbreviation.to_s) ? "Eastern Conference" : "Western Conference"
+        end
+
+        # Returns the division name for a team
+        #
+        # @api private
+        # @return [String, nil]
+        def division_name(detail)
+          division_for_team(detail.abbreviation.to_s)
+        end
+
+        # Looks up the division for a team abbreviation
+        #
+        # @api private
+        # @return [String, nil]
+        def division_for_team(abbr)
+          division = DIVISIONS.find { |teams, _| teams.include?(abbr) }&.last
+          "#{division} Division" if division
+        end
+
+        # Returns whether the stat represents a championship year
+        #
+        # @api private
+        # @return [Boolean]
+        def championship_year?(stat)
+          stat.nba_finals_appearance.eql?("LEAGUE CHAMPION")
+        end
+      end
+    end
+  end
+end

data/lib/nba/cli/formatters/time_formatters.rb

@@ -0,0 +1,82 @@
+module NBA
+  class CLI < Thor
+    module Formatters
+      # Formatters for time-related output
+      module TimeFormatters
+        # Pattern to match Eastern time format (e.g., "7:30 pm ET")
+        # @return [Regexp] the time pattern
+        ET_TIME_PATTERN = /\A(\d{1,2}):(\d{2})\s*(am|pm)\s*ET\z/i
+
+        # Converts Eastern time to local time zone
+        #
+        # @api private
+        # @param status [String] the status string (may contain ET time)
+        # @return [String] the status with time converted to local zone
+        def convert_et_to_local(status)
+          match = ET_TIME_PATTERN.match(status)
+          return status unless match
+
+          format_local_time(parse_et_time(match))
+        end
+
+        # Parses Eastern time components into a Time object
+        #
+        # @api private
+        # @param match [MatchData] the regex match with hour, minute, am/pm
+        # @return [Time] the time in Eastern timezone
+        def parse_et_time(match)
+          hour = Integer(match[1] || 0)
+          minute = Integer(match[2] || 0)
+          period = (match[3] || "am").downcase
+
+          hour = convert_to_24h(hour, period)
+          build_et_time(hour, minute)
+        end
+
+        # Converts 12-hour format to 24-hour format
+        #
+        # @api private
+        # @param hour [Integer] the hour in 12-hour format
+        # @param period [String] "am" or "pm"
+        # @return [Integer] the hour in 24-hour format
+        def convert_to_24h(hour, period)
+          if period.eql?("am")
+            hour.eql?(12) ? 0 : hour
+          else
+            hour.eql?(12) ? 12 : hour + 12
+          end
+        end
+
+        # Builds a Time object in Eastern timezone
+        #
+        # @api private
+        # @param hour [Integer] the hour in 24-hour format
+        # @param minute [Integer] the minute
+        # @return [Time] the time in Eastern timezone
+        def build_et_time(hour, minute)
+          today = Date.today
+          Time.new(today.year, today.month, today.day, hour, minute, nil, "-05:00")
+        end
+
+        # Formats a time in the local timezone
+        #
+        # @api private
+        # @param et_time [Time] the time in Eastern timezone
+        # @return [String] formatted local time string
+        def format_local_time(et_time)
+          local_time = et_time.localtime
+          zone_abbr = local_time_zone_abbr
+          local_time.strftime("%-I:%M %p #{zone_abbr}")
+        end
+
+        # Returns the local timezone abbreviation
+        #
+        # @api private
+        # @return [String] the timezone abbreviation (e.g., "PST", "EST")
+        def local_time_zone_abbr
+          Time.now.zone || "ET"
+        end
+      end
+    end
+  end
+end

data/lib/nba/cli/formatters.rb

@@ -0,0 +1,56 @@
+require_relative "formatters/time_formatters"
+require_relative "formatters/team_formatters"
+require_relative "formatters/game_formatters"
+require_relative "formatters/standings_formatters"
+require_relative "formatters/leaders_formatters"
+require_relative "formatters/player_formatters"
+
+module NBA
+  class CLI < Thor
+    # Helper methods for formatting CLI output
+    module Formatters
+      include TimeFormatters
+      include TeamFormatters
+      include GameFormatters
+      include StandingsFormatters
+      include LeadersFormatters
+      include PlayerFormatters
+
+      # Standard label width for formatted output
+      #
+      # @api private
+      # @return [Integer]
+      LABEL_WIDTH = 16
+
+      # Returns the maximum string length from the given values
+      #
+      # @api private
+      # @return [Integer]
+      def max_length(values) = values.map { |v| v.to_s.length }.max
+
+      # Centers a value within the given width
+      #
+      # @api private
+      # @return [String]
+      def center(value, width) = value.to_s.center(width)
+
+      # Formats a label and value as a single line
+      #
+      # @api private
+      # @return [String]
+      def format_label(label, value) = "#{label}: #{value}"
+
+      # Formats a label with multiple items across lines
+      #
+      # @api private
+      # @return [String]
+      def format_multiline_label(label, items)
+        indent = " " * (label.length + 2)
+        lines = items.each_slice(2).map { |pair| pair.join(", ") }
+        first_line = "#{label}: #{lines.first}"
+        continuation = lines.drop(1).map { |line| "#{indent}#{line}" }
+        ([first_line] + continuation).join("\n")
+      end
+    end
+  end
+end

data/lib/nba/cli/helpers.rb

@@ -0,0 +1,135 @@
+module NBA
+  class CLI < Thor
+    # Helper methods for CLI date parsing and team lookup
+    module Helpers
+      # Eastern Time offset from UTC in seconds
+      # @return [Integer] offset value in seconds
+      ET_OFFSET_SECONDS = 5 * 60 * 60
+
+      # Mapping of conference abbreviations to full names
+      # @return [Hash<String, String>] conference mapping
+      CONFERENCE_MAP = {"E" => "East", "W" => "West", nil => "Invalid"}.freeze
+
+      # Parses a date string into a Date object
+      #
+      # @api private
+      # @param date_str [String, nil] the date string
+      # @return [Date] the parsed date
+      def parse_date(date_str)
+        return eastern_time_date if date_str.nil? || date_str.eql?("today")
+        return eastern_time_date - 1 if date_str.eql?("yesterday")
+        return eastern_time_date + 1 if date_str.eql?("tomorrow")
+
+        parse_date_string(date_str)
+      end
+
+      # Parses a YYYYMMDD date string
+      #
+      # @api private
+      # @param date_str [String] the date string in YYYYMMDD format
+      # @return [Date] the parsed date
+      # @raise [SystemExit] if the date string is invalid
+      def parse_date_string(date_str)
+        Date.strptime(date_str, "%Y%m%d")
+      rescue Date::Error
+        say("Invalid date '#{date_str}'. Use YYYYMMDD format, 'today', 'yesterday', or 'tomorrow'.")
+        raise SystemExit
+      end
+
+      # Returns the current date in Eastern Time
+      #
+      # @api private
+      # @return [Date] the current Eastern Time date
+      def eastern_time_date = (Time.now.utc - ET_OFFSET_SECONDS).to_date
+
+      # Finds a team by name or abbreviation
+      #
+      # @api private
+      # @param name [String] the team name or abbreviation
+      # @return [Team, nil] the matching team or nil
+      def find_team_by_name(name)
+        pattern = Regexp.new(name, Regexp::IGNORECASE)
+        Teams.all.find { |t| pattern.match?(t.full_name) || pattern.match?(t.abbreviation) }
+      end
+
+      # Filters teams by name or abbreviation pattern, or returns all teams
+      #
+      # @api private
+      # @param name [String, nil] the team name or abbreviation pattern to filter by
+      # @return [Collection, Array] the matching teams
+      def filter_teams(name)
+        return Teams.all unless name
+
+        pattern = Regexp.new(name, Regexp::IGNORECASE)
+        Teams.all.select { |team| pattern.match?(team.full_name) || pattern.match?(team.abbreviation) }
+      end
+
+      # Normalizes a conference input to full name
+      #
+      # @api private
+      # @param input [String] the conference input (e.g., "e", "E", "East", "w", "W", "West")
+      # @return [String] the normalized conference name
+      def normalize_conference(input)
+        CONFERENCE_MAP.fetch(input.upcase[0].to_s, input)
+      end
+
+      # Fetches standings based on options
+      #
+      # @api private
+      # @return [Collection] the standings collection
+      def fetch_standings
+        return fetch_conference_standings if options[:conference]
+
+        options[:season] ? Standings.all(season: options.fetch(:season)) : Standings.all
+      end
+
+      # Fetches conference-specific standings
+      #
+      # @api private
+      # @return [Collection] the conference standings
+      def fetch_conference_standings
+        conf = normalize_conference(options.fetch(:conference))
+        options[:season] ? Standings.conference(conf, season: options.fetch(:season)) : Standings.conference(conf)
+      end
+
+      # Fetches schedule for a team
+      #
+      # @api private
+      # @param team [Team] the team
+      # @return [Collection] the schedule
+      def fetch_team_schedule(team)
+        season = options[:season]
+        season ? Schedule.by_team(team: team, season: season) : Schedule.by_team(team: team)
+      end
+
+      # Fetches roster for a team
+      #
+      # @api private
+      # @param team [Team] the team
+      # @return [Collection] the roster
+      def fetch_team_roster(team)
+        season = options[:season]
+        season ? Roster.find(team: team, season: season) : Roster.find(team: team)
+      end
+
+      # Resolves a category name to a Leaders constant
+      #
+      # @api private
+      # @param category [String] the category name
+      # @param category_map [Hash] mapping of category names to constant names
+      # @return [String] the Leaders constant value
+      def resolve_leader_category(category, category_map)
+        category_map[category.upcase] || Leaders::PTS
+      end
+
+      # Fetches games for a date, using live data for today
+      #
+      # @api private
+      # @param date [Date] the date
+      # @return [Collection] the games collection
+      def fetch_games(date)
+        date.eql?(eastern_time_date) ? LiveScoreboard.today : Scoreboard.games(date: date)
+      end
+    end
+  end
+end

data/lib/nba/cli.rb

@@ -1,35 +1,186 @@
-require 'thor'
+require "thor"
+require "date"
+require_relative "cli/formatters"
+require_relative "cli/display"
+require_relative "cli/helpers"
 
 module NBA
+  # Command-line interface for the NBA gem
+  #
+  # @api public
   class CLI < Thor
-    desc "games DATE", "Retrieve games' scoreboard of date"
-    method_option :date, :aliases => '-d', :desc => "format: YYYYMMDD"
+    include Formatters
+    include Display
+    include Helpers
+
+    # Mapping of category names and abbreviations to Leaders constants
+    # @return [Hash<String, String>] category mapping
+    CATEGORY_MAP = {
+      "PTS" => "PTS", "POINTS" => "PTS",
+      "REB" => "REB", "REBOUNDS" => "REB",
+      "AST" => "AST", "ASSISTS" => "AST",
+      "STL" => "STL", "STEALS" => "STL",
+      "BLK" => "BLK", "BLOCKS" => "BLK",
+      "FG_PCT" => "FG_PCT", "FG3_PCT" => "FG3_PCT", "FT_PCT" => "FT_PCT"
+    }.freeze
+
+    class_option :version, type: :boolean, aliases: "-v", desc: "Print version and exit"
+
+    remove_command :tree
+
+    # Returns whether Thor should exit on failure
+    #
+    # @api public
+    # @example
+    #   NBA::CLI.exit_on_failure? #=> true
+    # @return [Boolean] true if CLI should exit on failure
+    def self.exit_on_failure?
+      true
+    end
+
+    desc "games", "Retrieve games' scoreboard for a date"
+    method_option :date, type: :string, aliases: "-d", desc: "Date (YYYYMMDD, 'today', or 'yesterday')"
+    # Retrieves and displays games for a specified date
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.games
+    # @return [void]
     def games
-      if options[:date].nil? || options[:date] == 'today'
-        game_date_in_et = (Time.now.utc - 5 * 60 * 60).strftime("%Y%m%d")
-      elsif options[:date] == 'yesterday'
-        game_date_in_et = (Time.now.utc - (5 + 24) * 60 * 60).strftime("%Y%m%d")
+      date = parse_date(options[:date])
+      games_list = fetch_games(date)
+      games_list.empty? ? say("No games found for #{date}") : display_games(games_list)
+    end
+
+    desc "teams [NAME]", "List all teams or search by name"
+    method_option :roster, type: :boolean, aliases: "-r", default: false, desc: "Include roster"
+    # Lists all teams or searches for teams by name
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.teams("GSW")
+    # @param name [String, nil] the team name or abbreviation to search for
+    # @return [void]
+    def teams(name = nil)
+      matching_teams = filter_teams(name)
+      if matching_teams.empty?
+        say("No team found with name '#{name}'")
       else
-        game_date_in_et = options[:date]
+        display_teams(matching_teams, options.fetch(:roster), detailed: name)
       end
+    end
 
-      Game.all(game_date_in_et)
+    desc "player NAME", "Search for a player by name"
+    # Searches for players by name
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.player("LeBron")
+    # @param name [String] the player name to search for
+    # @return [void]
+    def player(name)
+      pattern = Regexp.new(name, Regexp::IGNORECASE)
+      matching = Players.all.select { |p| pattern.match?(p.full_name) }
+      if matching.empty?
+        say("No player found with name '#{name}'")
+      elsif matching.one?
+        matching.each { |p| display_player(p) }
+      else
+        display_players(matching)
+      end
     end
 
-    desc "teams", "Retrieve teams' info, with players' info if `-p` arg is passed"
-    method_option :name, :type => :string, :aliases => "-n", :required => true
-    method_option :players, :type => :boolean, :aliases => "-p", :default => false
-    def teams
-      team_results = Team.all.select { |team| team.name =~ %r|#{options[:name]}|i }
+    desc "standings", "Display current league standings"
+    method_option :conference, type: :string, aliases: "-c", desc: "Filter by conference (East/West)"
+    method_option :season, type: :numeric, aliases: "-s", desc: "Season year (e.g., 2024)"
+    # Displays current league standings
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.standings
+    # @return [void]
+    def standings
+      display_standings(fetch_standings)
+    end
 
-      if team_results.count == 0
-        puts "No team founded with name #{options[:name]}"
+    desc "leaders [CATEGORY]", "Display league leaders for a statistical category"
+    method_option :season, type: :numeric, aliases: "-s", desc: "Season year (e.g., 2024)"
+    method_option :limit, type: :numeric, aliases: "-l", default: 10, desc: "Number of leaders"
+    # Displays league leaders for a statistical category
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.leaders("PTS")
+    # @param category_name [String] the stat category (PTS, REB, AST, STL, BLK, FG_PCT, FG3_PCT, FT_PCT)
+    # @return [void]
+    def leaders(category_name = "PTS")
+      category = resolve_leader_category(category_name, CATEGORY_MAP)
+      leaders_list = if options[:season]
+        Leaders.find(category: category, limit: options.fetch(:limit),
+          season: options.fetch(:season))
       else
-        team_results.each do |team|
-          team.pretty_print
-          puts "-" * 42
-        end
+        Leaders.find(category: category, limit: options.fetch(:limit))
       end
+      display_leaders(leaders_list, category_name)
     end
+
+    desc "schedule TEAM", "Display schedule for a team"
+    method_option :season, type: :numeric, aliases: "-s", desc: "Season year (e.g., 2024)"
+    # Displays schedule for a team
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.schedule("Lakers")
+    # @param team_name [String] the team name or abbreviation
+    # @return [void]
+    def schedule(team_name)
+      team = find_team_by_name(team_name)
+      if team
+        schedule_list = fetch_team_schedule(team)
+        display_schedule(schedule_list, team)
+      else
+        say("No team found with name '#{team_name}'")
+      end
+    end
+
+    desc "roster TEAM", "Display roster for a team"
+    method_option :season, type: :numeric, aliases: "-s", desc: "Season year (e.g., 2024)"
+    # Displays roster for a team
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.roster("Lakers")
+    # @param team_name [String] the team name or abbreviation
+    # @return [void]
+    def roster(team_name)
+      team = find_team_by_name(team_name)
+      if team
+        roster_list = fetch_team_roster(team)
+        display_roster(roster_list, team)
+      else
+        say("No team found with name '#{team_name}'")
+      end
+    end
+
+    desc "version", "Display version information"
+    # Displays version information
+    #
+    # @api public
+    # @example
+    #   cli = NBA::CLI.new
+    #   cli.version
+    # @return [void]
+    def version
+      say("nba #{VERSION}")
+    end
+
+    map %w[-v --version] => :version
   end
 end

data/lib/nba/client.rb

@@ -0,0 +1,35 @@
+require_relative "connection"
+
+module NBA
+  # API client for making requests to the NBA Stats API
+  class Client
+    # Makes a GET request to the specified path
+    #
+    # @api public
+    # @example
+    #   client.get("commonplayerinfo?PlayerID=2544")
+    # @param path [String] the API path to request
+    # @return [String] the response body
+    def get(path) = connection.get(path)
+
+    # Returns the connection used for HTTP requests
+    #
+    # @api private
+    # @return [Connection] the connection instance
+    attr_reader :connection
+
+    # Initializes a new Client object
+    #
+    # @api public
+    # @example
+    #   client = NBA::Client.new
+    # @param connection [Connection] the connection to use for requests
+    # @return [NBA::Client] a new client instance
+    def initialize(connection: Connection.new)
+      @connection = connection
+    end
+  end
+
+  # Default client instance
+  CLIENT = Client.new
+end

data/lib/nba/collection.rb

@@ -0,0 +1,89 @@
+require "equalizer"
+require "forwardable"
+
+module NBA
+  # Represents a collection of objects
+  class Collection
+    extend Forwardable
+    include Equalizer.new(:elements)
+    include Enumerable
+
+    # @!method size
+    #   Returns the number of elements in the collection
+    #   @api public
+    #   @example
+    #     collection.size #=> 3
+    #   @return [Integer] the number of elements
+
+    # @!method empty?
+    #   Returns true if the collection has no elements
+    #   @api public
+    #   @example
+    #     collection.empty? #=> false
+    #   @return [Boolean] true if empty, false otherwise
+
+    # @!method first
+    #   Returns the first element in the collection
+    #   @api public
+    #   @example
+    #     collection.first #=> player1
+    #   @return [Object, nil] the first element or nil if empty
+
+    # @!method last
+    #   Returns the last element in the collection
+    #   @api public
+    #   @example
+    #     collection.last #=> player3
+    #   @return [Object, nil] the last element or nil if empty
+
+    # @!method length
+    #   Returns the number of elements in the collection
+    #   @api public
+    #   @example
+    #     collection.length #=> 3
+    #   @return [Integer] the number of elements
+
+    # @!method count
+    #   Returns the number of elements in the collection
+    #   @api public
+    #   @example
+    #     collection.count #=> 3
+    #   @return [Integer] the number of elements
+
+    def_delegators :elements, :size, :empty?, :first, :last
+
+    alias_method :length, :size
+    alias_method :count, :size
+
+    # Returns the elements in the collection
+    #
+    # @api private
+    # @return [Array] the elements
+    attr_reader :elements
+
+    # Initializes a new Collection
+    #
+    # @api public
+    # @example
+    #   collection = NBA::Collection.new([player1, player2])
+    # @param elements [Array] the elements in the collection
+    # @return [NBA::Collection] a new collection instance
+    def initialize(elements = [])
+      @elements = elements
+    end
+
+    # Iterates over the elements in the collection
+    #
+    # @api public
+    # @example
+    #   collection.each { |element| puts element }
+    # @yield [element] yields each element to the block
+    # @return [Enumerator, self] an enumerator or self
+    def each(&block)
+      return enum_for unless block
+
+      elements.each(&block)
+      self
+    end
+  end
+end