metacpanclient

package
v1.0.0 Latest Latest
Warning

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

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

Documentation

Overview

Package metacpanclient is a client for the MetaCPAN API, equivalent to MetaCPAN::Client. It is written to mirror the API and behavior as closely as possible, although the implementation varies in some places.

Index

Constants

View Source
const (
	MetaCPANURL = "https://fastapi.metacpan.org/v1"
)

Variables

View Source
var (
	ErrInvalidPodKind = errors.New("invalid pod kind")
)
View Source
var (
	ErrNilClient = errors.New("nil client")
)

Functions

This section is empty.

Types

type Author

type Author struct {
	// Blog is a list of blog URLs and feeds.
	Blog []struct {
		// URL is the URL of the blog.
		URL string `json:"url"`
		// Feed is the URL of the blog's RSS feed.
		Feed string `json:"feed"`
	} `json:"blog"`

	// Donation is a list of donation URLs.
	Donation []struct {
		// Name is the name of the donation service.
		Name string `json:"name"`

		// ID is the ID of the author on the donation service.
		ID string `json:"id"`
	} `json:"donation"`

	// Links is a list of links to the author's CPAN pages.
	Links struct {
		// BackCPANDirectory is a link to the author's BackCPAN
		// directory.
		BackCPANDirectory string `json:"backpan_directory"`

		// CPANDirectory is a link to the author's CPAN directory.
		CPANDirectory string `json:"cpan_directory"`

		// CPANTS is a link to the author's CPANTS page.
		CPANTS string `json:"cpants"`

		// CPANTestersMatrix is a link to the author's CPAN Testers
		// matrix page.
		CPANTestersMatrix string `json:"cpantesters_matrix"`

		// CPANTestersReports is a link to the author's CPAN Testers
		// reports page.
		CPANTestersReports string `json:"cpantesters_reports"`

		// MetaCPANExplorer is a link to the author's MetaCPAN
		// explorer page.
		MetaCPANExplorer string `json:"metacpan_explorer"`
	} `json:"links"`

	// PerlMongers is a set of Perl Mongers groups that the author
	// belongs to.
	PerlMongers []struct {
		// Name is the name of the perl monger's site.
		// Usually {city}.pm (i.e. Chicago.pm).
		Name string `json:"name"`
		// URL is the site's URL.
		URL string `json:"url"`
	} `json:"perlmongers"`

	// Profile contains a list of profiles the author has on various sites.
	Profile []struct {
		// Name is the name of the service the profile is on.
		Name string `json:"name"`
		// ID is the author's ID on the service.
		ID string `json:"id"`
	} `json:"profile"`

	// ReleaseCount is the number of releases the author has made.
	ReleaseCount struct {
		// BackpanOnly is the number of releases the author has
		// available on BackPAN.
		BackpanOnly int `json:"backpan-only"`

		// CPAN is the number of releases the author has available
		// on CPAN.
		CPAN int `json:"cpan"`

		// Latest is the number of unique releases the author has
		// made on CPAN.
		Latest int `json:"latest"`
	} `json:"release_count"`

	// ASCIIName is the author's name in ASCII, if available.
	ASCIIName string `json:"ascii_name"`

	// City is the author's city, if provided.
	City string `json:"city"`

	// Country is the author's country, if provided.
	Country string `json:"country"`

	// Directory is the author's directory on CPAN.
	Directory string `json:"dir"`

	// Email is a list of email addresses the author has provided.
	Email []string `json:"email"`

	// Extra is a list of extra information the author has provided.
	Extra map[string]string `json:"extra"`

	// GravatarURL is the URL of the author's gravatar.
	GravatarURL string `json:"gravatar_url"`

	// Name is the author's name.
	Name string `json:"name"`

	// PauseID is the author's PAUSE ID.
	PauseID string `json:"pauseid"`

	// RealName is the author's real name, if provided.
	Region string `json:"region"`

	// Updated is the last time the author's information was updated, in
	// ISO8601 format.
	Updated iso8601.Time `json:"updated"`

	// User is the author's unique user ID on MetaCPAN.
	User string `json:"user"`

	// Website is a list of URLs the author has provided.
	Website []string `json:"website"`
	// contains filtered or unexported fields
}

