/ 
Data-Section-Pluggable-0.07
/ Data::Section::Pluggable

NAME

Data::Section::Pluggable - Read structured data from __DATA__

VERSION

version 0.07

SYNOPSIS

use Data::Section::Pluggable;

my $dsp = Data::Section::Pluggable->new
                                  ->add_plugin('trim')
                                  ->add_plugin('json');

# prints "Welcome to Perl" without prefix
# or trailing white space.
say $dsp->get_data_section('hello.txt');

# also prints "Welcome to Perl"
say $dsp->get_data_section('hello.json')->{message};

# prints "This is base64 encoded.\n"
say $dsp->get_data_section('hello.bin');

__DATA__

@@ hello.txt
  Welcome to Perl


@@ hello.json
{"message":"Welcome to Perl"}

@@ hello.bin (base64)
VGhpcyBpcyBiYXNlNjQgZW5jb2RlZC4K

DESCRIPTION

Data::Section::Simple is a module to extract data from __DATA__ section of Perl source file. This module started out as a fork of Data::Section::Simple (itself based on Mojo::Loader), and includes some of its tests to ensure compatibility, but it also includes features not available in either of those modules.

This module caches the result of reading the __DATA__ section in the object if you use the OO interface. It doesn't do any caching of the processing required of "formats" (see below).

This module also supports base64 encoding using the same mechanism as Mojo::Loader, which is helpful for putting binary sections in __DATA__.

As mentioned, this module aims to be and is largely a drop in replacement for Data::Section::Simple with some extra features. Here are the known ways in which it is not compatible:

  • Because Data::Section::Simple does not support base64 encoded data, these data sections would include the (base64) in the filename instead of decoding the content.

  • When a section is not found Data::Section::Simple return the empty list from get_data_section, where as this module returns undef, in order to keep the return value more consistent.

CONSTRUCTOR

my $dsp = Data::Section::Pluggable->new($package);
my $dsp = Data::Section::Pluggable->new(\%attributes);
my $dsp = Data::Section::Pluggable->new(%attributes);

ATTRIBUTES

package

The name of the package to read from __DATA__. If not specified, then the current package will be used.

prefer_filesystem

If provided, this is a directory containing files from where content will be preferred over what is in the __DATA__ section, if available. This file still must still exist in the __DATA__ section to be found. This can be useful to do local testing with files on the filesystem, but release a script or test a just one combined file.

METHODS

get_data_section

my $hash = get_data_section;
my $data = get_data_section $name;
my $hash = $dsp->get_data_section;
my $data = $dsp->get_data_section($name);

Gets data from __DATA_. This can be called either as a function (which is optionally exported from this module), or as an object method. Creating an instance of Data::Section::Pluggable allows you to use packages other than the default or use plugins.

add_format

$dsp->add_format( $ext, sub ($dsp, $content) { return ... } );

Adds a content processor to the given filename extension. The extension should be a filename extension without the ., for example txt or json.

The callback takes the Data::Section::Pluggable instance as its first argument and the content to be processed as the second. This callback should return the processed content as a scalar.

You can chain multiple content processors to the same filename extension, and they will be called in the order that they were added.

add_plugin

$dsp->add_plugin( $name, %args );

Applies the plugin with $name. If the plugin supports instance mode (that is: it has a constructor named new), then %args will be passed to the constructor. For included plugins see "CORE PLUGINS". To write your own see "PLUGIN ROLES".

extract

$dsp->extract($dir);
$dsp->extract;

Extract all files in Data section to the given $dir, or if not provided the current directory.

CORE PLUGINS

json

Automatically decode json into Perl data structures. See Data::Section::Pluggable::Plugin::Json.

trim

Automatically trim leading and trailing white space. See Data::Section::Pluggable::Plugin::Trim.

PLUGIN ROLES

ContentProcessorPlugin

Used for adding content processors for specific formats. This is essentially a way to wrap the add_format method as a module. See Data::Section::Pluggable::Role::ContentProcessorPlugin.

SEE ALSO

These are some alternative modules that do a similar thing, each with their own feature set and limitations.

Data::Section
Data::Section::Simple
Data::Section::Writer
Mojo::Loader

AUTHOR

Graham Ollis <plicease@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2024 by Graham Ollis.

This is free software; you can redistribute it and/or modify it under the same terms as the Perl 5 programming language system itself.