File Coverage

blib/lib/Mojolicious/Plugin/NotYAMLConfig.pm

Criterion	Covered	Total	%
statement	22	22	100.0
branch	6	8	75.0
condition	1	2	50.0
subroutine	6	6	100.0
pod	2	2	100.0
total	37	40	92.5

package Mojolicious::Plugin::NotYAMLConfig;
use Mojo::Base 'Mojolicious::Plugin::JSONConfig';

use CPAN::Meta::YAML;
use Mojo::Util qw(decode encode);

sub parse {
  my ($self, $content, $file, $conf, $app) = @_;
  my $config = eval { $self->{yaml}->(encode('UTF-8', $self->render($content, $file, $conf, $app))) };
  die qq{Can't load configuration from file "$file": $@} if $@;
  die qq{Configuration file "$file" did not return a YAML mapping} unless ref $config eq 'HASH';
  return $config;
}

sub register {
  my ($self, $app, $conf) = @_;

  $conf->{ext} //= 'yml';
  $self->{yaml} = sub { CPAN::Meta::YAML::Load(decode 'UTF-8', shift) };
  if (my $mod = $conf->{module}) {
    die qq{YAML module $mod has no Load function} unless $self->{yaml} = $mod->can('Load');
  }

  return $self->SUPER::register($app, $conf);
}

1;

=encoding utf8

=head1 NAME

Mojolicious::Plugin::NotYAMLConfig - Not quite YAML configuration plugin

=head1 SYNOPSIS

  # myapp.yml (it's just YAML with embedded Perl)
  ---
  foo: bar
  baz:
    - ♥
  music_dir: <%= app->home->child('music') %>

  # Mojolicious
  my $config = $app->plugin('NotYAMLConfig');
  say $config->{foo};

  # Mojolicious::Lite
  my $config = plugin 'NotYAMLConfig';
  say $config->{foo};

  # foo.html.ep
  %= config->{foo}

  # The configuration is available application-wide
  my $config = app->config;
  say $config->{foo};

  # Everything can be customized with options
  my $config = plugin NotYAMLConfig => {file => '/etc/myapp.conf'};

=head1 DESCRIPTION

L is a YAML configuration plugin that preprocesses its input with L.
By default it uses L for parsing, which is not the best YAML module available, but good enough for
most config files. If you need something more correct you can use a different module like L with the
L option.

The application object can be accessed via C<$app> or the C function. A default configuration filename in the
application home directory will be generated from the value of L (C<$moniker.yml>). You can
extend the normal configuration file C<$moniker.yml> with C specific ones like C<$moniker.$mode.yml>, which will
be detected automatically.

These configuration values are currently reserved:

=over 2

=item C

If this configuration value has been set in L when this plugin is loaded, it will not do anything
besides loading deployment specific plugins.

=item C

  plugins:
    - SetUserGroup:
        user: sri
        group: staff

One or more deployment specific plugins that should be loaded right after this plugin has been loaded.

=back

The code of this plugin is a good example for learning to build new plugins, you're welcome to fork it.

See L for a list of plugins that are available by default.

=head1 OPTIONS

L inherits all options from L and supports the
following new ones.

=head2 module

  # Mojolicious::Lite
  plugin NotYAMLConfig => {module => 'YAML::PP'};

Alternative YAML module to use for parsing.

=head1 METHODS

L inherits all methods from L and implements the
following new ones.

=head2 parse

  $plugin->parse($content, $file, $conf, $app);

Process content with L and parse it with L.

  sub parse ($self, $content, $file, $conf, $app) {
    ...
    $content = $self->render($content, $file, $conf, $app);
    ...
    return $hash;
  }

=head2 register

  my $config = $plugin->register(Mojolicious->new);
  my $config = $plugin->register(Mojolicious->new, {file => '/etc/foo.conf'});

Register plugin in L application and merge configuration.

=head1 SEE ALSO

L, L, L.

=cut