File Coverage

blib/lib/Dist/Zilla/Plugin/MetaProvides.pm
Criterion Covered Total %
statement 10 10 100.0
branch n/a
condition n/a
subroutine 4 4 100.0
pod 0 1 0.0
total 14 15 93.3


line stmt bran cond sub pod time code
1 2     2   4186197 use 5.006;
  2         6  
2 2     2   6 use strict;
  2         2  
  2         37  
3 2     2   5 use warnings;
  2         3  
  2         190  
4              
5             package Dist::Zilla::Plugin::MetaProvides;
6              
7             our $VERSION = '2.002002'; # TRIAL
8              
9             # ABSTRACT: Generating and Populating 'provides' in your META.yml
10              
11             our $AUTHORITY = 'cpan:KENTNL'; # AUTHORITY
12              
13              
14              
15              
16              
17              
18              
19              
20              
21              
22              
23              
24              
25             sub register_component {
26 1     1 0 1216 require Carp;
27 1         187 Carp::croak(<<"EOF");
28             [MetaProvides] is merely a top level namespace, not an actual plugin.
29             Perhaps you wanted [MetaProvides::Package]? or [MetaProvides::Class] for MX:Declare style packages
30             EOF
31              
32             }
33             1;
34              
35             __END__
36              
37             =pod
38              
39             =encoding UTF-8
40              
41             =head1 NAME
42              
43             Dist::Zilla::Plugin::MetaProvides - Generating and Populating 'provides' in your META.yml
44              
45             =head1 VERSION
46              
47             version 2.002002
48              
49             =head1 SYNOPSIS
50              
51             This module is not intended to be used directly, but instead, one of the following sub-modules should be used in your projects dist.ini
52              
53             The most common usage should find
54              
55             [MetaProvides::Package]
56              
57             Sufficient for indexing traditional Perl5 modules.
58              
59             Advanced Usage:
60              
61             ; Traditional Perl5 Modules
62             [MetaProvides::Package]
63             inherit_version = 1 ; Default
64             inherit_missing = 1 ; Default
65             meta_noindex = 1 ; Default
66              
67             ; If using MooseX::Declare style "class" keywords.
68             ; Default configuration shown
69             [MetaProvides::Class]
70             inherit_version = 1 ; Default
71             inherit_missing = 1 ; Default
72             meta_noindex = 1 ; Default
73              
74             ; Hand Constructed Provides in an external file
75             [MetaProvides::FromFile]
76             inherit_version = 1 ; Default
77             inherit_missing = 1 ; Default
78              
79             file = some_file.ini ; mandatory flag
80             reader_name = Config::INI::Reader ;optional flag
81              
82             And then in some_file.ini
83              
84             [Imaginary::Package]
85             file = lib/Imaginary/Package.pm ;mandatory flag
86             version = 3.1415 ;optional flag, subject to rules in dist.ini
87              
88             =head1 DESCRIPTION
89              
90             This Distribution Contains a small bundle of plugins for various ways of
91             populating the C<META.yml> that is built with your distribution.
92              
93             The initial reason for this is due to stuff that uses L<MooseX::Declare>
94             style class definitions not being parseable by many tools upstream, so this
95             is here to cover this problem by defining it in the metadata.
96              
97             =begin MetaPOD::JSON v1.1.0
98              
99             {
100             "namespace":"Dist::Zilla::Plugin::MetaProvides"
101             }
102              
103              
104             =end MetaPOD::JSON
105              
106             =for Pod::Coverage register_component
107              
108             =head1 COMPONENT SUMMARY
109              
110             =head2 C<::Class>
111              
112             Scans L<Dist::Zilla>'s C<.pm> files and tries to identify classes using
113             L<Class::Discover>.
114              
115             L<Dist::Zilla::Plugin::MetaProvides::Class>
116              
117             =head2 C<::Package>
118              
119             Scans L<Dist::Zilla>'s C<.pm> files and tries to identify more traditional
120             packages using a combination of L<Module::Extract::VERSION> and
121             L<Module::Extract::Namespaces>.
122              
123             L<Dist::Zilla::Plugin::MetaProvides::Package>
124              
125             =head2 C<::FromFile>
126              
127             In the event both of the above don't work for your needs, pull in
128             hand-crafted metadata from a specified file.
129              
130             L<Dist::Zilla::Plugin::MetaProvides::FromFile>
131              
132             =head1 OPTION SUMMARY
133              
134             =head2 C<inherit_version>
135              
136             At the time this plugin runs to collect metadata from files,
137             the mungers won't have run yet to inject custom versions into files in the various
138             locations.
139              
140             If you want the versions reported in the C<provides> list to be consistent with
141             the ones actually in the files, you will need to use this option in its enabled
142             state.
143              
144             IE: Generally, if you are using version munging, you B<WILL> want this flag set
145             to C<1>.
146              
147             =head3 C<values>
148              
149             =over 4
150              
151             =item * C<< '0' >>
152              
153             Do not inherit version from C<Dist::Zilla>
154              
155             =item * C<< '1' >> B<[default]>
156              
157             Inherit version from L<Dist::Zilla>
158              
159             =back
160              
161             L<Dist::Zilla::Role::MetaProvider::Provider/inherit_version>
162              
163             =head2 C<inherit_missing>
164              
165             If for whatever reason you want to actually use the versions found in the modules
166             where present, and fall back to the value from L<Dist::Zilla>.
167              
168             C<inherit_version> will need to be turned off (C<0>) for this to be effective.
169              
170             =head3 values
171              
172             =over 4
173              
174             =item * C<< '0' >>
175              
176             Do not inherit version from C<Dist::Zilla> when one is missing.
177              
178             =item * C<< '1' >> B<[default]>
179              
180             Inherit version from L<Dist::Zilla> when one is missing.
181              
182             =back
183              
184             L<Dist::Zilla::Role::MetaProvider::Provider/inhert_missing>
185              
186             =head2 C<meta_noindex>
187              
188             This dictates how to behave when a discovered class is also present in the C<no_index> META field.
189              
190             =head3 values
191              
192             =over 4
193              
194             =item * C<< '0' >> B<[default]>
195              
196             C<no_index> META field will be ignored
197              
198             =item * C<< '1' >>
199              
200             C<no_index> META field will be recognised and things found in it will cause respective packages
201             to not be provided in the metadata.
202              
203             =back
204              
205             L<Dist::Zilla::Role::MetaProvider::Provider/meta_noindex>
206              
207             =head2 C<file>
208              
209             ( L<Dist::Zilla::Plugin::MetaProvides::FromFile> )
210              
211             This is a mandatory parameter that points to the file that contains manually
212             ( or otherwise ) crafted metadata to be integrated into your final META.yml
213              
214             File Must exist.
215              
216             =head2 C<reader_name>
217              
218             ( L<Dist::Zilla::Plugin::MetaProvides::FromFile> )
219              
220             This parameter is by default L<Config::INI::Reader>, but it can be in fact anything
221             that meets the following criteria.
222              
223             =over 4
224              
225             =item * Can be initialized an instance of
226              
227             =item * has a read_file method on the instance
228              
229             =item * read_file can take the parameter 'file'
230              
231             =item * read_file can return a hashref matching the following structure
232              
233             { 'Package::Name' => {
234             'file' => '/path/to/file',
235             'version' => 0.1,
236             }}
237              
238             =back
239              
240             =head1 AUTHOR
241              
242             Kent Fredric <kentnl@cpan.org>
243              
244             =head1 COPYRIGHT AND LICENSE
245              
246             This software is copyright (c) 2016 by Kent Fredric <kentfredric@gmail.com>.
247              
248             This is free software; you can redistribute it and/or modify it under
249             the same terms as the Perl 5 programming language system itself.
250              
251             =cut