NAME

Dist::Zilla::Util::ExpandINI - Read an INI file and expand bundles as you go.

VERSION

version 0.003003

SYNOPSIS

  # Write a dist.ini with a bundle anywhere you like
  my $string = <<"EOF";
  name = Foo
  version = 1.000

  [@Some::Author]
  EOF

  path('dist.ini.meta')->spew($string);

  # Generate a copy with bundles inlined.
  use Dist::Zilla::Util::ExpandINI;
  Dist::Zilla::Util::ExpandINI->filter_file( 'dist.ini.meta' => 'dist.ini' );

  # Hurrah, dist.ini has all the things!

  # Advanced Usage:
  my $filter = Dist::Zilla::Util::ExpandINI->new(
    include_does => [ 'Dist::Zilla::Role::FileGatherer', ],
    exclude_does => [ 'Dist::Zilla::Role::Releaser', ],
  );
  $filter->filter_file( 'dist.ini.meta' => 'dist.ini' );

DESCRIPTION

This module builds upon the previous work :Util::BundleInfo ( Which can extract configuration from a bundle in a manner similar to how dzil does it ) and integrates it with some very minimal INI handling to provide a tool capable of generating bundle-free dist.ini files from bundle-using dist.ini files!

At present its very naïve and only keeps semantic ordering, and I've probably gotten something wrong due to cutting the complexity of Config::MVP out of the loop.

But at this stage, bundles are the only thing modified in transit.

Every thing else is practically a token-level copy-paste.

METHODS

filter_file

                                           #  $source   , $dest
  Dist::Zilla::Util::ExpandINI->filter_file('source.ini','target.ini');

Reads $source, performs expansions, and emits $dest

filter_handle

  Dist::Zilla::Util::ExpandINI->filter_handle($reader,$writer);

Reads $reader, performs expansions, and emits to $writer

filter_string

  my $return = Dist::Zilla::Util::ExpandINI->filter_string($source);

Decodes $source, performs expansions, and returns expanded source.

ATTRIBUTES

include_does

An ArrayRef of Roles to include in the emitted INI from the source INI.

If this ArrayRef is empty, all Plugins will be included.

This is the default behavior.

  ->new( include_does => [ 'Dist::Zilla::Role::VersionProvider', ] );

( API Since 0.002000 )

exclude_does

An ArrayRef of Roles to exclude from the emitted INI.

If this ArrayRef is empty, no Plugins will be excluded

This is the default behavior.

  ->new( exclude_does => [ 'Dist::Zilla::Role::Releaser', ] );

( API Since 0.002000 )

comments

This attribute controls how comments are handled.

• all - All comments are copied ( Default )

• authordeps - Only comments that look like Dist::Zilla AuthorDeps are copied.

• none - No comments are copied.

( API Since 0.003000 )

COMMENT PRESERVATION

Comments are ( since v0.002000 ) arbitrarily supported in a very basic way. But the behavior may be surprising.

  [SectionHeader]
  BODY
  [SectionHeader]
  BODY

Is how Config::INI understands its content. So comment parsing is implemented as

  BODY:
    comments: [ "A", "B", "C" ],
    params:   [ "x=y","foo=bar" ]

So:

  [Header]
  ;A
  x = y ; Trailing Note
  ;B
  foo = bar ; Trailing Note

  ;Remark About Header2
  [Header2]

Is re-serialized as:

  [Header]
  ;A
  ;B
  ;Remark About Header2
  x = y
  foo = bar

  [Header2]

This behavior may seem surprising, but its surprising only if you have assumptions about how INI parsing works.

This also applies and has strange effects with bundles:

  [Header]
  x = y

  ; CommentAboutBundle
  [@Bundle]
  ; More Comments About Bundle

  [Header2]

This expands as:

  [Header]
  ; CommentAboutBundle
  x = y

  [BundleHeader1]
  arg = value

  [BundleHeader2]
  arg = value

  [BundleHeader3]
  ; More Comments About Bundle
  arg = value

  [Header2]

And also note, at this time, only whole-line comments are preserved. Suffix comments are stripped.

AUTHOR

Kent Fredric <kentnl@cpan.org>

COPYRIGHT AND LICENSE

This software is copyright (c) 2017 by Kent Fredric <kentfredric@gmail.com>.

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