/ 
WWW-PGXN-v0.13.0
River stage one • 1 direct dependent • 1 total dependent
/ WWW::PGXN

Name

WWW::PGXN - Interface to PGXN mirrors and the PGXN API

Synopsis

my $pgxn = WWW::PGXN->new( url => 'https://api.pgxn.org/' );
my $dist = $pgxn->get_distribution('pgTAP');
$dist->download_to('.');

Description

This module provide a simple Perl interface over the the PGXN API. It also works with any PGXN mirror server. It provides an interface for finding distributions, extensions, users, and tags, as well as for accessing documentation, lists of users, and the full-text search interface. WWW::PGXN is designed to make it dead simple for applications such as web apps and command-line clients to get the data they need from a PGXN mirror with a minimum of hassle, including via the file system, if there is a local mirror.

PGXN is a CPAN-inspired network for distributing extensions for the PostgreSQL RDBMS. All of the infrastructure tools, however, have been designed to be used to create networks for distributing any kind of release distributions and for providing a lightweight static file JSON REST API. As such, WWW::PGXN should work with any mirror that gets its data from a PGXN::Manager-managed master server, and with any PGXN::API-powered server.

Interface

Constructor

new

my $pgxn = WWW::PGXN->new(url => 'https://api.pgxn.org/');

Construct a new WWW::PGXN object. The only required attribute is url. The supported parameters are:

url

The base URL for the API server or mirror the client should fetch from. Required.

proxy

URL of a proxy server to use. Ignored if url is a file: URL.

Instance Accessors

url

my $url = $pgxn->url;
$pgxn->url($url);

Get or set the URL for the PGXN mirror or API server. May be a file: URL, in which case the API will be accessed purely via the file system. Otherwise it uses HTTP::Tiny to access the API.

proxy

my $proxy = $pgxn->proxy;
$pgxn->proxy($proxy);

Get or set the URL for a proxy server to use. Ignored if url is a file: URL.

Instance Methods

get_distribution

my $dist = $pgxn->get_distribution($dist_name, $version);

Finds the data for a distribution. Returns a WWW::PGXN::Distribution object. The first argument, the name of the distribution, is required. The second argument, the version, is optional. If not present, the current stable release will be retrieved.

If the distribution cannot be found, undef will be returned. For any other errors, an exception will be thrown.

get_extension

my $extension = $pgxn->get_extension($extension_name);

Finds the data for the named extension. Returns a WWW::PGXN::Extension object. If the extension cannot be found, undef will be returned. For any other errors, an exception will be thrown.

get_user

my $user = $pgxn->get_user($user_name);

Finds the data for the named user. Returns a WWW::PGXN::User object. If the user cannot be found, undef will be returned. For any other errors, an exception will be thrown.

get_tag

my $tag = $pgxn->get_tag($tag_name);

Finds the data for the named tag. Returns a WWW::PGXN::Tag object. If the tag cannot be found, undef will be returned. For any other errors, an exception will be thrown.

get_stats

my $stats = $pgxn->get_stats($stats_name);

Returns the contents of a stats file. The current stats names are:

  • summary

  • dist

  • extension

  • user

  • tag

get_userlist

my $userlist = $pgxn->get_userlist('t');

Returns a the contents of a user list, which contains data on all users whose nickname starts with the specified lowercase ASCII letter. If called against a mirror, this method always returns undef. When called against an API, it will always return an array of users. If there is no user list file for the specified letter, the array will be empty. Otherwise, it will contain a list of hash references with two keys:

  • user

    The user's nickname.

  • name

    The user's full name.

mirrors

my @mirrors = $pgxn->mirrors;

Returns a list of WWW::PGXN::Mirror objects representing all of the mirrors in the network to which the PGXN API or mirror server belongs.

spec

my $spec = $pgxn->spec;
my $html = $pgxn->spec('html');

