mapread

package module
v0.3.3 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Nov 18, 2026 License: Apache-2.0 Imports: 22 Imported by: 0

README

mapread

mapread gives a Go program the anime id mapping in animap's animap.json: which AniDB episodes an AniList entry is, which episodes AniDB lists with their AniDB episode ids, where each lands on TheTVDB, and which TMDB movie it is.

It reads, checks and downloads the version 2 file, and answers lookups over it in memory. It depends on two small libraries by the same author, jsonx for capped streaming JSON and httpclient for the redirect policy, needs Go 1.27.2 or later and is licensed under Apache-2.0.

Why use it

mapread is built for tools that turn an AniList, AniDB, TVDB or TMDB id into the others, such as a Sonarr or Radarr helper, and must not guess.

  • It applies the file's reading rule, so a lookup tells "lands nowhere" from "nothing stated" and from "no row", and flags a placement that rests only on a default.
  • Every TVDB placement a lookup answers with (Episode, OnTVDB, AtTVDB, Series, Routes) names its series, so a special TVDB files under another show is found on that show.
  • It gives the TVDB episode id of a placement where the file holds it, and finds the AniDB episodes on a TVDB episode by that id, so a reader whose series is numbered in another order than TVDB's official one can still place an episode.
  • It tells an episode AniDB lists, with its AniDB episode id, from a number AniDB does not list, and both from an anime whose list the file does not hold.
  • It shows ambiguity instead of hiding it: a TVDB episode or a TMDB movie returns every AniDB episode on it.
  • It refuses a file of another version or of the earlier version 2 shape, or one that breaks a rule listed under Decode rules, with errors a caller can match, so a caller keeps its last good copy.
  • It downloads a release at one tag and checks the file against its .sha256 sidecar, with redirects allowed only to GitHub's hosts over HTTPS.
  • Decoding streams the file under caps the caller sets, and every lookup returns a copy.

Read the file with jq instead if you need a one-off answer from a shell.

Install

go get github.com/cplieger/animap/mapread@latest

Usage

src := mapread.Source{Repo: "cplieger/animap"}
client := &http.Client{Timeout: time.Minute}

rel, err := src.Latest(ctx, client)
if err != nil {
	return err
}
if rel.Tag == heldTag {
	return nil // the copy you hold is the latest
}
got, err := rel.Fetch(ctx, client, mapread.DefaultLimits())
if err != nil {
	return err // keep the copy you hold
}
x := mapread.NewIndex(got.Document)

e, ok := x.Entry(21) // AniList 21
if ok {
	for _, s := range x.TVDBSeasons(e) {
		fmt.Println(s.Series, s.Seasons)
	}
}

Latest reads only the redirect GitHub answers for the latest release, so comparing its tag with the one you hold costs one request, or two when the repository was transferred or renamed and its old name redirects to the new one. The package examples show TVDBSeasons, AtTVDB, AtTVDBEpisodeID and Episode over a small file, and go test keeps them true.

How a lookup reads an episode

An anime row lists runs of AniDB episodes of one kind. A run's tvdb lists the TVDB episodes its first episode lands on, each on the row's tvdb_id unless the target names its own series, and each later episode of the run lands one episode on. A target's episode_ids, when present, are the TVDB episode ids of those episodes, one per episode of the run; a target without them has none the file holds. A run with "tvdb": [] lands nowhere on TVDB, and a run with no tvdb member states nothing there. A run's tmdb_movies are the TMDB movies each of its episodes is, several ids being aliases of one work; a run without it states no movie.

An episode no run names lands nowhere on TVDB and is no movie when its number is from 1 to the kind's last, or when the row holds AniDB's list (episodes_listed); past last on a row without the list, the file does not place it. An anime with no tvdb_id is on TVDB only where a run lands, on the series its targets name. Episode applies this rule and gives TVDB a Statement in one of three states, Lands with its placements, Nowhere or Unstated, or none when the episode is off TVDB; only Lands carries placements. A Placement is not a row's Target: it names its series, never 0, and carries its TVDB episode id, 0 when the file holds none, and its default flag. Every other lookup applies the same rule.

Episode also says what AniDB's list holds. Listed is an episode AniDB lists, with its AniDB episode id in ID. NotListed is a number AniDB does not list on an anime whose list the file holds, and ListingUnknown an anime whose list the file does not hold. It returns false for a reference that names no episode (an unknown kind or a number below 1), for an anime with no row, or for a number outside the anime's runs and past its last when the file holds no list for it. Episodes, AtTVDB, AtTVDBEpisodeID and AtTMDBMovie give each AniDB episode's id beside it, 0 where AniDB does not list it.

