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 ¶
- Constants
- Variables
- func ContentHash(doc *Document) (string, error)
- func Encode(doc *Document) ([]byte, error)
- func ValidType(t string) bool
- type AniDBEpisode
- type AniDBSource
- type Anime
- 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) AtTMDBMovie(id int) []Landing
- func (x *Index) AtTVDB(at TVDBEpisode) []Landing
- func (x *Index) AtTVDBEpisodeID(id int) []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) Movies(e Entry) [][]int
- func (x *Index) OnTVDB(ep EntryEpisode) TVDBReading
- func (x *Index) Routes(e Entry) Routes
- func (x *Index) Series(series int) []Span
- func (x *Index) TVDBSeasons(e Entry) []SeriesSeasons
- type Kind
- type Landing
- type Last
- type Limits
- type Listing
- type MappingSource
- type Part
- type Placement
- 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 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. A document in the earlier shape also says version 2; Decode refuses it by its sources.
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 ContentHash ¶ added in v0.2.0
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 ¶
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 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
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 ¶
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 ¶
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 ¶
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 ¶
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) AtTMDBMovie ¶ added in v0.2.0
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
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) 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 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
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) 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, 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.
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.
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.
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.
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 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, 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 ¶
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 ¶
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 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 ¶
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 {
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 Statement ¶
Statement is what the document says about one episode on TVDB. Placements 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 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.