The Perl and Raku Conference 2025: Greenville, South Carolina - June 27-29 Learn more

HAARG / MetaCPAN-API-0.51 / lib / MetaCPAN / API / POD.pm 

            

              
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
—
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103

              
use strict;
use warnings;
package MetaCPAN::API::POD;
# ABSTRACT: POD information for MetaCPAN::API
our $VERSION = '0.51';
use Carp;
use Moo::Role;
use namespace::autoclean;
# /pod/{module}
# /pod/{author}/{release}/{path}
sub pod {
    my $self  = shift;
    my %opts  = @_ ? @_ : ();
    my $url   = '';
    my $error = "Either provide 'module' or 'author and 'release' and 'path'";
    %opts or croak $error;
    if ( defined ( my $module = $opts{'module'} ) ) {
        $url = "pod/$module";
    } elsif (
        defined ( my $author  = $opts{'author'}  ) &&
        defined ( my $release = $opts{'release'} ) &&
        defined ( my $path    = $opts{'path'}    )
      ) {
        $url = "pod/$author/$release/$path";
    } else {
        croak $error;
    }
    # check content-type
    my %extra = ();
    if ( defined ( my $type = $opts{'content-type'} ) ) {
        $type =~ m{^ text/ (?: html|plain|x-pod|x-markdown ) $}x
            or croak 'Incorrect content-type provided';
        $extra{headers}{'content-type'} = $type;
    }
    $url = $self->base_url . "/$url";
    my $result = $self->ua->get( $url, \%extra );
    $result->{'success'}
        or croak "Failed to fetch '$url': " . $result->{'reason'};
    return $result->{'content'};
}
1;
__END__
=pod
=encoding UTF-8
=head1 NAME
MetaCPAN::API::POD - POD information for MetaCPAN::API
=head1 VERSION
version 0.51
=head1 DESCRIPTION
This role provides MetaCPAN::API with fetching POD information about modules
and distribution releases.
=head1 METHODS
=head2 pod
    my $result = $mcpan->pod( module => 'Moose' );
    # or
    my $result = $mcpan->pod(
        author  => 'DOY',
        release => 'Moose-2.0201',
        path    => 'lib/Moose.pm',
    );
Searches MetaCPAN for a module or a specific release and returns the POD.
Content type can also be specified, like so:
    my $result = $mcpan->pod( module => 'Moose', 'content-type' => 'x-pod' );
=head1 AUTHOR
Sawyer X <xsawyerx@cpan.org>
=head1 COPYRIGHT AND LICENSE
This software is copyright (c) 2011 by Sawyer X.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
=cut