lib/Catalyst/IOC/Container.pm

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