
=encoding utf8

=head1 NAME

Data::Object::Data

=cut

=head1 ABSTRACT

Data-Object Data Class

=cut

=head1 SYNOPSIS

  package Command;

  use Data::Object::Data;

  =help

  fetches results from the api

  =cut

  my $data = Data::Object::Data->new;

  my $help = $data->content('help');
  # fetches results ...

  my $token = $data->content('token');
  # token: the access token ...

  my $secret = $data->content('secret');
  # secret: the secret for ...

  my $flag = $data->contents('flag');
  # [,...]

  __DATA__

  =flag secret

  secret: the secret for the account

  =flag token

  token: the access token for the account

  =cut

=cut

=head1 DESCRIPTION

Data::Object::Data provides methods for parsing and extracting pod-like data
sections from any file or package. The pod-like syntax allows for using these
sections anywhere in the source code and Perl properly ignoring them.

=cut

=head1 METHODS

This package implements the following methods.

=cut

=head2 content

  content(Str $arg1) : Str

The content method returns the pod-like section where the name matches the
given string.

=over 4

=item content example

  =pod help

  Example content

  =cut

  # given $data

  $data->content('help');

  # Example content

=back

=cut

=head2 contents

  contents(Str $arg1) : ArrayRef

The contents method returns all pod-like sections that start with the given
string, e.g. C<pod> matches C<=pod foo>. This method returns an arrayref of
data for the matched sections.

=over 4

=item contents example

  =pod help

  Example content

  =cut

  # given $data

  $data->contents('pod');

  # [,...]

=back

=cut

=head2 data

  data(Str $arg1) : ArrayRef

The data method returns the contents from the C<DATA> and C<END> sections of a
package.

=over 4

=item data example

  # given $data

  $data->data($class);

  # ...

=back

=cut

=head2 file

  file(Str $arg1) : ArrayRef

The file method returns the contents of a file which contains pod-like sections
for a given filename.

=over 4

=item file example

  # given $data

  $data->file($args);

  # ...

=back

=cut

=head2 from_data

  from_data(Str $arg1) : Str

The from_data method returns content for the given class to be passed to the
constructor.

=over 4

=item from_data example

  # given $data

  $data->from_data($class);

  # ...

=back

=cut

=head2 from_file

  from_file(Str $arg1) : Str

The from_data method returns content for the given file to be passed to the
constructor.

=over 4

=item from_file example

  # given $data

  $data->from_file($file);

  # ...

=back

=cut

=head2 item

  item(Str $arg1) : HashRef

The item method returns metadata for the pod-like section that matches the
given string.

=over 4

=item item example

  =pod help

  Example content

  =cut

  # given $data

  $data->item('help');

  # {,...}

=back

=cut

=head2 list

  list(Str $arg1) : ArrayRef

The list method returns metadata for each pod-like section that matches the
given string.

=over 4

=item list example

  =pod help

  Example content

  =cut

  # given $data

  $data->list('pod');

  # [,...]

=back

=cut

=head2 parser

  parser(Str $arg1) : ArrayRef

The parser method extracts pod-like sections from a given string and returns an
arrayref of metadata.

=over 4

=item parser example

  # given $data

  $data->parser($string);

  # [,...]

=back

=cut

=head2 pluck

  pluck(Str $arg1, Str $arg2) : HashRef

The pluck method splices and returns metadata for the pod-like section that
matches the given list or item by name.

=over 4

=item pluck example

  =pod help

  Example content

  =cut

  # given $data

  $data->pluck('item', 'help');

  # {,...}

=back

=cut
