---
name: "Pod::Readme::Plugin"
section: "3pm"
platform: "linux"
package: "libpod-readme-perl"
version: "1.2.3-1"
release: "Debian 13 (Trixie)"
platforms: ["linux"]
url: "https://new.carta.tech/Pod::Readme::Plugin"
---

# Pod::Readme::Plugin(3pm)

Plugin role for Pod::Readme

## 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.