Skip to content
CPAN Meta Browser
Perl JavaScript
Branch: master
Clone or download

Latest commit

Fetching latest commit…
Cannot retrieve the latest commit at this time.

Files

Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
lib/CPANMetaBrowser
log
public
templates
.gitignore
LICENSE
README.pod
cpan-meta-browser.conf.example
cpan-meta-browser.pl
cpanfile

README.pod

NAME

CPAN Meta Browser

DESCRIPTION

CPAN Meta Browser is a two-part application for convenient access to metadata for the CPAN (Comprehensive Perl Archive Network). The first part is a refresh command which will download this metadata and index it into the selected backend database. The second part is a web application which provides search functionality into the indexed database.

/path/to/cpan-meta-browser.pl refresh
hypnotoad /path/to/cpan-meta-browser.pl

The Module Index Search searches the CPAN packages index, which is the file 02packages.details.txt. This is the canonical mapping of module name to the latest authorized stable release of that module, maintained by PAUSE and used by CPAN installers when given a module to install.

The Permissions Search searches the PAUSE permissions database, which is the file 06perms.txt. This is the listing of authors that can upload new stable releases of a module and have it indexed, and that can modify the permissions for that module name. The first-come permission, granted to the first user to upload a module name, has ultimate authority on the name, and can add or remove any other user's permissions. The permission manager permission can add or remove other co-maint permissions. The co-maint permission can only remove their own permission. Note that these module permissions are not hierarchical. An author must have permissions for each individual module name they wish to have indexed.

The Author Search searches the CPAN authors database, which is the file 00whois.xml. This contains public details of the PAUSE accounts.

INSTALLATION

Perl v5.20.0 or higher is required. Perl dependencies are listed in cpanfile. They can be installed by running:

cpanm --installdeps .

CONFIGURATION

CPAN Meta Browser is configured by the file cpan-meta-browser.conf in the application home directory. The configuration file is a Perl hash. The hypnotoad key will be used to configure Hypnotoad if it is used to start the web application.

There are three backends available for CPAN Meta Browser. The backend can be set as backend in the configuration file, or CPAN_META_BROWSER_BACKEND in the environment.

The default backend is sqlite and requires Mojo::SQLite. sqlite_path may be set to a file path to store the database (must be in a writable directory, defaults to cpan-meta.sqlite in the application home directory).

The pg backend requires Mojo::Pg and a PostgreSQL server running at least version 9.6, with the pg_trgm extension. This is usually packaged in the -contrib package for PostgreSQL and must be installed in the database that will be used:

CREATE EXTENSION pg_trgm;

pg_url must also be set to a database connection URL in the form postgresql://user:password@host:port/database.

The redis backend requires Mojo::Redis and a Redis server running at least version 3.2.0. redis_url may be set to a database connection URL in the form redis://x:auth@host:port/database (defaults to redis://localhost:6379/0).

API

In addition to the browser interface, CPAN Meta Browser provides an API to the contents of the files it indexes. The endpoints below are relative to the installation path, such as https://cpanmeta.grinnz.com/. All endpoints return JSON, and the module and author parameters are case insensitive and trim surrounding whitespace.

packages

GET /api/v2/packages/:module
GET /api/v2/packages/:module?as_prefix=1
GET /api/v2/packages/:module?as_infix=1
GET /api/v2/packages?module=:module&module=:module

Retrieves details from the CPAN module index for the specified module name. If the as_prefix option is enabled, details are returned for all module names starting with the specified prefix. If the as_infix option is enabled, details are returned for all module names containing the specified infix. Multiple module names may be specified as query parameters, but this will disable prefix/infix matching.

# GET /api/v2/packages/Moose
{
   "data" : [
      {
         "module" : "Moose",
         "owner" : "STEVAN",
         "path" : "E\/ET\/ETHER\/Moose-2.2010.tar.gz",
         "uploader" : "ETHER",
         "version" : "2.2010"
      }
   ],
   "last_updated" : "1519669561"
}

# GET /api/v2/packages/Mojo::UserAgent?as_prefix=1
{
   "data" : [
      {
         "module" : "Mojo::UserAgent",
         "owner" : "SRI",
         "path" : "S\/SR\/SRI\/Mojolicious-7.69.tar.gz",
         "uploader" : "SRI","version":null
      },
      {
         "module" : "Mojo::UserAgent::Cached",
         "owner" : "NICOMEN",
         "path" : "N\/NI\/NICOMEN\/Mojo-UserAgent-Cached-1.06.tar.gz",
         "uploader" : "NICOMEN",
         "version" : "1.06"
      },
      ...
      {
         "module" : "Mojo::UserAgent::Transactor",
         "owner" : "SRI",
         "path" : "S\/SR\/SRI\/Mojolicious-7.69.tar.gz",
         "uploader" : "SRI",
         "version" : null
      }
   ],
   "last_updated" : "1519669561"
}

# GET /api/v2/packages?module=LWP&module=Mojo
{
  "data": [
    {
      "module": "LWP",
      "owner": "OALDERS",
      "path": "O/OA/OALDERS/libwww-perl-6.38.tar.gz",
      "uploader": "OALDERS",
      "version": "6.38"
    },
    {
      "module": "Mojo",
      "owner": "SRI",
      "path": "S/SR/SRI/Mojolicious-8.14.tar.gz",
      "uploader": "SRI",
      "version": null
    }
  ],
  "last_updated": 1556271962
}

