.\" Automatically generated by Pod::Man 4.10 (Pod::Simple 3.35)
.\"
.\" Standard preamble:
.\" ========================================================================
.de Sp \" Vertical space (when we can't use .PP)
.if t .sp .5v
.if n .sp
..
.de Vb \" Begin verbatim text
.ft CW
.nf
.ne \\$1
..
.de Ve \" End verbatim text
.ft R
.fi
..
.\" Set up some character translations and predefined strings.  \*(-- will
.\" give an unbreakable dash, \*(PI will give pi, \*(L" will give a left
.\" double quote, and \*(R" will give a right double quote.  \*(C+ will
.\" give a nicer C++.  Capital omega is used to do unbreakable dashes and
.\" therefore won't be available.  \*(C` and \*(C' expand to `' in nroff,
.\" nothing in troff, for use with C<>.
.tr \(*W-
.ds C+ C\v'-.1v'\h'-1p'\s-2+\h'-1p'+\s0\v'.1v'\h'-1p'
.ie n \{\
.    ds -- \(*W-
.    ds PI pi
.    if (\n(.H=4u)&(1m=24u) .ds -- \(*W\h'-12u'\(*W\h'-12u'-\" diablo 10 pitch
.    if (\n(.H=4u)&(1m=20u) .ds -- \(*W\h'-12u'\(*W\h'-8u'-\"  diablo 12 pitch
.    ds L" ""
.    ds R" ""
.    ds C` ""
.    ds C' ""
'br\}
.el\{\
.    ds -- \|\(em\|
.    ds PI \(*p
.    ds L" ``
.    ds R" ''
.    ds C`
.    ds C'
'br\}
.\"
.\" Escape single quotes in literal strings from groff's Unicode transform.
.ie \n(.g .ds Aq \(aq
.el       .ds Aq '
.\"
.\" If the F register is >0, we'll generate index entries on stderr for
.\" titles (.TH), headers (.SH), subsections (.SS), items (.Ip), and index
.\" entries marked with X<> in POD.  Of course, you'll have to process the
.\" output yourself in some meaningful fashion.
.\"
.\" Avoid warning from groff about undefined register 'F'.
.de IX
..
.nr rF 0
.if \n(.g .if rF .nr rF 1
.if (\n(rF:(\n(.g==0)) \{\
.    if \nF \{\
.        de IX
.        tm Index:\\$1\t\\n%\t"\\$2"
..
.        if !\nF==2 \{\
.            nr % 0
.            nr F 2
.        \}
.    \}
.\}
.rr rF
.\" ========================================================================
.\"
.IX Title "Pod::Readme::Plugin 3pm"
.TH Pod::Readme::Plugin 3pm "2018-11-26" "perl v5.28.0" "User Contributed Perl Documentation"
.\" For nroff, turn off justification.  Always turn off hyphenation; it makes
.\" way too many mistakes in technical documents.
.if n .ad l
.nh
.SH "NAME"
Pod::Readme::Plugin \- Plugin role for Pod::Readme
.SH "DESCRIPTION"
.IX Header "DESCRIPTION"
Pod::Readme v1.0 and later supports plugins that extend the
capabilities of the module.
.SH "WRITING PLUGINS"
.IX Header "WRITING PLUGINS"
Writing plugins is straightforward. Plugins are Moo::Role modules
in the \f(CW\*(C`Pod::Readme::Plugin\*(C'\fR namespace.  For example,
.PP
.Vb 1
\&  package Pod::Readme::Plugin::myplugin;
\&
\&  use Moo::Role;
\&
\&  sub cmd_myplugin {
\&      my ($self, @args) = @_;
\&      my $res = $self\->parse_cmd_args( [qw/ arg1 arg2 /], @args );
\&
\&      ...
\&  }
.Ve
.PP
When Pod::Readme encounters \s-1POD\s0 with
.PP
.Vb 1
\&  =for readme plugin myplugin arg1 arg2
.Ve
.PP
the plugin role will be loaded, and the \f(CW\*(C`cmd_myplugin\*(C'\fR method will be
run.
.PP
Note that you do not need to specify a \f(CW\*(C`cmd_myplugin\*(C'\fR method.
.PP
Any method prefixed with \*(L"cmd_\*(R" will be a command that can be called
using the \f(CW\*(C`=for readme command\*(C'\fR syntax.
.PP
A plugin parses arguments using the \*(L"parse_cmd_arguments\*(R" method and
writes output using the write methods noted above.
.PP
See some of the included plugins, such as
Pod::Readme::Plugin::version for examples.
.PP
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.
.PP
.Vb 1
\&  use Types::Standard qw/ Int /;
\&
\&  has \*(Aqmyplugin_heading_level\*(Aq => (
\&    is      => \*(Aqrw\*(Aq,
\&    isa     => Int,
\&    default => 1,
\&    lazy    => 1,
\&  );
.Ve
.PP
Attributes should be lazy to ensure that their defaults are properly
set.
.PP
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.
.PP
Custom types in Pod::Readme::Types may be useful for attributes
when writing plugins, e.g.
.PP
.Vb 1
\&  use Pod::Readme::Types qw/ File HeadingLevel /;
\&
\&  has \*(Aqmyplugin_file\*(Aq => (
\&    is      => \*(Aqrw\*(Aq,
\&    isa     => File,
\&    coerce  => sub { File\->coerce(@_) },
\&    default => \*(AqChanges\*(Aq,
\&    lazy => 1,
\&  );
\&
\&  # We add this file to the list of dependencies
\&
\&  around \*(Aqdepends_on\*(Aq => sub {
\&    my ($orig, $self) = @_;
\&    return ($self\->myplugin_file, $self\->$orig);
\&  };
.Ve
.SH "ATTRIBUTES"
.IX Header "ATTRIBUTES"
.ie n .SS """verbatim_indent"""
.el .SS "\f(CWverbatim_indent\fP"
.IX Subsection "verbatim_indent"
The number of columns to indent a verbatim paragraph.
.SH "METHODS"
.IX Header "METHODS"
.ie n .SS """parse_cmd_args"""
.el .SS "\f(CWparse_cmd_args\fP"
.IX Subsection "parse_cmd_args"
.Vb 1
\&  my $hash_ref = $self\->parse_cmd_args( \e@allowed_keys, @args);
.Ve
.PP
This command parses arguments for a plugin and returns a hash
reference containing the argument values.
.PP
The \f(CW@args\fR parameter is a list of arguments passed to the command
method by Pod::Readme::Filter.
.PP
If an argument contains an equals sign, then it is assumed to take a
string.  (Strings containing whitespace should be surrounded by
quotes.)
.PP
Otherwise, an argument is assumed to be boolean, which defaults to
true. If the argument is prefixed by \*(L"no\-\*(R" or \*(L"no_\*(R" then it is given a
false value.
.PP
If the \f(CW@allowed_keys\fR parameter is given, then it will reject
argument keys that are not in that list.
.PP
For example,
.PP
.Vb 7
\&  my $res = $self\->parse_cmd_args(
\&              undef,
\&              \*(Aqarg1\*(Aq,
\&              \*(Aqno\-arg2\*(Aq,
\&              \*(Aqarg3="This is a string"\*(Aq,
\&              \*(Aqarg4=value\*(Aq,
\&  );
.Ve
.PP
will return a hash reference containing
.PP
.Vb 6
\&  {
\&     arg1 => 1,
\&     arg2 => 0,
\&     arg3 => \*(AqThis is a string\*(Aq,
\&     arg4 => \*(Aqvalue\*(Aq,
\&  }
.Ve
.ie n .SS """write_verbatim"""
.el .SS "\f(CWwrite_verbatim\fP"
.IX Subsection "write_verbatim"
.Vb 1
\&  $self\->write_verbatim($text);
.Ve
.PP
A utility method to write verbatim text, indented by
\&\*(L"verbatim_indent\*(R".
.ie n .SS """write_para"""
.el .SS "\f(CWwrite_para\fP"
.IX Subsection "write_para"
.Vb 1
\&  $self\->write_para(\*(AqThis is a paragraph\*(Aq);
.Ve
.PP
Utility method to write a \s-1POD\s0 paragraph.
.ie n .SS """write_head1"""
.el .SS "\f(CWwrite_head1\fP"
.IX Subsection "write_head1"
.ie n .SS """write_head2"""
.el .SS "\f(CWwrite_head2\fP"
.IX Subsection "write_head2"
.ie n .SS """write_head3"""
.el .SS "\f(CWwrite_head3\fP"
.IX Subsection "write_head3"
.ie n .SS """write_head4"""
.el .SS "\f(CWwrite_head4\fP"
.IX Subsection "write_head4"
.ie n .SS """write_over"""
.el .SS "\f(CWwrite_over\fP"
.IX Subsection "write_over"
.ie n .SS """write_item"""
.el .SS "\f(CWwrite_item\fP"
.IX Subsection "write_item"
.ie n .SS """write_back"""
.el .SS "\f(CWwrite_back\fP"
.IX Subsection "write_back"
.ie n .SS """write_begin"""
.el .SS "\f(CWwrite_begin\fP"
.IX Subsection "write_begin"
.ie n .SS """write_end"""
.el .SS "\f(CWwrite_end\fP"
.IX Subsection "write_end"
.ie n .SS """write_for"""
.el .SS "\f(CWwrite_for\fP"
.IX Subsection "write_for"
.ie n .SS """write_encoding"""
.el .SS "\f(CWwrite_encoding\fP"
.IX Subsection "write_encoding"
.ie n .SS """write_cut"""
.el .SS "\f(CWwrite_cut\fP"
.IX Subsection "write_cut"
.ie n .SS """write_pod"""
.el .SS "\f(CWwrite_pod\fP"
.IX Subsection "write_pod"
.Vb 1
\&  $self\->write_head1($text);
.Ve
.PP
Utility methods to write \s-1POD\s0 specific commands to the \f(CW\*(C`output_file\*(C'\fR.
.PP
These methods ensure the \s-1POD\s0 commands have extra newlines for
compatibility with older \s-1POD\s0 parsers.