lib/DBIx/Class/Schema/ResultSetAccessors.pm

   1 package DBIx::Class::Schema::ResultSetAccessors;
   2
   3 use strict;
   4 use warnings;
   5
   6 use String::CamelCase;
   7 use Lingua::EN::Inflect::Phrase;
   8 use Sub::Name 'subname';
   9
  10 our $VERSION = 0.001001;
  11
  12 sub register_source {
  13     my $self    = shift;
  14     my $moniker = $_[0];
  15     my $next    = $self->next::method(@_);
  16     my $schema  = ref($self) || $self;
  17
  18     my $accessor_name =
  19         exists $self->resultset_accessor_map->{$moniker}
  20              ? $self->resultset_accessor_map->{$moniker}
  21              : $self->resultset_accessor_name($moniker);
  22
  23     if ($schema->can($accessor_name)) {
  24         $self->throw_exception(
  25             "Can't create ResultSet accessor '$accessor_name'. " .
  26             "Schema method with the same name already exists. " .
  27             "Try overloading the name via resultset_accessor_map."
  28         );
  29     }
  30
  31     {
  32         no strict 'refs';
  33         no warnings 'redefine';
  34         *{"${schema}::${accessor_name}"} = subname "${schema}::${accessor_name}"
  35             => sub { shift->resultset($moniker) };
  36     }
  37
  38     return $next;
  39 }
  40
  41 sub resultset_accessor_map {
  42     {}
  43 }
  44
  45 sub resultset_accessor_name {
  46     my ($self, $moniker) = @_;
  47
  48     return $self->pluralize_resultset_accessor_name(
  49         String::CamelCase::decamelize($moniker)
  50     );
  51 }
  52
  53 sub pluralize_resultset_accessor_name {
  54     my ($self, $original) = @_;
  55
  56     return join '_', split /\s+/,
  57         Lingua::EN::Inflect::Phrase::to_PL(join ' ', split /_/, $original);
  58 }
  59
  60 1; # eof
  61
  62 __END__
  63
  64 =head1 NAME
  65
  66 DBIx::Class::Schema::ResultSetAccessors - Short hand ResultSet Accessors
  67
  68 =head1 SYNOPSIS
  69
  70   use MyApp::Schema;
  71   my $schema = MyApp::Schema->connect(...);
  72
  73   @artists = $schema->artists->all; # same as $schema->resultset('Artist')->all;
  74
  75 =head1 DESCRIPTION
  76
  77 Creates short hand accessor methods for each ResultSet. Accessor names are
  78 properly converted into lowercase and pluralized. E.g.
  79
  80  LinerNote -> liner_notes
  81  Artist    -> artists
  82  CD        -> cds
  83
  84 =head1 METHODS
  85
  86 =head2 resultset_accessor_map
  87
  88 Sometimes you will not want to, or will not be able to use an auto-generated
  89 accessor name. A common case would be when the accessor name conflicts with a
  90 built in DBIx::Class::Schema method. E.g. if you name your Result class
  91 "Source", a pluralized version of this would be "sources", which is a built in
  92 method.
  93
  94 This method allows you to redefine the names as you wish. Overload this method
  95 in your schema class and return a hashref map of Source => accessor names. E.g.:
  96
  97  # in your MyApp::Schema class
  98  sub resultset_accessor_map {
  99     {
 100         Source => 'my_sources',
 101         Artist => 'my_artists',
 102     }
 103  }
 104
 105  # later in your code
 106  $schema->my_source->all;
 107
 108 =head2 resultset_accessor_name($moniker)
 109
 110 This method is used to generate the accessor names. If you wish to create your
 111 own logic for generating the name, you can overload this method. The method
 112 takes a moniker (aka Source name) as a parameter and returns the accessor name.
 113
 114 Internally it simply uses L<String::CamelCase> to decamelize the name and pass
 115 it to L</pluralize_resultset_accessor_name> method.
 116
 117 =head2 pluralize_resultset_accessor_name($decamelized_name)
 118
 119 If you only wish to overload the pluralization of the accessor name, in case you
 120 want to add support for a language other than English, then you might only want
 121 to overload this method. The method accepts decamelized name (e.g. liner_note)
 122 and returns properly pluralized version of it.
 123
 124 =head1 SEE ALSO
 125
 126 =over 4
 127
 128 =item L<DBIx::Class>
 129
 130 =item L<String::CamelCase>
 131
 132 =item L<Lingua::EN::Inflect::Phrase>
 133
 134 =back
 135
 136 =head1 AUTHOR
 137
 138  Roman F.
 139  romanf@cpan.org
 140
 141 =head1 COPYRIGHT
 142
 143 Copyright (c) 2011 Roman F.
 144
 145 This program is free software; you can redistribute
 146 it and/or modify it under the same terms as Perl itself.
 147
 148 The full text of the license can be found in the
 149 LICENSE file included with this module.
 150
 151 =cut