Routes gives the ids an entry reaches. Its TVDB series are, per part, the series its episodes land on, in landing order, or the anime's tvdb_id when none of them lands. Its TMDB movies are the one list every episode of the entry states, the work the entry wholly is, and none when an episode states another list or none: an entry whose episodes are different works gets no movie, never their union. Movies lists the distinct works of an entry's episodes, and Anime.TVDBSeries every series an anime's episodes may land on, its tvdb_id first.

Decode rules

Decode refuses a document, with ErrInvalid unless another error is named, when:

  • its first member is not version 2 (ErrVersion, carrying a *VersionError with the version found), its sources names a member of the earlier version 2 shape, anime_offline_database, anime_lists, anidb_mirror or overlay (ErrVersion, with no *VersionError; those four names are retired and never name a sources member again), or its members are not version, generated_at, sources, attribution, anime and entries in that order, each once (ErrNotDocument); a member it does not know is skipped at every level, and a key repeated in one object, case-insensitively, is refused;
  • it is not UTF-8 (ErrNotDocument), a known member is null or of another JSON type, an integer is not written with digits alone, or an episode number or count is below 1 or a season below 0;
  • generated_at is not an RFC 3339 time in UTC, sources.mapping.revision is empty or over 100 bytes, sources.anidb.titles_dump is not a calendar date written yyyy-mm-dd, or the attribution's licences are not ODbL-1.0 and DbCL-1.0;
  • the anime are not ascending by anidb_id, a row has no anidb_id or one below 1 or carries nothing besides its id, type is not one of TV, MOVIE, OVA, ONA, SPECIAL and UNKNOWN, tvdb_id is below 1, mal_ids is empty, not ascending, repeats an id or holds an id below 1, last or episodes is empty, or an episode number, count or season is above 1,048,576;
  • the runs are not ascending by kind (regular, special, credit, promotion, parody, other) and start, overlap, or two consecutive runs continue each other: the next number, AniDB listing both or neither, targets that keep their series, season and default flag one episode on and hold episode_ids on both or neither, and equal tmdb_movies, which must be written as one run;
  • a run lacks kind, start or end, starts after its end, lists AniDB episode ids on a row without episodes_listed, not one per episode or below 1, ends past its kind's last (only a regular run of listed episodes stating neither tvdb nor tmdb_movies may), or lists no AniDB episode and states no landing: its tvdb is [], or absent on a row with no tvdb_id, and it has no tmdb_movies;
  • a run's tmdb_movies is empty, not ascending, repeats an id or holds an id below 1;
  • a target lacks season or episode; a run's targets are not ascending by series (the target's series, else the row's tvdb_id), season and episode, each once; a target's series is below 1 or is the row's tvdb_id; on a row with no tvdb_id, tvdb is [] or a target has no series; default is present and not true; a target's last landing is above 1,048,576; or a target's episode_ids are not one per episode of its run or hold an id below 1;
  • one TVDB episode (series, season and episode) has two TVDB episode ids, or one id names two TVDB episodes, in any rows;
  • an entry has no anilist_id or one below 1, the entries are not ascending by it, ids is empty, or ids.anidb or ids.mal is empty, not ascending and unique, or holds an id below 1;
  • a part lacks anidb_id or kind, names an anime with no row, has one of start and end, starts after its end, ends past its anime's last, or is combined but not regular with no range; or parts is empty;
  • it is over a cap (ErrTooLarge).

It does not check an entry's parts against its ids.anidb.

