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