Pod::R...:Plugin(3pm)

💖 Pod::R...:Plugin — the manual, but make it cute 💖

okay bestie, so this is Pod::R...:Plugin(3pm), from the User Contributed Perl Documentation collection, and it is exactly what you need if you want to know how plugins work in Pod::Readme. sit down, hydrate, let's go 🫶

---

✨ NAME ✨

Pod::Readme::Plugin — it's the plugin role for Pod::Readme. that's the whole name. periodt 💅

---

🌸 DESCRIPTION 🌸

so here's the tea: Pod::Readme v1.0 and later supports plugins that extend the capabilities of the module. that's it, that's the description. it's giving "short but iconic" ✨

---

🦋 WRITING PLUGINS 🦋

ngl, writing plugins is straightforward. like, genuinely. plugins are Moo::Role modules that live 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 );

    ...
}

so when Pod::Readme encounters POD that looks like

=for readme plugin myplugin arg1 arg2

the plugin role gets loaded, and the cmd_myplugin method gets run. main character energy, honestly 💅

note: you do not need to specify a cmd_myplugin method. no cap.

any method prefixed with cmd_ will be a command that can be called using the =for readme command syntax. so cmd_ = "this is callable", basically. iykyk 🎀

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

if you want examples, go look at some of the included plugins, such as Pod::Readme::Plugin::version. iconic behaviour, study it 📚

---

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. don't skip the lazy, bestie, it matters 😤

heads up: 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. like, the state sticks around. that's just how it is 💀

---

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. that's the vibe, that's the whole attribute 🌈

---

💜 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. cute and useful 🍓

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 — don't forget the quotes, she will not parse right 🙈)

otherwise, an argument is assumed to be boolean, which defaults to true. and if the argument is prefixed by no- or no_ then it is given a false value. classic.

if the @allowed_keys parameter is given, then it will reject argument keys that are not in that list. strict queen 👑

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',
}

slay. look at that output ✨

---

"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. simple, effective, we love her 💖

---

"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. legacy support besties, they're doing the work so you don't have to 🫡

---

and that's the whole page, bestie!! every option, every method, every word — all of it. you're officially a Pod::Readme::Plugin girlie now. go write something iconic 💅✨

mwah 💋 — this was Pod::R...:Plugin(3pm) from perl v5.28.0, dated 2018-11-26, part of the User Contributed Perl Documentation. see you in the group chat 🫶