API

  • Decode reads a document under Limits: a zero field takes its DefaultLimits() value: 32 MiB, 131,072 rows per table, 256 KiB per row, and 2,097,152 AniDB episodes named by the entries' parts and as many named by the runs' tmdb_movies, counted once per movie. It refuses a document that is not UTF-8 with ErrNotDocument. Encode writes the canonical form. ContentHash is the SHA-256 of the version, attribution, anime and entries, so generated_at and sources never change it.
  • Source.Latest and Release.Fetch download and verify a release. Fetched.Bytes is the document's size as downloaded.
  • NewIndex and its lookups: Entry, Anime, Episodes, Episode, Routes, Movies, OnTVDB, TVDBSeasons, AtTVDB, AtTVDBEpisodeID, AtTMDBMovie and Series. OnTVDB reads one entry episode on TVDB, on each series it lands on and on its anime's own series, where an episode filed only elsewhere lands on no season; its On answers for any series, and an entry episode one of whose AniDB episodes has an Unstated statement reads as unstated on every series it does not land on, never as fully stated there, while one off TVDB reads as landing nowhere there. TVDBSeasons groups those readings on every series one of the entry's episodes names, counting every entry episode on each: an entry episode rests on a default on a season when any of its AniDB episodes lands there by default. AtTVDBEpisodeID finds every AniDB episode on the TVDB episode an id names, as AtTVDB does there. Part.Identity tells the part that is a whole anime.
  • Errors to match with errors.Is: ErrVersion (with *VersionError naming the version found, none for the earlier version 2 shape), ErrNotDocument, ErrInvalid, ErrTooLarge, ErrChecksum, ErrRelease and ErrRedirect. An empty, truncated or failed read matches none of them, and nor does an HTTP 408, 425, 429 or 5xx answer, so a caller can retry it. Every answer Latest or Fetch refuses for its HTTP status or its redirect carries a *StatusError with its URL and status code, for errors.As; a 200 answer refused for its content (ErrChecksum, ErrTooLarge or a decode error) carries none, and nor does a redirect whose Location net/http cannot parse, which fails inside net/http as its *url.Error and matches no error above.

Decoding holds the whole document and its index in memory: set Limits.MaxDocumentBytes to what your memory allows.

The full reference is on pkg.go.dev.

Contributing

See CONTRIBUTING.md.

Disclaimer

This project is built with care and follows security best practices, but it is intended for personal / self-hosted use. No guarantees of fitness for production environments. Use at your own risk.

This project was built with AI assistance. The human maintainer defines architecture, supervises implementation, and makes all final decisions.

License

Apache-2.0. See LICENSE.

Documentation

Overview

Package mapread reads and writes animap.json version 2, the anime id mapping between AniDB, AniList, MyAnimeList, TheTVDB and TMDB movies.

Decode reads a document under caps and refuses one that breaks a rule the README lists under "Decode rules", or one in the earlier version 2 shape; Encode writes its canonical form and ContentHash hashes what a release publishes as data. Source.Latest and Release.Fetch download a release and verify it against its .sha256 sidecar. An Index answers the lookups: an AniList entry to its episodes, routes, movies and TVDB seasons, an AniDB episode to its TVDB placements with their TVDB episode ids, its movies and its AniDB episode id, a TVDB episode, a TVDB episode id or a TMDB movie to every AniDB episode on it, and a TVDB series to its anime in TVDB order. The README states the reading rule every lookup applies.

Index

Examples

Constants

View Source
const Version = 2

Version is the major version of the format this package reads and writes. It is raised only for a breaking change; a member added within a version is additive and Decode ignores members it does not know. A document in the earlier shape also says version 2; Decode refuses it by its sources.

Variables

View Source
var (
	ErrVersion     = errors.New("mapread: unsupported version")
	ErrNotDocument = errors.New("mapread: not an animap document")
	ErrTooLarge    = errors.New("mapread: over a decode limit")
	ErrInvalid     = errors.New("mapread: invalid document")
	ErrChecksum    = errors.New("mapread: checksum mismatch")
	ErrRelease     = errors.New("mapread: unexpected release answer")
	ErrRedirect    = errors.New("mapread: redirect refused")
)

Errors Decode, Source.Latest and Release.Fetch return, matched with errors.Is. An empty body, a truncated one and a failed read are plain wrapped errors, so a caller can treat them as transient; these are not.

Functions

func ContentHash added in v0.2.0

func ContentHash(doc *Document) (string, error)

ContentHash is the SHA-256, in hex, of what doc publishes as data: its version, attribution, anime and entries. GeneratedAt and Sources do not change it, so a rebuild that changes no row keeps its hash.

func Encode

func Encode(doc *Document) ([]byte, error)

Encode returns doc's canonical encoding: minified, with no HTML escaping, no trailing newline and the members in declared order. It does not validate; Decode does. A document Decode read may hold an anime row or an ids object filled only by members this package does not know, which Encode writes empty and Decode then refuses.

func ValidType

func ValidType(t string) bool

ValidType reports whether t is a published type, or "" for none.

Types

type AniDBEpisode

type AniDBEpisode struct {
	Ref
	ID int
}

AniDBEpisode is an AniDB episode the document names, with its AniDB episode id, 0 when AniDB's list does not hold it.

