gopkg

README

gopkg

gopkg is a small Go package for searching pkg.go.dev and returning matching import paths.

It is designed to be useful in two ways:

• as a public Go library you can import in tools, scripts, or editor integrations
• as a small CLI you can run locally from cmd/gopkg

Features

• Search the pkg.go.dev index from Go code
• Return clean import paths instead of raw HTML
• Configure a custom HTTP client or base URL for tests
• Format results as newline-delimited output for terminals and scripts
• Includes examples and unit tests

Installation

Install the library in your module:

go get github.com/alex-held/gopkg

Install the CLI:

go install github.com/alex-held/gopkg/cmd/gopkg@latest

CLI usage

Usage:

gopkg [flags] <query>

The <query> argument is required and is passed to pkg.go.dev search.

CLI arguments

Flag	Description	Default
-l, --limit	Maximum number of packages to print	-1 (no limit)
-v, --verbose	Enable verbose logging to stderr	false

CLI examples

Search for packages matching cobra:

gopkg cobra

Limit the output to the first 5 matches:

gopkg --limit 5 cobra

Use the short flag form:

gopkg -l 10 chi

Enable verbose output while searching:

gopkg --verbose bubbletea

Run the command from the repository without installing it:

go run ./cmd/gopkg --limit 5 cobra

If fzf is installed, the CLI will offer interactive selection before printing the final result. If fzf is not installed, the command prints the formatted results directly.

pkg.go.dev notes

This module is set up to be consumed as a public package:

• public module path: github.com/alex-held/gopkg
• package-level GoDoc in doc.go
• documented exported API in gopkg.go
• runnable examples in example_test.go

Once pushed to GitHub, documentation should render at:

• https://pkg.go.dev/github.com/alex-held/gopkg

Development

Run the test suite:

go test ./...

Format the code:

gofmt -w .

License

Add your preferred license before publishing publicly.

Documentation

Overview

Package gopkg provides a small client for searching Go packages indexed by pkg.go.dev.

The package is intentionally minimal: you can use Search for quick lookups or configure a Client when you need a custom HTTP client or a pkg.go.dev-compatible base URL for testing.

Results are returned as import paths, which makes the package useful for tooling, scripts, CLIs, and editor integrations.

Index

• Constants
• Variables
• func FormatResults(results []string, limit int) string
• func Search(ctx context.Context, query string) ([]string, error)
• type Client
  • func NewClient() *Client
  • func (c *Client) Search(ctx context.Context, query string) ([]string, error)

Examples

• Client.Search
• FormatResults

Constants

const DefaultBaseURL = "https://pkg.go.dev"

DefaultBaseURL is the default host queried by Client.

Variables

var ErrEmptyQuery = errors.New("query must not be empty")

ErrEmptyQuery is returned when a search query is blank or only whitespace.

Functions

func FormatResults

func FormatResults(results []string, limit int) string

FormatResults joins import paths into newline-delimited output. When limit is greater than zero, only the first limit entries are included.

Example

package main

import (
	"fmt"

	"github.com/alex-held/gopkg"
)

func main() {
	results := []string{
		"github.com/spf13/cobra",
		"github.com/spf13/pflag",
	}

	fmt.Println(gopkg.FormatResults(results, 1))
}

Output:
github.com/spf13/cobra

func Search

func Search(ctx context.Context, query string) ([]string, error)

Search queries pkg.go.dev using a default client and returns matching import paths.

Types

type Client

type Client struct {
	HTTPClient *http.Client
	BaseURL    string
}

Client searches the pkg.go.dev index.

Zero values are usable: a nil HTTP client falls back to http.DefaultClient, and an empty BaseURL falls back to DefaultBaseURL.

func NewClient

func NewClient() *Client

NewClient returns a Client configured for pkg.go.dev.

func (*Client) Search

func (c *Client) Search(ctx context.Context, query string) ([]string, error)

Search queries the configured pkg.go.dev-compatible endpoint and returns matching import paths in the same order they appear in the search results page.

Example

package main

import (
	"context"
	"fmt"
	"net/http"
	"net/http/httptest"

	"github.com/alex-held/gopkg"
)

func main() {
	server := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
		_, _ = w.Write([]byte(`
			<div class="SearchSnippet-headerContainer"><a href="/github.com/spf13/cobra">cobra</a></div>
			<div class="SearchSnippet-headerContainer"><a href="/github.com/spf13/pflag">pflag</a></div>
		`))
	}))
	defer server.Close()

	client := gopkg.NewClient()
	client.BaseURL = server.URL

	results, err := client.Search(context.Background(), "cobra")
	if err != nil {
		fmt.Println("error:", err)
		return
	}

	fmt.Println(gopkg.FormatResults(results, -1))
}

Output:
github.com/spf13/cobra
github.com/spf13/pflag