view release on metacpan or  search on metacpan

lib/Gnuplot/Builder/Dataset.pm  view on Meta::CPAN

If a blessed object is set to the C<$opt_name>, that object is returned.

If the option is not set in C<$dataset>, the value of its parent is returned.
If none of the ancestors doesn't have the option, it returns an empty list in list context
or C<undef> in scalar context.

=head2 $dataset = $dataset->delete_option($opt_name, ...)

Delete the option from the C<$dataset>.
You can specify more than one C<$opt_name>s.

Note the difference between C<delete_option($opt_name)> and C<< set_option($opt_name => undef) >>.
C<delete_option()> removes the option setting from the C<$dataset>,
so it's up to its ancestors to determine the value of the option.
On the other hand, C<set_option()> always overrides the parent's setting.

=head1 OBJECT METHODS - INLINE DATA

Methods about the inline data of the dataset.

=head2 $dataset = $dataset->set_data($data_provider)

Set the inline data of the C<$dataset>.

C<$data_provider> is either C<undef>, a string or a code-ref.

=over

=item *

If C<$data_provider> is C<undef>, it means that C<$dataset> has no inline data.

=item *

If C<$data_provider> is a string, that is the inline data of the C<$dataset>.

    $dataset->set_data(<<INLINE_DATA);
    1 10
    2 20
    3 30
    INLINE_DATA

=item *

If C<$data_provider> is a code-ref, it is called in void context when C<$dataset> needs the inline data.

    $data_provider->($dataset, $writer)

C<$dataset> is passed as the first argument to the code-ref.
The second argument (C<$writer>) is a code-ref that you have to call to write inline data.

    $dataset->set_data(sub {
        my ($dataset, $writer) = @_;
        foreach my $x (1 .. 3) {
            my $y = $x * 10;
            $writer->("$x $y\n");
        }
    });

This allows for very large inline data streaming directly into the gnuplot process.

If you don't pass any data to C<$writer>, it means the C<$dataset> doesn't have inline data at all.

=back

=head2 $dataset = $dataset->write_data_to($writer)

Write the inline data using the C<$writer>.
This method is required by plotting methods of L<Gnuplot::Builder::Script>.

C<$writer> is a code-ref that is called by the C<$dataset> to write inline data.
C<$writer> can be called zero or more times.

    my $inline_data = "";
    $dataset->write_data_to(sub {
        my ($data_part) = @_;
        $inline_data .= $data_part;
    });

If C<$dataset> doesn't have inline data setting,
it's up to C<$dataset>'s ancestors to write the inline data.
If none of them have inline data, C<$writer> is not called at all.

=head2 $dataset = $dataset->delete_data()

Delete the inline data setting from the C<$dataset>.

=head1 OBJECT METHODS - INHERITANCE

L<Gnuplot::Builder::Dataset> supports prototype-based inheritance
just like L<Gnuplot::Builder::Script>.

A child dataset inherits the source, the options and the inline data from its parent.
The child can override them individually, or use the parent's setting as-is.

=head2 $dataset = $dataset->set_parent($parent_dataset)

Set C<$parent_dataset> as the C<$dataset>'s parent.

If C<$parent_dataset> is C<undef>, C<$dataset> doesn't have parent anymore.

=head2 $parent_dataset = $dataset->get_parent()

Return the C<$dataset>'s parent.

If C<$dataset> doesn't have any parent, it returns C<undef>.

=head2 $child_dataset = $dataset->new_child()

Create and return a new child of the C<$dataset>.

This is equivalent to C<< Gnuplot::Builder::Dataset->new->set_parent($dataset) >>.

=head1 OVERLOAD

When you evaluate a C<$dataset> as a string, it executes C<< $dataset->to_string() >>. That is,

    "$dataset" eq $dataset->to_string;

=head1 Data::Focus COMPATIBLITY