README

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