view release on metacpan or  search on metacpan

lib/ASPEER/MakeMaker/Markdown/Pod/MM.pm  view on Meta::CPAN

                verbose("markpod: %s -> %s: skipped, missing target", $fn, $target_fn);
                next;
            }
            msg("markpod: %s -> %s: starting merge", $fn, $target_fn);
            my $markpod_or=Markdown::Pod::Embed->new();
            my $pod_changed=$markpod_or->markpod_process_and_update($target_fn);
            if (!defined $pod_changed) {
                msg("markpod: %s -> %s: finished, skipped", $fn, $target_fn);
            }
            elsif ($pod_changed) {
                msg("markpod: %s -> %s: finished, updated pod", $fn, $target_fn);
            }
            else {
                msg("markpod: %s -> %s: finished, no changes", $fn, $target_fn);
            }
        }
        else {
            verbose("markpod: %s -> %s: skipped, unsupported target", $fn, $target_fn);

        }

    }


    #  Done
    #
    return undef;

}


sub readme {


    #  Build README files from README.md or VERSION_FROM markdown
    #
    my ($self, $param_hr)=(shift(), arg(@_));
    require Markdown::Pod::Embed;


    #  Get manifest for any file additions we make
    #
    require ExtUtils::Manifest;
    my $manifest_hr=ExtUtils::Manifest::maniread();
    my @manifest_add;
    my $version_from_fn=$param_hr->{'VERSION_FROM'};
    my $readme_md_fn='README.md';
    my $readme_fn='README';
    my $markpod_or=Markdown::Pod::Embed->new();
    my $md;
    my $source_fn;


    #  Use an existing Markdown README when one is available
    #
    if (-f $readme_md_fn) {
        $source_fn=$readme_md_fn;
        $md=slurp($readme_md_fn);
    }
    elsif (-e $readme_md_fn || -l $readme_md_fn) {
        return err("$readme_md_fn exists and is not a regular file");
    }
    elsif (-e $readme_fn || -l $readme_fn) {
        verbose('markpod: %s exists without %s, leaving both unchanged', $readme_fn, $readme_md_fn);
        return undef;
    }
    else {
        unless (defined $version_from_fn && length $version_from_fn) {
            verbose('markpod: no VERSION_FROM file, no README files created');
            return undef;
        }
        $md=$markpod_or->markpod_markdown_source($version_from_fn);
        unless (defined $md && length $md) {
            msg('markpod: %s -> %s: skipped, no markdown source', $version_from_fn, $readme_fn);
            return undef;
        }
        my $readme_md=$md;
        $readme_md.=$/ unless $readme_md=~/\n\z/;
        blurp($readme_md_fn, $readme_md) ||
            return err();
        push @manifest_add, $readme_md_fn unless exists $manifest_hr->{$readme_md_fn};
        $source_fn=$readme_md_fn;
    }
    msg('markpod: %s -> %s: starting render', $source_fn, $readme_fn);


    #  No markdown means nothing to render
    #
    unless (defined $md && length $md) {
        msg('markpod: %s -> %s: finished, skipped empty markdown source', $source_fn, $readme_fn);
        manifest_add(\@manifest_add) if @manifest_add;
        return undef;
    }


    #  Convert markdown to text
    #
    my $text=$markpod_or->markpod_markdown_text($md);


    #  Update README only when changed
    #
    my $existing_readme=-f $readme_fn ? slurp($readme_fn) : '';
    if (md5_hex($existing_readme) ne md5_hex($text)) {
        $markpod_or->outfile($text, $readme_fn) ||
            return err();
        msg('markpod: %s -> %s: finished, updated', $source_fn, $readme_fn);
    }
    else {
        msg('markpod: %s -> %s: finished, no changes', $source_fn, $readme_fn);
    }

    push @manifest_add, $readme_fn unless exists $manifest_hr->{$readme_fn};
    manifest_add(\@manifest_add) if @manifest_add;

}


sub manifest_add {

    my ($file_ar)=@_;
    return undef unless @{$file_ar};
    require ExtUtils::Manifest;
    my %add=map { $_ => '' } @{$file_ar};
    ExtUtils::Manifest::maniadd(\%add);
    return 1;

}


1;


__END__

=begin markdown

# NAME

ASPEER::MakeMaker::Markdown::Pod::MM - MakeMaker integration for ASPEER::MakeMaker::Markdown::Pod

# SYNOPSIS

In `Makefile.PL`:

```perl
BEGIN {
    use lib './lib';
    eval {
        require ASPEER::MakeMaker::Markdown::Pod;
        ASPEER::MakeMaker::Markdown::Pod->import;
        1;
    };
}
```

Then run:

```bash
perl Makefile.PL
make doc
make readme
```

# DESCRIPTION