view release on metacpan or  search on metacpan

lib/Acme/CreatingCPANModules.pm  view on Meta::CPAN

[slide] And now we're at the first test file.

Currently, through C<Test::More>, it checks to see if the module loads
correctly. It also diagnoses what it's doing.

[slide] Then we have another test file, which was recently introduced,
to check if files like README and Changes have content written by you
or are just the default templates.

[slide] The next one is checks if you're documenting all your public
functions. It assumes that if you have a private function (that is, a
function that's not meant for the public but rather to be used by your
other functions) you will name it something commencing with an
underscore.

This means that you need a section with the name of each function that
doesn't begin with an underscore.

[slide] And this one over here ensures that your POD is valid.

[slide] So let's go through it one more time: Changes for the list
of changes, MANIFEST with the list of files, Makefile.PL to be used
for installation, README, your module, and a bunch of tests.

[slide] Very well, then. Time for the live demo!

[I change to the next workspace and we're set] You know what they say
about live demos? They say "Don't!" O:-)

OK, then, first we'll create our module. [I type `module-starter
--module=Acme::CreatingCPANModules --author='Jose Castro'
--email=cog@cpan.org`]

There, done.

Now, the first I'm gonna do is get rid of C<boilerplate.t>. Well, not
really getting rid of it, I'll just put it aside for the time being
and I'll explain you later why I'm doing it. [`cd
Acme-CreatingCPANModules` and `mv t/boilerplate .`]

Now we're set.

Suppose we were installing this module.

The first thing to do it `perl Makefile.PL` [`perl Makefile.PL` and ls
-al]. As you can see, this has created C<Makefile>.

This now allows us to do things like this [`make`]. And now we can
test our distribution [`make test`].

As you can see, all our tests have passed... but that's simply because
we still don't have anything interesting in our module...

Let's add some code. [I add the code for new(), set() and get(), as
follows:

  sub new {
    my $self = shift;
    my $foo = shift;
    bless \$foo, $self;
  }

  sub set {
    my $self = shift;
    my $newfoo = shift;
    defined $newfoo or return undef;
    $$self = $newfoo;
    return $self->get();
  }

  sub get {
    my $self = shift;
    return $$self;
  }

and some documentation for these methods]

Now, let's run the tests again. [`make test`]

OK, so we haven't broken anything yet, good :-)

Now, let's add some more tests [`cp t/00-load.t t/01-basic.t`].

As you can see, [`make test`] running the tests again runs this new file.

Now let's change a few things in this new file of ours. [`vim
t/01-basic.t`, remove the last line and add instead:

  my $object = Acme::CreatingCPANModules->new();

  isa_ok( $object, 'Acme::CreatingCPANModules' );
]

This is going to ensure that creating a new Acme::CreatingCPANModules
object actually creates one.

Now, what do you think will happen if I run the tests again?

[`make test`] See? If complains that you ran one more test than
expected. Have a look to the test file again.

See right over there? You're saying that you're going to run one test
[point to third line], but you actually run two [point to use_ok and
to isa_ok].

What you'd have to do is to change that 1 to a 2, but I'll tell you a
little secret of mine: just use C<Test::More> with 'no_plan' [change
the third line in the test file to:

  use Test::More 'no_plan';#tests => 1;
].

OK, so let's add some more tests.

[add, at the bottom of the file:

  $object->set( 5 );

  is( $object->get(), 5 );
]

lib/Acme/CreatingCPANModules.pm  view on Meta::CPAN

[slide]

What next?

I'd like to point you to another article I wrote a while ago, which is
available on Perlmonks.

There's also a very good book on the subject, which covers a lot more
than what we talked about here. The book is "Writing Perl Modules for
CPAN", by Sam Tregar, and it's free, as in "you can download it".

You can subscribe the C<module-authors@perl.org> mailing list if you
need more help (you can also contact me).

If you need to contact a PAUSE admin, send an email to
C<modules@perl.org> (you can't subscribe that list, you can only send
mail to it).

The slides for this talk are inside a module called
C<Acme::CreatingCPANModules>, available on CPAN. You can get to this
module from my homepage, http://jose-castro.org/

It's really simple because it's my name and it's been in every slide
so far! :-) Bottom right corner, Jose Castro, can't miss it! :-)

Somewhere on that page you'll be able to find these slides. I think
currently their at the top right corner. That might change in the
future, and they may go under the "Talks" section, but they'll be
there and they'll be easy to find.

So thank you very much for your time, get C<Module::Starter> on your
machine and start a module today.

Don't be afraid of uploading it to CPAN. People will help you when you
do something wrong :-)

[slide]

Thank you.

Any questions? [email me at cog@cpan.org if you have any :-) ]

I'll leave the previous slide with the links while I answer questions.
[and back to the previous slide]

=head1 EXPORT

This module is OO, so it doesn't export anything...

=head1 FUNCTIONS

=head2 new

Creates a new Acme::CreatingCPANModules object.

=cut

sub new {
  my $self = shift;
  my $foo = shift;
  bless \$foo, $self;
}

=head2 set

Sets the new value of the object.

=cut

sub set {
  my $self = shift;
  my $newfoo = shift;
  defined $newfoo or return undef;
  $$self = $newfoo;
  return $self->get();
}

=head2 get

Gets the current value of the object.

=cut

sub get {
  my $self = shift;
  return $$self;
}

=head1 AUTHOR

Jose Castro, C<< <cog at cpan.org> >>

=head1 BUGS

Please report any bugs or feature requests to
C<bug-acme-creatingcpanmodules at rt.cpan.org>, or through the web interface at
L<http://rt.cpan.org/NoAuth/ReportBug.html?Queue=Acme-CreatingCPANModules>.
I will be notified, and then you'll automatically be notified of progress on
your bug as I make changes.

=head1 SUPPORT

You can find documentation for this module with the perldoc command.

    perldoc Acme::CreatingCPANModules

You can also look for information at:

=over 4

=item * AnnoCPAN: Annotated CPAN documentation

L<http://annocpan.org/dist/Acme-CreatingCPANModules>

=item * CPAN Ratings

L<http://cpanratings.perl.org/d/Acme-CreatingCPANModules>

=item * RT: CPAN's request tracker

L<http://rt.cpan.org/NoAuth/Bugs.html?Dist=Acme-CreatingCPANModules>