Returns the contents of the PGXN Meta Spec document. By default, this is a text document. But you can get an HTML version by passing HTML as the argument. Pass txt to be specific about wanting the text document.

my $results = $pgxn->search( query => 'tap' );
$results    = $pgxn->search( query => 'wicked', index => 'dists' );

Sends a search query to the API server (not supported for mirrors). For an API server accessed via a file: URL, PGXN::API::Searcher is required and used to fetch the results directly. Otherwise, an HTTP request is sent to the server as usual.

The supported parameters are:

query

The search query. See Lucy::Search::QueryParser for the supported syntax of the query. Required.

index

The name of the search index to query. The default is "docs". The possible values are:

docs
dists
extensions
users
tags
offset

How many hits to skip before showing results. Defaults to 0.

limit

Maximum number of hits to return. Defaults to 50 and may not be greater than 1024.

Currently the return value is a hash composed directly from the JSON returned by the search request. See PGXN::API::Searcher for details on its structure.

meta_url_for

my $meta_url = $pgxn->meta_url_for($dist_name, $dist_version);

Returns the URL for a distribution meta file. This is the file fetched by get_distribution().

download_url_for

my $download_url = $pgxn->download_url_for($dist_name, $dist_version);

Returns the download URL for a distribution and version. This is the zipped archive file containing the distribution itself.

source_url_for

my $source_url = $pgxn->source_url_for($dist_name, $dist_version);

Returns the URL for a distribution source file. This URL is available only from an API server, not a mirror.

html_doc_url_for

my $doc_url = $pgxn->html_doc_url_for($dist_name, $dist_version, $doc_path);

Returns the URL for a distribution documentation file. This URL is available only from an API server, not a mirror.

extension_url_for

my $extension_url = $pgxn->extension_url_for($extension_name);

Returns the URL for an extension metadata file. This is the file fetched by get_extension().

user_url_for

my $user_url = $pgxn->user_url_for($nickname);

Returns the URL for an user metadata file. This is the file fetched by get_user().

tag_url_for

my $tag_url = $pgxn->tag_url_for($tag_name);

Returns the URL for an tag metadata file. This is the file fetched by get_tag().

meta_path_for

my $meta_path = $pgxn->meta_path_for($dist_name, $dist_version);

Returns the path for a distribution meta file.

download_path_for

my $download_path = $pgxn->download_path_for($dist_name, $dist_version);

Returns the download path for a distribution and version.

source_path_for

my $source_path = $pgxn->source_path_for($dist_name, $dist_version);

Returns the path for a distribution source file. This path is available only from an API server, not a mirror.

html_doc_path_for

my $doc_path = $pgxn->html_doc_path_for($dist_name, $dist_version, $doc_path);

Returns the PATH for a distribution documentation file. This PATH is available only from an API server, not a mirror.

extension_path_for

my $extension_path = $pgxn->extension_path_for($extension_name);

Returns the path for an extension metadata file.

user_path_for

my $user_path = $pgxn->user_path_for($nickname);

Returns the path for an user metadata file.

tag_path_for

my $tag_path = $pgxn->tag_path_for($tag_name);

Returns the path for an tag metadata file.

See Also

  • PGXN

    The PostgreSQL Extension Network, the reference implementation of the PGXN infrastructure.

  • PGXN::API

    Creates and serves a PGXN API implementation from a PGXN mirror.

  • API Documentation

    Comprehensive documentation of the REST API provided by PGXN::API and consumed by WWW::PGXN.

  • PGXN::Manager

    Server for managing a master PGXN mirror and allowing users to upload distributions to it.

Support

This module is stored in a public GitHub repository. Feel free to fork and contribute! Please file bug reports via GitHub Issues

Author

David E. Wheeler <david@justatheory.com>

Copyright and License

Copyright (c) 2011-2024 David E. Wheeler. Some Rights Reserved.

This module is free software; you can redistribute it and/or modify it under the same terms as Perl itself.