If you are working on an in-house project you probably won't want to release it to CPAN. In that case you are welcome to skip this part. However even it that case it might be useful for you to know how modules can be packaged for CPAN. After all even for in-house project you might set up a private CPAN repository injecting your modules. For that case it is a good idea to know how to package the code.

Some people will say it is too early to make an official release. After all we can only parse a very limited Markua syntax.

So why do I release it anyway and how do I do it?

Getting feedback

One of the most important part of any development work, both proprietary and Open Source is the learning. We need to learn what the clients really want. We need to understand the spec better. We need to make sure our code runs on all the platforms we would like it to run.

The motto of Open Source "Release early, release often" says it very nicely.

For proprietary applications it is usually called Continuous Delivery and Continuous Deployment.

CPAN Testers

I have some hope that after releasing the code to CPAN a few more people will look at it and comment on it, but that's not the most important thing at this point.

Once I upload a module to CPAN it will be picked up by the CPAN testers and it will be tested in many Operating systems and many versions of Perl. A great way to make sure the code works everywhere.

Changes

The Changes file is the simplest at this point. It should list all the changes made since the previous release, but as this is our first release we don't have much to do with it:

examples/markua-parser/0764270/Changes

  1. Changes for Markua::Parser module
  2.  
  3. 0.01 2018.03.28
  4.     - First version

Add POD to the module

POD that stands for Plain Old Documentation is a markup language used in Perl to add user-documentation to Perl code. We add a short explanation of what is this module and how to use it.

We also add some Copyright and License information.

