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