Author contains all available information about a specific author on CPAN.

func (*Author) MetaCPANURL

func (a *Author) MetaCPANURL() string

MetaCPANURL returns the URL of the author's MetaCPAN page.

func (*Author) Releases

func (a *Author) Releases() (ResultSet[*Release], error)

Releases returns a ResultSet[*Release] of the author's releases.

func (*Author) UnmarshalJSON

func (a *Author) UnmarshalJSON(data []byte) error

type Bugs

type Bugs struct {
	// Open is the number of open bugs on a given repo
	Open int `json:"open"`
	// Closed is the number of closed bugs on a given repo
	Closed int `json:"closed"`
	// Active is the number of active bugs on a given repo
	Active int `json:"active"`
	// Source is the URL of the repo
	Source string `json:"source"`
}

Bugs contains information about bugs within a distribution

func (*Bugs) UnmarshalJSON

func (b *Bugs) UnmarshalJSON(data []byte) error

type Client

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

Client is the main interface to the MetaCPAN API. It is equivalent to MetaCPAN::Client in Perl. It is thread-safe.

func NewClient

func NewClient(debug bool, scrollSize uint16, scrollTime time.Duration,
	userAgent string, domains ...string) (*Client, error)

NewClient returns a new MetaCPAN client. If domain is empty, the default domain is used ("https://fastapi.metacpan.org").

func (*Client) AllAuthors

func (mc *Client) AllAuthors() (ResultSet[*Author], error)

func (*Client) AllDistributions

func (mc *Client) AllDistributions() (ResultSet[*Distribution], error)

func (*Client) AllFavorites

func (mc *Client) AllFavorites() (ResultSet[*Favorite], error)

func (*Client) AllModules

func (mc *Client) AllModules() (ResultSet[*Module], error)

func (*Client) AllReleases

func (mc *Client) AllReleases() (ResultSet[*Release], error)

func (*Client) Author

func (mc *Client) Author(s string) (*Author, error)

func (*Client) AuthorSearch

func (mc *Client) AuthorSearch(args map[string]interface{}) (
	ResultSet[*Author], error)

func (*Client) Autocomplete

func (mc *Client) Autocomplete(s string) ([]*File, error)

func (*Client) AutocompleteSuggest

func (mc *Client) AutocompleteSuggest(s string) ([]*File, error)

func (*Client) Close

func (mc *Client) Close() error

func (*Client) Cover

func (mc *Client) Cover(s string) (*Cover, error)

func (*Client) Debug

func (mc *Client) Debug() bool

func (*Client) Distribution

func (mc *Client) Distribution(s string) (*Distribution, error)

func (*Client) DistributionSearch

func (mc *Client) DistributionSearch(args map[string]interface{}) (
	ResultSet[*Distribution], error)

func (*Client) Domains

func (mc *Client) Domains() []string

func (*Client) DownloadURL

func (mc *Client) DownloadURL(release string, r *version.Range,
	dev bool) (*DownloadURL, error)

func (*Client) Favorite

func (mc *Client) Favorite(args map[string]interface{}) (ResultSet[*Favorite],
	error)

func (*Client) File

func (mc *Client) File(s string) (*File, error)

func (*Client) Mirror

func (mc *Client) Mirror(s string) (*Mirror, error)

func (*Client) Module

func (mc *Client) Module(s string) (*Module, error)

func (*Client) ModuleSearch

func (mc *Client) ModuleSearch(args map[string]interface{}) (
	ResultSet[*Module], error)

func (*Client) Package

func (mc *Client) Package(s string) (*Package, error)

func (*Client) Permission

func (mc *Client) Permission(s string) (*Permission, error)

func (*Client) Pod

func (mc *Client) Pod(s string) (*Pod, error)

func (*Client) Rating

func (mc *Client) Rating(args map[string]interface{}) (ResultSet[*Rating],
	error)

func (*Client) Recent

func (mc *Client) Recent(count uint16) (ResultSet[*Release], error)

func (*Client) Release

func (mc *Client) Release(s string) (*Release, error)

func (*Client) ReleaseSearch

func (mc *Client) ReleaseSearch(args map[string]interface{}) (
	ResultSet[*Release], error)

