/ 
App-CpanDak-0.0.2
/ App::CpanDak::Specials

NAME

App::CpanDak::Specials - fetch and expose the "special" instructions for distributions

VERSION

version 0.0.2

SYNOPSIS

my $distribution_to_build = 'Foo-Bar-1.2.3';

my $specials = App::CpanDak::Specials->new();

$specials->apply_patch_to($distribution_to_build, $path_to_source);

unless ($specials->option_for('Foo-Bar-1.2.3', 'notest')) {
   run_the_tests();
}

DESCRIPTION

Given a directory containing specially-named YAML and patch files, this class matches them to CPAN-style distribution names, and exposes their contents.

NOTE: the YAML files are parsed by CPAN::Meta::YAML, which does not understand all of YAML; we're using it because it's already a dependency of App::cpanminus.

METHODS

new

my $specials = App::CpanDak::Specials->new();

my $specials = App::CpanDak::Specials->new($path_to_specials);

Constructor. Looks for the special instructions files in the path contained in the PERL_CPANDAK_SPECIALS_PATH environment variable, or in the given path.

Normally you just use the first form.

match_for

my $file_path = $specials->match_for($cpandak->dak_dist, '.patch');

Tries to find a file with the given extension, whose name matches the given distribution.

If we're building Foo-Bar version 1.2.3, the example above would look for:

  • $path_to_specials/Foo-Bar-1.2.3.patch

  • $path_to_specials/Foo-Bar.patch

and return the first filename that exists, or undef if none does.

all_options_for

my $options_hash = $specials->all_options_for($cpandak->dak_dist);

Returns the contents of the options file for the given distribution, or undef if it doesn't exist. An options file has extension .options.yml.

Options files should contain a single YAML dictionary, with simple strings as keys. Example:

---
notest: 1

option_for

my $option_value = $specials->option_for($cpandak->dak_dist, 'notest');

Same as:

my $option_value = $specials->all_options_for($cpandak->dak_dist)->{notest};

but simpler and safer. Returns undef if the file, or the option, doesn't exist.

env_for

my $env_hash = $specials->env_for($cpandak->dak_dist, $phase);

Returns the contents of the environment file for the given distribution and phase, or undef if it doesn't exist. An environment file has extension .$phase.env.yml.

Environment files should contain a single YAML dictionary, with simple strings as keys, and simple strings (or null/undef) as values. Example:

---
TMP_SOCKET_PATH: '/tmp/'
SKIP_NETWORK: '1'
PLACK_ENV: ~  # remove this variable from the environment

apply_patch_to

$specials->apply_patch_to($cpandak->dak_dist, $directory);

Applies the patch for the given distribution to the files under the given directory, or does nothing if the patch doesn't exist. If the patch exists but can't be applied cleanly, this method will die.

A patch file has extension .patch. It is applied by calling patch -p1. The file should contain a unified patch like those generated by git diff or diff -ru.

AUTHOR

Gianni Ceccarelli <dakkar@thenautilus.net>

COPYRIGHT AND LICENSE

This software is copyright (c) 2026 by Gianni Ceccarelli <dakkar@thenautilus.net>.

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