lib/Catalyst/IOC/Container.pm

   1 package Catalyst::IOC::Container;
   2 use Bread::Board;
   3 use Moose;
   4 use Config::Any;
   5 use Data::Visitor::Callback;
   6 use Catalyst::Utils ();
   7 use Devel::InnerPackage ();
   8 use Hash::Util qw/lock_hash/;
   9 use MooseX::Types::LoadableClass qw/ LoadableClass /;
  10 use Moose::Util;
  11 use Catalyst::IOC::BlockInjection;
  12 use Catalyst::IOC::ConstructorInjection;
  13 use Module::Pluggable::Object ();
  14 use namespace::autoclean;
  15
  16 extends 'Bread::Board::Container';
  17
  18 has config_local_suffix => (
  19     is      => 'ro',
  20     isa     => 'Str',
  21     default => 'local',
  22 );
  23
  24 has driver => (
  25     is      => 'ro',
  26     isa     => 'HashRef',
  27     default => sub { +{} },
  28 );
  29
  30 has file => (
  31     is      => 'ro',
  32     isa     => 'Str',
  33     default => '',
  34 );
  35
  36 has substitutions => (
  37     is      => 'ro',
  38     isa     => 'HashRef',
  39     default => sub { +{} },
  40 );
  41
  42 has application_name => (
  43     is      => 'ro',
  44     isa     => 'Str',
  45     default => 'MyApp',
  46 );
  47
  48 has sub_container_class => (
  49     isa     => LoadableClass,
  50     is      => 'ro',
  51     coerce  => 1,
  52     default => 'Catalyst::IOC::SubContainer',
  53     handles => {
  54         new_sub_container => 'new',
  55     }
  56 );
  57
  58 sub BUILD {
  59     my ( $self, $params ) = @_;
  60
  61     $self->add_service(
  62         $self->${\"build_${_}_service"}
  63     ) for qw/
  64         substitutions
  65         file
  66         driver
  67         application_name
  68         prefix
  69         extensions
  70         path
  71         config
  72         raw_config
  73         global_files
  74         local_files
  75         global_config
  76         local_config
  77         config_local_suffix
  78         config_path
  79         locate_components
  80     /;
  81
  82     $self->add_sub_container(
  83         $self->build_controller_subcontainer
  84     );
  85
  86     # FIXME - the config should be merged at this point
  87     my $config        = $self->resolve( service => 'config' );
  88     my $default_view  = $params->{default_view}  || $config->{default_view};
  89     my $default_model = $params->{default_model} || $config->{default_model};
  90
  91     $self->add_sub_container(
  92         $self->build_view_subcontainer(
  93             default_component => $default_view,
  94         )
  95     );
  96
  97     $self->add_sub_container(
  98         $self->build_model_subcontainer(
  99             default_component => $default_model,
 100         )
 101     );
 102 }
 103
 104 sub build_model_subcontainer {
 105     my $self = shift;
 106
 107     return $self->new_sub_container( @_,
 108         name => 'model',
 109     );
 110 }
 111
 112 sub build_view_subcontainer {
 113     my $self = shift;
 114
 115     return $self->new_sub_container( @_,
 116         name => 'view',
 117     );
 118 }
 119
 120 sub build_controller_subcontainer {
 121     my $self = shift;
 122
 123     return $self->new_sub_container(
 124         name => 'controller',
 125     );
 126 }
 127
 128 sub build_application_name_service {
 129     my $self = shift;
 130
 131     return Bread::Board::Literal->new( name => 'application_name', value => $self->application_name );
 132 }
 133
 134 sub build_driver_service {
 135     my $self = shift;
 136
 137     return Bread::Board::Literal->new( name => 'driver', value => $self->driver );
 138 }
 139
 140 sub build_file_service {
 141     my $self = shift;
 142
 143     return Bread::Board::Literal->new( name => 'file', value => $self->file );
 144 }
 145
 146 sub build_substitutions_service {
 147     my $self = shift;
 148
 149     return Bread::Board::Literal->new( name => 'substitutions', value => $self->substitutions );
 150 }
 151
 152 sub build_extensions_service {
 153     my $self = shift;
 154
 155     return Bread::Board::BlockInjection->new(
 156         lifecycle => 'Singleton',
 157         name => 'extensions',
 158         block => sub {
 159             return \@{Config::Any->extensions};
 160         },
 161     );
 162 }
 163
 164 sub build_prefix_service {
 165     my $self = shift;
 166
 167     return Bread::Board::BlockInjection->new(
 168         lifecycle => 'Singleton',
 169         name => 'prefix',
 170         block => sub {
 171             return Catalyst::Utils::appprefix( shift->param('application_name') );
 172         },
 173         dependencies => [ depends_on('application_name') ],
 174     );
 175 }
 176
 177 sub build_path_service {
 178     my $self = shift;
 179
 180     return Bread::Board::BlockInjection->new(
 181         lifecycle => 'Singleton',
 182         name => 'path',
 183         block => sub {
 184             my $s = shift;
 185
 186             return Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG' )
 187             || $s->param('file')
 188             || $s->param('application_name')->path_to( $s->param('prefix') );
 189         },
 190         dependencies => [ depends_on('file'), depends_on('application_name'), depends_on('prefix') ],
 191     );
 192 }
 193
 194 sub build_config_service {
 195     my $self = shift;
 196
 197     return Bread::Board::BlockInjection->new(
 198         lifecycle => 'Singleton',
 199         name => 'config',
 200         block => sub {
 201             my $s = shift;
 202
 203             my $v = Data::Visitor::Callback->new(
 204                 plain_value => sub {
 205                     return unless defined $_;
 206                     return $self->_config_substitutions( $s->param('application_name'), $s->param('substitutions'), $_ );
 207                 }
 208
 209             );
 210             $v->visit( $s->param('raw_config') );
 211         },
 212         dependencies => [ depends_on('application_name'), depends_on('raw_config'), depends_on('substitutions') ],
 213     );
 214 }
 215
 216 sub build_raw_config_service {
 217     my $self = shift;
 218
 219     return Bread::Board::BlockInjection->new(
 220         lifecycle => 'Singleton',
 221         name => 'raw_config',
 222         block => sub {
 223             my $s = shift;
 224
 225             my @global = @{$s->param('global_config')};
 226             my @locals = @{$s->param('local_config')};
 227
 228             my $config = {};
 229             for my $cfg (@global, @locals) {
 230                 for (keys %$cfg) {
 231                     $config = Catalyst::Utils::merge_hashes( $config, $cfg->{$_} );
 232                 }
 233             }
 234             return $config;
 235         },
 236         dependencies => [ depends_on('global_config'), depends_on('local_config') ],
 237     );
 238 }
 239
 240 sub build_global_files_service {
 241     my $self = shift;
 242
 243     return Bread::Board::BlockInjection->new(
 244         lifecycle => 'Singleton',
 245         name => 'global_files',
 246         block => sub {
 247             my $s = shift;
 248
 249             my ( $path, $extension ) = @{$s->param('config_path')};
 250
 251             my @extensions = @{$s->param('extensions')};
 252
 253             my @files;
 254             if ( $extension ) {
 255                 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
 256                 push @files, $path;
 257             } else {
 258                 @files = map { "$path.$_" } @extensions;
 259             }
 260             return \@files;
 261         },
 262         dependencies => [ depends_on('extensions'), depends_on('config_path') ],
 263     );
 264 }
 265
 266 sub build_local_files_service {
 267     my $self = shift;
 268
 269     return Bread::Board::BlockInjection->new(
 270         lifecycle => 'Singleton',
 271         name => 'local_files',
 272         block => sub {
 273             my $s = shift;
 274
 275             my ( $path, $extension ) = @{$s->param('config_path')};
 276             my $suffix = $s->param('config_local_suffix');
 277
 278             my @extensions = @{$s->param('extensions')};
 279
 280             my @files;
 281             if ( $extension ) {
 282                 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
 283                 $path =~ s{\.$extension}{_$suffix.$extension};
 284                 push @files, $path;
 285             } else {
 286                 @files = map { "${path}_${suffix}.$_" } @extensions;
 287             }
 288             return \@files;
 289         },
 290         dependencies => [ depends_on('extensions'), depends_on('config_path'), depends_on('config_local_suffix') ],
 291     );
 292 }
 293
 294 sub build_global_config_service {
 295     my $self = shift;
 296
 297     return Bread::Board::BlockInjection->new(
 298         lifecycle => 'Singleton',
 299         name => 'global_config',
 300         block => sub {
 301             my $s = shift;
 302
 303             return Config::Any->load_files({
 304                 files       => $s->param('global_files'),
 305                 filter      => \&_fix_syntax,
 306                 use_ext     => 1,
 307                 driver_args => $s->param('driver'),
 308             });
 309         },
 310         dependencies => [ depends_on('global_files') ],
 311     );
 312 }
 313
 314 sub build_local_config_service {
 315     my $self = shift;
 316
 317     return Bread::Board::BlockInjection->new(
 318         lifecycle => 'Singleton',
 319         name => 'local_config',
 320         block => sub {
 321             my $s = shift;
 322
 323             return Config::Any->load_files({
 324                 files       => $s->param('local_files'),
 325                 filter      => \&_fix_syntax,
 326                 use_ext     => 1,
 327                 driver_args => $s->param('driver'),
 328             });
 329         },
 330         dependencies => [ depends_on('local_files') ],
 331     );
 332 }
 333
 334 sub build_config_path_service {
 335     my $self = shift;
 336
 337     return Bread::Board::BlockInjection->new(
 338         lifecycle => 'Singleton',
 339         name => 'config_path',
 340         block => sub {
 341             my $s = shift;
 342
 343             my $path = $s->param('path');
 344             my $prefix = $s->param('prefix');
 345
 346             my ( $extension ) = ( $path =~ m{\.(.{1,4})$} );
 347
 348             if ( -d $path ) {
 349                 $path =~ s{[\/\\]$}{};
 350                 $path .= "/$prefix";
 351             }
 352
 353             return [ $path, $extension ];
 354         },
 355         dependencies => [ depends_on('prefix'), depends_on('path') ],
 356     );
 357 }
 358
 359 sub build_config_local_suffix_service {
 360     my $self = shift;
 361
 362     return Bread::Board::BlockInjection->new(
 363         lifecycle => 'Singleton',
 364         name => 'config_local_suffix',
 365         block => sub {
 366             my $s = shift;
 367             my $suffix = Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG_LOCAL_SUFFIX' ) || $self->config_local_suffix;
 368
 369             return $suffix;
 370         },
 371         dependencies => [ depends_on('application_name') ],
 372     );
 373 }
 374
 375 sub build_locate_components_service {
 376     my $self = shift;
 377
 378     return Bread::Board::BlockInjection->new(
 379         lifecycle => 'Singleton',
 380         name      => 'locate_components',
 381         block     => sub {
 382             my $s      = shift;
 383             my $class  = $s->param('application_name');
 384             my $config = $s->param('config')->{ setup_components };
 385
 386             Catalyst::Exception->throw(
 387                 qq{You are using search_extra config option. That option is\n} .
 388                 qq{deprecated, please refer to the documentation for\n} .
 389                 qq{other ways of achieving the same results.\n}
 390             ) if delete $config->{ search_extra };
 391
 392             my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
 393
 394             my $locator = Module::Pluggable::Object->new(
 395                 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
 396                 %$config
 397             );
 398
 399             # XXX think about ditching this sort entirely
 400             my @comps = sort { length $a <=> length $b } $locator->plugins;
 401
 402             return \@comps;
 403         },
 404         dependencies => [ depends_on('application_name'), depends_on('config') ],
 405     );
 406 }
 407
 408 sub setup_components {
 409     my $self = shift;
 410     my $class = $self->resolve( service => 'application_name' );
 411     my @comps = @{ $self->resolve( service => 'locate_components' ) };
 412     my %comps = map { $_ => 1 } @comps;
 413     my $deprecatedcatalyst_component_names = 0;
 414
 415     for my $component ( @comps ) {
 416
 417         # We pass ignore_loaded here so that overlay files for (e.g.)
 418         # Model::DBI::Schema sub-classes are loaded - if it's in @comps
 419         # we know M::P::O found a file on disk so this is safe
 420
 421         Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
 422     }
 423
 424     for my $component (@comps) {
 425         $self->add_component( $component, $class );
 426         # FIXME - $instance->expand_modules() is broken
 427         my @expanded_components = $self->expand_component_module( $component );
 428
 429         if (
 430             !$deprecatedcatalyst_component_names &&
 431             ($deprecatedcatalyst_component_names = $component =~ m/::[CMV]::/) ||
 432             ($deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @expanded_components)
 433         ) {
 434             # FIXME - should I be calling warn here?
 435             $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
 436                 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
 437             );
 438         }
 439
 440         for my $component (@expanded_components) {
 441             $self->add_component( $component, $class )
 442                 unless $comps{$component};
 443         }
 444     }
 445
 446     $self->get_sub_container('model')->make_single_default;
 447     $self->get_sub_container('view')->make_single_default;
 448 }
 449
 450 sub _fix_syntax {
 451     my $config     = shift;
 452     my @components = (
 453         map +{
 454             prefix => $_ eq 'Component' ? '' : $_ . '::',
 455             values => delete $config->{ lc $_ } || delete $config->{ $_ }
 456         },
 457         grep { ref $config->{ lc $_ } || ref $config->{ $_ } }
 458             qw( Component Model M View V Controller C Plugin )
 459     );
 460
 461     foreach my $comp ( @components ) {
 462         my $prefix = $comp->{ prefix };
 463         foreach my $element ( keys %{ $comp->{ values } } ) {
 464             $config->{ "$prefix$element" } = $comp->{ values }->{ $element };
 465         }
 466     }
 467 }
 468
 469 sub _config_substitutions {
 470     my ( $self, $name, $subs, $arg ) = @_;
 471
 472     $subs->{ HOME } ||= sub { shift->path_to( '' ); };
 473     $subs->{ ENV } ||=
 474         sub {
 475             my ( $c, $v ) = @_;
 476             if (! defined($ENV{$v})) {
 477                 Catalyst::Exception->throw( message =>
 478                     "Missing environment variable: $v" );
 479                 return "";
 480             } else {
 481                 return $ENV{ $v };
 482             }
 483         };
 484     $subs->{ path_to } ||= sub { shift->path_to( @_ ); };
 485     $subs->{ literal } ||= sub { return $_[ 1 ]; };
 486     my $subsre = join( '|', keys %$subs );
 487
 488     $arg =~ s{__($subsre)(?:\((.+?)\))?__}{ $subs->{ $1 }->( $name, $2 ? split( /,/, $2 ) : () ) }eg;
 489     return $arg;
 490 }
 491
 492 sub get_component_from_sub_container {
 493     my ( $self, $sub_container_name, $name, $c, @args ) = @_;
 494
 495     my $sub_container = $self->get_sub_container( $sub_container_name );
 496
 497     if (!$name) {
 498         my $default = $sub_container->default_component;
 499
 500         return $sub_container->get_component( $default, $c, @args )
 501             if $default && $sub_container->has_service( $default );
 502
 503         # FIXME - should I be calling $c->log->warn here?
 504         # this is never a controller, so this is safe
 505         $c->log->warn( "Calling \$c->$sub_container_name() is not supported unless you specify one of:" );
 506         $c->log->warn( "* \$c->config(default_$sub_container_name => 'the name of the default $sub_container_name to use')" );
 507         $c->log->warn( "* \$c->stash->{current_$sub_container_name} # the name of the view to use for this request" );
 508         $c->log->warn( "* \$c->stash->{current_${sub_container_name}_instance} # the instance of the $sub_container_name to use for this request" );
 509
 510         return;
 511     }
 512
 513     return $sub_container->get_component_regexp( $name, $c, @args )
 514         if ref $name;
 515
 516     return $sub_container->get_component( $name, $c, @args )
 517         if $sub_container->has_service( $name );
 518
 519     $c->log->warn(
 520         "Attempted to use $sub_container_name '$name', " .
 521         "but it does not exist"
 522     );
 523
 524     return;
 525 }
 526
 527 sub find_component {
 528     my ( $self, $component, $c, @args ) = @_;
 529     my ( $type, $name ) = _get_component_type_name($component);
 530     my @result;
 531
 532     return $self->get_component_from_sub_container(
 533         $type, $name, $c, @args
 534     ) if $type;
 535
 536     my $query = ref $component
 537               ? $component
 538               : qr{^$component$}
 539               ;
 540
 541     for my $subcontainer_name (qw/model view controller/) {
 542         my $subcontainer = $self->get_sub_container( $subcontainer_name );
 543         my @components   = $subcontainer->get_service_list;
 544         @result          = grep { m{$component} } @components;
 545
 546         return map { $subcontainer->get_component( $_, $c, @args ) } @result
 547             if @result;
 548     }
 549
 550     # FIXME - I guess I shouldn't be calling $c->components here
 551     # one last search for things like $c->comp(qr/::M::/)
 552     @result = $self->find_component_regexp(
 553         $c->components, $component, $c, @args
 554     ) if !@result and ref $component;
 555
 556     # it expects an empty list on failed searches
 557     return @result;
 558 }
 559
 560 sub find_component_regexp {
 561     my ( $self, $components, $component, @args ) = @_;
 562     my @result;
 563
 564     my @components = grep { m{$component} } keys %{ $components };
 565
 566     for (@components) {
 567         my ($type, $name) = _get_component_type_name($_);
 568
 569         push @result, $self->get_component_from_sub_container(
 570             $type, $name, @args
 571         ) if $type;
 572     }
 573
 574     return @result;
 575 }
 576
 577 # FIXME sorry for the name again :)
 578 sub get_components_types {
 579     my ( $self ) = @_;
 580     my @comps_types;
 581
 582     for my $sub_container_name (qw/model view controller/) {
 583         my $sub_container = $self->get_sub_container($sub_container_name);
 584         for my $service ( $sub_container->get_service_list ) {
 585             my $comp     = $self->resolve(service => $service);
 586             my $compname = ref $comp || $comp;
 587             my $type     = ref $comp ? 'instance' : 'class';
 588             push @comps_types, [ $compname, $type ];
 589         }
 590     }
 591
 592     return @comps_types;
 593 }
 594
 595 sub get_all_components {
 596     my $self = shift;
 597     my %components;
 598
 599     my $containers = {
 600         map { $_ => $self->get_sub_container($_) } qw(model view controller)
 601     };
 602
 603     for my $container (keys %$containers) {
 604         for my $component ($containers->{$container}->get_service_list) {
 605             my $comp = $containers->{$container}->resolve(
 606                 service => $component
 607             );
 608             my $comp_name = ref $comp || $comp;
 609             $components{$comp_name} = $comp;
 610         }
 611     }
 612
 613     return lock_hash %components;
 614 }
 615
 616 sub add_component {
 617     my ( $self, $component, $class ) = @_;
 618     my ( $type, $name ) = _get_component_type_name($component);
 619
 620     return unless $type;
 621
 622     $self->get_sub_container($type)->add_service(
 623         Catalyst::IOC::ConstructorInjection->new(
 624             lifecycle => 'Singleton', # FIXME?
 625             name      => $name,
 626             class     => $component,
 627             dependencies => [
 628                 depends_on( '/application_name' ),
 629                 depends_on( '/config' ),
 630             ],
 631             parameters => {
 632                 suffix => {
 633                     isa => 'Str',
 634                     default => Catalyst::Utils::class2classsuffix( $component ),
 635                 },
 636             },
 637         )
 638     );
 639 }
 640
 641 # FIXME: should this sub exist?
 642 # should it be moved to Catalyst::Utils,
 643 # or replaced by something already existing there?
 644 sub _get_component_type_name {
 645     my ( $component ) = @_;
 646
 647     my @parts = split /::/, $component;
 648
 649     while (my $type = shift @parts) {
 650         return ('controller', join '::', @parts)
 651             if $type =~ /^(c|controller)$/i;
 652
 653         return ('model', join '::', @parts)
 654             if $type =~ /^(m|model)$/i;
 655
 656         return ('view', join '::', @parts)
 657             if $type =~ /^(v|view)$/i;
 658     }
 659
 660     return (undef, $component);
 661 }
 662
 663 sub expand_component_module {
 664     my ( $class, $module ) = @_;
 665     return Devel::InnerPackage::list_packages( $module );
 666 }
 667
 668 1;
 669
 670 __END__
 671
 672 =pod
 673
 674 =head1 NAME
 675
 676 Catalyst::Container - IOC for Catalyst components
 677
 678 =head1 SYNOPSIS
 679
 680 =head1 DESCRIPTION
 681
 682 =head1 METHODS
 683
 684 =head1 Containers
 685
 686 =head2 build_model_subcontainer
 687
 688 Container that stores all models.
 689
 690 =head2 build_view_subcontainer
 691
 692 Container that stores all views.
 693
 694 =head2 build_controller_subcontainer
 695
 696 Container that stores all controllers.
 697
 698 =head1 Services
 699
 700 =head2 build_application_name_service
 701
 702 Name of the application (such as MyApp).
 703
 704 =head2 build_driver_service
 705
 706 Config options passed directly to the driver being used.
 707
 708 =head2 build_file_service
 709
 710 ?
 711
 712 =head2 build_substitutions_service
 713
 714 Executes all the substitutions in config. See L</_config_substitutions> method.
 715
 716 =head2 build_extensions_service
 717
 718 =head2 build_prefix_service
 719
 720 =head2 build_path_service
 721
 722 =head2 build_config_service
 723
 724 =head2 build_raw_config_service
 725
 726 =head2 build_global_files_service
 727
 728 =head2 build_local_files_service
 729
 730 =head2 build_global_config_service
 731
 732 =head2 build_local_config_service
 733
 734 =head2 build_config_path_service
 735
 736 =head2 build_config_local_suffix_service
 737
 738 Determines the suffix of files used to override the main config. By default
 739 this value is C<local>, which will load C<myapp_local.conf>.  The suffix can
 740 be specified in the following order of preference:
 741
 742 =over
 743
 744 =item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>
 745
 746 =item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>
 747
 748 =back
 749
 750 The first one of these values found replaces the default of C<local> in the
 751 name of the local config file to be loaded.
 752
 753 For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
 754 ConfigLoader will try and load C<myapp_testing.conf> instead of
 755 C<myapp_local.conf>.
 756
 757 =head2 get_component_from_sub_container($sub_container, $name, $c, @args)
 758
 759 Looks for components in a given subcontainer (such as controller, model or view), and returns the searched component. If $name is undef, it returns the default component (such as default_view, if $sub_container is 'view'). If $name is a regexp, it returns an array of matching components. Otherwise, it looks for the component with name $name.
 760
 761 =head2 get_components_types
 762
 763 =head2 get_all_components
 764
 765 Fetches all the components, in each of the sub_containers model, view and controller, and returns a readonly hash. The keys are the class names, and the values are the blessed objects. This is what is returned by $c->components.
 766
 767 =head2 add_component
 768
 769 Adds a component to the appropriate subcontainer. The subcontainer is guessed by the component name given.
 770
 771 =head2 find_component
 772
 773 Searches for components in all containers. If $component is the full class name, the subcontainer is guessed, and it gets the searched component in there. Otherwise, it looks for a component with that name in all subcontainers. If $component is a regexp, it calls the method below, find_component_regexp, and matches all components against that regexp.
 774
 775 =head2 find_component_regexp
 776
 777 Finds components that match a given regexp. Used internally, by find_component.
 778
 779 =head2 setup_component
 780
 781 =head2 _fix_syntax
 782
 783 =head2 _config_substitutions
 784
 785 This method substitutes macros found with calls to a function. There are a
 786 number of default macros:
 787
 788 =over
 789
 790 =item * C<__HOME__> - replaced with C<$c-E<gt>path_to('')>
 791
 792 =item * C<__ENV(foo)__> - replaced with the value of C<$ENV{foo}>
 793
 794 =item * C<__path_to(foo/bar)__> - replaced with C<$c-E<gt>path_to('foo/bar')>
 795
 796 =item * C<__literal(__FOO__)__> - leaves __FOO__ alone (allows you to use
 797 C<__DATA__> as a config value, for example)
 798
 799 =back
 800
 801 The parameter list is split on comma (C<,>). You can override this method to
 802 do your own string munging, or you can define your own macros in
 803 C<MyApp-E<gt>config-E<gt>{ 'Plugin::ConfigLoader' }-E<gt>{ substitutions }>.
 804 Example:
 805
 806     MyApp->config->{ 'Plugin::ConfigLoader' }->{ substitutions } = {
 807         baz => sub { my $c = shift; qux( @_ ); }
 808     }
 809
 810 The above will respond to C<__baz(x,y)__> in config strings.
 811
 812 =head2 $c->expand_component_module( $component, $setup_component_config )
 813
 814 Components found by C<locate_components> will be passed to this method, which
 815 is expected to return a list of component (package) names to be set up.
 816
 817 =head2 build_locate_components_service
 818
 819 This method is meant to provide a list of component modules that should be
 820 setup for the application.  By default, it will use L<Module::Pluggable>.
 821
 822 Specify a C<setup_components> config option to pass additional options directly
 823 to L<Module::Pluggable>.
 824
 825 =head2 setup_components
 826
 827 =head1 AUTHORS
 828
 829 Catalyst Contributors, see Catalyst.pm
 830
 831 =head1 COPYRIGHT
 832
 833 This library is free software. You can redistribute it and/or modify it under
 834 the same terms as Perl itself.
 835
 836 =cut