lib/CatalystX/Declare.pm

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