[libdist-zilla-role-bootstrap-perl] 04/06: Document and make xtests happy
Axel Beckert
abe at deuxchevaux.org
Sat Aug 8 11:58:20 UTC 2015
This is an automated email from the git hooks/post-receive script.
abe pushed a commit to annotated tag 0.2.0-source
in repository libdist-zilla-role-bootstrap-perl.
commit 322740b88dffaa04695d45a4a55437f3f2aa494a
Author: Kent Fredric <kentfredric at gmail.com>
Date: Sat Sep 21 21:25:20 2013 +1200
Document and make xtests happy
---
README.mkdn | 75 +++++++++++++++++++++++++++++++
dist.ini | 2 +-
lib/Dist/Zilla/Role/Bootstrap.pm | 97 +++++++++++++++++++++++++++++++++++++++-
perlcritic.rc | 4 +-
weaver.ini | 16 ++-----
5 files changed, 177 insertions(+), 17 deletions(-)
diff --git a/README.mkdn b/README.mkdn
index fe78c3a..99eaeb6 100644
--- a/README.mkdn
+++ b/README.mkdn
@@ -32,34 +32,109 @@ For users of plugins:
## `bootstrap`
+Any user specified `bootstrap` method will be invoked during `plugin_from_config`.
+
+This is __AFTER__ `->new`, __AFTER__ `->BUILD`, and __AFTER__ `dzil`'s internal `plugin_from_config` steps.
+
+This occurs within the `register_component` phase of the plug-in loading and configuration.
+
+This also occurs __BEFORE__ `Dist::Zilla` attaches the plug-in into the plug-in stash.
+
# ATTRIBUTES
## `distname`
+The name of the distribution.
+
+This value is vivified by asking `zilla->name`.
+
+Usually this value is populated by `dist.ini` in the property `name`
+
+However, occasionally, this value is discovered by a `plugin`.
+
+In such a case, that plugin cannot be bootstrapped, because that plugin __MUST__ be loaded prior to bootstrap.
+
## `try_built`
+This attribute controls how the consuming `plugin` behaves.
+
+- false __(default)__ : bootstrapping is only done to `PROJECTROOT/lib`
+- true : bootstrap attempts to try `PROJECTROOT/<distname>-<version>/lib`
+
## `fallback`
+This attribute is for use in conjunction with `try_built`
+
+- `false` : When `PROJECTROOT/<distname>-<version>` does not exist, don't perform any bootstrapping
+- `true` __(default)__ : When `PROJECTROOT/<distname>-<version>` does not exist, bootstrap to `PROJECTROOT/lib`
+
## `try_built_method`
+This attribute controls how `try_built` behaves when multiple directories exist that match `PROJECTROOT/<distname>-.*`
+
+Two valid options at this time:
+
+- `mtime` __(default)__ : Pick the directory with the most recent `mtime`
+- `parseversion` : Attempt to parse versions on all candidate directories and use the one with the largest version.
+
+Prior to `0.2.0` this property did not exist, and default behaviour was to assume `0 Candidates` and `2 or more Candidates` were the same problem.
+
# PRIVATE ATTRIBUTES
## `_cwd`
## `_bootstrap_root`
+Internal: This is the real legwork, and resolves the base directory using the bootstrap resolution protocol.
+
+It should always return a project root of some kind, whether it be a source tree, or built source tree.
+
+It can also return `undef` if discovery concludes that no bootstrap can or should be performed.
+
# PRIVATE METHODS
## `_pick_latest_mtime`
+"Latest" `mtime` candidate selector
+
+ my $directory = $self->_pick_latest_mtime(@directory_objects)
+
## `_get_candidate_version`
+Attempt to resolve a version from a directory name
+
+ my $version = $self->_get_candidate_version($directory_object)
+
+__NOTE:__ At this time, the presence of `-TRIAL` is simply stripped and ignored
+
## `_pick_latest_parseversion`
+"Latest" `version` candidate selector
+
+ my $directory = $self->_pick_latest_parseversion(@directory_objects)
+
## `_pick_candidate`
+Pick a directory from a list of candidates using the method described by `try_built_method`
+
+ my $directory = $self->_pick_candidate( @directory_objects );
+
## `_add_inc`
+Internal: Used to perform the final step of injecting library paths into `@INC`
+
+ $self->_add_inc("$libraryPath");
+
+# PRIVATE FUNCTIONS
+
+## `_max_by`
+
+Proxy for [`List::UtilsBy::__max\_by__`](http://search.cpan.org/perldoc?List::UtilsBy#max\_by)
+
+## `_nmax_by`
+
+Proxy for [`List::UtilsBy::__nmax\_by__`](http://search.cpan.org/perldoc?List::UtilsBy#nmax\_by)
+
{
"namespace":"Dist::Zilla::Role::Bootstrap",
"interface":"role",
diff --git a/dist.ini b/dist.ini
index 90b9bb6..12df089 100644
--- a/dist.ini
+++ b/dist.ini
@@ -4,7 +4,7 @@ author = Kent Fredric <kentfredric at gmail.com>
license = Perl_5
copyright_holder = Kent Fredric <kentfredric at gmail.com>
-; Uncomment this to bootstrap via self
+; Uncomment this to bootstrap via self
; [Bootstrap::lib]
; try_built = 1
diff --git a/lib/Dist/Zilla/Role/Bootstrap.pm b/lib/Dist/Zilla/Role/Bootstrap.pm
index a40eccc..9df9194 100644
--- a/lib/Dist/Zilla/Role/Bootstrap.pm
+++ b/lib/Dist/Zilla/Role/Bootstrap.pm
@@ -41,12 +41,18 @@ For users of plugins:
fallback = 0 ; # don't bootstrap at all if /Dist-Name-.*/ matches != 1 things
fallback = 1 ; # fallback to / if /Dist-Name-.*/ matches != 1 things
-
+
=cut
with 'Dist::Zilla::Role::Plugin';
+=p_func C<_max_by>
+
+Proxy for L<< C<List::UtilsBy::B<max_by>>|List::UtilsBy/max_by >>
+
+=cut
+
sub _max_by(&@) {
no warnings 'redefine';
require List::UtilsBy;
@@ -54,6 +60,12 @@ sub _max_by(&@) {
goto &List::UtilsBy::max_by;
}
+=p_func C<_nmax_by>
+
+Proxy for L<< C<List::UtilsBy::B<nmax_by>>|List::UtilsBy/nmax_by >>
+
+=cut
+
sub _nmax_by(&@) {
no warnings 'redefine';
require List::UtilsBy;
@@ -80,6 +92,16 @@ around 'dump_config' => sub {
=attr C<distname>
+The name of the distribution.
+
+This value is vivified by asking C<< zilla->name >>.
+
+Usually this value is populated by C<dist.ini> in the property C<name>
+
+However, occasionally, this value is discovered by a C<plugin>.
+
+In such a case, that plugin cannot be bootstrapped, because that plugin B<MUST> be loaded prior to bootstrap.
+
=cut
has distname => ( isa => 'Str', is => ro =>, lazy => 1, builder => sub { $_[0]->zilla->name; }, );
@@ -100,6 +122,17 @@ has _cwd => (
=attr C<try_built>
+This attribute controls how the consuming C<plugin> behaves.
+
+=over 4
+
+=item * false B<(default)> : bootstrapping is only done to C<PROJECTROOT/lib>
+
+=item * true : bootstrap attempts to try C<< PROJECTROOT/<distname>-<version>/lib >>
+
+=back
+
+
=cut
has try_built => (
@@ -111,6 +144,16 @@ has try_built => (
=attr C<fallback>
+This attribute is for use in conjunction with C<try_built>
+
+=over 4
+
+=item * C<false> : When C<< PROJECTROOT/<distname>-<version> >> does not exist, don't perform any bootstrapping
+
+=item * C<true> B<(default)> : When C<< PROJECTROOT/<distname>-<version> >> does not exist, bootstrap to C<< PROJECTROOT/lib >>
+
+=back
+
=cut
has fallback => (
@@ -122,17 +165,35 @@ has fallback => (
=attr C<try_built_method>
+This attribute controls how C<try_built> behaves when multiple directories exist that match C<< PROJECTROOT/<distname>-.* >>
+
+Two valid options at this time:
+
+=over 4
+
+=item * C<mtime> B<(default)> : Pick the directory with the most recent C<mtime>
+
+=item * C<parseversion> : Attempt to parse versions on all candidate directories and use the one with the largest version.
+
+=back
+
+Prior to C<0.2.0> this property did not exist, and default behaviour was to assume C<0 Candidates> and C<2 or more Candidates> were the same problem.
+
=cut
has try_built_method => (
isa => 'Str',
is => ro =>,
lazy => 1,
- builder => sub { return 'mtime' }
+ builder => sub { return 'mtime' },
);
=p_method C<_pick_latest_mtime>
+"Latest" C<mtime> candidate selector
+
+ my $directory = $self->_pick_latest_mtime(@directory_objects)
+
=cut
sub _pick_latest_mtime {
@@ -142,6 +203,12 @@ sub _pick_latest_mtime {
=p_method C<_get_candidate_version>
+Attempt to resolve a version from a directory name
+
+ my $version = $self->_get_candidate_version($directory_object)
+
+B<NOTE:> At this time, the presence of C<-TRIAL> is simply stripped and ignored
+
=cut
sub _get_candidate_version {
@@ -157,6 +224,10 @@ sub _get_candidate_version {
=p_method C<_pick_latest_parseversion>
+"Latest" C<version> candidate selector
+
+ my $directory = $self->_pick_latest_parseversion(@directory_objects)
+
=cut
sub _pick_latest_parseversion {
@@ -171,6 +242,10 @@ my (%methods) = (
=p_method C<_pick_candidate>
+Pick a directory from a list of candidates using the method described by C<try_built_method>
+
+ my $directory = $self->_pick_candidate( @directory_objects );
+
=cut
sub _pick_candidate {
@@ -186,6 +261,12 @@ sub _pick_candidate {
=p_attr C<_bootstrap_root>
+Internal: This is the real legwork, and resolves the base directory using the bootstrap resolution protocol.
+
+It should always return a project root of some kind, whether it be a source tree, or built source tree.
+
+It can also return C<undef> if discovery concludes that no bootstrap can or should be performed.
+
=cut
has _bootstrap_root => (
@@ -222,6 +303,10 @@ has _bootstrap_root => (
=p_method C<_add_inc>
+Internal: Used to perform the final step of injecting library paths into C<@INC>
+
+ $self->_add_inc("$libraryPath");
+
=cut
sub _add_inc {
@@ -236,6 +321,14 @@ sub _add_inc {
=requires C<bootstrap>
+Any user specified C<bootstrap> method will be invoked during C<plugin_from_config>.
+
+This is B<AFTER> C<< ->new >>, B<AFTER> C<< ->BUILD >>, and B<AFTER> C<dzil>'s internal C<plugin_from_config> steps.
+
+This occurs within the C<register_component> phase of the plug-in loading and configuration.
+
+This also occurs B<BEFORE> C<Dist::Zilla> attaches the plug-in into the plug-in stash.
+
=cut
requires 'bootstrap';
diff --git a/perlcritic.rc b/perlcritic.rc
index 8c0d884..a59e977 100644
--- a/perlcritic.rc
+++ b/perlcritic.rc
@@ -1,5 +1,5 @@
severity = 1
-exclude = RequireTidyCode RequirePodSections ProhibitPostfixControls RequireRcsKeywords RequireExplicitPackage
+exclude = RequireTidyCode RequirePodSections ProhibitPostfixControls RequireRcsKeywords RequireExplicitPackage ProhibitNoWarnings ProhibitSubroutinePrototypes
include = Moose::ProhibitMultipleWiths Moose::ProhibitNewMethod Moose::RequireCleanNamespace Moose::RequireMakeImmutable
color = 1
verbose = 9
@@ -10,7 +10,7 @@ allow_includes = 1
[CodeLayout::ProhibitTrailingWhitespace]
[Documentation::PodSpelling]
-stop_words =
+stop_words = behaviour
[Subroutines::ProhibitUnusedPrivateSubroutines]
private_name_regex = _(?!build_)\w
diff --git a/weaver.ini b/weaver.ini
index 735607b..55ce96e 100644
--- a/weaver.ini
+++ b/weaver.ini
@@ -24,18 +24,6 @@ command = method
[Collect / ATTRIBUTES]
command = attr
-;[Collect / FILTER_METHODS]
-;header = FILTER METHODS
-;command = filter
-
-;[Collect / TERMINATOR_LIST_METHODS]
-;header = TERMINATOR LIST METHODS
-;command = terminator
-
-;[Collect / MIRROR_LIST_METHODS]
-;header = MIRROR LIST METHODS
-;command = mirrorlist
-
[Collect / PRIVATE_ATTRIBUTES]
header = PRIVATE ATTRIBUTES
command = p_attr
@@ -44,6 +32,10 @@ command = p_attr
header = PRIVATE METHODS
command = p_method
+[Collect / PRIVATE_FUNCTIONS]
+header = PRIVATE FUNCTIONS
+command = p_func
+
[Leftovers]
[Region / postlude]
--
Alioth's /usr/local/bin/git-commit-notice on /srv/git.debian.org/git/pkg-perl/packages/libdist-zilla-role-bootstrap-perl.git
More information about the Pkg-perl-cvs-commits
mailing list