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 List::Util qw(first);
   8 use Devel::InnerPackage ();
   9 use Hash::Util qw/lock_hash/;
  10 use MooseX::Types::LoadableClass qw/ LoadableClass /;
  11 use Moose::Util;
  12 use Scalar::Util qw/refaddr/;
  13 use Catalyst::IOC::BlockInjection;
  14 use Catalyst::IOC::ConstructorInjection;
  15 use Module::Pluggable::Object ();
  16 use namespace::autoclean;
  17
  18 extends 'Bread::Board::Container';
  19
  20 has config_local_suffix => (
  21     is      => 'ro',
  22     isa     => 'Str',
  23     default => 'local',
  24 );
  25
  26 has driver => (
  27     is      => 'ro',
  28     isa     => 'HashRef',
  29     default => sub { +{} },
  30 );
  31
  32 has file => (
  33     is      => 'ro',
  34     isa     => 'Str',
  35     default => '',
  36 );
  37
  38 has substitutions => (
  39     is      => 'ro',
  40     isa     => 'HashRef',
  41     default => sub { +{} },
  42 );
  43
  44 has application_name => (
  45     is       => 'ro',
  46     isa      => 'Str',
  47     required => 1,
  48 );
  49
  50 has sub_container_class => (
  51     isa     => LoadableClass,
  52     is      => 'ro',
  53     coerce  => 1,
  54     default => 'Catalyst::IOC::SubContainer',
  55     handles => {
  56         new_sub_container => 'new',
  57     }
  58 );
  59
  60 sub BUILD {
  61     my ( $self, $params ) = @_;
  62
  63     $self->add_service(
  64         $self->${\"build_${_}_service"}
  65     ) for qw/
  66         substitutions
  67         file
  68         driver
  69         application_name
  70         prefix
  71         extensions
  72         path
  73         config
  74         raw_config
  75         global_files
  76         local_files
  77         global_config
  78         local_config
  79         class_config
  80         config_local_suffix
  81         config_path
  82         locate_components
  83     /;
  84
  85     my $config = $self->resolve( service => 'config' );
  86
  87     # don't force default_component to be undef if the config wasn't set
  88     my @default_view  = $config->{default_view}
  89                       ? ( default_component => $config->{default_view} )
  90                       : ( )
  91                       ;
  92     my @default_model = $config->{default_model}
  93                       ? ( default_component => $config->{default_model} )
  94                       : ( )
  95                       ;
  96
  97     $self->add_sub_container(
  98         $self->build_component_subcontainer
  99     );
 100
 101     $self->add_sub_container(
 102         $self->build_controller_subcontainer
 103     );
 104
 105     $self->add_sub_container(
 106         $self->build_view_subcontainer( @default_view )
 107     );
 108
 109     $self->add_sub_container(
 110         $self->build_model_subcontainer( @default_model )
 111     );
 112
 113     {
 114         no strict 'refs';
 115         no warnings 'once';
 116         my $class = ref $self;
 117         ${ $class . '::customise_container' }->($self)
 118             if ${ $class . '::customise_container' };
 119     }
 120 }
 121
 122 sub build_model_subcontainer {
 123     my $self = shift;
 124
 125     return $self->new_sub_container( @_,
 126         name => 'model',
 127     );
 128 }
 129
 130 sub build_view_subcontainer {
 131     my $self = shift;
 132
 133     return $self->new_sub_container( @_,
 134         name => 'view',
 135     );
 136 }
 137
 138 sub build_controller_subcontainer {
 139     my $self = shift;
 140
 141     return $self->new_sub_container(
 142         name => 'controller',
 143     );
 144 }
 145
 146 sub build_component_subcontainer {
 147     my $self = shift;
 148
 149     return Bread::Board::Container->new(
 150         name => 'component',
 151     );
 152 }
 153
 154 sub build_home_service {
 155     my $self = shift;
 156
 157     return Bread::Board::BlockInjection->new(
 158         lifecycle => 'Singleton',
 159         name => 'home',
 160         block => sub {
 161             my $self = shift;
 162             my $class = $self->param('application_name');
 163
 164             if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
 165                 $home = $env;
 166             }
 167
 168             $home ||= Catalyst::Utils::home($class);
 169
 170             return $home;
 171         },
 172         dependencies => [ depends_on('application_name') ],
 173     );
 174 }
 175
 176 # FIXME: very ambiguous - maybe root_dir?
 177 sub build_root_service {
 178     my $self = shift;
 179
 180     return Bread::Board::BlockInjection->new(
 181         lifecycle => 'Singleton',
 182         name => 'root',
 183         block => sub {
 184             my $self = shift;
 185
 186             return Path::Class::Dir->new( $self->param('home') )->subdir('root');
 187         },
 188         dependencies => [ depends_on('home') ],
 189     );
 190 }
 191
 192 sub build_application_name_service {
 193     my $self = shift;
 194
 195     return Bread::Board::Literal->new( name => 'application_name', value => $self->application_name );
 196 }
 197
 198 sub build_driver_service {
 199     my $self = shift;
 200
 201     return Bread::Board::Literal->new( name => 'driver', value => $self->driver );
 202 }
 203
 204 sub build_file_service {
 205     my $self = shift;
 206
 207     return Bread::Board::Literal->new( name => 'file', value => $self->file );
 208 }
 209
 210 sub build_substitutions_service {
 211     my $self = shift;
 212
 213     return Bread::Board::Literal->new( name => 'substitutions', value => $self->substitutions );
 214 }
 215
 216 sub build_extensions_service {
 217     my $self = shift;
 218
 219     return Bread::Board::BlockInjection->new(
 220         lifecycle => 'Singleton',
 221         name => 'extensions',
 222         block => sub {
 223             return \@{Config::Any->extensions};
 224         },
 225     );
 226 }
 227
 228 sub build_prefix_service {
 229     my $self = shift;
 230
 231     return Bread::Board::BlockInjection->new(
 232         lifecycle => 'Singleton',
 233         name => 'prefix',
 234         block => sub {
 235             return Catalyst::Utils::appprefix( shift->param('application_name') );
 236         },
 237         dependencies => [ depends_on('application_name') ],
 238     );
 239 }
 240
 241 sub build_path_service {
 242     my $self = shift;
 243
 244     return Bread::Board::BlockInjection->new(
 245         lifecycle => 'Singleton',
 246         name => 'path',
 247         block => sub {
 248             my $s = shift;
 249
 250             return Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG' )
 251             || $s->param('file')
 252             || $s->param('application_name')->path_to( $s->param('prefix') );
 253         },
 254         dependencies => [ depends_on('file'), depends_on('application_name'), depends_on('prefix') ],
 255     );
 256 }
 257
 258 sub build_config_service {
 259     my $self = shift;
 260
 261     return Bread::Board::BlockInjection->new(
 262         lifecycle => 'Singleton',
 263         name => 'config',
 264         block => sub {
 265             my $s = shift;
 266
 267             my $v = Data::Visitor::Callback->new(
 268                 plain_value => sub {
 269                     return unless defined $_;
 270                     return $self->_config_substitutions( $s->param('application_name'), $s->param('substitutions'), $_ );
 271                 }
 272
 273             );
 274             $v->visit( $s->param('raw_config') );
 275         },
 276         dependencies => [ depends_on('application_name'), depends_on('raw_config'), depends_on('substitutions') ],
 277     );
 278 }
 279
 280 sub build_raw_config_service {
 281     my $self = shift;
 282
 283     return Bread::Board::BlockInjection->new(
 284         lifecycle => 'Singleton',
 285         name => 'raw_config',
 286         block => sub {
 287             my $s = shift;
 288
 289             my @global = @{$s->param('global_config')};
 290             my @locals = @{$s->param('local_config')};
 291
 292             my $config = $s->param('class_config');
 293
 294             for my $cfg (@global, @locals) {
 295                 for (keys %$cfg) {
 296                     $config = Catalyst::Utils::merge_hashes( $config, $cfg->{$_} );
 297                 }
 298             }
 299
 300             return $config;
 301         },
 302         dependencies => [ depends_on('global_config'), depends_on('local_config'), depends_on('class_config') ],
 303     );
 304 }
 305
 306 sub build_global_files_service {
 307     my $self = shift;
 308
 309     return Bread::Board::BlockInjection->new(
 310         lifecycle => 'Singleton',
 311         name => 'global_files',
 312         block => sub {
 313             my $s = shift;
 314
 315             my ( $path, $extension ) = @{$s->param('config_path')};
 316
 317             my @extensions = @{$s->param('extensions')};
 318
 319             my @files;
 320             if ( $extension ) {
 321                 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
 322                 push @files, $path;
 323             } else {
 324                 @files = map { "$path.$_" } @extensions;
 325             }
 326             return \@files;
 327         },
 328         dependencies => [ depends_on('extensions'), depends_on('config_path') ],
 329     );
 330 }
 331
 332 sub build_local_files_service {
 333     my $self = shift;
 334
 335     return Bread::Board::BlockInjection->new(
 336         lifecycle => 'Singleton',
 337         name => 'local_files',
 338         block => sub {
 339             my $s = shift;
 340
 341             my ( $path, $extension ) = @{$s->param('config_path')};
 342             my $suffix = $s->param('config_local_suffix');
 343
 344             my @extensions = @{$s->param('extensions')};
 345
 346             my @files;
 347             if ( $extension ) {
 348                 die "Unable to handle files with the extension '${extension}'" unless grep { $_ eq $extension } @extensions;
 349                 $path =~ s{\.$extension}{_$suffix.$extension};
 350                 push @files, $path;
 351             } else {
 352                 @files = map { "${path}_${suffix}.$_" } @extensions;
 353             }
 354             return \@files;
 355         },
 356         dependencies => [ depends_on('extensions'), depends_on('config_path'), depends_on('config_local_suffix') ],
 357     );
 358 }
 359
 360 sub build_class_config_service {
 361     my $self = shift;
 362
 363     return Bread::Board::BlockInjection->new(
 364         lifecycle => 'Singleton',
 365         name => 'class_config',
 366         block => sub {
 367             my $s   = shift;
 368             my $app = $s->param('application_name');
 369
 370             # Container might be called outside Catalyst context
 371             return {} unless Class::MOP::is_class_loaded($app);
 372
 373             # config might not have been defined
 374             return $app->config || {};
 375         },
 376         dependencies => [ depends_on('application_name') ],
 377     );
 378 }
 379
 380 sub build_global_config_service {
 381     my $self = shift;
 382
 383     return Bread::Board::BlockInjection->new(
 384         lifecycle => 'Singleton',
 385         name => 'global_config',
 386         block => sub {
 387             my $s = shift;
 388
 389             return Config::Any->load_files({
 390                 files       => $s->param('global_files'),
 391                 filter      => \&_fix_syntax,
 392                 use_ext     => 1,
 393                 driver_args => $s->param('driver'),
 394             });
 395         },
 396         dependencies => [ depends_on('global_files') ],
 397     );
 398 }
 399
 400 sub build_local_config_service {
 401     my $self = shift;
 402
 403     return Bread::Board::BlockInjection->new(
 404         lifecycle => 'Singleton',
 405         name => 'local_config',
 406         block => sub {
 407             my $s = shift;
 408
 409             return Config::Any->load_files({
 410                 files       => $s->param('local_files'),
 411                 filter      => \&_fix_syntax,
 412                 use_ext     => 1,
 413                 driver_args => $s->param('driver'),
 414             });
 415         },
 416         dependencies => [ depends_on('local_files') ],
 417     );
 418 }
 419
 420 sub build_config_path_service {
 421     my $self = shift;
 422
 423     return Bread::Board::BlockInjection->new(
 424         lifecycle => 'Singleton',
 425         name => 'config_path',
 426         block => sub {
 427             my $s = shift;
 428
 429             my $path = $s->param('path');
 430             my $prefix = $s->param('prefix');
 431
 432             my ( $extension ) = ( $path =~ m{\.(.{1,4})$} );
 433
 434             if ( -d $path ) {
 435                 $path =~ s{[\/\\]$}{};
 436                 $path .= "/$prefix";
 437             }
 438
 439             return [ $path, $extension ];
 440         },
 441         dependencies => [ depends_on('prefix'), depends_on('path') ],
 442     );
 443 }
 444
 445 sub build_config_local_suffix_service {
 446     my $self = shift;
 447
 448     return Bread::Board::BlockInjection->new(
 449         lifecycle => 'Singleton',
 450         name => 'config_local_suffix',
 451         block => sub {
 452             my $s = shift;
 453             my $suffix = Catalyst::Utils::env_value( $s->param('application_name'), 'CONFIG_LOCAL_SUFFIX' ) || $self->config_local_suffix;
 454
 455             return $suffix;
 456         },
 457         dependencies => [ depends_on('application_name') ],
 458     );
 459 }
 460
 461 sub build_locate_components_service {
 462     my $self = shift;
 463
 464     return Bread::Board::BlockInjection->new(
 465         lifecycle => 'Singleton',
 466         name      => 'locate_components',
 467         block     => sub {
 468             my $s      = shift;
 469             my $class  = $s->param('application_name');
 470             my $config = $s->param('config')->{ setup_components };
 471
 472             Catalyst::Exception->throw(
 473                 qq{You are using search_extra config option. That option is\n} .
 474                 qq{deprecated, please refer to the documentation for\n} .
 475                 qq{other ways of achieving the same results.\n}
 476             ) if delete $config->{ search_extra };
 477
 478             my @paths = qw( ::Controller ::C ::Model ::M ::View ::V );
 479
 480             my $locator = Module::Pluggable::Object->new(
 481                 search_path => [ map { s/^(?=::)/$class/; $_; } @paths ],
 482                 %$config
 483             );
 484
 485             return [ $locator->plugins ];
 486         },
 487         dependencies => [ depends_on('application_name'), depends_on('config') ],
 488     );
 489 }
 490
 491 sub setup_components {
 492     my $self = shift;
 493     my $class = $self->resolve( service => 'application_name' );
 494     my @comps = @{ $self->resolve( service => 'locate_components' ) };
 495     my %comps = map { $_ => 1 } @comps;
 496     my $deprecatedcatalyst_component_names = 0;
 497
 498     my $app_locate_components_addr = refaddr(
 499         $class->can('locate_components')
 500     );
 501     my $cat_locate_components_addr = refaddr(
 502         Catalyst->can('locate_components')
 503     );
 504
 505     if ($app_locate_components_addr != $cat_locate_components_addr) {
 506         # FIXME - why not just say: @comps = $class->locate_components() ?
 507         $class->log->warn(qq{You have overridden locate_components. That } .
 508             qq{no longer works. Please refer to the documentation to achieve } .
 509             qq{similar results.\n}
 510         );
 511     }
 512
 513     for my $component ( @comps ) {
 514
 515         # We pass ignore_loaded here so that overlay files for (e.g.)
 516         # Model::DBI::Schema sub-classes are loaded - if it's in @comps
 517         # we know M::P::O found a file on disk so this is safe
 518
 519         Catalyst::Utils::ensure_class_loaded( $component, { ignore_loaded => 1 } );
 520     }
 521
 522     for my $component (@comps) {
 523         $self->add_component( $component );
 524         # FIXME - $instance->expand_modules() is broken
 525         my @expanded_components = $self->expand_component_module( $component );
 526
 527         if (
 528             !$deprecatedcatalyst_component_names &&
 529             ($deprecatedcatalyst_component_names = $component =~ m/::[CMV]::/) ||
 530             ($deprecatedcatalyst_component_names = grep { /::[CMV]::/ } @expanded_components)
 531         ) {
 532             # FIXME - should I be calling warn here?
 533             # Maybe it's time to remove it, or become fatal
 534             $class->log->warn(qq{Your application is using the deprecated ::[MVC]:: type naming scheme.\n}.
 535                 qq{Please switch your class names to ::Model::, ::View:: and ::Controller: as appropriate.\n}
 536             );
 537         }
 538
 539         for my $component (@expanded_components) {
 540             $self->add_component( $component )
 541                 unless $comps{$component};
 542         }
 543     }
 544 }
 545
 546 sub _fix_syntax {
 547     my $config     = shift;
 548     my @components = (
 549         map +{
 550             prefix => $_ eq 'Component' ? '' : $_ . '::',
 551             values => delete $config->{ lc $_ } || delete $config->{ $_ }
 552         },
 553         grep { ref $config->{ lc $_ } || ref $config->{ $_ } }
 554             qw( Component Model M View V Controller C Plugin )
 555     );
 556
 557     foreach my $comp ( @components ) {
 558         my $prefix = $comp->{ prefix };
 559         foreach my $element ( keys %{ $comp->{ values } } ) {
 560             $config->{ "$prefix$element" } = $comp->{ values }->{ $element };
 561         }
 562     }
 563 }
 564
 565 sub _config_substitutions {
 566     my ( $self, $name, $subs, $arg ) = @_;
 567
 568     $subs->{ HOME } ||= sub { shift->path_to( '' ); };
 569     $subs->{ ENV } ||=
 570         sub {
 571             my ( $c, $v ) = @_;
 572             if (! defined($ENV{$v})) {
 573                 Catalyst::Exception->throw( message =>
 574                     "Missing environment variable: $v" );
 575                 return "";
 576             } else {
 577                 return $ENV{ $v };
 578             }
 579         };
 580     $subs->{ path_to } ||= sub { shift->path_to( @_ ); };
 581     $subs->{ literal } ||= sub { return $_[ 1 ]; };
 582     my $subsre = join( '|', keys %$subs );
 583
 584     $arg =~ s{__($subsre)(?:\((.+?)\))?__}{ $subs->{ $1 }->( $name, $2 ? split( /,/, $2 ) : () ) }eg;
 585     return $arg;
 586 }
 587
 588 sub get_component_from_sub_container {
 589     my ( $self, $sub_container_name, $name, $c, @args ) = @_;
 590
 591     my $sub_container = $self->get_sub_container( $sub_container_name );
 592
 593     if (!$name) {
 594         my $default = $sub_container->default_component;
 595
 596         return $sub_container->get_component( $default, $c, @args )
 597             if $default && $sub_container->has_service( $default );
 598
 599         # FIXME - should I be calling $c->log->warn here?
 600         # this is never a controller, so this is safe
 601         $c->log->warn( "Calling \$c->$sub_container_name() is not supported unless you specify one of:" );
 602         $c->log->warn( "* \$c->config(default_$sub_container_name => 'the name of the default $sub_container_name to use')" );
 603         $c->log->warn( "* \$c->stash->{current_$sub_container_name} # the name of the view to use for this request" );
 604         $c->log->warn( "* \$c->stash->{current_${sub_container_name}_instance} # the instance of the $sub_container_name to use for this request" );
 605
 606         return;
 607     }
 608
 609     return $sub_container->get_component_regexp( $name, $c, @args )
 610         if ref $name;
 611
 612     return $sub_container->get_component( $name, $c, @args )
 613         if $sub_container->has_service( $name );
 614
 615     $c->log->warn(
 616         "Attempted to use $sub_container_name '$name', " .
 617         "but it does not exist"
 618     );
 619
 620     return;
 621 }
 622
 623 sub find_component {
 624     my ( $self, $component, @args ) = @_;
 625     my ( $type, $name ) = _get_component_type_name($component);
 626     my @result;
 627
 628     return $self->get_component_from_sub_container(
 629         $type, $name, @args
 630     ) if $type;
 631
 632     my $query = ref $component
 633               ? $component
 634               : qr{^$component$}
 635               ;
 636
 637     for my $subcontainer_name (qw/model view controller/) {
 638         my $subcontainer = $self->get_sub_container( $subcontainer_name );
 639         my @components   = $subcontainer->get_service_list;
 640         @result          = grep { m{$component} } @components;
 641
 642         return map { $subcontainer->get_component( $_, @args ) } @result
 643             if @result;
 644     }
 645
 646     # one last search for things like $c->comp(qr/::M::/)
 647     @result = $self->_find_component_regexp(
 648         $component, @args
 649     ) if !@result and ref $component;
 650
 651     # it expects an empty list on failed searches
 652     return @result;
 653 }
 654
 655 sub _find_component_regexp {
 656     my ( $self, $component, $ctx, @args ) = @_;
 657     my @result;
 658
 659     my @components = grep { m{$component} } keys %{ $self->get_all_components($ctx) };
 660
 661     for (@components) {
 662         my ($type, $name) = _get_component_type_name($_);
 663
 664         push @result, $self->get_component_from_sub_container(
 665             $type, $name, $ctx, @args
 666         ) if $type;
 667     }
 668
 669     return @result;
 670 }
 671
 672 sub get_all_components {
 673     my ($self, $class) = @_;
 674     my %components;
 675
 676     # FIXME - if we're getting from these containers, we need to either:
 677     #   - pass 'ctx' and 'accept_context_args' OR
 678     #   - make these params optional
 679     # big problem when setting up the dispatcher - this method is called
 680     # as $container->get_all_components('MyApp'). What to do with Request
 681     # life cycles?
 682     foreach my $type (qw/model view controller /) {
 683         my $container = $self->get_sub_container($type);
 684
 685         for my $component ($container->get_service_list) {
 686             my $comp_service = $container->get_service($component);
 687
 688             $components{$comp_service->catalyst_component_name} = $comp_service->get(ctx => $class);
 689         }
 690     }
 691
 692     return lock_hash %components;
 693 }
 694
 695 sub add_component {
 696     my ( $self, $component ) = @_;
 697     my ( $type, $name ) = _get_component_type_name($component);
 698
 699     return unless $type;
 700
 701     # The 'component' sub-container will create the object, and store it's
 702     # instance, which, by default, will live throughout the application.
 703     # The model/view/controller sub-containers only reference the instance
 704     # held in the aforementioned sub-container, and execute the ACCEPT_CONTEXT
 705     # sub every time they are called, when it exists.
 706     my $instance_container       = $self->get_sub_container('component');
 707     my $accept_context_container = $self->get_sub_container($type);
 708
 709     # Custom containers might have added the service already
 710     # We don't want to override that
 711     return if $accept_context_container->has_service( $name );
 712
 713     my $component_service_name = "${type}_${name}";
 714
 715     $instance_container->add_service(
 716         Catalyst::IOC::ConstructorInjection->new(
 717             name      => $component_service_name,
 718             catalyst_component_name => $component,
 719             class     => $component,
 720             lifecycle => 'Singleton',
 721             dependencies => [
 722                 depends_on( '/application_name' ),
 723             ],
 724         ),
 725     );
 726     # XXX - FIXME - We have to explicitly build the service here,
 727     #               causing the COMPONENT method to be called early here, as otherwise
 728     #               if the component method defines other classes (e.g. the
 729     #               ACCEPT_CONTEXT injection Model::DBIC::Schema does)
 730     #               then they won't be found by Devel::InnerPackage
 731     # see also t/aggregate/unit_core_component_loading.t
 732     $instance_container->get_service($component_service_name)->get;
 733
 734     $accept_context_container->add_service(
 735         Catalyst::IOC::BlockInjection->new(
 736             name         => $name,
 737             catalyst_component_name => $component,
 738             dependencies => [
 739                 depends_on( "/component/$component_service_name" ),
 740             ],
 741             block => sub { shift->param($component_service_name) },
 742         )
 743     );
 744 }
 745
 746 # FIXME: should this sub exist?
 747 # should it be moved to Catalyst::Utils,
 748 # or replaced by something already existing there?
 749 sub _get_component_type_name {
 750     my ( $component ) = @_;
 751     my $result;
 752
 753     while ( !$result and (my $index = index $component, '::') > 0 ) {
 754         my $type   = lc substr $component, 0, $index;
 755         $component = substr $component, $index + 2;
 756         $result    = first { $type eq $_ or $type eq substr($_, 0, 1) }
 757                          qw{ model view controller };
 758     }
 759
 760     return ($result, $component);
 761 }
 762
 763 sub expand_component_module {
 764     my ( $class, $module ) = @_;
 765     return Devel::InnerPackage::list_packages( $module );
 766 }
 767
 768 1;
 769
 770 __END__
 771
 772 =pod
 773
 774 =head1 NAME
 775
 776 Catalyst::Container - IOC for Catalyst components
 777
 778 =head1 SYNOPSIS
 779
 780 =head1 DESCRIPTION
 781
 782 =head1 METHODS
 783
 784 =head1 Methods for Building Containers
 785
 786 =head2 build_component_subcontainer
 787
 788 Container that stores all components, i.e. all models, views and controllers
 789 together. Each service is an instance of the actual component, and by default
 790 it lives while the application is running. Retrieving components from this
 791 sub-container will instantiate the component, if it hasn't been instantiated
 792 already, but will not execute ACCEPT_CONTEXT.
 793
 794 =head2 build_model_subcontainer
 795
 796 Container that stores references for all models that are inside the components
 797 sub-container. Retrieving a model triggers ACCEPT_CONTEXT, if it exists.
 798
 799 =head2 build_view_subcontainer
 800
 801 Same as L<build_model_subcontainer>, but for views.
 802
 803 =head2 build_controller_subcontainer
 804
 805 Same as L<build_model_subcontainer>, but for controllers.
 806
 807 =head1 Methods for Building Services
 808
 809 =head2 build_application_name_service
 810
 811 Name of the application (such as MyApp).
 812
 813 =head2 build_driver_service
 814
 815 Config options passed directly to the driver being used.
 816
 817 =head2 build_file_service
 818
 819 ?
 820
 821 =head2 build_substitutions_service
 822
 823 This method substitutes macros found with calls to a function. There are a
 824 number of default macros:
 825
 826 =over
 827
 828 =item * C<__HOME__> - replaced with C<$c-E<gt>path_to('')>
 829
 830 =item * C<__ENV(foo)__> - replaced with the value of C<$ENV{foo}>
 831
 832 =item * C<__path_to(foo/bar)__> - replaced with C<$c-E<gt>path_to('foo/bar')>
 833
 834 =item * C<__literal(__FOO__)__> - leaves __FOO__ alone (allows you to use
 835 C<__DATA__> as a config value, for example)
 836
 837 =back
 838
 839 The parameter list is split on comma (C<,>). You can override this method to
 840 do your own string munging, or you can define your own macros in
 841 C<< <MyApp->config( 'Plugin::ConfigLoader' => { substitutions => { ... } } ) >>.
 842 Example:
 843
 844     MyApp->config( 'Plugin::ConfigLoader' => {
 845         substitutions => {
 846             baz => sub { my $c = shift; qux( @_ ); },
 847         },
 848     });
 849
 850 The above will respond to C<__baz(x,y)__> in config strings.
 851
 852 =head2 build_extensions_service
 853
 854 Config::Any's available config file extensions (e.g. xml, json, pl, etc).
 855
 856 =head2 build_prefix_service
 857
 858 The prefix, based on the application name, that will be used to look-up the
 859 config files (which will be in the format $prefix.$extension). If the app is
 860 MyApp::Foo, the prefix will be myapp_foo.
 861
 862 =head2 build_path_service
 863
 864 The path to the config file (or environment variable, if defined).
 865
 866 =head2 build_config_service
 867
 868 The resulting configuration for the application, after it has successfully
 869 been loaded, and all substitutions have been made.
 870
 871 =head2 build_raw_config_service
 872
 873 The merge of local_config and global_config hashes, before substitutions.
 874
 875 =head2 build_global_files_service
 876
 877 Gets all files for config that don't have the local_suffix, such as myapp.conf.
 878
 879 =head2 build_local_files_service
 880
 881 Gets all files for config that have the local_suffix, such as myapp_local.conf.
 882
 883 =head2 build_global_config_service
 884
 885 Reads config from global_files.
 886
 887 =head2 build_local_config_service
 888
 889 Reads config from local_files.
 890
 891 =head2 build_class_config_service
 892
 893 Reads config set from the application's class attribute config,
 894 i.e. MyApp->config( name => 'MyApp', ... )
 895
 896 =head2 build_config_path_service
 897
 898 Splits the path to the config file, and returns on array ref containing
 899 the path to the config file minus the extension in the first position,
 900 and the extension in the second.
 901
 902 =head2 build_config_local_suffix_service
 903
 904 Determines the suffix of files used to override the main config. By default
 905 this value is C<local>, which will load C<myapp_local.conf>.  The suffix can
 906 be specified in the following order of preference:
 907
 908 =over
 909
 910 =item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>
 911
 912 =item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>
 913
 914 =back
 915
 916 The first one of these values found replaces the default of C<local> in the
 917 name of the local config file to be loaded.
 918
 919 For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
 920 ConfigLoader will try and load C<myapp_testing.conf> instead of
 921 C<myapp_local.conf>.
 922
 923 =head2 build_locate_components_service
 924
 925 This method is meant to provide a list of component modules that should be
 926 setup for the application.  By default, it will use L<Module::Pluggable>.
 927
 928 Specify a C<setup_components> config option to pass additional options directly
 929 to L<Module::Pluggable>.
 930
 931 =head1 Other methods
 932
 933 =head2 get_component_from_sub_container($sub_container, $name, $c, @args)
 934
 935 Looks for components in a given sub-container (such as controller, model or
 936 view), and returns the searched component. If $name is undef, it returns the
 937 default component (such as default_view, if $sub_container is 'view'). If
 938 $name is a regexp, it returns an array of matching components. Otherwise, it
 939 looks for the component with name $name.
 940
 941 =head2 get_all_components
 942
 943 Fetches all the components, in each of the sub_containers model, view and
 944 controller, and returns a read-only hash. The keys are the class names, and
 945 the values are the blessed objects. This is what is returned by $c->components.
 946
 947 =head2 add_component
 948
 949 Adds a component to the appropriate sub-container. The sub-container is guessed
 950 by the component name given.
 951
 952 =head2 find_component
 953
 954 Searches for components in all containers. If $component is the full class
 955 name, the sub-container is guessed, and it gets the searched component in there.
 956 Otherwise, it looks for a component with that name in all sub-containers. If
 957 $component is a regexp it calls _find_component_regexp and matches all
 958 components against that regexp.
 959
 960 =head2 expand_component_module
 961
 962 Components found by C<locate_components> will be passed to this method, which
 963 is expected to return a list of component (package) names to be set up.
 964
 965 =head2 setup_components
 966
 967 Uses locate_components service to list the components, and adds them to the
 968 appropriate sub-containers, using add_component().
 969
 970 =head1 AUTHORS
 971
 972 Catalyst Contributors, see Catalyst.pm
 973
 974 =head1 COPYRIGHT
 975
 976 This library is free software. You can redistribute it and/or modify it under
 977 the same terms as Perl itself.
 978
 979 =cut