func (*Client) ReleasedToday

func (mc *Client) ReleasedToday() (ResultSet[*Release], error)

func (*Client) ReverseDependencies

func (mc *Client) ReverseDependencies(s string) (ResultSet[*Release], error)

func (*Client) UserAgent

func (mc *Client) UserAgent() string

type Cover

type Cover struct {
	// Criteria is the coverage criteria for the distribution.
	Criteria struct {
		// Branch contains the coverage statistic by code branch.
		Branch float64 `json:"branch"`

		// Condition is the coverage statistic by conditional.
		Condition float64 `json:"condition"`

		// Statement is the coverage statistic by statement.
		Statement float64 `json:"statement"`

		// Subroutine is the coverage statistic by subroutine.
		Subroutine float64 `json:"subroutine"`

		// Total is the overall coverage.
		Total float64 `json:"total"`
	} `json:"criteria"`

	// Distribution is the name of the distribution this Cover pertains to.
	Distribution string `json:"Distribution"`

	// Release is the name of the release this Cover pertains to.
	Release string `json:"release"`

	// Version is the version of the release this Cover pertains to.
	Version version.JSON `json:"version"`
}

Cover contains information about a distribution's test coverage.

func (*Cover) UnmarshalJSON

func (c *Cover) UnmarshalJSON(data []byte) error

type Distribution

type Distribution struct {
	// Name is the name of the distribution
	Name string `json:"name"`

	// Bugs contains information about bugs within a distribution
	Bugs struct {
		// Github contains information about bugs on GitHub
		Github Bugs `json:"github"`
		// RT contains information about bugs on rt.cpan.org
		RT Bugs `json:"rt"`
	} `json:"bugs"`

	// River contains information about the distribution's "CPAN River"
	River struct {
		// Bucket indicates how far "upstream" the distribution is.
		Bucket int `json:"bucket"`

		// Immediate indicates the number of distributions that depend
		// immediately on this distribution.
		Immediate int `json:"immediate"`

		// Total indicates the total number of distributions that
		// depend on this distribution, including indirect
		// dependencies.
		Total int `json:"total"`
	} `json:"river"`
	// contains filtered or unexported fields
}

Distribution contains information about a distribution.

func (*Distribution) Github

func (d *Distribution) Github() Bugs

Github returns the bugs on GitHub for the distribution.

func (*Distribution) RT

func (d *Distribution) RT() Bugs

RT returns the bugs on rt.cpan.org for the distribution

type DownloadURL

type DownloadURL struct {
	// ChecksumSHA256 is the SHA256 checksum of the release.
	ChecksumSHA256 string `json:"checksum_sha256"`

	// ChecksumMD5 is the MD5 checksum of the release.
	ChecksumMD5 string `json:"checksum_md5"`

	// Date is the release date for a given distribution
	Date iso8601.Time `json:"date"`

	// DownloadURL is the URL to download the release archive.
	DownloadURL string `json:"download_url"`

	// Status is the release status for the given distribution.
	Status ReleaseStatus `json:"status"`

	// Version is the specific version this DownloadURL pertains to.
	Version version.JSON `json:"version"`
}

DownloadURL contains information about a download URL for a given release.

type Favorite

type Favorite struct {
	// Author is the PAUSE ID of the author.
	Author string `json:"author"`

	// Date is the date the user favorited the distribution.
	Date iso8601.Time `json:"date"`

	// Distribution is the name of the distribution.
	Distribution string `json:"distribution"`

	// ID is the ID of the favorite.
	ID string `json:"id"`

	// Release is the name of the release.
	Release string `json:"release"`

	// User is the UUID of the user who favorited the distribution.
	User string `json:"user"`
	// contains filtered or unexported fields
}

Favorite is an object specifying info about a favorite on MetaCPAN.

type File

type File struct {
	FileInfo
	// contains filtered or unexported fields
}

File is an object specifying info about a file on MetaCPAN.

func (*File) MetaCPANURL

func (f *File) MetaCPANURL() string

func (*File) Pod

func (f *File) Pod(kind PodKind) (string, error)

func (*File) Source

func (f *File) Source() (string, error)

