NAME

       Pod::Readme::Plugin - Plugin role for Pod::Readme

DESCRIPTION

       Pod::Readme v1.0 and later supports plugins that extend the capabilities of the module.

WRITING PLUGINS

       Writing plugins is straightforward. Plugins are Moo::Role modules in the
       "Pod::Readme::Plugin" namespace.  For example,

         package Pod::Readme::Plugin::myplugin;

         use Moo::Role;

         sub cmd_myplugin {
             my ($self, @args) = @_;
             my $res = $self->parse_cmd_args( [qw/ arg1 arg2 /], @args );

             ...
         }

       When Pod::Readme encounters POD with

         =for readme plugin myplugin arg1 arg2

       the plugin role will be loaded, and the "cmd_myplugin" method will be run.

       Note that you do not need to specify a "cmd_myplugin" method.

       Any method prefixed with "cmd_" will be a command that can be called using the "=for
       readme command" syntax.

       A plugin parses arguments using the "parse_cmd_arguments" method and writes output using
       the write methods noted above.

       See some of the included plugins, such as Pod::Readme::Plugin::version for examples.

       Any attributes in the plugin should be prefixed with the name of the plugin, to avoid any
       conflicts with attribute and method names from other plugins, e.g.

         use Types::Standard qw/ Int /;

         has 'myplugin_heading_level' => (
           is      => 'rw',
           isa     => Int,
           default => 1,
           lazy    => 1,
         );

       Attributes should be lazy to ensure that their defaults are properly set.

       Be aware that changing default values of an attribute based on arguments means that the
       next time a plugin method is run, the defaults will be changed.

       Custom types in Pod::Readme::Types may be useful for attributes when writing plugins, e.g.

         use Pod::Readme::Types qw/ File HeadingLevel /;

         has 'myplugin_file' => (
           is      => 'rw',
           isa     => File,
           coerce  => sub { File->coerce(@_) },
           default => 'Changes',
           lazy => 1,
         );

         # We add this file to the list of dependencies

         around 'depends_on' => sub {
           my ($orig, $self) = @_;
           return ($self->myplugin_file, $self->$orig);
         };

ATTRIBUTES

   "verbatim_indent"
       The number of columns to indent a verbatim paragraph.

METHODS

   "parse_cmd_args"
         my $hash_ref = $self->parse_cmd_args( \@allowed_keys, @args);

       This command parses arguments for a plugin and returns a hash reference containing the
       argument values.

       The @args parameter is a list of arguments passed to the command method by
       Pod::Readme::Filter.

       If an argument contains an equals sign, then it is assumed to take a string.  (Strings
       containing whitespace should be surrounded by quotes.)

       Otherwise, an argument is assumed to be boolean, which defaults to true. If the argument
       is prefixed by "no-" or "no_" then it is given a false value.

       If the @allowed_keys parameter is given, then it will reject argument keys that are not in
       that list.

       For example,

         my $res = $self->parse_cmd_args(
                     undef,
                     'arg1',
                     'no-arg2',
                     'arg3="This is a string"',
                     'arg4=value',
         );

       will return a hash reference containing

         {
            arg1 => 1,
            arg2 => 0,
            arg3 => 'This is a string',
            arg4 => 'value',
         }

   "write_verbatim"
         $self->write_verbatim($text);

       A utility method to write verbatim text, indented by "verbatim_indent".

   "write_para"
         $self->write_para('This is a paragraph');

       Utility method to write a POD paragraph.

   "write_head1"
   "write_head2"
   "write_head3"
   "write_head4"
   "write_over"
   "write_item"
   "write_back"
   "write_begin"
   "write_end"
   "write_for"
   "write_encoding"
   "write_cut"
   "write_pod"
         $self->write_head1($text);

       Utility methods to write POD specific commands to the "output_file".

       These methods ensure the POD commands have extra newlines for compatibility with older POD
       parsers.