xkcd

README

go-xkcd

HTTP Client for the xkcd API.

Details on the xkcd API can be found here.

Install

Outside a project using go modules, get the latest version by running:

go get github.com/nishanths/go-xkcd

Inside a project using go modules, use:

go get github.com/nishanths/go-xkcd@latest

Example

The following program prints details about xkcd.com/599:

package main

import (
    "context"
    "fmt"
    "log"

    "github.com/nishanths/go-xkcd/v2"
)

func main() {
    client := xkcd.NewClient()

    comic, err := client.Get(context.Background(), 599)
    if err != nil {
        log.Fatal(err)
    }
    fmt.Printf("%s: %s\n", comic.Title, comic.ImageURL) // Apocalypse: http://imgs.xkcd.com/comics/apocalypse.png
}

Test

To run tests:

$ go test -race

Godoc

https://godoc.org/github.com/nishanths/go-xkcd

License

The MIT License. Copyright © Nishanth Shanmugham.

Documentation

Overview

Package xkcd provides a HTTP client for the xkcd.com JSON API.

Example:

c := xkcd.NewClient()

comic, err := c.Latest(context.Background())
if err != nil {
    log.Fatal(err)
}
fmt.Printf("%+v\n", comic)

All methods on Client are safe to use concurrently.

More details on the xkcd API can be found at https://xkcd.com/json.html.

Index

• Constants
• type Client
  • func NewClient() *Client
  • func (c *Client) Get(ctx context.Context, number int) (Comic, error)
  • func (c *Client) Image(ctx context.Context, number int) (io.Reader, string, error)
  • func (c *Client) Latest(ctx context.Context) (Comic, error)
• type Comic
• type StatusError
  • func (e StatusError) Error() string

Constants

const BaseURL = "https://xkcd.com"

BaseURL is the default base URL for the xkcd JSON API.

Types

type Client

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

func NewClient

func NewClient() *Client

NewClient constructs a client using http.DefaultClient and the default base URL. The returned client is ready for use.

func (*Client) Get

func (c *Client) Get(ctx context.Context, number int) (Comic, error)

Get returns the xkcd comic for the given comic number.

func (*Client) Image

func (c *Client) Image(ctx context.Context, number int) (io.Reader, string, error)

Image returns the image data for the given comic number and the value of the image response's Content-Type header.

func (*Client) Latest

func (c *Client) Latest(ctx context.Context) (Comic, error)

Latest returns the latest xkcd comic.

type Comic

type Comic struct {
	Alt        string
	Day        int
	ImageURL   string
	URL        string
	Month      int
	News       string
	Number     int
	SafeTitle  string
	Title      string
	Transcript string
	Year       int
}

Comic contains information about an xkcd comic.

type StatusError

type StatusError struct {
	Code int
}

StatusError is returned when a bad response status code is received from the API.

func (StatusError) Error

func (e StatusError) Error() string