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¶

METHODS¶

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

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

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

  $self->write_verbatim($text);

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

  $self->write_head1($text);