Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Update Docs

  • Loading branch information...
commit 46829b0df3c1dbd159bde1bcb677597fb6b2a9ed 1 parent e970130
@kentfredric kentfredric authored
View
53 README.mkdn
@@ -4,7 +4,7 @@ Path::IsDev - Determine if a given Path resembles a development source tree
# VERSION
-version 1.000002
+version 1.001000
# SYNOPSIS
@@ -63,10 +63,11 @@ This module operates on a very simplistic level, and its easy for false-positive
There are two types of Heuristics, Postive/Confirming Heuristics, and Negative/Disconfirming Heuristics.
-Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special marker directories.
+Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special
+marker directories.
-For instance, the files `META.yml`, `Makefile.PL`, and `Build.PL` are all __Positive Heuristic__ markers, because their presence
-often indicates a "root" of a development tree.
+For instance, the files `META.yml`, `Makefile.PL`, and `Build.PL` are all __Positive Heuristic__ markers, because their
+presence often indicates a "root" of a development tree.
And for instance, the directories `t/`, `xt/` and `.git/` are also __Positive Heuristic__ markers, because these structures
are common in `perl` development trees, and uncommon in install trees.
@@ -81,10 +82,11 @@ Etc.
Under normal circumstances, neither `$HOME` nor those 3 paths are considered `dev`.
-However, all it takes to cause a false positive, is for somebody to install a `t` or `xt` directory, or a marker file in one of the
-above directories for `path_isdev($dir)` to return true.
+However, all it takes to cause a false positive, is for somebody to install a `t` or `xt` directory, or a marker file in one of
+the above directories for `path_isdev($dir)` to return true.
-This may not be a problem, at least, until you use `Path::FindDev` which combines `Path::IsDev` with recursive up-level traversal.
+This may not be a problem, at least, until you use `Path::FindDev` which combines `Path::IsDev` with recursive up-level
+traversal.
$HOME/
$HOME/lib/
@@ -98,7 +100,9 @@ This may not be a problem, at least, until you use `Path::FindDev` which combine
And it is this kind of problem that usually catches people off guard.
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] + ::Tool::Dzil => 0 : dist.ini does not exist
@@ -119,7 +123,9 @@ No wonder!
rm /home/kent/perl5/META.yml
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] Matching /home/kent/perl5
@@ -141,7 +147,9 @@ Or, you could use a negative heuristic.
touch /home/kent/perl5/.path_isdev_ignore
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] Matching /home/kent/perl5
[Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
@@ -168,7 +176,8 @@ Just remember, a __Negative__ Heuristic __excludes the path it is associated wit
## Positive Heuristics bundled with this distribution
-- [`Changelog`](https://metacpan.org/pod/Path::IsDev::Heuristic::Changelog) - Files matching `Changes`, `Changelog`, and similar, case insensitive, extensions optional.
+- [`Changelog`](https://metacpan.org/pod/Path::IsDev::Heuristic::Changelog) - Files matching `Changes`, `Changelog`, and similar, case
+insensitive, extensions optional.
- [`DevDirMarker`](https://metacpan.org/pod/Path::IsDev::Heuristic::DevDirMarker) - explicit `.devdir` file to indicate a project root.
- [`META`](https://metacpan.org/pod/Path::IsDev::Heuristic::META) - `META.yml`/`META.json`
- [`MYMETA`](https://metacpan.org/pod/Path::IsDev::Heuristic::MYMETA) - `MYMETA.yml`/`MYMETA.json`
@@ -220,26 +229,22 @@ If this poses a security concern for the user, then this security hole can be el
# SECURITY
-Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code,
-and possibly stash that evil set in a poorly secured privileged users @INC
+Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code, and possibly stash that
+evil set in a poorly secured privileged users @INC
-And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into executing arbitrary code.
+And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into
+executing arbitrary code.
-Though granted, if you can do either of those 2 things, you're probably security vulnerable anyway, and granted, if you could do either of those 2 things you could do much more evil things by the following:
+Though granted, if you can do either of those 2 things, you're probably security vulnerable anyway, and granted, if you could do
+either of those 2 things you could do much more evil things by the following:
export PERL5OPT="-MEvil::Module"
So with that in understanding, saying this modules default utility is "insecure" is mostly a bogus argument.
And to that effect, this module does nothing to "lock down" that mechanism, and this module encourages you
-to __NOT__ force a set, unless you __NEED__ to, and strongly suggests that forcing a set for the purpose of security will achieve no real improvement in security, while simultaneously reducing utility.
-
-{
- "namespace":"Path::IsDev",
- "interface":"exporter"
-}
-
-
+to __NOT__ force a set, unless you __NEED__ to, and strongly suggests that forcing a set for the purpose of security will achieve
+no real improvement in security, while simultaneously reducing utility.
# AUTHOR
@@ -247,7 +252,7 @@ Kent Fredric <kentfredric@gmail.com>
# COPYRIGHT AND LICENSE
-This software is copyright (c) 2013 by Kent Fredric <kentfredric@gmail.com>.
+This software is copyright (c) 2014 by Kent Fredric <kentfredric@gmail.com>.
This is free software; you can redistribute it and/or modify it under
the same terms as the Perl 5 programming language system itself.
View
42 lib/Path/IsDev.pm
@@ -35,10 +35,11 @@ This module operates on a very simplistic level, and its easy for false-positive
There are two types of Heuristics, Postive/Confirming Heuristics, and Negative/Disconfirming Heuristics.
-Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special marker directories.
+Positive Heuristics and Negative Heuristics are based solely on the presence of specific marker files in a directory, or special
+marker directories.
-For instance, the files C<META.yml>, C<Makefile.PL>, and C<Build.PL> are all B<Positive Heuristic> markers, because their presence
-often indicates a "root" of a development tree.
+For instance, the files C<META.yml>, C<Makefile.PL>, and C<Build.PL> are all B<Positive Heuristic> markers, because their
+presence often indicates a "root" of a development tree.
And for instance, the directories C<t/>, C<xt/> and C<.git/> are also B<Positive Heuristic> markers, because these structures
are common in C<perl> development trees, and uncommon in install trees.
@@ -53,10 +54,11 @@ Etc.
Under normal circumstances, neither C<$HOME> nor those 3 paths are considered C<dev>.
-However, all it takes to cause a false positive, is for somebody to install a C<t> or C<xt> directory, or a marker file in one of the
-above directories for C<path_isdev($dir)> to return true.
+However, all it takes to cause a false positive, is for somebody to install a C<t> or C<xt> directory, or a marker file in one of
+the above directories for C<path_isdev($dir)> to return true.
-This may not be a problem, at least, until you use C<Path::FindDev> which combines C<Path::IsDev> with recursive up-level traversal.
+This may not be a problem, at least, until you use C<Path::FindDev> which combines C<Path::IsDev> with recursive up-level
+traversal.
$HOME/
$HOME/lib/
@@ -71,7 +73,9 @@ This may not be a problem, at least, until you use C<Path::FindDev> which combin
And it is this kind of problem that usually catches people off guard.
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] + ::Tool::Dzil => 0 : dist.ini does not exist
@@ -92,7 +96,9 @@ No wonder!
rm /home/kent/perl5/META.yml
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] Matching /home/kent/perl5
@@ -114,7 +120,9 @@ Or, you could use a negative heuristic.
touch /home/kent/perl5/.path_isdev_ignore
- PATH_ISDEV_DEBUG=1 perl -Ilib -MPath::FindDev=find_dev -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
+ PATH_ISDEV_DEBUG=1 \
+ perl -Ilib -MPath::FindDev=find_dev \
+ -E "say find_dev(q{/home/kent/perl5/perlbrew/perls/perl-5.19.3/lib/site_perl})"
...
[Path::IsDev=0] Matching /home/kent/perl5
[Path::IsDev=0] - ::IsDev::IgnoreFile => 1 : .path_isdev_ignore exists
@@ -147,7 +155,8 @@ Just remember, a B<Negative> Heuristic B<excludes the path it is associated with
=over 4
-=item * L<< C<Changelog>|Path::IsDev::Heuristic::Changelog >> - Files matching C<Changes>, C<Changelog>, and similar, case insensitive, extensions optional.
+=item * L<< C<Changelog>|Path::IsDev::Heuristic::Changelog >> - Files matching C<Changes>, C<Changelog>, and similar, case
+insensitive, extensions optional.
=item * L<< C<DevDirMarker>|Path::IsDev::Heuristic::DevDirMarker >> - explicit C<.devdir> file to indicate a project root.
@@ -219,19 +228,22 @@ If this poses a security concern for the user, then this security hole can be el
=head1 SECURITY
-Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code,
-and possibly stash that evil set in a poorly secured privileged users @INC
+Its conceivable, than an evil user could construct an evil set, containing arbitrary and vulnerable code, and possibly stash that
+evil set in a poorly secured privileged users @INC
-And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into executing arbitrary code.
+And if they managed to achieve that, if they could poison the privileged users %ENV, they could trick the privileged user into
+executing arbitrary code.
-Though granted, if you can do either of those 2 things, you're probably security vulnerable anyway, and granted, if you could do either of those 2 things you could do much more evil things by the following:
+Though granted, if you can do either of those 2 things, you're probably security vulnerable anyway, and granted, if you could do
+either of those 2 things you could do much more evil things by the following:
export PERL5OPT="-MEvil::Module"
So with that in understanding, saying this modules default utility is "insecure" is mostly a bogus argument.
And to that effect, this module does nothing to "lock down" that mechanism, and this module encourages you
-to B<NOT> force a set, unless you B<NEED> to, and strongly suggests that forcing a set for the purpose of security will achieve no real improvement in security, while simultaneously reducing utility.
+to B<NOT> force a set, unless you B<NEED> to, and strongly suggests that forcing a set for the purpose of security will achieve
+no real improvement in security, while simultaneously reducing utility.
=cut
View
7 lib/Path/IsDev/Heuristic/DevDirMarker.pm
@@ -13,10 +13,11 @@ package Path::IsDev::Heuristic::DevDirMarker;
This Heuristic is a workaround that is likely viable in the event none of the other Heuristics work.
-All this heuristic checks for is the presence of a special file called C<.devdir>, which is intended as an explicit notation that "This directory is a project root".
+All this heuristic checks for is the presence of a special file called C<.devdir>, which is intended as an explicit notation that
+"This directory is a project root".
-An example case where you might need such a Heuristic, is the scenario where you're not working
-with a Perl C<CPAN> dist, but are instead working on a project in a different language, where Perl is simply there for build/test purposes.
+An example case where you might need such a Heuristic, is the scenario where you're not working with a Perl C<CPAN> dist, but are
+instead working on a project in a different language, where Perl is simply there for build/test purposes.
=cut
View
2  lib/Path/IsDev/Role/Matcher/Child/Exists/Any/Dir.pm
@@ -28,7 +28,7 @@ with 'Path::IsDev::Role::Matcher::Child::Exists::Any';
$class->child_exists_dir( $result_object, $childname );
-Return match if C<$childname> exists as a directory child of C<< $result_object->path >>,
+Return match if C<$childname> exists as a directory child of C<< $result_object->path >>.
=cut
Please sign in to comment.
Something went wrong with that request. Please try again.