/ 
Venus-5.01
River stage two • 3 direct dependents • 56 total dependents
⭐ Starred 2 GitHub stars
/ Venus::Text::Pod

NAME

Venus::Text::Pod - Text (Pod) Class

ABSTRACT

Text (Pod) Class for Perl 5

SYNOPSIS

package main;

use Venus::Text::Pod;

my $text = Venus::Text::Pod->new('t/data/sections');

# $text->find(undef, 'name');

DESCRIPTION

This package provides methods for extracting POD blocks from any file or package.

POD syntax

# pod syntax

=head1 NAME

Example #1

=cut

=head1 NAME

Example #2

=cut

# pod-ish syntax

=name

Example #1

=cut

=name

Example #2

=cut

POD syntax (nested)

# pod syntax (nested)

=nested

Example #1

+=head1 WHY?

blah blah blah

+=cut

More information on the same topic as was previously mentioned in the
previous section demonstrating the topic, obviously from said section.

=cut

METHODS

This package provides the following methods:

count

count(hashref $criteria) (number)

The count method uses the criteria provided to "search" for and return the number of blocks found.

Since 4.15

count example 1
# given: synopsis;

my $count = $text->count;

# 7

data

data() (string)

The data method returns the contents of the "file" to be parsed.

Since 4.15

data example 1
# given: synopsis;

$text = $text->data;

# ...

find

find(maybe[string] $list, maybe[string] $name) (arrayref)

The find method is a wrapper around "search" as shorthand for searching by list and name.

Since 4.15

find example 1
# given: synopsis;

my $find = $text->find(undef, 'name');

# [
#   { data => ["Example #1"], index => 4, list => undef, name => "name" },
#   { data => ["Example #2"], index => 5, list => undef, name => "name" },
# ]
find example 2
# given: synopsis;

my $find = $text->find('head1', 'NAME');

# [
#   { data => ["Example #1"], index => 1, list => "head1", name => "NAME" },
#   { data => ["Example #2"], index => 2, list => "head1", name => "NAME" },
# ]

new

new(any @args) (Venus::Text::Pod)

The new method constructs an instance of the package.

Since 4.15

new example 1
package main;

use Venus::Text::Pod;

my $new = Venus::Text::Pod->new;

# bless(..., "Venus::Text::Pod")
new example 2
package main;

use Venus::Text::Pod;

my $new = Venus::Text::Pod->new('t/data/sections');

# bless(..., "Venus::Text::Pod")
new example 3
package main;

use Venus::Text::Pod;

my $new = Venus::Text::Pod->new(file => 't/data/sections');

# bless(..., "Venus::Text::Pod")
find(hashref $criteria) (arrayref)

The search method returns the set of blocks matching the criteria provided. This method can return a list of values in list-context.

Since 4.15

search example 1
# given: synopsis;

my $search = $text->search({list => undef, name => 'name'});

# [
#   { data => ["Example #1"], index => 4, list => undef, name => "name" },
#   { data => ["Example #2"], index => 5, list => undef, name => "name" },
# ]
search example 2
# given: synopsis;

my $search = $text->search({list => 'head1', name => 'NAME'});

# [
#   { data => ["Example #1"], index => 1, list => "head1", name => "NAME" },
#   { data => ["Example #2"], index => 2, list => "head1", name => "NAME" },
# ]

string

string(maybe[string] $list, maybe[string] $name) (string)

The string method is a wrapper around "find" as shorthand for searching by list and name, returning only the strings found.

Since 4.15

string example 1
# given: synopsis;

my $string = $text->string(undef, 'name');

# "Example #1\nExample #2"
string example 2
# given: synopsis;

my $string = $text->string('head1', 'NAME');

# "Example #1\nExample #2"
string example 3
# given: synopsis;

my @string = $text->string('head1', 'NAME');

# ("Example #1", "Example #2")

AUTHORS

Awncorp, awncorp@cpan.org

LICENSE

Copyright (C) 2022, Awncorp, awncorp@cpan.org.

This program is free software, you can redistribute it and/or modify it under the terms of the Apache license version 2.0.