Debian Codegraph @

README

raw
1 NAME
2 DBIx::Class::Candy - Sugar for your favorite ORM, DBIx::Class
3
4 SYNOPSIS
5 package MyApp::Schema::Result::Artist;
6
7 use DBIx::Class::Candy -autotable => v1;
8
9 primary_column id => {
10 data_type => 'int',
11 is_auto_increment => 1,
12 };
13
14 column name => {
15 data_type => 'varchar',
16 size => 25,
17 is_nullable => 1,
18 };
19
20 has_many albums => 'A::Schema::Result::Album', 'artist_id';
21
22 1;
23
24 DESCRIPTION
25 "DBIx::Class::Candy" is a simple sugar layer for definition of
26 DBIx::Class results. Note that it may later be expanded to add sugar for
27 more "DBIx::Class" related things. By default "DBIx::Class::Candy":
28
29 * turns on strict and warnings
30
31 * sets your parent class
32
33 * exports a bunch of the package methods that you normally use to
34 define your DBIx::Class results
35
36 * makes a few aliases to make some of the original method names
37 shorter or more clear
38
39 * defines very few new subroutines that transform the arguments passed
40 to them
41
42 It assumes a DBIx::Class::Core-like API, but you can tailor it to suit
43 your needs.
44
45 IMPORT OPTIONS
46 See "SETTING DEFAULT IMPORT OPTIONS" for information on setting these
47 schema wide.
48
49 -base
50 use DBIx::Class::Candy -base => 'MyApp::Schema::Result';
51
52 The first thing you can do to customize your usage of
53 "DBIx::Class::Candy" is change the parent class. Do that by using the
54 "-base" import option.
55
56 -autotable
57 use DBIx::Class::Candy -autotable => v1;
58
59 Don't waste your precious keystrokes typing "table 'buildings'", let
60 "DBIx::Class::Candy" do that for you! See "AUTOTABLE VERSIONS" for what
61 the existing versions will generate for you.
62
63 -components
64 use DBIx::Class::Candy -components => ['FilterColumn'];
65
66 "DBIx::Class::Candy" allows you to set which components you are using at
67 import time so that the components can define their own sugar to export
68 as well. See DBIx::Class::Candy::Exports for details on how that works.
69
70 -perl5
71 use DBIx::Class::Candy -perl5 => v10;
72
73 I love the new features in Perl 5.10 and 5.12, so I felt that it would
74 be nice to remove the boiler plate of doing "use feature ':5.10'" and
75 add it to my sugar importer. Feel free not to use this.
76
77 -experimental
78 use DBIx::Class::Candy -experimental => ['signatures'];
79
80 I would like to use signatures and postfix dereferencing in all of my
81 "DBIx::Class" classes. This makes that goal trivial.
82
83 IMPORTED SUBROUTINES
84 Most of the imported subroutines are the same as what you get when you
85 use the normal interface for result definition: they have the same names
86 and take the same arguments. In general write the code the way you
87 normally would, leaving out the "__PACKAGE__->" part. The following are
88 methods that are exported with the same name and arguments:
89
90 belongs_to
91 has_many
92 has_one
93 inflate_column
94 many_to_many
95 might_have
96 remove_column
97 remove_columns
98 resultset_attributes
99 resultset_class
100 sequence
101 source_name
102 table
103
104 There are some exceptions though, which brings us to:
105
106 IMPORTED ALIASES
107 These are merely renamed versions of the functions you know and love.
108 The idea is to make your result classes a tiny bit prettier by aliasing
109 some methods. If you know your "DBIx::Class" API you noticed that in the
110 "SYNOPSIS" I used "column" instead of "add_columns" and "primary_key"
111 instead of "set_primary_key". The old versions work, this is just nicer.
112 A list of aliases are as follows:
113
114 column => 'add_columns',
115 primary_key => 'set_primary_key',
116 unique_constraint => 'add_unique_constraint',
117 relationship => 'add_relationship',
118
119 SETTING DEFAULT IMPORT OPTIONS
120 Eventually you will get tired of writing the following in every single
121 one of your results:
122
123 use DBIx::Class::Candy
124 -base => 'MyApp::Schema::Result',
125 -perl5 => v12,
126 -autotable => v1,
127 -experimental => ['signatures'];
128
129 You can set all of these for your whole schema if you define your own
130 "Candy" subclass as follows:
131
132 package MyApp::Schema::Candy;
133
134 use base 'DBIx::Class::Candy';
135
136 sub base { $_[1] || 'MyApp::Schema::Result' }
137 sub perl_version { 12 }
138 sub autotable { 1 }
139 sub experimental { ['signatures'] }
140
141 Note the "$_[1] ||" in "base". All of these methods are passed the
142 values passed in from the arguments to the subclass, so you can either
143 throw them away, honor them, die on usage, or whatever. To be clear, if
144 you define your subclass, and someone uses it as follows:
145
146 use MyApp::Schema::Candy
147 -base => 'MyApp::Schema::Result',
148 -perl5 => v18,
149 -autotable => v1,
150 -experimental => ['postderef'];
151
152 Your "base" method will get "MyApp::Schema::Result", your "perl_version"
153 will get 18, your "experimental" will get "['postderef']", and your
154 "autotable" will get 1.
155
156 SECONDARY API
157 has_column
158 There is currently a single "transformer" for "add_columns", so that
159 people used to the Moose api will feel more at home. Note that this may
160 go into a "Candy Component" at some point.
161
162 Example usage:
163
164 has_column foo => (
165 data_type => 'varchar',
166 size => 25,
167 is_nullable => 1,
168 );
169
170 primary_column
171 Another handy little feature that allows you to define a column and set
172 it as the primary key in a single call:
173
174 primary_column id => {
175 data_type => 'int',
176 is_auto_increment => 1,
177 };
178
179 If your table has multiple columns in its primary key, merely call this
180 method for each column:
181
182 primary_column person_id => { data_type => 'int' };
183 primary_column friend_id => { data_type => 'int' };
184
185 unique_column
186 This allows you to define a column and set it as unique in a single
187 call:
188
189 unique_column name => {
190 data_type => 'varchar',
191 size => 30,
192 };
193
194 AUTOTABLE VERSIONS
195 Currently there are two versions:
196
197 "v1"
198 It looks at your class name, grabs everything after "::Schema::Result::"
199 (or "::Result::"), removes the "::"'s, converts it to underscores
200 instead of camel-case, and pluralizes it. Here are some examples if
201 that's not clear:
202
203 MyApp::Schema::Result::Cat -> cats
204 MyApp::Schema::Result::Software::Building -> software_buildings
205 MyApp::Schema::Result::LonelyPerson -> lonely_people
206 MyApp::DB::Result::FriendlyPerson -> friendly_people
207 MyApp::DB::Result::Dog -> dogs
208
209 'singular'
210 It looks at your class name, grabs everything after "::Schema::Result::"
211 (or "::Result::"), removes the "::"'s and converts it to underscores
212 instead of camel-case. Here are some examples if that's not clear:
213
214 MyApp::Schema::Result::Cat -> cat
215 MyApp::Schema::Result::Software::Building -> software_building
216 MyApp::Schema::Result::LonelyPerson -> lonely_person
217 MyApp::DB::Result::FriendlyPerson -> friendly_person
218 MyApp::DB::Result::Dog -> dog
219
220 Also, if you just want to be different, you can easily set up your own
221 naming scheme. Just add a "gen_table" method to your candy subclass. The
222 method gets passed the class name and the autotable version, which of
223 course you may ignore. For example, one might just do the following:
224
225 sub gen_table {
226 my ($self, $class) = @_;
227
228 $class =~ s/::/_/g;
229 lc $class;
230 }
231
232 Which would transform "MyApp::Schema::Result::Foo" into
233 "myapp_schema_result_foo".
234
235 Or maybe instead of using the standard "MyApp::Schema::Result" namespace
236 you decided to be different and do "MyApp::DB::Table" or something silly
237 like that. You could pre-process your class name so that the default
238 "gen_table" will still work:
239
240 sub gen_table {
241 my $self = shift;
242 my $class = $_[0];
243
244 $class =~ s/::DB::Table::/::Schema::Result::/;
245 return $self->next::method(@_);
246 }
247
248 AUTHOR
249 Arthur Axel "fREW" Schmidt <[email protected]>
250
251 COPYRIGHT AND LICENSE
252 This software is copyright (c) 2024 by Arthur Axel "fREW" Schmidt.
253
254 This is free software; you can redistribute it and/or modify it under
255 the same terms as the Perl 5 programming language system itself.
256