type FileInfo

type FileInfo struct {
	// Module is a list of modules indexed from within the file.
	Module []struct {
		// Name is the name of the module.
		Name string `json:"name"`

		// Indexed indicates whether the module is indexed by MetaCPAN.
		Indexed bool `json:"indexed"`

		// Authorized indicates whether the module is an authorized
		// upload.
		Authorized bool `json:"authorized"`

		// Version is the module's version.
		Version version.JSON `json:"version"`

		// VersionNumified is the version rendered as a float64
		VersionNumified float64 `json:"version_numified"`

		// AssociatedPod is the path to the POD documentation for the
		// given module.
		AssociatedPod string `json:"associated_pod"`
	} `json:"module"`

	// Stat contains info about the file similar to os.FileStat
	Stat Stat `json:"stat"`

	// Abstract contains the abstract portion of the name from the pod
	// documentation.
	Abstract string `json:"abstract"`

	// Author contains the author's Pause ID.
	Author string `json:"author"`

	// Date indicates when the file was uploaded.
	Date iso8601.Time `json:"date"`

	// Description contains the info from the DESCRIPTION field in a file's
	// documentation, if it exists.
	Description string `json:"description"`

	// Distribution is the name of the distribution that contains the file.
	Distribution string `json:"distribution"`

	// Documentation is the name of the module contained by this File.
	Documentation string `json:"documentation"`

	// DownloadURL is the url for the distribution archive for this file.
	DownloadURL string `json:"download_url"`

	// ID is the MetaCPAN ID for this file.
	ID string `json:"id"`

	// Level is the depth of the file from the archive root.
	Level int `json:"level"`

	// Maturity is the release maturity, i.e. release or developer
	Maturity Maturity `json:"maturity"`

	// Mime is the file's mime type.
	Mime string `json:"mime"`

	// Name is the file's name without any directory path
	Name string `json:"name"`

	// Path is the file path within the archive.
	Path string `json:"path"`

	// PodLines contains information about the documentation lines and
	// layout.
	PodLines [][]int `json:"pod_lines"`

	// Release is the release that contains this particular file.
	Release string `json:"release"`

	// SLOC is the number of lines of code in the file.
	SLOC int `json:"sloc"`

	// SLOP is the number of lines of POD in the file.
	SLOP int `json:"slop"`

	// Status is the release status for the file.
	Status ReleaseStatus `json:"status"`

	// Version is the version of the distribution that contains this file.
	Version version.JSON `json:"version"`

	// VersionNumified is the version of the distribution that contains
	// this file, in float format.
	VersionNumified float64 `json:"version_numified"`

	// Authorized indicates whether this file is from an authorized upload.
	Authorized bool `json:"authorized"`

	// Binary indicates whether this file has binary data.
	Binary bool `json:"binary"`

	// Deprecated indicates whether this file is deprecated.
	Deprecated bool `json:"deprecated"`

	// Directory indicates whether this file is a directory.
	Directory bool `json:"directory"`

	// Indexed indicates whether the content of the file is indexed.
	Indexed bool `json:"indexed"`
}

type Maturity

type Maturity = internal.XEnum[MaturityKind]

type MaturityKind

type MaturityKind int
const (
	MaturityKindReleased MaturityKind
	MaturityKindDeveloper
)

func (MaturityKind) Parse

func (m MaturityKind) Parse(s string) (MaturityKind, error)

func (MaturityKind) String

func (m MaturityKind) String() string

type Mirror

type Mirror struct {
	AKAName  string `json:"aka_name"`
	AOrCName string `json:"A_or_CNAME"`
	CCode    string `json:"ccode"`
	City     string `json:"city"`
	Contact  []struct {
		ContactSite string `json:"contact_site"`
		ContactUser string `json:"contact_user"`
	} `json:"contact"`
	Country      string       `json:"country"`
	DNSRR        string       `json:"dnsrr"`
	FTP          string       `json:"ftp"`
	Freq         string       `json:"freq"`
	HTTP         string       `json:"http"`
	InceptDate   iso8601.Time `json:"inceptdate"`
	Location     [2]float64   `json:"location"`
	Name         string       `json:"name"`
	Note         string       `json:"note"`
	Organization string       `json:"org"`
	RSync        string       `json:"rsync"`
	Region       string       `json:"region"`
	ReitreDate   iso8601.Time `json:"reitredate"`
	Src          string       `json:"src"`
	Tz           string       `json:"tz"`
}

