lib/Catalyst/IOC/Container.pm

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