type AniDBSource added in v0.2.0

type AniDBSource struct {
	TitlesDump string `json:"titles_dump"`
}

AniDBSource is the AniDB title dump the anime list reflects: TitlesDump is its source date, yyyy-mm-dd.

type Anime

type Anime struct {
	AniDBID        int    `json:"anidb_id"`
	Type           string `json:"type,omitempty"`
	TVDBID         int    `json:"tvdb_id,omitempty"`
	MALIDs         []int  `json:"mal_ids,omitempty"`
	Last           Last   `json:"last,omitzero"`
	EpisodesListed bool   `json:"episodes_listed,omitempty"`
	Episodes       []Run  `json:"episodes,omitempty"`
}

Anime is one AniDB anime: its ids on other services, the highest episode number of each kind the document places, and its episodes: the ones AniDB lists, with their AniDB episode ids, and where they land. EpisodesListed says AniDB's episode list was read, so a number no run lists with an id is one AniDB does not list. Read an episode through Index.Episode, which applies the reading rule.

func (*Anime) TVDBSeries added in v0.2.0

func (a *Anime) TVDBSeries() []int

TVDBSeries is every TVDB series a's episodes may land on: TVDBID first when a has one, then each other series a target names, in run order, each once. It is empty for an anime on no TVDB series.

type Attribution

type Attribution struct {
	License            string `json:"license"`
	LicenseURL         string `json:"license_url"`
	ContentsLicense    string `json:"contents_license"`
	ContentsLicenseURL string `json:"contents_license_url"`
	Notice             string `json:"notice"`
}

Attribution is the licence notice the document carries.

type Document

type Document struct {
	Version     int         `json:"version"`
	GeneratedAt string      `json:"generated_at"`
	Sources     Sources     `json:"sources"`
	Attribution Attribution `json:"attribution"`
	Anime       []Anime     `json:"anime"`
	Entries     []Entry     `json:"entries"`
}

Document is a whole animap.json.

func Decode

func Decode(r io.Reader, lim Limits) (*Document, error)

Decode reads one document from r, streaming it, under lim. It refuses with ErrVersion a document whose first member is not version 2, before reading further, and one in the earlier version 2 shape, once it reads sources; and one not UTF-8 or breaking a rule the README lists under "Decode rules". It does not check an entry's parts against its ids.anidb. Members it does not know are ignored at every level, a key matching one only case-insensitively among them; a key repeated in one object, case-insensitively, is invalid.

type Entry

type Entry struct {
	AniListID int    `json:"anilist_id"`
	Type      string `json:"type,omitempty"`
	IDs       *IDs   `json:"ids,omitempty"`
	Parts     []Part `json:"parts,omitempty"`
}

Entry is one AniList entry: its type, its ids and the AniDB episodes it is (Parts), in entry episode order.

type EntryEpisode

type EntryEpisode struct {
	Refs   []AniDBEpisode
	Number int
}

EntryEpisode is entry episode Number (from 1) and the AniDB episodes it is: one, or every regular episode of a combined part.

type Episode

type Episode struct {
	TVDB       *Statement
	TMDBMovies []int
	Listing    Listing
	ID         int
}

Episode is an AniDB episode's TVDB statement, nil when it is off TVDB, the TMDB movies it is, nil for none stated, and what AniDB's list says of it: ID is its AniDB episode id when Listing is Listed, else 0.

type Fetched

type Fetched struct {
	Document *Document
	// Bytes is the document body's length as read.
	Bytes  int64
	SHA256 [32]byte
}

Fetched is a verified, decoded release asset and the SHA-256 its sidecar names.

type IDs

type IDs struct {
	AniDB []int `json:"anidb,omitempty"`
	MAL   []int `json:"mal,omitempty"`
}

IDs are an entry's ids, each list ascending and unique: AniDB the AniDB anime it may be, two or more being ambiguous, and MAL its MyAnimeList ids.

type Index

type Index struct {
	// contains filtered or unexported fields
}

Index answers lookups over one decoded document. Every result is a copy, so a caller may change it freely.

func NewIndex

func NewIndex(doc *Document) *Index

NewIndex indexes doc, which must be non-nil and accepted by Decode; the Index then owns it, and the caller must not modify doc afterwards.

func (*Index) Anime

func (x *Index) Anime(aid int) (Anime, bool)

Anime is the row of AniDB id aid.

func (*Index) AtTMDBMovie added in v0.2.0

func (x *Index) AtTMDBMovie(id int) []Landing