type Module

type Module struct {
	FileInfo
	// contains filtered or unexported fields
}

func (*Module) MetaCPANURL

func (m *Module) MetaCPANURL() string

func (*Module) Package

func (m *Module) Package() (*Package, error)

func (*Module) Permission

func (m *Module) Permission() (*Permission, error)

type Package

type Package struct {
	// Author is the PAUSE ID of the author
	Author string `json:"author"`

	// ModuleName is the name of the module of the package.
	ModuleName string `json:"module_name"`

	// Distribution is the distribution in which this module exists.
	Distribution string `json:"distribution"`

	// DistVersion is the latest version of the distribution.
	DistVersion version.JSON `json:"dist_version"`

	// Version is the latest version of the module
	Version version.JSON `json:"version"`
}

type Permission

type Permission struct {
	// The name of the module this permission belongs to.
	ModuleName string `json:"module_name"`

	// Owner is the owner of the module.
	Owner string `json:"owner"`

	// CoMaintainers is the list of other maintainers with permissions for
	// the module.
	CoMaintainers []string `json:"co_maintainers"`
}

type Phase

type Phase = internal.XEnum[PhaseKind]

type PhaseKind

type PhaseKind int
const (
	PhaseKindBuild PhaseKind
	PhaseKindConfigure
	PhaseKindDevelop
	PhaseKindRuntime
	PhaseKindTest
)

func (PhaseKind) Parse

func (p PhaseKind) Parse(s string) (PhaseKind, error)

func (PhaseKind) String

func (p PhaseKind) String() string

type Pod

type Pod struct {
	// Name is the name of the module this Pod belongs to.
	Name string `json:"name"`

	// URLPrefix is the url to be used for the links within the POD
	// documentation.
	URLPrefix string `json:"url_prefix"`

	// XPod is the raw POD for the file.
	XPod string `json:"x_pod"`

	// HTML is the POD in html form.
	HTML string `json:"html"`

	// XMarkdown is the POD in markdown form.
	XMarkdown string `json:"x_markdown"`

	// Plain is the POD formatted as plain text, such as you might find
	Plain string `json:"plain"`
	// contains filtered or unexported fields
}

func NewPod

func NewPod(name, urlPrefix string, mc *Client) (*Pod, error)

type PodKind

type PodKind string
const (
	PodKindHTML      PodKind = "html"
	PodKindPlain     PodKind = "plain"
	PodKindXMarkdown PodKind = "x_markdown"
	PodKindXPod      PodKind = "x_pod"
)

type Rating

type Rating struct {
	Date         string `json:"date"`
	Release      string `json:"release"`
	Author       string `json:"author"`
	Details      string `json:"details"`
	Rating       string `json:"rating"`
	Distribution string `json:"distribution"`
	Helpful      int    `json:"helpful"`
	User         string `json:"user"`
	// contains filtered or unexported fields
}

type Relationship

type Relationship = internal.XEnum[RelationshipKind]

type RelationshipKind

type RelationshipKind int
const (
	RelationshipKindRequires RelationshipKind
	RelationshipKindRecommends
	RelationshipKindSuggests
	RelationshipKindConflicts
)

func (RelationshipKind) Parse

func (RelationshipKind) String

func (r RelationshipKind) String() string

type Release

