Skip site navigation (1)Skip section navigation (2)

FreeBSD Manual Pages

  
 
  

home | help
Pod::Readme::Plugin(3)User Contributed Perl DocumentatioPod::Readme::Plugin(3)

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.

perl v5.32.0			  2018-10-31		Pod::Readme::Plugin(3)

NAME | DESCRIPTION | WRITING PLUGINS | ATTRIBUTES | METHODS

Want to link to this manual page? Use this URL:
<https://www.freebsd.org/cgi/man.cgi?query=Pod::Readme::Plugin&sektion=3&manpath=FreeBSD+12.2-RELEASE+and+Ports>

home | help