AtTMDBMovie is every AniDB episode stated to be TMDB movie id, by AniDB id, kind and number.

func (*Index) AtTVDB

func (x *Index) AtTVDB(at TVDBEpisode) []Landing

AtTVDB is every AniDB episode landing on at, stated or by default, by AniDB id, kind and number. Two or more is an ambiguity the caller sees.

Example
package main

import (
	"fmt"
	"os"

	"github.com/cplieger/animap/mapread"
)

func main() {
	f, err := os.Open("testdata/place.json")
	if err != nil {
		panic(err)
	}
	defer f.Close()
	doc, err := mapread.Decode(f, mapread.DefaultLimits())
	if err != nil {
		panic(err)
	}
	x := mapread.NewIndex(doc)
	for _, l := range x.AtTVDB(mapread.TVDBEpisode{Series: 500, Season: 2, Episode: 1}) {
		fmt.Printf("AniDB %d %s %d (AniDB episode id %d), default %t\n", l.AniDB, l.Kind, l.Number, l.ID, l.Default)
	}
}
Output:
AniDB 1 regular 6 (AniDB episode id 1006), default false
AniDB 1 regular 7 (AniDB episode id 1007), default false

func (*Index) AtTVDBEpisodeID added in v0.2.0

func (x *Index) AtTVDBEpisodeID(id int) []Landing

AtTVDBEpisodeID is every AniDB episode landing on the TVDB episode of id, as AtTVDB finds them there, whether or not each placement holds the id; nil when no target gives id. A reader holding a TVDB episode by id, in whatever order its series is numbered, reaches the official one here.

Example
package main

import (
	"fmt"
	"os"

	"github.com/cplieger/animap/mapread"
)

func main() {
	f, err := os.Open("testdata/place.json")
	if err != nil {
		panic(err)
	}
	defer f.Close()
	doc, err := mapread.Decode(f, mapread.DefaultLimits())
	if err != nil {
		panic(err)
	}
	x := mapread.NewIndex(doc)
	for _, l := range x.AtTVDBEpisodeID(5012) {
		fmt.Printf("AniDB %d %s %d (AniDB episode id %d)\n", l.AniDB, l.Kind, l.Number, l.ID)
	}
}
Output:
AniDB 1 regular 4 (AniDB episode id 1004)

func (*Index) Entry

func (x *Index) Entry(al int) (Entry, bool)

Entry is the entry of AniList id al.

func (*Index) Episode

func (x *Index) Episode(ref Ref) (Episode, bool)

Episode applies the reading rule to one AniDB episode. It is false when ref's kind is not one of the six or its number is below 1, when its anime has no row, or when the row carries no AniDB episode list and no run covers the number and it is past the kind's last. Otherwise a covering run gives its TVDB statement and movies, and no run means it lands nowhere on TVDB and is no movie; an anime with no TVDBID is on TVDB only where a covering run lands. A covering run with ids makes it Listed, and else it is NotListed on a row with AniDB's list.

Example
package main

import (
	"fmt"
	"os"

	"github.com/cplieger/animap/mapread"
)

func main() {
	f, err := os.Open("testdata/place.json")
	if err != nil {
		panic(err)
	}
	defer f.Close()
	doc, err := mapread.Decode(f, mapread.DefaultLimits())
	if err != nil {
		panic(err)
	}
	x := mapread.NewIndex(doc)
	listing := map[mapread.Listing]string{mapread.Listed: "listed", mapread.NotListed: "not listed", mapread.ListingUnknown: "unknown"}
	state := map[mapread.State]string{mapread.Lands: "lands", mapread.Nowhere: "nowhere", mapread.Unstated: "unstated"}
	for _, n := range []int{5, 50} {
		ep, _ := x.Episode(mapread.Ref{AniDB: 1, Kind: mapread.Special, Number: n})
		fmt.Printf("special %d: %s, AniDB episode id %d, TVDB %s\n", n, listing[ep.Listing], ep.ID, state[ep.TVDB.State])
		for _, p := range ep.TVDB.Placements {
			fmt.Printf("  on TVDB %d S%dE%d, TVDB episode id %d, default %t\n", p.Series, p.Season, p.Episode, p.ID, p.Default)
		}
	}
}
Output:
special 5: listed, AniDB episode id 2005, TVDB lands
  on TVDB 500 S0E5, TVDB episode id 5005, default true
special 50: not listed, AniDB episode id 0, TVDB nowhere

func (*Index) Episodes

