Skip to content

Latest commit

 

History

History
169 lines (130 loc) · 4.16 KB

README.md

File metadata and controls

169 lines (130 loc) · 4.16 KB

Pokedex CLI

A command-line Pokédex application built in Go that lets you explore Pokémon locations, catch Pokémon, and build your own Pokédex using the PokéAPI.

Features

  • Map Navigation: Browse through location areas in the Pokémon world

    • map - View the next 20 location areas
    • mapb - View the previous 20 location areas

  • Explore Locations: Discover which Pokémon appear in each area

    • explore <location_area> - List all Pokémon in a specific location

  • Catch Pokémon: Attempt to catch Pokémon and add them to your Pokédex

    • catch <pokemon_name> - Try to catch a Pokémon (50% success rate)

  • Inspect Pokémon: View detailed stats and types of caught Pokémon

    • inspect <pokemon_name> - Display a Pokémon's height, weight, types, and stats

  • View Your Collection: See all Pokémon you've caught

    • pokedex - List all caught Pokémon

  • Smart Caching: Responses are cached for 5 minutes to reduce API calls

Installation

Requirements

  • Go 1.25.4 or higher

Build

go build -o pokedex .

Run

./pokedex

Usage

Start the interactive REPL:

$ ./pokedex
Pokedex >

Example Session

Pokedex > map
caspian-sea
cerulean-cave
...

Pokedex > explore cerulean-cave
Found Pokemon:
- articuno
- mew
- mewtwo

Pokedex > catch mewtwo
Throwing a Pokeball at mewtwo...
Caught mewtwo!

Pokedex > inspect mewtwo
Inspecting mewtwo...
Name: mewtwo
Height: 20
Weight: 1220
Types:
- psychic
Stats:
- hp: 106
- attack: 110
- defense: 90
...

Pokedex > pokedex
Caught Pokemon:
- mewtwo

Pokedex > help
Welcome to the Pokedex!
Usage:
exit: Exits the Pokedex application
help: Displays a help message
map: Displays the names of 20 location areas in the Pokemon world
mapb: Displays the names of previous 20 location areas in the Pokemon world
explore <location_area>: Lists the Pokemon in a location area
catch <pokemon_name>: Catches a Pokemon
inspect <pokemon_name>: Inspect a caught Pokemon's details
pokedex: View all caught Pokemon

Pokedex > exit
Closing the Pokedex... Goodbye!

Architecture

Main Components

  • main.go - CLI REPL, command handlers, and JSON unmarshaling logic
  • internal/pokecache/main.go - Thread-safe caching system with automatic expiration
    • Entries expire after 5 minutes
    • Prevents redundant API calls
    • Uses goroutines and mutexes for concurrent safety

Data Structures

  • APIResponse: Parses paginated location data from PokéAPI
  • Pokemon: Holds Pokémon details (name, height, weight, stats, types)
  • LocationArea: Represents Pokémon encounters in a specific area
  • Cache: Thread-safe in-memory cache with TTL-based cleanup

Technical Details

JSON Tag Mapping

The application uses struct tags to map JSON keys to Go fields:

type Pokemon struct {
    Name   string `json:"name"`      // Maps JSON "name" key
    Height int    `json:"height"`    // Maps JSON "height" key
    Weight int    `json:"weight"`    // Maps JSON "weight" key
}

Caching Strategy

  • 5-minute TTL for all cached responses
  • Background goroutine cleans expired entries
  • Mutex-protected concurrent access

API Integration

  • Uses PokéAPI v2 (free, no authentication required)
  • Endpoints:
    • Location areas: https://pokeapi.co/api/v2/location-area/
    • Pokémon details: https://pokeapi.co/api/v2/pokemon/{name}

Project Structure

.
├── main.go                          # CLI entry point and commands
├── go.mod                           # Module definition
├── README.md                        # This file
└── internal/
    └── pokecache/
        ├── main.go                  # Cache implementation
        └── cache_test.go            # Cache tests

Future Enhancements

  • Persist caught Pokémon to disk
  • Display Pokémon images in the terminal
  • Add battle mechanics between caught Pokémon
  • Search Pokémon by type or stat range
  • Add leaderboards for catching streaks

License

MIT

Contributing

Feel free to fork and submit pull requests!

Resources