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 B<This module is EXPERIMENTAL>
  97
  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
 143         final action qux {
 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