func (x *Index) Episodes(e Entry) []EntryEpisode

Episodes expands e's parts into its episodes, in order.

func (*Index) Movies added in v0.2.0

func (x *Index) Movies(e Entry) [][]int

Movies is the TMDB movies of e's episodes: one list per distinct work, that is per distinct list an episode states, in episode order. An episode stating none adds nothing.

func (*Index) OnTVDB

func (x *Index) OnTVDB(ep EntryEpisode) TVDBReading

OnTVDB reads every AniDB episode of ep on TVDB, the one aggregate of an entry episode's landings that TVDBSeasons and other readers derive from. Each placement counts on its series, and each AniDB episode of an anime with a TVDBID also reads on that series, so one landing only elsewhere lands on no season there. ep comes from Episodes; a ref the document does not hold reads as Off.

func (*Index) Routes

func (x *Index) Routes(e Entry) Routes

Routes are the ids e reaches through its parts.

func (*Index) Series

func (x *Index) Series(series int) []Span

Series lists the AniDB anime whose regular episodes land on TVDB series, in TVDB order: by first landing, default targets included.

func (*Index) TVDBSeasons

func (x *Index) TVDBSeasons(e Entry) []SeriesSeasons

TVDBSeasons groups e's episodes per TVDB series and season by their OnTVDB reading, on each series one of them names, in the order they first name it. Every entry episode counts on every such series, read as TVDBReading.On reads it there: once per season it lands on, and where it lands on none, as unstated or as nowhere.

Example
package main

import (
	"fmt"
	"os"

	"github.com/cplieger/animap/mapread"
)

func main() {
	f, err := os.Open("testdata/mini.json")
	if err != nil {
		panic(err)
	}
	defer f.Close()
	doc, err := mapread.Decode(f, mapread.DefaultLimits())
	if err != nil {
		panic(err)
	}
	x := mapread.NewIndex(doc)
	e, _ := x.Entry(108)
	for _, s := range x.TVDBSeasons(e) {
		for _, season := range s.Seasons {
			fmt.Printf("TVDB %d season %d: stated %v, by default %v\n", s.Series, season.Season, season.Stated, season.Default)
		}
	}
}
Output:
TVDB 5005 season 0: stated [1 2], by default [3]

type Kind

type Kind string

Kind is an AniDB episode type.

const (
	Regular   Kind = "regular"
	Special   Kind = "special"
	Credit    Kind = "credit"
	Promotion Kind = "promotion"
	Parody    Kind = "parody"
	Other     Kind = "other"
)

The kinds, in the order the document lists them.

func Kinds

func Kinds() []Kind

Kinds returns every kind in document order, a new slice on each call.

type Landing

type Landing struct {
	AniDBEpisode
	Default bool
}

Landing is an AniDB episode found on a TVDB episode or a TMDB movie; Default marks a TVDB placement that rests only on a default.

type Last

type Last struct {
	Regular   int `json:"regular,omitempty"`
	Special   int `json:"special,omitempty"`
	Credit    int `json:"credit,omitempty"`
	Promotion int `json:"promotion,omitempty"`
	Parody    int `json:"parody,omitempty"`
	Other     int `json:"other,omitempty"`
}

Last is the highest episode number of each kind the document places; 0 means none. AniDB can list regular episodes past Regular, which runs name with their ids and state no landing for.

func (Last) Of

func (l Last) Of(k Kind) int

Of is the highest number of kind k, 0 for none or an unknown kind.

func (Last) Set

func (l Last) Set(k Kind, n int) Last

Set returns l with kind k's highest number n; an unknown kind is ignored.

type Limits

type Limits struct {
	// MaxDocumentBytes caps the whole document.
	MaxDocumentBytes int64
	// MaxRows caps each table's rows.
	MaxRows int
	// MaxRowBytes caps one encoded row, and the sources and attribution
	// members.
	MaxRowBytes int
	// MaxEpisodes caps the AniDB episodes all entries' parts name, summed,
	// what Index.Episodes expands over every entry; and apart from them
	// the episodes the runs' tmdb_movies name, once per movie, what
	// Index.AtTMDBMovie expands over every movie.
	MaxEpisodes int
}

Limits bound one Decode. A zero field takes DefaultLimits' value.

func DefaultLimits

func DefaultLimits() Limits

DefaultLimits are the limits a zero Limits takes.

type Listing

type Listing int

Listing is what AniDB's episode list says of an episode.