examples/markua-parser/0764270/lib/Markua/Parser.pm

  1. package Markua::Parser;
  2. use strict;
  3. use warnings;
  4. use Path::Tiny qw(path);
  5.  
  6. our $VERSION = 0.01;
  7.  
  8. sub new {
  9.     my ($class) = @_;
  10.     my $self = bless {}, $class;
  11.     return $self;
  12. }
  13.  
  14. sub parse_file {
  15.     my ($self, $filename) = @_;
  16.     my $path = path($filename);
  17.     my $dir = $path->parent->stringify;
  18.     my @entries;
  19.     my @errors;
  20.     my $cnt = 0;
  21.  
  22.     $self->{text} = '';
  23.  
  24.     for my $line ($path->lines_utf8) {
  25.         $cnt++;
  26.         if ($line =~ /^(#{1,6}) (\S.*)/) {
  27.             push @entries, {
  28.                 tag => 'h' . length($1),
  29.                 text => $2,
  30.             };
  31.             next;
  32.         }
  33.  
  34.         # numbered list
  35.         if ($line =~ m{\A(\d+)([.\)])( {1,4}|\t)(\S.*)}) {
  36.             my ($number, $sep, $space, $text) = ($1, $2, $3, $4);
  37.             if (not $self->{tag}) {
  38.                 $self->{tag} = 'numbered-list';
  39.                 $self->{list} = [];
  40.             }
  41.  
  42.             if ($self->{tag} eq 'numbered-list') {
  43.                 push @{ $self->{list} }, {
  44.                         number => $number,
  45.                         sep    => $sep,
  46.                         space  => $space,
  47.                         text   => $text,
  48.                         raw    => $line,
  49.                 };
  50.                 next;
  51.             }
  52.  
  53.             die "What to do if a numbered list starts in the middle of another element?";
  54.         }
  55.  
  56.         # bulleted list
  57.         if ($line =~ m{\A([\*-])( {1,4}|\t)(\S.*)}) {
  58.             my ($bullet, $space, $text) = ($1, $2, $3);
  59.             if (not $self->{tag}) {
  60.                 $self->{tag} = 'list';
  61.                 $self->{list}{type} = 'bulleted';
  62.                 $self->{list}{bullet} = $bullet;
  63.                 $self->{list}{space} = $space;
  64.                 $self->{list}{ok} = 1;
  65.                 $self->{list}{items} = [$text];
  66.                 $self->{list}{raw} = [$line];
  67.                 next;
  68.             }
  69.  
  70.             if ($self->{tag} eq 'list') {
  71.                 if ($self->{list}{type} ne 'bulleted' or
  72.                     $self->{list}{bullet} ne $bullet  or
  73.                     $self->{list}{space} ne $space) {
  74.                     $self->{list}{ok} = 0;
  75.                 }
  76.                 push @{ $self->{list}{raw} }, $line;
  77.                 push @{ $self->{list}{items} }, $text;
  78.                 next;
  79.             }
  80.  
  81.             die "What to do if a bulleted list starts in the middle of another element?";
  82.         }
  83.  
  84. # I should remember to always use \A instead of ^ even thoygh here we are really parsing lines so those two are the same
  85.         if ($line =~ /\A ! \[([^\]]*)\]    \(([^\)]+)\)  \s* \Z/x) {
  86.             my $title = $1;
  87.             my $file_to_include = $2;
  88.             eval {
  89.                 my $text = path("$dir/$file_to_include")->slurp_utf8;
  90.                 push @entries, {
  91.                     tag   => 'code',
  92.                     title => $title,
  93.                     text  => $text,
  94.                 };
  95.             };
  96.             if ($@) {
  97.                 push @errors, {
  98.                     row => $cnt,
  99.                     line => $line,
  100.                     error => "Could not read included file '$file_to_include'",
  101.                 };
  102.             }
  103.             next;
  104.         }
  105.  
  106.         # anything else defaults to paragraph
  107.         if ($line =~ /\S/) {
  108.             $self->{tag} = 'p';
  109.             $self->{text} .= $line;
  110.             next;
  111.         }
  112.  
  113.         if ($line =~ /^\s*$/) {
  114.             $self->save_tag(\@entries);
  115.             next;
  116.         }
  117.  
  118.         push @errors, {
  119.             row => $cnt,
  120.             line => $line,
  121.         }
  122.     }
  123.     $self->save_tag(\@entries);
  124.     return \@entries, \@errors;
  125. }
  126.  
  127. sub save_tag {
  128.     my ($self, $entries) = @_;
  129.  
  130.     if ($self->{tag} and $self->{tag} eq 'numbered-list') {
  131.         # TODO: verify that it is a proper list
  132.         for my $row (@{ $self->{list} }) {
  133.             delete $row->{raw};
  134.             delete $row->{sep};
  135.             delete $row->{space};
  136.         }
  137.         push @$entries, {
  138.             tag => $self->{tag},
  139.             list => $self->{list},
  140.         };
  141.         $self->{tag} = undef;
  142.         delete $self->{list};
  143.         return;
  144.     }
  145.  
  146.  
  147.     if ($self->{tag} and $self->{tag} eq 'list') {
  148.         if ($self->{list}{ok}) {
  149.             delete $self->{list}{raw};
  150.             delete $self->{list}{ok};
  151.             delete $self->{list}{space};
  152.             delete $self->{list}{bullet};
  153.             push @$entries, {
  154.                 tag => $self->{tag},
  155.                 list => $self->{list},
  156.             };
  157.             $self->{tag} = undef;
  158.             delete $self->{list};
  159.             return;
  160.         }
  161.  
  162.         # If it is a failed list, convert it to paragraph
  163.         $self->{tag} = 'p';
  164.         $self->{text} = join '', @{ $self->{list}{raw} };
  165.         delete $self->{list};
  166.     }
  167.  
  168.     if ($self->{tag}) {
  169.         $self->{text} =~ s/\n+\Z//;
  170.         push @$entries, {
  171.             tag => $self->{tag},
  172.             text => $self->{text},
  173.         };
  174.         $self->{tag} = undef;
  175.         $self->{text} = '';
  176.     }
  177.     return;
  178. }
  179.  
  180. 1;
  181.  
  182. __END__
  183.  
  184. =head1 NAME
  185.  
  186. Markua::Parser - Parsing Markua files and for writing books, generating DOM
  187.  
  188. =head1 SYNOPSIS
  189.  
  190.     use Markua::Parser;
  191.     my $m = Markua::Parser->new;
  192.     my ($result, $errors) = $m->parse_file("path/to/file.md");
  193.  
  194. =head1 DESCRIPTION
  195.  
  196. L<Markua|https://leanpub.com/markua/read> is a Markdown inspired language to write books.
  197. It was created by Peter Armstrong for L<LeanPub|https://leanpub.com/>
  198. They have an in-house partial implementation in Ruby.
  199.  
  200. This is an Open Source partial implementation in Perl.
  201.  
  202. The development process is described in the L<Creating a Markua Parser in Perl 5|https://leanpub.com/markua-parser-in-perl5> eBook.
  203.  
  204. =head1 COPYRIGHT
  205.  
  206. Copyright 2018 Gabor Szabo L<https://szabgab.com/>
  207.  
  208. =head1 LICENSE
  209.  
  210. This program is free software; you can redistribute it and/or
  211. modify it under the same terms as Perl 5 itself.
  212.  
  213. =head1 DISCLAIMER OF WARRANTY
  214.  
  215. BECAUSE THIS SOFTWARE IS LICENSED FREE OF CHARGE, THERE IS NO WARRANTY
  216. FOR THE SOFTWARE, TO THE EXTENT PERMITTED BY APPLICABLE LAW. EXCEPT WHEN
  217. OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND/OR OTHER PARTIES
  218. PROVIDE THE SOFTWARE "AS IS" WITHOUT WARRANTY OF ANY KIND, EITHER
  219. EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED
  220. WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE. THE
  221. ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE SOFTWARE IS WITH
  222. YOU. SHOULD THE SOFTWARE PROVE DEFECTIVE, YOU ASSUME THE COST OF ALL
  223. NECESSARY SERVICING, REPAIR, OR CORRECTION.
  224.  
  225. IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
  226. WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MAY MODIFY AND/OR
  227. REDISTRIBUTE THE SOFTWARE AS PERMITTED BY THE ABOVE LICENCE, BE
  228. LIABLE TO YOU FOR DAMAGES, INCLUDING ANY GENERAL, SPECIAL, INCIDENTAL,
  229. OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE
  230. THE SOFTWARE (INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING
  231. RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A
  232. FAILURE OF THE SOFTWARE TO OPERATE WITH ANY OTHER SOFTWARE), EVEN IF
  233. SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
  234. SUCH DAMAGES.
  235.  
  236.  
  237. =cut
  238.  
  239. # Copyright 2018 Gabor Szabo https://szabgab.com/
  240. # LICENSE
  241. # This program is free software; you can redistribute it and/or
  242. # modify it under the same terms as Perl 5 itself.
  243.  

