lib/Catalyst/Utils.pm

   1 package Catalyst::Utils;
   2
   3 use strict;
   4 use Catalyst::Exception;
   5 use File::Spec;
   6 use HTTP::Request;
   7 use Path::Class;
   8 use URI;
   9 use Class::Inspector;
  10
  11 =head1 NAME
  12
  13 Catalyst::Utils - The Catalyst Utils
  14
  15 =head1 SYNOPSIS
  16
  17 See L<Catalyst>.
  18
  19 =head1 DESCRIPTION
  20
  21 =head1 METHODS
  22
  23 =head2 appprefix($class)
  24
  25         MyApp::Foo becomes myapp_foo
  26
  27 =cut
  28
  29 sub appprefix {
  30     my $class = shift;
  31     $class =~ s/\:\:/_/g;
  32     $class = lc($class);
  33     return $class;
  34 }
  35
  36 =head2 class2appclass($class);
  37
  38     MyApp::C::Foo::Bar becomes MyApp
  39     My::App::C::Foo::Bar becomes My::App
  40
  41 =cut
  42
  43 sub class2appclass {
  44     my $class = shift || '';
  45     my $appname = '';
  46     if ( $class =~ /^(.*)::([MVC]|Model|View|Controller)?::.*$/ ) {
  47         $appname = $1;
  48     }
  49     return $appname;
  50 }
  51
  52 =head2 class2classprefix($class);
  53
  54     MyApp::C::Foo::Bar becomes MyApp::C
  55     My::App::C::Foo::Bar becomes My::App::C
  56
  57 =cut
  58
  59 sub class2classprefix {
  60     my $class = shift || '';
  61     my $prefix;
  62     if ( $class =~ /^(.*::[MVC]|Model|View|Controller)?::.*$/ ) {
  63         $prefix = $1;
  64     }
  65     return $prefix;
  66 }
  67
  68 =head2 class2classsuffix($class);
  69
  70     MyApp::C::Foo::Bar becomes C::Foo::Bar
  71
  72 =cut
  73
  74 sub class2classsuffix {
  75     my $class = shift || '';
  76     my $prefix = class2appclass($class) || '';
  77     $class =~ s/$prefix\:\://;
  78     return $class;
  79 }
  80
  81 =head2 class2env($class);
  82
  83 Returns the environment name for class.
  84
  85     MyApp becomes MYAPP
  86     My::App becomes MY_APP
  87
  88 =cut
  89
  90 sub class2env {
  91     my $class = shift || '';
  92     $class =~ s/\:\:/_/g;
  93     return uc($class);
  94 }
  95
  96 =head2 class2prefix( $class, $case );
  97
  98 Returns the uri prefix for a class. If case is false the prefix is converted to lowercase.
  99
 100     My::App::C::Foo::Bar becomes foo/bar
 101
 102 =cut
 103
 104 sub class2prefix {
 105     my $class = shift || '';
 106     my $case  = shift || 0;
 107     my $prefix;
 108     if ( $class =~ /^.*::([MVC]|Model|View|Controller)?::(.*)$/ ) {
 109         $prefix = $case ? $2 : lc $2;
 110         $prefix =~ s/\:\:/\//g;
 111     }
 112     return $prefix;
 113 }
 114
 115 =head2 class2tempdir( $class [, $create ] );
 116
 117 Returns a tempdir for a class. If create is true it will try to create the path.
 118
 119     My::App becomes /tmp/my/app
 120     My::App::C::Foo::Bar becomes /tmp/my/app/c/foo/bar
 121
 122 =cut
 123
 124 sub class2tempdir {
 125     my $class  = shift || '';
 126     my $create = shift || 0;
 127     my @parts = split '::', lc $class;
 128
 129     my $tmpdir = dir( File::Spec->tmpdir, @parts )->cleanup;
 130
 131     if ( $create && !-e $tmpdir ) {
 132
 133         eval { $tmpdir->mkpath };
 134
 135         if ($@) {
 136             Catalyst::Exception->throw(
 137                 message => qq/Couldn't create tmpdir '$tmpdir', "$@"/ );
 138         }
 139     }
 140
 141     return $tmpdir->stringify;
 142 }
 143
 144 =head2 home($class)
 145
 146 Returns home directory for given class.
 147
 148 =cut
 149
 150 sub home {
 151     my $class = shift;
 152
 153     # make an $INC{ $key } style string from the class name
 154     (my $file = "$class.pm") =~ s{::}{/}g;
 155
 156     if ( my $inc_entry = $INC{$file} ) {
 157         {
 158             # look for an uninstalled Catalyst app
 159
 160             # find the @INC entry in which $file was found
 161             (my $path = $inc_entry) =~ s/$file$//;
 162             my $home = dir($path)->absolute->cleanup;
 163
 164             # pop off /lib and /blib if they're there
 165             $home = $home->parent while $home =~ /b?lib$/;
 166
 167             # only return the dir if it has a Makefile.PL or Build.PL
 168             if (-f $home->file("Makefile.PL") or -f $home->file("Build.PL")) {
 169
 170                 # clean up relative path:
 171                 # MyApp/script/.. -> MyApp
 172
 173                 my ($lastdir) = $home->dir_list( -1, 1 );
 174                 if ( $lastdir eq '..' ) {
 175                     $home = dir($home)->parent->parent;
 176                 }
 177
 178                 return $home->stringify;
 179             }
 180         }
 181
 182         {
 183             # look for an installed Catalyst app
 184
 185             # trim the .pm off the thing ( Foo/Bar.pm -> Foo/Bar/ )
 186             ( my $path = $inc_entry) =~ s/\.pm$//;
 187             my $home = dir($path)->absolute->cleanup;
 188
 189             # return if if it's a valid directory
 190             return $home->stringify if -d $home;
 191         }
 192     }
 193
 194     # we found nothing
 195     return 0;
 196 }
 197
 198 =head2 prefix($class, $name);
 199
 200 Returns a prefixed action.
 201
 202     MyApp::C::Foo::Bar, yada becomes foo/bar/yada
 203
 204 =cut
 205
 206 sub prefix {
 207     my ( $class, $name ) = @_;
 208     my $prefix = &class2prefix($class);
 209     $name = "$prefix/$name" if $prefix;
 210     return $name;
 211 }
 212
 213 =head2 request($uri)
 214
 215 Returns an L<HTTP::Request> object for a uri.
 216
 217 =cut
 218
 219 sub request {
 220     my $request = shift;
 221     unless ( ref $request ) {
 222         if ( $request =~ m/^http/i ) {
 223             $request = URI->new($request)->canonical;
 224         }
 225         else {
 226             $request = URI->new( 'http://localhost' . $request )->canonical;
 227         }
 228     }
 229     unless ( ref $request eq 'HTTP::Request' ) {
 230         $request = HTTP::Request->new( 'GET', $request );
 231     }
 232     return $request;
 233 }
 234
 235 =head2 ensure_class_loaded($class_name)
 236
 237 Loads the class unless it already has been loaded.
 238
 239 =cut
 240
 241 sub ensure_class_loaded {
 242     my $class = shift;
 243     my $opts  = shift;
 244
 245     return if !$opts->{ ignore_loaded }
 246         && Class::Inspector->loaded( $class ); # if a symbol entry exists we don't load again
 247
 248     # this hack is so we don't overwrite $@ if the load did not generate an error
 249     my $error;
 250     {
 251         local $@;
 252         eval "require $class";
 253         $error = $@;
 254     }
 255
 256     die $error if $error;
 257     die "require $class was successful but the package is not defined"
 258         unless Class::Inspector->loaded($class);
 259
 260     return 1;
 261 }
 262
 263 =head2 merge_hashes($hashref, $hashref)
 264
 265 Base code to recursively merge two hashes together with right-hand precedence.
 266
 267 =cut
 268
 269 sub merge_hashes {
 270     my ( $lefthash, $righthash ) = @_;
 271
 272     return $lefthash unless defined $righthash;
 273
 274     my %merged = %$lefthash;
 275     for my $key ( keys %$righthash ) {\r
 276         my $right_ref = ( ref $righthash->{ $key } || '' ) eq 'HASH';\r
 277         my $left_ref  = ( ( exists $lefthash->{ $key } && ref $lefthash->{ $key } ) || '' ) eq 'HASH';\r
 278         if( $right_ref and $left_ref ) {\r
 279             $merged{ $key } = merge_hashes(
 280                 $lefthash->{ $key }, $righthash->{ $key }
 281             );\r
 282         }
 283         else {
 284             $merged{ $key } = $righthash->{ $key };
 285         }\r
 286     }
 287
 288     return \%merged;
 289 }
 290
 291
 292 =head1 AUTHOR
 293
 294 Sebastian Riedel, C<sri@cpan.org>
 295 Yuval Kogman, C<nothingmuch@woobling.org>
 296
 297 =head1 COPYRIGHT
 298
 299 This program is free software, you can redistribute it and/or modify it under
 300 the same terms as Perl itself.
 301
 302 =cut
 303
 304 1;