const (
	// ListingUnknown is an anime whose row carries no AniDB episode list.
	ListingUnknown Listing = iota
	// Listed is an episode AniDB lists, with its AniDB episode id.
	Listed
	// NotListed is a number AniDB's list holds no episode at.
	NotListed
)

type MappingSource added in v0.2.0

type MappingSource struct {
	Revision string `json:"revision"`
}

MappingSource is the mapping state read: Revision is an opaque, non-empty identifier of at most 100 bytes.

type Part

type Part struct {
	AniDBID  int  `json:"anidb_id"`
	Kind     Kind `json:"kind"`
	Start    int  `json:"start,omitempty"`
	End      int  `json:"end,omitempty"`
	Combined bool `json:"combined,omitempty"`
}

Part is AniDB episodes of one anime and kind. With no range it names episodes 1 to the anime's Last of that kind. Each named episode is one entry episode, except that a Combined part, every regular episode of the anime, is one.

func (Part) Identity

func (p Part) Identity() bool

Identity reports whether p is the anime itself, its regular episodes with no range and not combined: the part an identity gives an entry.

type Placement added in v0.2.0

type Placement struct {
	TVDBEpisode
	ID      int
	Default bool
}

Placement is a TVDB episode an AniDB episode lands on, as an Index answers it: its series resolved, never 0; ID its TVDB episode id, 0 when the document does not hold it; and Default when it rests only on a default, not on a stated placement.

type Ref

type Ref struct {
	Kind   Kind
	AniDB  int
	Number int
}

Ref is one AniDB episode: its anime, kind and number in that kind.

type Release

type Release struct {
	Source Source
	Tag    string
}

Release is one tagged release of a Source.

func (Release) Fetch

func (r Release) Fetch(ctx context.Context, c *http.Client, lim Limits) (Fetched, error)

Fetch downloads r's animap.json and its .sha256 sidecar, both at r.Tag, checks the body against the sidecar and decodes it under lim. Redirects are followed only over HTTPS to the Source's host and GitHub's asset hosts; another is ErrRedirect wrapping the redirect's *StatusError. An HTTP 408, 425, 429 or 5xx answer is a plain, retryable *StatusError; any other but 200 is ErrRelease wrapping one. A mismatch or malformed sidecar is ErrChecksum, a body over lim.MaxDocumentBytes ErrTooLarge. c must not be nil; its CheckRedirect is not used.

type Routes

type Routes struct {
	TVDB       []int
	TMDBMovies []int
}

Routes are the ids an entry reaches through its parts, each once in part order. TVDB is, per part, the series its episodes land on in landing order, or its anime's TVDBID when none of them lands. TMDBMovies is the one list every episode of the entry states, the work the entry wholly is, and empty when an episode states none or another list.

type Run

type Run struct {
	Kind            Kind      `json:"kind"`
	Start           int       `json:"start"`
	End             int       `json:"end"`
	AniDBEpisodeIDs []int     `json:"anidb_episode_ids,omitempty"`
	TVDB            *[]Target `json:"tvdb,omitempty"`
	TMDBMovies      []int     `json:"tmdb_movies,omitempty"`
}

Run is consecutive AniDB episodes Start to End of one kind: episode Start+i lands on (Series, Season, Episode+i) of every TVDB target. A nil TVDB states nothing there; an empty list lands nowhere. TMDBMovies are the TMDB movies each episode of the run is, aliases of one work, nil for none stated. AniDBEpisodeIDs[i] is episode Start+i's AniDB episode id when AniDB lists the run's episodes, and nil when it lists none of them.

func (*Run) ExtendedBy

func (r *Run) ExtendedBy(next *Run) bool

ExtendedBy reports whether next continues r, so the two must be written as one run: the next number of r's kind, both listed by AniDB or neither, TVDB statements of the same form whose targets keep their series, season and Default flag, are each one episode on and hold TVDB episode ids in both or neither, and equal TMDBMovies. Decode refuses a document holding such a pair; a producer merges it.

type SeasonBasis

type SeasonBasis struct {
	Season  int
	Default bool
}

SeasonBasis is a season an entry episode lands on: Default when any of its landings there rests on a default alone, so not Default means every one is stated.

type SeasonEpisodes

type SeasonEpisodes struct {
	Stated  []int
	Default []int
	Season  int
}

SeasonEpisodes are the entry episodes landing on one season, ascending, by their SeasonBasis there: Default when any of an entry episode's landings on the season rests on a default alone, else Stated.

type SeriesReading

