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::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';
  12
  13     around keywords {
  14         $self->$orig,
  15         ControllerKeyword->new(identifier => 'controller'),
  16         RoleKeyword->new(identifier => 'controller_role'),
  17         ApplicationKeyword->new(identifier => 'application'),
  18     }
  19 }
  20
  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
  58         action base as '';
  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
  72     controller_role MyApp::Web::ControllerRole::Bar {
  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
  96 This module provides a declarative syntax for L<Catalyst|Catalyst::Runtime>
  97 applications. Its main focus is currently on common and repetitious parts of
  98 the application, such as the application class itself, controllers, and
  99 controller roles.
 100
 101 =head2 Not a Source Filter
 102
 103 The used syntax elements are not parsed via source filter mechanism, but
 104 through L<Devel::Declare>, which is a much less fragile deal to handle and
 105 allows extensions to mix without problems. For example, all keywords added
 106 by this module are separete handlers.
 107
 108 =head2 Syntax Documentation
 109
 110 The documentation about syntax is in the respective parts of the distribution
 111 below the C<CatalystX::Declare::Keyword::> namespace. Here are the manual
 112 pages you will be interested in to familiarize yourself with this module's
 113 syntax extensions:
 114
 115 =over
 116
 117 =item L<CatalystX::Declare::Keyword::Application>
 118
 119 =item L<CatalystX::Declare::Keyword::Controller>
 120
 121 =item L<CatalystX::Declare::Keyword::Action>
 122
 123 =item L<CatalystX::Declare::Keyword::Role>
 124
 125 =back
 126
 127 Things like models, views, roles for request or response objects, can be built
 128 declaratively with L<MooseX::Declare>, which is used to additionally provide
 129 keywords for C<class>, C<role>, C<method> and the available method modifier
 130 declarations. This allows for constructs such as:
 131
 132     use CatalystX::Declare;
 133
 134     class Foo {
 135
 136         method bar { 23 }
 137     }
 138
 139     controller MyApp::Web::Controller::Baz {
 140
 141         final action qux {
 142             $ctx->response->body(Foo->new->bar)
 143         }
 144     }
 145
 146 =head1 SEE ALSO
 147
 148 =head2 For Usage Information
 149
 150 These links are intended for the common user of this module.
 151
 152 =over
 153
 154 =item L<Catalyst::Runtime>
 155
 156 =item L<Catalyst::Devel>
 157
 158 =item L<Catalyst::Manual>
 159
 160 Although you probably already know Catalyst, since you otherwise probably
 161 wouldn't be here, I include these links for completeness sake.
 162
 163 =item L<Moose>
 164
 165 The powerful modern Perl object orientation implementation that is used
 166 as basis for Catalyst. L<MooseX::Declare>, on which L<CatalystX::Declare>
 167 is based, provides a declarative syntax for L<Moose>.
 168
 169 =item L<MooseX::Declare>
 170
 171 We inherit almost all functionality from L<MooseX::Declare> to allow the
 172 declaration of traditional classes, roles, methods, modifiers, etc. Refer
 173 to this documentation first for syntax elements that aren't part of
 174 L<CatalystX::Declare>.
 175
 176 =item L<MooseX::Method::Signatures>
 177
 178 This isn't directly used, but L<MooseX::Declare> utilises this to provide
 179 us with method and modifier declarations. For extended information on the
 180 usage of methods, especially signatures, refer to this module after
 181 looking for an answer in the L<MooseX::Declare> documentation.
 182
 183 =back
 184
 185 =head2 For Developer Information
 186
 187 This section contains links relevant to the implementation of this module.
 188
 189 =over
 190
 191 =item L<Devel::Declare>
 192
 193 You could call this is the basic machine room that runs the interaction with
 194 perl. It provides a way to hook into perl's source code parsing and change
 195 small parts on a per-statement basis.
 196
 197 =item L<MooseX::MethodAttributes>
 198
 199 We use this module to easily communicate the action attributes to
 200 L<Catalyst|Catalyst::Runtime>. Currently, this is the easiest solution for
 201 now but may be subject to change in the future.
 202
 203 =back
 204
 205
 206 =head1 AUTHOR
 207
 208 =over
 209
 210 =item Robert 'phaylon' Sedlacek, L<E<lt>rs@474.atE<gt>>
 211
 212 =back
 213
 214 With contributions from, and many thanks to:
 215
 216 =over
 217
 218 =item Florian Ragwitz
 219
 220 =item John Napiorkowski
 221
 222 =back
 223
 224
 225 =head1 LICENSE
 226
 227 This program is free software; you can redistribute it and/or modify it under
 228 the same terms as perl itself.
 229
 230 =cut