NAME

    Data::Section::Writer - Write __DATA__ section files for Data::Section,
    Data::Section::Simple or Mojo::Loader::data_section

VERSION

    version 0.04

SYNOPSIS

    This code:

     use strict;
     use warnings;
     use Data::Section::Writer;
     use Path::Tiny qw( path );
     
     Data::Section::Writer
       ->new( perl_filename => "foo.pl" )
       ->add_file( "hello.txt", "hello world" )
       ->add_file( "a.out", path("a.out")->slurp_raw, 'base64' )
       ->update_file;

    Will add this to the bottom of foo.pl

     __DATA__
     @@ a.out (base64)
     f0VMRgIBAQAAAAAAAAAAAAMAPgABAAAAQBAAAAAAAABAAAAAAAAAAGA2AAAAAAAAAAAAAEAAOAAN
     AEAAHQAcAAYAAAAEAAAAQAAAAAAAAABAAAAAAAAAAEAAAAAAAAAA2AIAAAAAAADYAgAAAAAAAAgA
     AAAAAAAAAwAAAAQAAAAYAwAAAAAAABgDAAAAAAAAGAMAAAAAAAAcAAAAAAAAABwAAAAAAAAAAQAA
     ...
     @@ hello.txt
     hello world

    (binary file truncated for readability)

DESCRIPTION

    This class is an interface for updating the __DATA__ section of your
    Perl module or script programmatically for it to work with one of the
    many modules that allows for multiple files in a __DATA__ section, such
    as Data::Section, Data::Section::Simple, Data::Section::Pluggable or
    Mojo::Loader.

    Data::Section uses a different header format by default, but you can
    still use this module with it if you set header_re to qr/^@@ (.*)$/.

ATTRIBUTES

 perl_filename

    The name of the Perl source file. If not provided then the source for
    the caller will be used.

METHODS

 add_file

     $writer->add_file($text_filename, $content);
     $writer->add_file($binary_filename, $content, 'base64');

    Add a file. Binary files can be encoded using base64. Such binaries
    files are only supported by Mojo::Loader at the moment.

 render_section

     my $perl = $writer->render_section;

    Returns the __DATA__ section.

 update_file

     $writer->update_file;

    Update the existing Perl source file, OR create a new Perl source file
    with just the __DATA__ section.

    [version 0.02]

    Starting with version 0.02, this method will not write to the file if
    the content won't change.

 unchanged

    [version 0.02]

     my $bool = $writer->unchanged;

    Returns:

    undef

      If "update_file" hasn't been called yet.

    0

      If the last call to "update_file" modified the file.

    1

      If the last call to "update_file" did not modify the file.

 add_format

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

    Adds a content formatter 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::Writable instance as its first
    argument and the content to be processed as the second. This callback
    should return the format content as a scalar.

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

 add_plugin

     $writer->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".

CORE PLUGINS

    This module will work with some core Data::Section::Pluggable plugins
    listed here.

 json

    Automatically encode json into Perl data structures.

    See Data::Section::Pluggable::Plugin::Json.

PLUGIN ROLES

 FormatContentPlugin

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

CAVEATS

    Added text files will get an added trailing new line if they do not
    already have them. This is a requirement of the format used by the data
    section modules.

    For binary files (base64 encoded) the content returned by Mojo::Loader
    should be identical.

    Not tested, and probably not working for Windows formatted text files,
    though patches for this are welcome.

SEE ALSO

    Data::Section::Pluggable

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.