lib/Catalyst/IOC/Container.pm

   1 package Catalyst::IOC::Container;
   2 use Bread::Board qw/depends_on/;
   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             my $home;
 164
 165             if ( my $env = Catalyst::Utils::env_value( $class, 'HOME' ) ) {
 166                 $home = $env;
 167             }
 168
 169             $home ||= Catalyst::Utils::home($class);
 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 __PACKAGE__->meta->make_immutable;
 769
 770 1;
 771
 772 __END__
 773
 774 =pod
 775
 776 =head1 NAME
 777
 778 Catalyst::Container - IOC for Catalyst components
 779
 780 =head1 SYNOPSIS
 781
 782 =head1 DESCRIPTION
 783
 784 =head1 METHODS
 785
 786 =head1 Methods for Building Containers
 787
 788 =head2 build_component_subcontainer
 789
 790 Container that stores all components, i.e. all models, views and controllers
 791 together. Each service is an instance of the actual component, and by default
 792 it lives while the application is running. Retrieving components from this
 793 sub-container will instantiate the component, if it hasn't been instantiated
 794 already, but will not execute ACCEPT_CONTEXT.
 795
 796 =head2 build_model_subcontainer
 797
 798 Container that stores references for all models that are inside the components
 799 sub-container. Retrieving a model triggers ACCEPT_CONTEXT, if it exists.
 800
 801 =head2 build_view_subcontainer
 802
 803 Same as L<build_model_subcontainer>, but for views.
 804
 805 =head2 build_controller_subcontainer
 806
 807 Same as L<build_model_subcontainer>, but for controllers.
 808
 809 =head1 Methods for Building Services
 810
 811 =head2 build_application_name_service
 812
 813 Name of the application (such as MyApp).
 814
 815 =head2 build_driver_service
 816
 817 Config options passed directly to the driver being used.
 818
 819 =head2 build_file_service
 820
 821 ?
 822
 823 =head2 build_substitutions_service
 824
 825 This method substitutes macros found with calls to a function. There are a
 826 number of default macros:
 827
 828 =over
 829
 830 =item * C<__HOME__> - replaced with C<$c-E<gt>path_to('')>
 831
 832 =item * C<__ENV(foo)__> - replaced with the value of C<$ENV{foo}>
 833
 834 =item * C<__path_to(foo/bar)__> - replaced with C<$c-E<gt>path_to('foo/bar')>
 835
 836 =item * C<__literal(__FOO__)__> - leaves __FOO__ alone (allows you to use
 837 C<__DATA__> as a config value, for example)
 838
 839 =back
 840
 841 The parameter list is split on comma (C<,>). You can override this method to
 842 do your own string munging, or you can define your own macros in
 843 C<< <MyApp->config( 'Plugin::ConfigLoader' => { substitutions => { ... } } ) >>.
 844 Example:
 845
 846     MyApp->config( 'Plugin::ConfigLoader' => {
 847         substitutions => {
 848             baz => sub { my $c = shift; qux( @_ ); },
 849         },
 850     });
 851
 852 The above will respond to C<__baz(x,y)__> in config strings.
 853
 854 =head2 build_extensions_service
 855
 856 Config::Any's available config file extensions (e.g. xml, json, pl, etc).
 857
 858 =head2 build_prefix_service
 859
 860 The prefix, based on the application name, that will be used to look-up the
 861 config files (which will be in the format $prefix.$extension). If the app is
 862 MyApp::Foo, the prefix will be myapp_foo.
 863
 864 =head2 build_path_service
 865
 866 The path to the config file (or environment variable, if defined).
 867
 868 =head2 build_config_service
 869
 870 The resulting configuration for the application, after it has successfully
 871 been loaded, and all substitutions have been made.
 872
 873 =head2 build_raw_config_service
 874
 875 The merge of local_config and global_config hashes, before substitutions.
 876
 877 =head2 build_global_files_service
 878
 879 Gets all files for config that don't have the local_suffix, such as myapp.conf.
 880
 881 =head2 build_local_files_service
 882
 883 Gets all files for config that have the local_suffix, such as myapp_local.conf.
 884
 885 =head2 build_global_config_service
 886
 887 Reads config from global_files.
 888
 889 =head2 build_local_config_service
 890
 891 Reads config from local_files.
 892
 893 =head2 build_class_config_service
 894
 895 Reads config set from the application's class attribute config,
 896 i.e. MyApp->config( name => 'MyApp', ... )
 897
 898 =head2 build_config_path_service
 899
 900 Splits the path to the config file, and returns on array ref containing
 901 the path to the config file minus the extension in the first position,
 902 and the extension in the second.
 903
 904 =head2 build_config_local_suffix_service
 905
 906 Determines the suffix of files used to override the main config. By default
 907 this value is C<local>, which will load C<myapp_local.conf>.  The suffix can
 908 be specified in the following order of preference:
 909
 910 =over
 911
 912 =item * C<$ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }>
 913
 914 =item * C<$ENV{ CATALYST_CONFIG_LOCAL_SUFFIX }>
 915
 916 =back
 917
 918 The first one of these values found replaces the default of C<local> in the
 919 name of the local config file to be loaded.
 920
 921 For example, if C< $ENV{ MYAPP_CONFIG_LOCAL_SUFFIX }> is set to C<testing>,
 922 ConfigLoader will try and load C<myapp_testing.conf> instead of
 923 C<myapp_local.conf>.
 924
 925 =head2 build_locate_components_service
 926
 927 This method is meant to provide a list of component modules that should be
 928 setup for the application.  By default, it will use L<Module::Pluggable>.
 929
 930 Specify a C<setup_components> config option to pass additional options directly
 931 to L<Module::Pluggable>.
 932
 933 =head1 Other methods
 934
 935 =head2 get_component_from_sub_container($sub_container, $name, $c, @args)
 936
 937 Looks for components in a given sub-container (such as controller, model or
 938 view), and returns the searched component. If $name is undef, it returns the
 939 default component (such as default_view, if $sub_container is 'view'). If
 940 $name is a regexp, it returns an array of matching components. Otherwise, it
 941 looks for the component with name $name.
 942
 943 =head2 get_all_components
 944
 945 Fetches all the components, in each of the sub_containers model, view and
 946 controller, and returns a read-only hash. The keys are the class names, and
 947 the values are the blessed objects. This is what is returned by $c->components.
 948
 949 =head2 add_component
 950
 951 Adds a component to the appropriate sub-container. The sub-container is guessed
 952 by the component name given.
 953
 954 =head2 find_component
 955
 956 Searches for components in all containers. If $component is the full class
 957 name, the sub-container is guessed, and it gets the searched component in there.
 958 Otherwise, it looks for a component with that name in all sub-containers. If
 959 $component is a regexp it calls _find_component_regexp and matches all
 960 components against that regexp.
 961
 962 =head2 expand_component_module
 963
 964 Components found by C<locate_components> will be passed to this method, which
 965 is expected to return a list of component (package) names to be set up.
 966
 967 =head2 setup_components
 968
 969 Uses locate_components service to list the components, and adds them to the
 970 appropriate sub-containers, using add_component().
 971
 972 =head1 AUTHORS
 973
 974 Catalyst Contributors, see Catalyst.pm
 975
 976 =head1 COPYRIGHT
 977
 978 This library is free software. You can redistribute it and/or modify it under
 979 the same terms as Perl itself.
 980
 981 =cut