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.