perms

GET /api/v2/perms?author=:author
GET /api/v2/perms?module=:module
GET /api/v2/perms?author=:author&module=:module&as_prefix=1&other_authors=1
GET /api/v2/perms?module=:module&as_infix=1

Retrieves details from the CPAN permissions database for the specified author CPAN ID and/or module name. If the as_prefix option is enabled, details are returned for all module names starting with the specified prefix. If the as_infix option is enabled, details are returned for all module names containing the specified infix. If the other_authors option is enabled, details are returned for all authors with permissions for the matched modules, not just the specified author CPAN ID.

# GET /api/v2/perms?author=LWWWP
{
   "data" : [
      {
         "author" : "LWWWP",
         "best_permission" : "f",
         "module" : "HTML::Entities",
         "owner" : "LWWWP"
      },
      {
         "author" : "LWWWP",
         "best_permission" : "c",
         "module" : "HTML::FormatMarkdown",
         "owner" : "NIGELM"
      },
      ...
      {
         "author" : "LWWWP",
         "best_permission" : "f",
         "module" : "WWW::RobotRules",
         "owner" : "LWWWP"
      }
   ],
   "last_updated" : "1519670202"
}

# GET /api/v2/perms?author=LWWWP&other_authors=1
{
   "data" : [
      {
         "author" : "ETHER",
         "best_permission" : "c",
         "module" : "HTML::Entities",
         "owner" : "LWWWP"
      },
      {
         "author" : "GAAS",
         "best_permission" : "c",
         "module" : "HTML::Entities",
         "owner" : "LWWWP"
      },
      ...
      {
         "author" : "MSTROUT",
         "best_permission" : "c",
         "module" : "WWW::RobotRules",
         "owner" : "LWWWP"
      }
   ],
   "last_updated" : "1519670202"
}

# GET /api/v2/perms?author=LWWWP&module=LWP::UserAgent
{
   "data" : [
      {
         "author" : "LWWWP",
         "best_permission" : "f",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      }
   ],
   "last_updated" : "1519670202"
}

# GET /api/v2/perms?author=LWWWP&module=LWP::UserAgent&other_authors=1
{
   "data" : [
      {
         "author" : "ETHER",
         "best_permission" : "c",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      },
      {
         "author" : "GAAS",
         "best_permission" : "c",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      },
      ...
      {
         "author" : "OALDERS",
         "best_permission" : "c",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      }
   ],
   "last_updated" : "1519670802"
}

# GET /api/v2/perms?module=LWP::UserAgent&as_prefix=1
{
   "data" : [
      {
         "author" : "ETHER",
         "best_permission" : "c",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      },
      {
         "author" : "GAAS",
         "best_permission" : "c",
         "module" : "LWP::UserAgent",
         "owner" : "LWWWP"
      },
      ...
      {
         "author" : "SEKIMURA",
         "best_permission" : "f",
         "module" : "LWP::UserAgent::WithCache",
         "owner" : "SEKIMURA"
      }
   ],
   "last_updated" : "1519670802"
}

authors

GET /api/v2/authors/:author
GET /api/v2/authors/:author?as_prefix=1
GET /api/v2/authors/:author?as_infix=1

Retrieves details from the CPAN author database for the specified author CPAN ID. If the as_prefix option is enabled, details are returned for all author CPAN IDs starting with the specified prefix. If the as_infix option is enabled, details are returned for all author CPAN IDs containing the specified infix.

# GET /api/v2/authors/DBOOK
{
   "data" : [
      {
         "asciiname" : null,
         "author" : "DBOOK",
         "email" : null,
         "fullname" : "Dan Book",
         "has_cpandir" : true,
         "homepage" : "http:\/\/github.com\/Grinnz",
         "introduced" : 1417016502
      }
   ],
   "last_updated" : "1519670892"
}

# GET /api/v2/authors/XA?as_prefix=1
{
   "data" : [
      {
         "asciiname" : null,
         "author" : "XACHEN",
         "email" : "...",
         "fullname" : "Justin Cassidy",
         "has_cpandir" : false,
         "homepage" : null,
         "introduced" : 1251852104
      },
      {
         "asciiname" : "Grzegorz Rozniecki",
         "author" : "XAERXESS",
         "email" : "...",
         "fullname" : "Grzegorz Rożniecki",
         "has_cpandir" : true,
         "homepage" : null,
         "introduced" : 1360005262
      },
      ...
      {
         "asciiname" : null,
         "author" : "XAXXON",
         "email" : "...",
         "fullname" : "Zac Hansen",
         "has_cpandir" : false,
         "homepage" : "http:\/\/xaxxon.slackworks.com\/",
         "introduced" : 1133035986
      }
   ],
   "last_updated" : "1519670892"
}

COPYRIGHT AND LICENSE

This software is Copyright (c) 2017 by Dan Book <dbook@cpan.org>.

This is free software, licensed under:

The Artistic License 2.0 (GPL Compatible)

Bundled Perl 5 Raptor Copyright (c) 2012, Sebastian Riedel.

Licensed under the CC-SA License, Version 4.0 http://creativecommons.org/licenses/by-sa/4.0.

You can’t perform that action at this time.