# New Ticket Created by "Sandy Bultena"
# Please include the string: [perl #44621]
# in the subject line of all future correspondence about this issue.
# <URL: http://rt.perl.org/rt3/Ticket/Display.html?id=44621 >
OK, I'm game!
----- Original Message -----
From: "James E Keenan" <[EMAIL PROTECTED]>
To: <[EMAIL PROTECTED]>
Sent: Monday, August 13, 2007 9:31 PM
Subject: [CAGE] Finish this module: Parrot::YetToBeNamed!
> This ticket is a cage-cleaning assignment that would be especially
> good for a newcomer to the Parrot project to take on. It entails the
> creation of a module written in Perl 5 to be placed under lib/Parrot/
> which would serve as a repository for Perl 5 subroutines which can be
> imported on demand by any Perl 5 packages anywhere in the Parrot
> distribution at any point in the compile-build-test-install cycle.
>
> More precisely, it involves the *completion* of such a module,
> because I've begun the module's specification below. Your task will
> be to complete the documentation, write tests of the interface, then
> write the code to implement the interface -- and then repeat the
> cycle until you get a high-quality Perl 5 package.
>
> The impetus for this module comes from an inline comment made by Andy
> Lester in r20618 of config/auto/attributes.pm:
>
> 20618 petdance # Stolen from Parrot::Test
> 20618 petdance # Should be put somewhere more central
> 20618 petdance sub _slurp_file {
> 20618 petdance my ($file_name) = @_;
> 20618 petdance
> 20618 petdance open( my $SLURP, '<', $file_name ) or die "open
> '$file_name': $!";
> 20618 petdance local $/ = undef;
> 20618 petdance my $file = <$SLURP> . '';
> 20618 petdance $file =~ s/\cM\cJ/\n/g;
> 20618 petdance close $SLURP;
> 20618 petdance
> 20618 petdance return $file;
> 20618 petdance }
>
> Code to slurp a file into a string can be found in many places,
> notably in the Perl Cookbook and in Uri's CPAN module File::Slurp.
> But File::Slurp is not part of the Perl 5 core distribution. That
> means it is not automatically available to Parrot developers. But
> it's certainly something that would be nice to have. I wondered why
> no one had made it available already.
>
> It turns out, someone *had* made it available already -- but *not*
> available throughout all parts of the Parrot installation cycle. A
> subroutine called slurp_file() is automatically exported by
> Parrot::Test and is used *very* extensively throughout the build and
> test phases (see attached file 'slurp_file.usages.txt' -- but note
> that some instances of the string 'slurp_file' pertain to PIR code).
>
> So I wondered: Why didn't Andy simply call Parrot::Test::slurp_file
> () in config/auto/attributes.pm? Why was he complaining that it
> wasn't "central" enough?
>
> The answer is that Parrot::Test has a dependency on Parrot::Config:
>
> use Parrot::Config;
>
> ... and Parrot::Config doesn't come into existence until after the
> configuration phase has completed! So Parrot::Test::slurp_file() can
> only be used in the build and later phases -- even though it itself
> has no dependency on Parrot::Config. It was not available when/where
> Andy needed it, because config/auto/attributes.pm is part of the
> configuration phase.
>
> In fact, slurp_file() doesn't have anything to do with testing per
> se. There is no intrinsic reason why it should be housed in
> Parrot::Test. (That's probably just where it first proved useful
> some 8000 commits ago.)
>
> It therefore makes sense to:
>
> 1. Extract slurp_file() from Parrot::Test.
> 2. Place it in a new package under lib/Parrot/ from which it is
> exported on demand (*not* automatically, as is currently the case;
> that's < best practice).
> 3. Make this a package that can hold other self-contained, non-
> object-oriented, utility subroutines written in Perl 5 that can be
> useful in all phases of the Parrot installation cycle.
> 4. Replace all current calls to Parrot::Test::slurp_file() with
> calls to Parrot::YetToBeNamed::slurp_file().
> 5. And, of course, to do it right: write unit tests for the
> subroutines exported by Parrot::YetToBeNamed.
>
> What do you need to accomplish these objectives? You don't need C,
> PIR or PASM. In fact, you don't need to know anything about Parrot
> at all! You only need competence in Perl 5. (Of course, it would
> help if you've drunk the koolaid Schwern first started brewing seven
> years ago. See any YAPC talk on module development or testing given
> by him, chromatic, Ian Langworth, Paul Johnson, Andy or myself in
> recent years.)
>
> In fact, this would be a great assignment for any/all of you who came
> to our Parrot BOF at YAPC, said you were interested in joining the
> project, but haven't yet started an assignment. Or a good assignment
> for those of you in Phalanx Phoenix!
>
> So don't be bashful. Step up to the plate and hit this one out of
> the ballpark -- and stop me before I use another baseball metaphor!
>
> kid51
>
>