type Release struct {
	Dependency []struct {
		Phase        Phase        `json:"phase"`
		Relationship Relationship `json:"relationship"`
		Module       string       `json:"module"`
		Version      version.JSON `json:"version"`
	} `json:"dependency"`
	Stat struct {
		MTime int `json:"mtime"`
		Mode  int `json:"mode"`
		Size  int `json:"size"`
	} `json:"stat"`
	Tests struct {
		Unknown int `json:"unknown"`
		Pass    int `json:"pass"`
		Fail    int `json:"fail"`
		NA      int `json:"na"`
	} `json:"tests"`
	Abstract        string        `json:"abstract"`
	Archive         string        `json:"archive"`
	Author          string        `json:"author"`
	ChecksumMD5     string        `json:"checksum_md5"`
	ChecksumSHA256  string        `json:"checksum_sha256"`
	Date            string        `json:"date"`
	Distribution    string        `json:"Distribution"`
	DownloadURL     string        `json:"download_url"`
	License         []string      `json:"license"`
	MainModule      string        `json:"main_module"`
	Maturity        Maturity      `json:"maturity"`
	Metadata        cm.Spec       `json:"metadata"`
	Name            string        `json:"name"`
	Provides        []string      `json:"provides"`
	Resources       cm.Resources  `json:"resources"`
	Status          ReleaseStatus `json:"status"`
	Version         version.JSON  `json:"version"`
	VersionNumified float64       `json:"version_numified"`
	Authorized      bool          `json:"authorized"`
	Deprecated      bool          `json:"deprecated"`
	First           bool          `json:"first"`
	// contains filtered or unexported fields
}

func (*Release) Changes

func (r *Release) Changes() (string, error)

func (*Release) MetaCPANURL

func (r *Release) MetaCPANURL() string

func (*Release) UnmarshalJSON

func (r *Release) UnmarshalJSON(data []byte) error

type ReleaseStatus

type ReleaseStatus = internal.XEnum[ReleaseStatusKind]

type ReleaseStatusKind

type ReleaseStatusKind int
const (
	ReleaseStatusKindLatest ReleaseStatusKind
	ReleaseStatusKindCPAN
	ReleaseStatusKindBackpan
)

func (ReleaseStatusKind) Parse

func (ReleaseStatusKind) String

func (s ReleaseStatusKind) String() string

type Request

type Request[T result] struct {
	// contains filtered or unexported fields
}

func NewRequest

func NewRequest[T result](domain, baseURL string, debug bool,
	mc *Client) *Request[T]

func (*Request[T]) DisableDebug

func (r *Request[T]) DisableDebug()

func (*Request[T]) EnableDebug

func (r *Request[T]) EnableDebug()

func (*Request[T]) Fetch

func (r *Request[T]) Fetch(s string, m map[string]interface{}) (T, error)

func (*Request[T]) IsDebug

func (r *Request[T]) IsDebug() bool

func (*Request[T]) SSearch

func (r *Request[T]) SSearch(params map[string]interface{}) (*Scroll[T],
	error)

func (*Request[T]) SetClient

func (r *Request[T]) SetClient(mc *Client) error

type ResultSet

type ResultSet[T result] interface {
	HasScroller() bool
	Scroller() *Scroll[T]
	Items() []T
	Aggregations() map[string]interface{}
	Next() (T, error)
	Total() int
	// contains filtered or unexported methods
}

type Scroll

type Scroll[T result] struct {
	// contains filtered or unexported fields
}

func NewScroll

func NewScroll[T result](baseURL string, dur time.Duration,
	size uint16) *Scroll[T]

func (*Scroll[T]) Next

func (s *Scroll[T]) Next() (T, error)

func (*Scroll[T]) Total

func (s *Scroll[T]) Total() int

func (*Scroll[T]) Type

func (s *Scroll[T]) Type() Type

func (*Scroll[T]) UnmarshalJSON

func (s *Scroll[T]) UnmarshalJSON(data []byte) error

type Stat

type Stat struct {
	ModTime time.Time   `json:"mtime"`
	Mode    fs.FileMode `json:"mode"`
	Size    int64       `json:"size"`
}

func (*Stat) MarshalJSON

func (s *Stat) MarshalJSON() ([]byte, error)

func (*Stat) UnmarshalJSON

func (s *Stat) UnmarshalJSON(data []byte) error

type Type

type Type int
const (
	TypeAuthor Type
	TypeDistribution
	TypeFavorite
	TypeFile
	TypeModule
	TypeRating
	TypeRelease
)

func (*Type) MarshalJSON

func (r *Type) MarshalJSON() ([]byte, error)

func (*Type) String

func (r *Type) String() string

func (*Type) UnmarshalJSON

func (r *Type) UnmarshalJSON(data []byte) error

Jump to

Keyboard shortcuts

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