NAME

Venus::Data - Data Class

ABSTRACT

Data Class for Perl 5

SYNOPSIS

  package main;
  use Venus::Data;
  my $data = Venus::Data->new('t/data/sections');
  # $data->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

INHERITS

This package inherits behaviors from:

Venus::Path

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;
  my $count = $data->docs->count;
  # 6

count example 2

  # given: synopsis;
  my $count = $data->text->count;
  # 3

data

  data() (string)

The data method returns the text between the "DATA" and "END" sections of a Perl package or file.

Since 0.01

data example 1

  # given: synopsis;
  $data = $data->data;
  # ...

docs

  docs() (Venus::Data)

The docs method configures the instance for parsing POD blocks.

Since 0.01

docs example 1

  # given: synopsis;
  my $docs = $data->docs;
  # bless({ etag => "=cut", from => "read", stag => "=", ... }, "Venus::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;
  my $find = $data->docs->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 = $data->docs->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;
  my $find = $data->text->find(undef, 'name');
  # [
  #   { data => ["Example Name"], index => 1, list => undef, name => "name" },
  # ]

find example 4

  # given: synopsis;
  my $find = $data->text->find('titles', '#1');
  # [
  #   { data => ["Example Title #1"], index => 2, list => "titles", name => "#1" },
  # ]

search

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

search example 1

  # given: synopsis;
  my $search = $data->docs->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 = $data->docs->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;
  my $find = $data->text->search({list => undef, name => 'name'});
  # [
  #   { data => ["Example Name"], index => 1, list => undef, name => "name" },
  # ]

search example 4

  # given: synopsis;
  my $search = $data->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;
  my $string = $data->docs->string(undef, 'name');
  # "Example #1\nExample #2"

string example 2

  # given: synopsis;
  my $string = $data->docs->string('head1', 'NAME');
  # "Example #1\nExample #2"

string example 3

  # given: synopsis;
  my $string = $data->text->string(undef, 'name');
  # "Example Name"

string example 4

  # given: synopsis;
  my $string = $data->text->string('titles', '#1');
  # "Example Title #1"

string example 5

  # given: synopsis;
  my @string = $data->docs->string('head1', 'NAME');
  # ("Example #1", "Example #2")

text

  text() (Venus::Data)

The text method configures the instance for parsing DATA blocks.

Since 0.01

text example 1

  # given: synopsis;
  my $text = $data->text;
  # bless({ etag  => '@@ end', from  => 'data', stag  => '@@ ', ... }, "Venus::Data")

AUTHORS

Awncorp, "awncorp@cpan.org"

LICENSE

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