Documentation
¶
Overview ¶
Package mapread reads and writes animap.json version 2, the anime id mapping between AniDB, AniList, TVDB, TMDB and the services anime-offline-database lists.
Decode reads a document under caps and refuses one that breaks a rule it checks: the types, the caps and the rules docs/schema.md lists under "Order and checks", except the order of entries with no AniList id. It does not check an entry's parts against its ids.anidb. 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 placements and TVDB seasons, an AniDB episode to its placements and its AniDB episode id, a TVDB or TMDB episode to every AniDB episode on it, a TMDB movie to its anime, and a TVDB series to its anime in TVDB order. The README states the reading rule every lookup applies.
Index ¶
- Constants
- Variables
- func Encode(doc *Document) ([]byte, error)
- func ValidType(t string) bool
- type AniDBEpisode
- type AniDBMirrorSource
- type Anime
- type AnimeListsSource
- type Attribution
- type Document
- type Entry
- type EntryEpisode
- type Episode
- type Fetched
- type IDs
- type Index
- func (x *Index) Anime(aid int) (Anime, bool)
- func (x *Index) AtTMDB(at TMDBEpisode) []Landing
- func (x *Index) AtTVDB(at TVDBEpisode) []Landing
- func (x *Index) Entry(al int) (Entry, bool)
- func (x *Index) Episode(ref Ref) (Episode, bool)
- func (x *Index) Episodes(e Entry) []EntryEpisode
- func (x *Index) OnTVDB(ep EntryEpisode) TVDBReading
- func (x *Index) Routes(e Entry) Routes
- func (x *Index) Series(series int) []Span
- func (x *Index) TMDBMovie(id int) []int
- func (x *Index) TVDBSeasons(e Entry) []SeriesSeasons
- type Kind
- type Landing
- type Last
- type Limits
- type Listing
- type OfflineDatabaseSource
- type OverlaySource
- type Part
- type Ref
- type Release
- type Routes
- type Run
- type SeasonBasis
- type SeasonEpisodes
- type SeriesReading
- type SeriesSeasons
- type Source
- type Sources
- type Span
- type State
- type Statement
- type StatusError
- type TMDBEpisode
- type TVDBEpisode
- type TVDBReading
- type Target
- type VersionError
Examples ¶
Constants ¶
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.
Variables ¶
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 Encode ¶
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.
Types ¶
type AniDBEpisode ¶
AniDBEpisode is an AniDB episode the document names, with its AniDB episode id, 0 when AniDB's list does not hold it.
type AniDBMirrorSource ¶
type AniDBMirrorSource struct {
Repository string `json:"repository"`
Commit string `json:"commit"`
}
AniDBMirrorSource is the AniDB mirror commit read.
type Anime ¶
type Anime struct {
AniDBID int `json:"anidb_id"`
Type string `json:"type,omitempty"`
TVDBID int `json:"tvdb_id,omitempty"`
TMDBTVID int `json:"tmdb_tv_id,omitempty"`
TMDBMovieIDs []int `json:"tmdb_movie_ids,omitempty"`
IMDbIDs []string `json:"imdb_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.
type AnimeListsSource ¶
type AnimeListsSource struct {
Repository string `json:"repository"`
Commit string `json:"commit"`
File string `json:"file"`
}
AnimeListsSource is the Anime-Lists commit read.
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 ¶
Decode reads one document from r, streaming it, under lim. It refuses a document whose first member is not version 2 before reading further, and one not UTF-8 or with an invalid row: it checks the types, the caps and docs/schema.md's "Order and checks" but the order of entries with no AniList id (entryOrder), and not 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,omitempty"`
Type string `json:"type,omitempty"`
Episodes int `json:"episodes,omitempty"`
IDs *IDs `json:"ids,omitempty"`
Parts []Part `json:"parts,omitempty"`
}
Entry is one published identity row: keyed by its AniList id when it has one, merging every anime-offline-database entry that names that id, and otherwise one database entry. It holds its ids on every service the database lists, its episode count, 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 ¶
Episode is an AniDB episode's statements, a site nil where the anime has no id on it, 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"`
AnimeCountdown []int `json:"animecountdown,omitempty"`
AnimePlanet []string `json:"animeplanet,omitempty"`
AniSearch []int `json:"anisearch,omitempty"`
ANN []int `json:"ann,omitempty"`
Kitsu []int `json:"kitsu,omitempty"`
LiveChart []int `json:"livechart,omitempty"`
MAL []int `json:"mal,omitempty"`
NotifyMoe []string `json:"notifymoe,omitempty"`
Simkl []int `json:"simkl,omitempty"`
}
IDs are an entry's ids per service, each list ascending and unique. The members are declared alphabetically, so the encoded member is the sort key of entries with no AniList id.
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 ¶
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) AtTMDB ¶
func (x *Index) AtTMDB(at TMDBEpisode) []Landing
AtTMDB is every AniDB episode landing on at, as AtTVDB.
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) Episode ¶
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, on each site the anime has an id for, a run covering it gives that run's statement, and no run means it lands nowhere; 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])
}
}
Output: special 5: listed, AniDB episode id 2005, TVDB lands 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) 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. ep comes from Episodes; a ref the document does not hold reads as Off.
func (*Index) Series ¶
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: an entry episode counts once per season it lands on, and on a series 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.
type Landing ¶
type Landing struct {
AniDBEpisode
Default bool
}
Landing is an AniDB episode found on a site episode; Default marks a placement that rests only on a node 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 site for.
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.
MaxEpisodes int
}
Limits bound one Decode. A zero field takes DefaultLimits' value.
type OfflineDatabaseSource ¶
type OfflineDatabaseSource struct {
Repository string `json:"repository"`
Release string `json:"release"`
Asset string `json:"asset"`
SHA256 string `json:"sha256"`
}
OfflineDatabaseSource is the anime-offline-database release asset read.
type OverlaySource ¶
type OverlaySource struct {
SHA256 string `json:"sha256"`
Entries int `json:"entries"`
Links int `json:"links,omitempty"`
}
OverlaySource is the overlay applied on top of Anime-Lists: Entries patched nodes and Links overlay links applied.
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.
type Release ¶
Release is one tagged release of a Source.
func (Release) Fetch ¶
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 ¶
Routes are the ids an entry reaches through its parts: the TVDB series and TMDB shows of every part's anime, and the TMDB movies and IMDb titles of the anime a whole-anime part names, each once in part order.
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"`
TMDB *[]Target `json:"tmdb,omitempty"`
}
Run is consecutive AniDB episodes Start to End of one kind: episode Start+i lands on (Season, Episode+i) of every target. A nil site means nothing stated there; an empty list lands nowhere. 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 ¶
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, and on each site a statement of the same form whose targets keep their season and Default flag and are each one episode on. Decode refuses a document holding such a pair; a producer merges it.
type SeasonBasis ¶
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 ¶
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 on the series has nothing stated, 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 ¶
Latest asks which tag the latest release is, reading no body: GitHub answers releases/latest with a 302 to the tag's page. An HTTP 408, 425, 429 or 5xx answer is a plain *StatusError a caller can retry; any other answer, a 302 to anything but a dated data release's tag included, is ErrRelease wrapping one. c must not be nil; its CheckRedirect is not used.
type Sources ¶
type Sources struct {
AnimeOfflineDatabase OfflineDatabaseSource `json:"anime_offline_database"`
AnimeLists AnimeListsSource `json:"anime_lists"`
AniDBMirror AniDBMirrorSource `json:"anidb_mirror"`
Overlay OverlaySource `json:"overlay"`
}
Sources names the inputs 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 Statement ¶
Statement is what the document says about one episode on one site. Targets is non-empty when State is Lands, and nil otherwise.
type StatusError ¶
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.
func (*StatusError) Error ¶
func (e *StatusError) Error() string
type TMDBEpisode ¶
type TMDBEpisode struct{ Show, Season, Episode int }
TMDBEpisode is an episode of a TMDB show.
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
}
TVDBReading is where one entry episode lands on TVDB: on each series one of its AniDB episodes' anime is on, in the order they first name it, and Off when one of them is on no TVDB series.
type Target ¶
type Target struct {
Season int `json:"season"`
Episode int `json:"episode"`
Default bool `json:"default,omitempty"`
}
Target is a site episode in official order. Default marks a target that rests only on a node default, not on a written mapping.
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.