lib/CatalystX/Declare.pm

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