{"id":17488422,"url":"https://github.com/metacpan/metacpan-client","last_synced_at":"2025-04-22T15:24:58.213Z","repository":{"id":14823860,"uuid":"17546535","full_name":"metacpan/MetaCPAN-Client","owner":"metacpan","description":"Home of the official MetaCPAN Perl API client.","archived":false,"fork":false,"pushed_at":"2024-11-25T19:14:25.000Z","size":654,"stargazers_count":24,"open_issues_count":4,"forks_count":23,"subscribers_count":17,"default_branch":"master","last_synced_at":"2025-04-19T09:29:31.182Z","etag":null,"topics":["cpan","metacpan","perl"],"latest_commit_sha":null,"homepage":null,"language":"Perl","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":"tiagopog/jsonapi-utils","license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/metacpan.png","metadata":{"files":{"readme":"README.pod","changelog":"Changes","contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2014-03-08T17:05:11.000Z","updated_at":"2025-04-15T16:45:24.000Z","dependencies_parsed_at":"2022-08-29T01:51:24.419Z","dependency_job_id":"9776f026-9b21-47aa-9f45-41ff48cf17df","html_url":"https://github.com/metacpan/MetaCPAN-Client","commit_stats":{"total_commits":547,"total_committers":28,"mean_commits":"19.535714285714285","dds":0.663619744058501,"last_synced_commit":"70a21c7da08bbfee02c45786e20e61bcac3d862f"},"previous_names":[],"tags_count":41,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metacpan%2FMetaCPAN-Client","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metacpan%2FMetaCPAN-Client/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metacpan%2FMetaCPAN-Client/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/metacpan%2FMetaCPAN-Client/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/metacpan","download_url":"https://codeload.github.com/metacpan/MetaCPAN-Client/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":250265778,"owners_count":21402165,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["cpan","metacpan","perl"],"created_at":"2024-10-19T04:07:08.610Z","updated_at":"2025-04-22T15:24:58.165Z","avatar_url":"https://github.com/metacpan.png","language":"Perl","funding_links":[],"categories":[],"sub_categories":[],"readme":"=pod\n\n=encoding UTF-8\n\n=head1 NAME\n\nMetaCPAN::Client - A comprehensive, DWIM-featured client to the MetaCPAN API\n\n=head1 VERSION\n\nversion 2.033000\n\n=head1 SYNOPSIS\n\n    # simple usage\n    my $mcpan  = MetaCPAN::Client-\u003enew();\n    my $author = $mcpan-\u003eauthor('XSAWYERX');\n    my $dist   = $mcpan-\u003edistribution('MetaCPAN-Client');\n\n    # advanced usage with cache (contributed by Kent Fredric)\n    use CHI;\n    use WWW::Mechanize::Cached;\n    use HTTP::Tiny::Mech;\n    use MetaCPAN::Client;\n\n    my $mcpan = MetaCPAN::Client-\u003enew(\n      ua =\u003e HTTP::Tiny::Mech-\u003enew(\n        mechua =\u003e WWW::Mechanize::Cached-\u003enew(\n          cache =\u003e CHI-\u003enew(\n            driver   =\u003e 'File',\n            root_dir =\u003e '/tmp/metacpan-cache',\n          ),\n        ),\n      ),\n    );\n\n    # now $mcpan caches results\n\n=head1 DESCRIPTION\n\nThis is a hopefully-complete API-compliant client to MetaCPAN\n(L\u003chttps://metacpan.org\u003e) with DWIM capabilities, to make your life easier.\n\n=head1 ATTRIBUTES\n\n=head2 request\n\nInternal attribute representing the request object making the request to\nMetaCPAN and analyzing the results. You probably don't want to set this, nor\nshould you have any usage of it.\n\n=head2 ua\n\nIf provided, L\u003cMetaCPAN::Client::Request\u003e will use the user agent object\ninstead of the default, which is L\u003cHTTP::Tiny\u003e.\n\nThen it can be used to fetch the user agent object used by\nL\u003cMetaCPAN::Client::Request\u003e.\n\n=head2 domain\n\nIf given, will be used to alter the API domain.\n\n=head2 debug\n\nIf given, errors will include some low-level detailed message.\n\n=head1 METHODS\n\n=head2 author\n\n    my $author = $mcpan-\u003eauthor('XSAWYERX');\n    my $author = $mcpan-\u003eauthor($search_spec);\n\nFinds an author by either its PAUSE ID or by a search spec defined by a hash\nreference. Since it is common to many other searches, it is explained below\nunder C\u003cSEARCH SPEC\u003e.\n\nReturns a L\u003cMetaCPAN::Client::Author\u003e object on a simple search (PAUSE ID), or\na L\u003cMetaCPAN::Client::ResultSet\u003e object populated with\nL\u003cMetaCPAN::Client::Author\u003e objects on a complex (L\u003csearch spec based|/\"SEARCH SPEC\"\u003e) search.\n\n=head2 cover\n\n    my $cover = $mcpan-\u003ecover('Moose-2.2007');\n\nReturns a L\u003cMetaCPAN::Client::Cover\u003e object.\n\n=head2 distribution\n\n    my $dist = $mcpan-\u003edistribution('MetaCPAN-Client');\n    my $dist = $mcpan-\u003edistribution($search_spec);\n\nFinds a distribution by either its distribution name or by a search spec\ndefined by a hash reference. Since it is common to many other searches, it is\nexplained below under C\u003cSEARCH SPEC\u003e.\n\nReturns a L\u003cMetaCPAN::Client::Distribution\u003e object on a simple search\n(distribution name), or a L\u003cMetaCPAN::Client::ResultSet\u003e object populated with\nL\u003cMetaCPAN::Client::Distribution\u003e objects on a complex (L\u003csearch spec based|/\"SEARCH SPEC\"\u003e)\nsearch.\n\n=head2 file\n\nReturns a L\u003cMetaCPAN::Client::File\u003e object.\n\n=head2 favorite\n\n    my $favorite = $mcpan-\u003efavorite({ distribution =\u003e 'Moose' });\n\nReturns a L\u003cMetaCPAN::Client::ResultSet\u003e object containing\nL\u003cMetaCPAN::Client::Favorite\u003e results.\n\n=head2 rating\n\n    my $rating = $mcpan-\u003erating({ distribution =\u003e 'Moose' });\n\nReturns a L\u003cMetaCPAN::Client::ResultSet\u003e object containing\nL\u003cMetaCPAN::Client::Rating\u003e results.\n\n=head2 release\n\n    my $release = $mcpan-\u003erelease('MetaCPAN-Client');\n    my $release = $mcpan-\u003erelease($search_spec);\n\nFinds a release by either its distribution name or by a search spec defined by\na hash reference. Since it is common to many other searches, it is explained\nbelow under C\u003cSEARCH SPEC\u003e.\n\nReturns a L\u003cMetaCPAN::Client::Release\u003e object on a simple search (release name),\nor a L\u003cMetaCPAN::Client::ResultSet\u003e object populated with\nL\u003cMetaCPAN::Client::Release\u003e objects on a complex (L\u003csearch spec based|/\"SEARCH SPEC\"\u003e) search.\n\n=head2 mirror\n\n    my $mirror = $mcpan-\u003emirror('kr.freebsd.org');\n\nReturns a L\u003cMetaCPAN::Client::Mirror\u003e object.\n\n=head2 module\n\n    my $module = $mcpan-\u003emodule('MetaCPAN::Client');\n    my $module = $mcpan-\u003emodule($search_spec);\n\nFinds a module by either its module name or by a search spec defined by a hash\nreference. Since it is common to many other searches, it is explained below\nunder C\u003cSEARCH SPEC\u003e.\n\nReturns a L\u003cMetaCPAN::Client::Module\u003e object on a simple search (module name), or\na L\u003cMetaCPAN::Client::ResultSet\u003e object populated with\nL\u003cMetaCPAN::Client::Module\u003e objects on a complex (L\u003csearch spec based|/\"SEARCH SPEC\"\u003e) search.\n\n=head2 package\n\n    my $package = $mcpan-\u003epackage('MooseX::Types');\n\nReturns a L\u003cMetaCPAN::Client::Package\u003e object.\n\n=head2 permission\n\n    my $permission = $mcpan-\u003epermission('MooseX::Types');\n\nReturns a L\u003cMetaCPAN::Client::Permission\u003e object.\n\n=head2 reverse_dependencies\n\n    my $deps = $mcpan-\u003ereverse_dependencies('Search::Elasticsearch');\n\nall L\u003cMetaCPAN::Client::Release\u003e objects of releases that are directly\ndependent on a given module, returned as L\u003cMetaCPAN::Client::ResultSet\u003e.\n\n=head2 rev_deps\n\nAlias to C\u003creverse_dependencies\u003e described above.\n\n=head2 autocomplete\n\n    my $ac = $mcpan-\u003eautocomplete('Danc');\n\nCall the search/autocomplete endpoint with a query string.\n\nReturns an array reference.\n\n=head2 autocomplete_suggest\n\n    my $ac = $mcpan-\u003eautocomplete_suggest('Moo');\n\nCall the search/autocomplete/suggest endpoint with a query string.\n\nReturns an array reference.\n\n=head2 recent\n\n    my $recent = $mcpan-\u003erecent(10);\n    my $recent = $mcpan-\u003erecent('today');\n\nreturn the latest N releases, or all releases from today.\n\nreturns a L\u003cMetaCPAN::Client::ResultSet\u003e of L\u003cMetaCPAN::Client::Release\u003e.\n\n=head2 pod\n\nGet POD for given file/module name.\nreturns a L\u003cMetaCPAN::Client::Pod\u003e object, which supports various output\nformats (html, plain, x_pod \u0026 x_markdown).\n\n    my $pod = $mcpan-\u003epod('Moo')-\u003ehtml;\n    my $pod = $mcpan-\u003epod('Moo', { url_prefix =\u003e $prefix })-\u003ehtml;\n\n=head2 download_url\n\nRetrieve information from the 'download_url' endpoint\n\n    my $download_url = $mcpan-\u003edownload_url($distro, [$version_or_range, $dev]);\n\n    # request the last available version\n    my $download_url = $mcpan-\u003edownload_url('Moose');\n\n    # request an older version\n    my $download_url = $mcpan-\u003edownload_url('Moose', '1.01');\n\n    # using a range\n    my $download_url = $mcpan-\u003edownload_url('Moose', '\u003c=1.01');\n    my $download_url = $mcpan-\u003edownload_url('Moose', '\u003e1.01,\u003c=2.00');\n\nRange operators are '== != \u003c= \u003e= \u003c \u003e !'.\nYou can use a comma ',' to add multiple rules.\n\n    # requesting dev release\n    my $download_url = $mcpan-\u003edownload_url('Moose', '\u003e1.01', 1);\n\nReturns a L\u003cMetaCPAN::Client::DownloadURL\u003e object\n\n=head2 all\n\nRetrieve all matches for authors/modules/distributions/favorites or releases.\n\n    my $all_releases = $mcpan-\u003eall('releases')\n\nWhen called with a second parameter containing a hash ref,\nwill support the following keys:\n\n=head3 fields\n\nSee SEARCH PARAMS.\n\n   my $all_releases = $mcpan-\u003eall('releases', { fields =\u003e [...] })\n\n=head3 _source\n\nSee SEARCH PARAMS.\n\n   my $all_releases = $mcpan-\u003eall('releases', { _source =\u003e [...] })\n\n=head3 es_filter\n\nPass a raw Elasticsearch filter structure to reduce the number\nof elements returned by the query.\n\n    my $some_releases = $mcpan-\u003eall('releases', { es_filter =\u003e {...} })\n\n=head2 BUILDARGS\n\nInternal construction wrapper. Do not use.\n\n=head1 SEARCH PARAMS\n\nMost searches take params as an optional hash-ref argument.\nthese params will be passed to the search action.\n\nIn non-scrolled searches, 'fields' filter is the only supported\nparameter ATM.\n\n=head2 fields\n\nFilter the fields to reduce the amount of data pulled from MetaCPAN.\ncan be passed as a csv list or an array ref.\n\n    my $module = $mcpan-\u003emodule('Moose', { fields =\u003e \"version,author\" });\n    my $module = $mcpan-\u003emodule('Moose', { fields =\u003e [qw/version author/] });\n\n=head2 _source\n\nNote: this param and its description are a bit too Elasticsearch specific.\njust like 'es_filter' - use only if you know what you're dealing with.\n\nSome fields are not indexed in Elasticsearch but stored as part of\nthe entire document.\n\nThese fields can still be read, but without the internal Elasticsearch\noptimizations and the server will internally read the whole document.\n\nWhy do we even need those? because we don't index everything and some things\nwe can't to begin with (like non-leaf fields that hold a structure)\n\n    my $module = $mcpan-\u003eall('releases', { _source =\u003e \"stat\" });\n\n=head2 scroller_time\n\nNote: please use with caution.\n\nThis parameter will set the maximum lifetime of the Elasticsearch scroller on\nthe server (default = '5m').  Normally you do not need to set this value (as\ntweaking this value can affect resources on the server).  In case you do, you\nprobably need to check the efficiency of your code/queries.  (Feel free to\nreach out to us for assistance).\n\n    my $module = $mcpan-\u003eall('releases', { scroller_time =\u003e '3m' });\n\n=head2 scroller_size\n\nNote: please use with caution.\n\nThis parameter will set the buffer size to be pulled from Elasticsearch\nwhen scrolling (default = 1000).\nThis will affect query performance and memory usage, but you will still\nget an iterator back to fetch one object at a time.\n\n    my $module = $mcpan-\u003eall('releases', { scroller_size =\u003e 500 });\n\n=head3 sort\n\nPass a raw Elasticsearch sort specification for the query.\n\n    my $some_releases = $mcpan-\u003eall('releases', { sort =\u003e [{ date =\u003e { order =\u003e 'desc' } }] })\n\nNote: this param and is a bit too specific to Elasticsearch.  Just like\nL\u003c/es_filter\u003e, only use this if you know what you're dealing with.\n\n=head1 SEARCH SPEC\n\nThe hash-based search spec is common to many searches. It is quite\nfeature-rich and allows you to disambiguate different types of searches.\n\nBasic search specs just contain a hash of keys and values:\n\n    my $author = $mcpan-\u003eauthor( { name =\u003e 'Micha Nasriachi' } );\n\n    # the following is the same as -\u003eauthor('MICKEY')\n    my $author = $mcpan-\u003eauthor( { pauseid =\u003e 'MICKEY' } );\n\n    # find all people named Dave, not covering Davids\n    # will return a resultset\n    my $daves = $mcpan-\u003eauthor( { name =\u003e 'Dave *' } );\n\n=head2 OR\n\nIf you want to do a more complicated query that has an I\u003cOR\u003e condition,\nsuch as \"this or that\", you can use the following syntax with the C\u003ceither\u003e\nkey:\n\n    # any author named \"Dave\" or \"David\"\n    my $daves = $mcpan-\u003eauthor( {\n        either =\u003e [\n            { name =\u003e 'Dave *'  },\n            { name =\u003e 'David *' },\n        ]\n    } );\n\n=head2 AND\n\nIf you want to do a more complicated query that has an I\u003cAND\u003e condition,\nsuch as \"this and that\", you can use the following syntax with the C\u003call\u003e\nkey:\n\n    # any users named 'John' with a Gmail account\n    my $johns = $mcpan-\u003eauthor( {\n        all =\u003e [\n            { name  =\u003e 'John *'     },\n            { email =\u003e '*gmail.com' },\n        ]\n    } );\n\nOr, to get either the given version of a release, or the latest:\n\n    my $releases = $mcpan-\u003erelease( {\n        all =\u003e [\n          { distribution =\u003e 'GraphViz2' },\n          ($version ? { version =\u003e $version } : { status =\u003e 'latest' }),\n        ],\n    } );\n\nIf you want to do something even more complicated,\nYou can also nest your queries, e.g.:\n\n    my $gmail_daves_or_cpan_sams = $mcpan-\u003eauthor( {\n        either =\u003e [\n            { all =\u003e [ { name =\u003e 'Dave *'  },\n                       { email =\u003e '*gmail.com' } ]\n            },\n            { all =\u003e [ { name =\u003e 'Sam *' },\n                       { email =\u003e '*cpan.org' } ]\n            },\n        ],\n    } );\n\n=head2 NOT\n\nIf you want to filter out some of the results of an either/all query\nadding a I\u003cNOT\u003e filter condition, such as \"not these\", you can use the\nfollowing syntax with the C\u003cnot\u003e key:\n\n    # any author named \"Dave\" or \"David\"\n    my $daves = $mcpan-\u003eauthor( {\n        either =\u003e [\n            { name =\u003e 'Dave *'  },\n            { name =\u003e 'David *' },\n        ],\n        not =\u003e [\n            { email =\u003e '*gmail.com' },\n        ],\n    } );\n\n=head1 DESIGN\n\nThis module has three purposes:\n\n=over 4\n\n=item * Provide 100% of the MetaCPAN API\n\nThis module will be updated regularly on every MetaCPAN API change, and intends\nto provide the user with as much of the API as possible, no shortcuts. If it's\ndocumented in the API, you should be able to do it.\n\nBecause of this design decision, this module has an official MetaCPAN namespace\nwith the blessing of the MetaCPAN developers.\n\nNotice this module currently only provides the beta API, not the old\nsoon-to-be-deprecated API.\n\n=item * Be lightweight, to allow flexible usage\n\nWhile many modules would help make writing easier, it's important to take into\naccount how they affect your compile-time, run-time, overall memory\nconsumption, and CPU usage.\n\nBy providing a slim interface implementation, more users are able to use this\nmodule, such as long-running processes (like daemons), CLI or GUI applications,\ncron jobs, and more.\n\n=item * DWIM\n\nWhile it's possible to access the methods defined by the API spec, there's still\na matter of what you're really trying to achieve. For example, when searching\nfor I\u003c\"Dave\"\u003e, you want to find both I\u003cDave Cross\u003e and I\u003cDave Rolsky\u003e (and any\nother I\u003cDave\u003e), but you also want to search for a PAUSE ID of I\u003cDAVE\u003e, if one\nexists.\n\nThis is where DWIM comes in. This module provides you with additional generic\nmethods which will try to do what they think you want.\n\nOf course, this does not prevent you from manually using the API methods. You\nstill have full control over that, if that's what you wish.\n\nYou can (and should) read up on the general methods, which will explain how\ntheir DWIMish nature works, and what searches they run.\n\n=back\n\n=head1 AUTHORS\n\n=over 4\n\n=item *\n\nSawyer X \u003cxsawyerx@cpan.org\u003e\n\n=item *\n\nMickey Nasriachi \u003cmickey@cpan.org\u003e\n\n=back\n\n=head1 COPYRIGHT AND LICENSE\n\nThis software is copyright (c) 2016 by Sawyer X.\n\nThis is free software; you can redistribute it and/or modify it under\nthe same terms as the Perl 5 programming language system itself.\n\n=cut\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetacpan%2Fmetacpan-client","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmetacpan%2Fmetacpan-client","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmetacpan%2Fmetacpan-client/lists"}