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

NAME

Venus::Text - Text Class

ABSTRACT

Text Class for Perl 5

SYNOPSIS

package main;

use Venus::Text;

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

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

DESCRIPTION

This package provides methods for extracting DATA sections and POD blocks from any file or package. The package can be configured to parse either POD or DATA blocks, and it defaults to being configured for POD blocks.

DATA syntax

__DATA__

# data syntax

@@ name

Example Name

@@ end

@@ titles #1

Example Title #1

@@ end

@@ titles #2

Example Title #2

@@ end

DATA syntax (nested)

__DATA__

# data syntax (nested)

@@ nested

Example Nested

+@@ demo

blah blah blah

+@@ end

@@ end

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 0.01

count example 1
# given: synopsis;

$text->stag('=');

$text->etag('=cut');

my $count = $text->count;

# 7
count example 2
# given: synopsis;

$text->stag('@@ ');

$text->etag('@@ end');

my $count = $text->count;

# 3

data

data() (string)

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

Since 0.01

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 0.01

find example 1
# given: synopsis;

$text->stag('=');

$text->etag('=cut');

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;

$text->stag('=');

$text->etag('=cut');

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

# [
#   { data => ["Example #1"], index => 1, list => "head1", name => "NAME" },
#   { data => ["Example #2"], index => 2, list => "head1", name => "NAME" },
# ]
find example 3
# given: synopsis;

$text->stag('@@ ');

$text->etag('@@ end');

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

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

$text->stag('@@ ');

$text->etag('@@ end');

my $find = $text->find('titles', '#1');

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

new

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

The new method constructs an instance of the package.

Since 4.15

new example 1
package main;

use Venus::Text;

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

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

use Venus::Text;

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

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

use Venus::Text;

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

# bless(..., "Venus::Text")
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 0.01

search example 1
# given: synopsis;

$text->stag('=');

$text->etag('=cut');

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;

$text->stag('=');

$text->etag('=cut');

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" },
# ]
search example 3
# given: synopsis;

$text->stag('@@ ');

$text->etag('@@ end');

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

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

$text->stag('@@ ');

$text->etag('@@ end');

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

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

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 1.67

string example 1
# given: synopsis;

$text->stag('=');

$text->etag('=cut');

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

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

$text->stag('=');

$text->etag('=cut');

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

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

$text->stag('@@ ');

$text->etag('@@ end');

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

# "Example Name"
string example 4
# given: synopsis;

$text->stag('@@ ');

$text->etag('@@ end');

my $string = $text->string('titles', '#1');

# "Example Title #1"
string example 5
# given: synopsis;

$text->stag('=');

$text->etag('=cut');

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.