type SeriesReading struct {
	Seasons  []SeasonBasis
	Series   int
	Unstated bool
}

SeriesReading is an entry episode on one TVDB series: the seasons it lands on, ascending; Unstated when it lands on none there and one of its AniDB episodes has nothing stated on TVDB, and it lands nowhere there when it lands on none and is not Unstated.

type SeriesSeasons

type SeriesSeasons struct {
	Seasons  []SeasonEpisodes
	Series   int
	Nowhere  int
	Unstated int
}

SeriesSeasons is where an entry's episodes land on one TVDB series: each season with the entry episodes landing there, and how many land nowhere on it or have nothing stated.

type Source

type Source struct {
	// Repo is owner/name, such as "cplieger/animap".
	Repo string
	// Base is an https origin, with no userinfo or path; "" is
	// https://github.com.
	Base string
}

Source is a repository whose releases carry animap.json.

func (Source) Latest

func (s Source) Latest(ctx context.Context, c *http.Client) (Release, error)

Latest asks which tag the latest release is, reading no body: GitHub answers releases/latest with a 302 to the tag's page. A transferred or renamed repository answers with a 301 or 308 to its new releases/latest on the same host; Latest follows one and returns a Release whose Source names the new repository. An HTTP 408, 425, 429 or 5xx answer is a plain *StatusError a caller can retry; any other, a 302 to anything but a dated data release's tag or a second move included, is ErrRelease wrapping one. c must not be nil; its CheckRedirect is not used.

type Sources

type Sources struct {
	Mapping MappingSource `json:"mapping"`
	AniDB   AniDBSource   `json:"anidb"`
}

Sources names what the document was built from.

type Span

type Span struct {
	First, Last TVDBEpisode
	AniDB       int
	Exact       bool
}

Span is the range of an AniDB anime's regular-episode landings on one TVDB series: First to Last, not every number between; Exact when every landing is stated, not a default.

type State

type State int

State is what a Statement says of an episode on TVDB.

const (
	// Unstated is a run that omits tvdb: the document states nothing.
	Unstated State = iota
	// Nowhere is an episode that lands nowhere on TVDB.
	Nowhere
	// Lands is an episode landing on the Statement's Placements.
	Lands
)

type Statement

type Statement struct {
	Placements []Placement
	State      State
}

Statement is what the document says about one episode on TVDB. Placements is non-empty when State is Lands, and nil otherwise.

type StatusError

type StatusError struct {
	URL  string
	Code int
}

StatusError is the status of every answer Latest or Fetch refuses for its status or its redirect; a 200 refused for its body carries none, and nor does a redirect whose Location net/http cannot parse, which fails inside net/http as its *url.Error.

func (*StatusError) Error

func (e *StatusError) Error() string

type TVDBEpisode

type TVDBEpisode struct{ Series, Season, Episode int }

TVDBEpisode is an episode of a TVDB series in official order.

type TVDBReading

type TVDBReading struct {
	Series   []SeriesReading
	Off      bool
	Unstated bool
}

TVDBReading is where one entry episode lands on TVDB: on each series one of its AniDB episodes lands on or whose anime's TVDBID it is, in the order they first name it; Off when one of them is off TVDB; and Unstated when one of them has nothing stated on TVDB, its Statement Unstated. On reads it on any one series.

func (TVDBReading) On added in v0.2.0

func (r TVDBReading) On(series int) SeriesReading

On is r on series: its reading there when it has one, and else one landing on no season there, Unstated when r is, so an episode with nothing stated is never read as fully stated on a series it names none of.

type Target

type Target struct {
	Series     int   `json:"series,omitempty"`
	Season     int   `json:"season"`
	Episode    int   `json:"episode"`
	EpisodeIDs []int `json:"episode_ids,omitempty"`
	Default    bool  `json:"default,omitempty"`
}

Target is a TVDB episode in official order as a row writes it; an Index answers with a Placement instead. Series is the TVDB series it is on when that is not the row's TVDBID, 0 for the row's. EpisodeIDs[i] is the TVDB episode id of Episode+i, where the run's episode Start+i lands, nil when the document holds none. Default marks a target that rests only on a default, not on a stated placement.

type VersionError

type VersionError struct{ Found int }

VersionError is a document of another version; it matches ErrVersion.

func (*VersionError) Error

func (e *VersionError) Error() string

func (*VersionError) Unwrap

func (*VersionError) Unwrap() error

Unwrap makes errors.Is(err, ErrVersion) hold.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL