PokedexCLI

A small interactive command-line Pokedex client implemented in Go.

This project provides a simple REPL-driven CLI to browse Pokemon locations and encounter data from the public PokeAPI (https://pokeapi.co/). It demonstrates HTTP usage, JSON decoding, a small in-memory time-expiring cache, and basic command handling.

Contents

• main.go — program entry (starts the REPL)
• repl.go — REPL loop, input cleaning and commands registry
• command_*.go — command implementations (map, mapb, explore, catch, inspect, pokedex, help, exit)
• pokemon.go — project types and models (Pokemon shape)
• internal/pokeapi — thin wrappers that call PokeAPI and decode JSON
• internal/pokecache — small in-memory cache with time-based reaping

Quick summary

Start the program, then use commands like map, mapb, explore <location-area>, catch <pokemon>, inspect <pokemon>, and pokedex to interact with the PokeAPI. The CLI keeps a local map of caught Pokemon for inspection and listing.

Prerequisites

• Go 1.22+ installed and available on your PATH.
• Network access to https://pokeapi.co for runtime operations.

Build

From the repository root run:

go build -o pokedexcli ./...

This produces a pokedexcli executable.

Run

# Run the built binary
./pokedexcli

When started you'll be presented with a prompt:

Pokedex >

Type help to list commands.

Commands

Commands are implemented in repl.go and in the command_*.go files. Below is the available command set and examples.

• help

  • Description: Displays a help message listing available commands.
  • Example: help

• map

  • Description: Displays the next page of world location areas (20 per page by default). Results are printed to stdout. Paging is stored in the CLI session.
  • Example: map

• mapb

  • Description: Displays the previous page of locations.
  • Example: mapb

• explore <location-area>

  • Description: Lists Pokemon encountered in the given location-area. Provide the area name or id as used by the PokeAPI path.
  • Example: explore kanto-route-1 (use the exact area slug/path expected by the API)

• catch <pokemon>

  • Description: Attempts to 'catch' a Pokémon with a simple randomized mechanic. If successful, the Pokemon is stored in the local in-memory pokedex map and can be inspected later.
  • Example: catch pikachu

• inspect <pokemon>

  • Description: Shows saved details (height, weight, stats, types) for a previously caught Pokemon.
  • Example: inspect pikachu

• pokedex

  • Description: Lists all caught Pokemon names in your local session.
  • Example: pokedex

• exit

  • Description: Exits the CLI.

Unknown commands print Unknown command.

How the commands work

• REPL and command routing

  • repl.go provides the interactive loop. It reads input, cleans it (cleanInput), tokenizes into command and args, then invokes the matching callback from the commands() map.

• PokeAPI interaction

  • Networking code lives in internal/pokeapi. For example, FetchLocationPage in internal/pokeapi/location_list.go performs a GET request, reads the body, and unmarshals it into a Location struct.

• Caching

  • internal/pokecache/cache.go defines a small race-safe cache that stores API response bodies keyed by URL.
  • Each entry stores createdAt and val (the raw bytes). A background goroutine (reapLoop) runs a time.Ticker and removes entries older than the configured interval.

• Catch mechanic

  • command_catch.go queries the PokeAPI for a Pokemon (/api/v2/pokemon/<name>), and uses a simple probability routine (catchPokemon) based on the Pokemon's BaseExperience to randomly determine success.

Tests

Run all tests with:

go test ./...

Planned Future Improvements

• Persist the caught Pokemon to disk (JSON file) to maintain a persistent pokedex between runs.
• Update the CLI to support the "up" arrow to cycle through previous commands.
• Simulate battles between pokemon
• Random encounters with wild pokemon