/ 
Dist-Zilla-Plugin-WeaveFile-0.002
/ Dist::Zilla::Plugin::WeaveFile

NAME

Dist::Zilla::Plugin::WeaveFile - Create project files by weaving together POD, metadata, and snippets

VERSION

version 0.002

SYNOPSIS

DESCRIPTION

Dist-Zilla-Plugin-WeaveFile is a Dist::Zilla plugin, command, and test plugin for creating project files by weaving together POD documentation, distribution metadata, and text snippets using templates.

STATUS

Dist-Zilla-Plugin-WeaveFile is currently being developed so changes in the API are possible, though not likely.

In your dist.ini:

; Uses default config file .weavefilerc
[WeaveFile / README.md]

; Uses a custom config file and specifies file explicitly
[WeaveFile]
config = install-weave.yaml
file = INSTALL

[Test::WeaveFile]

Then run:

dzil weave            # generate all configured files
dzil weave README.md  # generate one file

MOTIVATION

It used to be so that a repository was only a place of work and the distribution was the actual result of that work. Only the contents of the distribution mattered. People would read the files README and INSTALL from the distribution after having downloaded it.

Not so anymore. Today the repository is out in the open in GitHub, GitLab, Codeberg or other shared hosting site. On the other hand, the documentation in the distribution is often discarded as distribution packages are rarely downloaded manually but rather via a package manager which installs them automatically.

Publicly viewable repository has in fact become much more than just a place of work. It is also an advertisement for the project and of the community behind it, if there is more than one author or contributor.

When a potential user first finds the project repository, the hosting site commonly presents him with the project README file. That makes README file in fact the welcome page to the project. Its purpose is changed from being purely informational to being an advertisement which competes for user's attention with bright colors, animated pictures, videos and exciting diagrams, shapes and "bumper stickers".

But under all the exciting cover it must also remain true to its nature: present the project as precisely as possible and stay up to date with its development.

README might also not be the only file which needs to be kept up to date because it is accessed in the (public) repository. Other potential files can include INSTALL, Changes and CODEOWNERS.

Many files therefore contain text which must be updated at least at the time of release: version numbers, API documentation, examples, file lists.

It is difficult to keep these files in sync with the code; just like documentation, which fact every programmer knows. This Dist::Zilla plugin will prevent the files from falling out of sync because their content is tested continuously.

There are other ways to do this, for instance Dist::Zilla::Plugin::CopyFilesFromBuild.

It is my philosophy that nothing in the repository is changed behind programmer's back. It can also be dangerous to the programmer if he is not a frequent Git committer. Failed local tests are much safer. And when the test fails, it is easy to run dzil weave to update the files.

USAGE

Define which files to generate in dist.ini, write the file templates in a YAML config file (default config file name .weavefilerc), and use dzil weave to generate or update the files.

The config file uses Template::Toolkit syntax with access to:

  • dist - distribution metadata (name, abstract, version, author, authors)

  • snippets - reusable text fragments defined in the config

  • pod(source, section) - extracts a POD section from a Perl module or script and converts it to Markdown

Config file format

The config file (YAML) has two sections:

---
snippets:
    badges: |
        [![CPAN](https://img.shields.io/cpan/v/My-Dist)](https://metacpan.org/dist/My-Dist)
    license: |
        This software is free software.

files:
    "README.md": |
        [% snippets.badges %]
        # [% dist.name %]
        [% dist.abstract %]
        [% pod("My::Module", "SYNOPSIS") %]
        [% pod("My::Module", "DESCRIPTION") %]
        [% snippets.license %]

The plugin Dist::Zilla::Plugin::WeaveFile does not actually do anything, except verify the configuration is correct. The configuration is used by Dist::Zilla::Plugin::Test::WeaveFile when creating the test files during the build phase. By default the tests are placed in xt/author directory, e.g. xt/author/weave_README_md.t

The configuration is also used by the command dzil weave (Dist::Zilla::App::Command::weave). Run the command when you need to create or update the files, for example, if the tests have failed.

# usage: dzil weave [<file>]
dzil weave README.md
# or, to create all files (or none if no defined)
dzil weave

During the build phase, when Dist::Zilla::Plugin::Test::WeaveFile prepares the test files, it runs the file generation just like user would run it manually with dzil weave and embeds the result into the equivalent test file. During test phase this is compared with the existing file.

ATTRIBUTES

config

Path to the YAML config file, relative to the project root. Defaults to .weavefilerc.

file

Output filename. Defaults to the plugin moniker (the part after / in [WeaveFile / README.md]).

SEE ALSO

Dist::Zilla::Plugin::CopyFilesFromBuild
Dist::Zilla::Plugin::CopyReadmeFromBuild

AUTHOR

Mikko Koivunalho <mikkoi@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2025 by Mikko Koivunalho.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.