Update Makefile.PL

Now that we have added the POD to the module, we can take the ABSTRACT from there. We need to set the LICENSE field. We can include links to the GitHub repository of the project to make it easier for visitors of MetaCPAN to find the source code and contribute. There is some explanation about the various fields in the article Makefile.PL of ExtUtils::MakeMaker.

examples/markua-parser/0764270/Makefile.PL

  1. use strict;
  2. use warnings;
  3. use ExtUtils::MakeMaker;
  4.  
  5. WriteMakefile(
  6.     NAME          => 'Markua::Parser',
  7.     AUTHOR        => q{Gabor Szabo <szabgab@cpan.org>},
  8.     VERSION_FROM  => 'lib/Markua/Parser.pm',
  9.     ABSTRACT_FROM => 'lib/Markua/Parser.pm',
  10.     LICENSE       => 'perl',
  11.     PL_FILES      => {},
  12.     PREREQ_PM     => {
  13.         'Path::Tiny'      => 0.072,
  14.         'JSON::MaybeXS'   => 1,
  15.     },
  16.     TEST_REQUIRES => {
  17.           'Test::More'    => 1.001014,
  18.     },
  19.     META_MERGE    => {
  20.         'meta-spec' => { version => 2 },
  21.          resources => {
  22.              repository => {
  23.                  type => 'git',
  24.                  url  => 'https://github.com/szabgab/perl5-markua-parser.git',
  25.                  web  => 'https://github.com/szabgab/perl5-markua-parser',
  26.              },
  27.              bugtracker => {web => 'https://github.com/szabgab/perl5-markua-parser/issues'},
  28.              homepage   => 'https://github.com/szabgab/perl5-markua-parser',
  29.          },
  30.     },
  31. );

MANIFEST and MANIFEST.SKIP

When we create the distribution we are going to run make manifest that will create a file called MANIFEST and then it will use the content of that file to know which files to include in the distribution.

The MANIFEST.SKIP file is a place where we can create rules which files to include in the MANIFEST file and which not.

examples/markua-parser/0764270/MANIFEST.SKIP

  1. ^.appveyor.yml
  2. ^.travis.yml
  3. ^.git/
  4. ^.gitignore
  5. ^MYMETA.*
  6. ^MYMETA.yml
  7. ^pm_to_blib
  8. ^Makefile$
  9. ^MANIFEST.bak
  10. ^MANIFEST.SKIP
  11. ^blib/

Creating the distribution

perl Makefile.PL
make
make test
make manifest
make dist

This will create a file called Markua-Parser-0.01.tar.gz. We can upload that to PAUSE the upload server of CPAN. 

git add .
git commit -m "prepare files for the first release to CPAN"
git push

commit

We also put a tag on this commit to make it easier to find the version that was used for this release. 

git tag -m v0.01 -a v0.01
git push --tags