Commit | Line | Data |
9c11a562 |
1 | use MooseX::Declare; |
2 | |
856ac9a7 |
3 | class CatalystX::Declare extends MooseX::Declare is dirty { |
9c11a562 |
4 | |
856ac9a7 |
5 | use aliased 'CatalystX::Declare::Keyword::Controller', 'ControllerKeyword'; |
6 | use aliased 'CatalystX::Declare::Keyword::Role', 'RoleKeyword'; |
7 | use aliased 'CatalystX::Declare::Keyword::Application', 'ApplicationKeyword'; |
8 | |
9 | clean; |
10 | |
11 | our $VERSION = '0.001'; |
9c11a562 |
12 | |
13 | around keywords { |
14 | $self->$orig, |
15 | ControllerKeyword->new(identifier => 'controller'), |
e2dc918e |
16 | RoleKeyword->new(identifier => 'component_role'), |
856ac9a7 |
17 | ApplicationKeyword->new(identifier => 'application'), |
9c11a562 |
18 | } |
19 | } |
20 | |
856ac9a7 |
21 | __END__ |
22 | |
23 | =head1 NAME |
24 | |
25 | CatalystX::Declare - EXPERIMENTAL Declarative Syntax for Catalyst Applications |
26 | |
27 | =head1 SYNOPSIS |
28 | |
29 | =head2 Application |
30 | |
31 | use CatalystX::Declare; |
32 | |
33 | application MyApp::Web with Static::Simple { |
34 | |
35 | $CLASS->config(name => 'My Declarative Web Application'); |
36 | } |
37 | |
38 | =head2 Controllers |
39 | |
40 | use CatalystX::Declare; |
41 | |
42 | controller MyApp::Web::Controller::Foo |
43 | with MyApp::Web::ControllerRole::Bar { |
44 | |
45 | use MooseX::Types::Moose qw( Str ); |
46 | |
47 | |
48 | has welcome_message => ( |
49 | is => 'rw', |
50 | isa => Str, |
51 | required => 1, |
52 | lazy_build => 1, |
53 | ); |
54 | |
55 | method _build_welcome_message { 'Welcome' } |
56 | |
57 | |
6e2492a4 |
58 | action base under '/' as ''; |
856ac9a7 |
59 | |
60 | under base { |
61 | |
62 | final action welcome { |
63 | $ctx->response->body( $self->welcome_message ); |
64 | } |
65 | } |
66 | } |
67 | |
68 | =head2 Roles |
69 | |
70 | use CatalystX::Declare; |
71 | |
e2dc918e |
72 | component_role MyApp::Web::ControllerRole::Bar { |
856ac9a7 |
73 | |
74 | use MyApp::Types qw( Username ); |
75 | |
76 | |
77 | around _build_welcome_message { $self->$orig . '!' } |
78 | |
79 | after welcome (Object $ctx) { |
80 | |
81 | $ctx->response->body(join "\n", |
82 | $ctx->response->body, |
83 | time(), |
84 | ); |
85 | } |
86 | |
87 | |
88 | final action special_welcome (Username $name) under base { |
89 | |
90 | $ctx->response->body('Hugs to ' . $name); |
91 | } |
92 | } |
93 | |
94 | =head1 DESCRIPTION |
95 | |
894774be |
96 | B<This module is EXPERIMENTAL> |
97 | |
856ac9a7 |
98 | This module provides a declarative syntax for L<Catalyst|Catalyst::Runtime> |
99 | applications. Its main focus is currently on common and repetitious parts of |
100 | the application, such as the application class itself, controllers, and |
101 | controller roles. |
102 | |
103 | =head2 Not a Source Filter |
104 | |
105 | The used syntax elements are not parsed via source filter mechanism, but |
106 | through L<Devel::Declare>, which is a much less fragile deal to handle and |
107 | allows extensions to mix without problems. For example, all keywords added |
108 | by this module are separete handlers. |
109 | |
110 | =head2 Syntax Documentation |
111 | |
112 | The documentation about syntax is in the respective parts of the distribution |
113 | below the C<CatalystX::Declare::Keyword::> namespace. Here are the manual |
114 | pages you will be interested in to familiarize yourself with this module's |
115 | syntax extensions: |
116 | |
117 | =over |
118 | |
119 | =item L<CatalystX::Declare::Keyword::Application> |
120 | |
121 | =item L<CatalystX::Declare::Keyword::Controller> |
122 | |
123 | =item L<CatalystX::Declare::Keyword::Action> |
124 | |
125 | =item L<CatalystX::Declare::Keyword::Role> |
126 | |
127 | =back |
128 | |
129 | Things like models, views, roles for request or response objects, can be built |
130 | declaratively with L<MooseX::Declare>, which is used to additionally provide |
131 | keywords for C<class>, C<role>, C<method> and the available method modifier |
132 | declarations. This allows for constructs such as: |
133 | |
134 | use CatalystX::Declare; |
135 | |
136 | class Foo { |
137 | |
138 | method bar { 23 } |
139 | } |
140 | |
141 | controller MyApp::Web::Controller::Baz { |
142 | |
6e2492a4 |
143 | final action qux under '/' { |
856ac9a7 |
144 | $ctx->response->body(Foo->new->bar) |
145 | } |
146 | } |
147 | |
148 | =head1 SEE ALSO |
149 | |
150 | =head2 For Usage Information |
151 | |
152 | These links are intended for the common user of this module. |
153 | |
154 | =over |
155 | |
156 | =item L<Catalyst::Runtime> |
157 | |
158 | =item L<Catalyst::Devel> |
159 | |
160 | =item L<Catalyst::Manual> |
161 | |
162 | Although you probably already know Catalyst, since you otherwise probably |
163 | wouldn't be here, I include these links for completeness sake. |
164 | |
165 | =item L<Moose> |
166 | |
167 | The powerful modern Perl object orientation implementation that is used |
168 | as basis for Catalyst. L<MooseX::Declare>, on which L<CatalystX::Declare> |
169 | is based, provides a declarative syntax for L<Moose>. |
170 | |
171 | =item L<MooseX::Declare> |
172 | |
173 | We inherit almost all functionality from L<MooseX::Declare> to allow the |
174 | declaration of traditional classes, roles, methods, modifiers, etc. Refer |
175 | to this documentation first for syntax elements that aren't part of |
176 | L<CatalystX::Declare>. |
177 | |
178 | =item L<MooseX::Method::Signatures> |
179 | |
180 | This isn't directly used, but L<MooseX::Declare> utilises this to provide |
181 | us with method and modifier declarations. For extended information on the |
182 | usage of methods, especially signatures, refer to this module after |
183 | looking for an answer in the L<MooseX::Declare> documentation. |
184 | |
185 | =back |
186 | |
187 | =head2 For Developer Information |
188 | |
189 | This section contains links relevant to the implementation of this module. |
190 | |
191 | =over |
192 | |
193 | =item L<Devel::Declare> |
194 | |
195 | You could call this is the basic machine room that runs the interaction with |
196 | perl. It provides a way to hook into perl's source code parsing and change |
197 | small parts on a per-statement basis. |
198 | |
199 | =item L<MooseX::MethodAttributes> |
200 | |
201 | We use this module to easily communicate the action attributes to |
202 | L<Catalyst|Catalyst::Runtime>. Currently, this is the easiest solution for |
203 | now but may be subject to change in the future. |
204 | |
205 | =back |
206 | |
207 | |
208 | =head1 AUTHOR |
209 | |
210 | =over |
211 | |
212 | =item Robert 'phaylon' Sedlacek, L<E<lt>rs@474.atE<gt>> |
213 | |
214 | =back |
215 | |
216 | With contributions from, and many thanks to: |
217 | |
218 | =over |
219 | |
220 | =item Florian Ragwitz |
221 | |
222 | =item John Napiorkowski |
223 | |
224 | =back |
225 | |
226 | |
227 | =head1 LICENSE |
228 | |
229 | This program is free software; you can redistribute it and/or modify it under |
230 | the same terms as perl itself. |
231 | |
232 | =cut |