NAME

       Dist::Zilla::Plugin::PkgVersion - add a $VERSION to your packages

VERSION

       version 6.030

SYNOPSIS

       in dist.ini

         [PkgVersion]

DESCRIPTION

       This plugin will add lines like the following to each package in each Perl module or
       program (more or less) within the distribution:

         $MyModule::VERSION = '0.001';

       or

         { our $VERSION = '0.001'; }

       ...where 0.001 is the version of the dist, and MyModule is the name of the package being
       given a version.  (In other words, it always uses fully-qualified names to assign
       versions.)

       It will skip any package declaration that includes a newline between the "package" keyword
       and the package name, like:

         package
           Foo::Bar;

       This sort of declaration is also ignored by the CPAN toolchain, and is typically used when
       doing monkey patching or other tricky things.

PERL VERSION

       This module should work on any version of perl still receiving updates from the Perl 5
       Porters.  This means it should work on any version of perl released in the last two to
       three years.  (That is, if the most recently released version is v5.40, then this module
       should work on both v5.40 and v5.38.)

       Although it may work on older versions of perl, no guarantee is made that the minimum
       required version will not be increased.  The version may be increased for any reason, and
       there is no promise that patches will be accepted to lower the minimum required perl.

ATTRIBUTES

   die_on_existing_version
       If true, then when PkgVersion sees an existing $VERSION assignment, it will throw an
       exception rather than skip the file.  This attribute defaults to false.

   die_on_line_insertion
       By default, PkgVersion looks for a blank line after each "package" statement.  If it finds
       one, it inserts the $VERSION assignment on that line.  If it doesn't, it will insert a new
       line, which means the shipped copy of the module will have different line numbers (off by
       one) than the source.  If "die_on_line_insertion" is true, PkgVersion will raise an
       exception rather than insert a new line.

   use_package
       This option, if true, will not insert an assignment to $VERSION but will replace the
       existing "package" declaration with one that includes a version like:

         package Module::Name 0.001;

   use_our
       The idea here was to insert "{ our $VERSION = '0.001'; }" instead of
       "$Module::Name::VERSION = '0.001';".  It turns out that this causes problems with some
       analyzers.  Use of this feature is deprecated.

       Something else will replace it in the future.

   use_begin
       If true, the version assignment is wrapped in a BEGIN block.  This may help in rare cases,
       such as when DynaLoader has to be called at BEGIN time, and requires VERSION.  This option
       should be needed rarely.

       Also note that assigning to $VERSION before the module has finished compiling can lead to
       confused behavior with attempts to determine whether a module was successfully loaded on
       perl v5.8.

   finder
       This is the name of a FileFinder for finding modules to edit.  The default value is
       ":InstallModules" and ":ExecFiles"; this option can be used more than once.

       Other predefined finders are listed in "default_finders" in
       Dist::Zilla::Role::FileFinderUser.  You can define your own with the [FileFinder::ByName]
       and [FileFinder::Filter] plugins.

SEE ALSO

       Core Dist::Zilla plugins: PodVersion, AutoVersion, NextRelease.

       Other Dist::Zilla plugins: OurPkgVersion inserts version numbers using "our $VERSION =
       '...';" and without changing line numbers

AUTHOR

       Ricardo SIGNES 😏 <cpan@semiotic.systems>

COPYRIGHT AND LICENSE

       This software is copyright (c) 2023 by Ricardo SIGNES.

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