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 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 provides a declarative syntax for Catalyst applications. Its
  70     main focus is currently on common and repetitious parts of the
  71     application, such as the application class itself, controllers, and
  72     controller roles.
  73
  74   Not a Source Filter
  75     The used syntax elements are not parsed via source filter mechanism, but
  76     through Devel::Declare, which is a much less fragile deal to handle and
  77     allows extensions to mix without problems. For example, all keywords
  78     added by this module are separete handlers.
  79
  80   Syntax Documentation
  81     The documentation about syntax is in the respective parts of the
  82     distribution below the "CatalystX::Declare::Keyword::" namespace. Here
  83     are the manual pages you will be interested in to familiarize yourself
  84     with this module's syntax extensions:
  85
  86     CatalystX::Declare::Keyword::Application
  87     CatalystX::Declare::Keyword::Controller
  88     CatalystX::Declare::Keyword::Action
  89     CatalystX::Declare::Keyword::Role
  90
  91     Things like models, views, roles for request or response objects, can be
  92     built declaratively with MooseX::Declare, which is used to additionally
  93     provide keywords for "class", "role", "method" and the available method
  94     modifier declarations. This allows for constructs such as:
  95
  96         use CatalystX::Declare;
  97
  98         class Foo {
  99
 100             method bar { 23 }
 101         }
 102
 103         controller MyApp::Web::Controller::Baz {
 104
 105             final action qux {
 106                 $ctx->response->body(Foo->new->bar)
 107             }
 108         }
 109
 110 SEE ALSO
 111   For Usage Information
 112     These links are intended for the common user of this module.
 113
 114     Catalyst::Runtime
 115     Catalyst::Devel
 116     Catalyst::Manual
 117         Although you probably already know Catalyst, since you otherwise
 118         probably wouldn't be here, I include these links for completeness
 119         sake.
 120
 121     Moose
 122         The powerful modern Perl object orientation implementation that is
 123         used as basis for Catalyst. MooseX::Declare, on which
 124         CatalystX::Declare is based, provides a declarative syntax for
 125         Moose.
 126
 127     MooseX::Declare
 128         We inherit almost all functionality from MooseX::Declare to allow
 129         the declaration of traditional classes, roles, methods, modifiers,
 130         etc. Refer to this documentation first for syntax elements that
 131         aren't part of CatalystX::Declare.
 132
 133     MooseX::Method::Signatures
 134         This isn't directly used, but MooseX::Declare utilises this to
 135         provide us with method and modifier declarations. For extended
 136         information on the usage of methods, especially signatures, refer to
 137         this module after looking for an answer in the MooseX::Declare
 138         documentation.
 139
 140   For Developer Information
 141     This section contains links relevant to the implementation of this
 142     module.
 143
 144     Devel::Declare
 145         You could call this is the basic machine room that runs the
 146         interaction with perl. It provides a way to hook into perl's source
 147         code parsing and change small parts on a per-statement basis.
 148
 149     MooseX::MethodAttributes
 150         We use this module to easily communicate the action attributes to
 151         Catalyst. Currently, this is the easiest solution for now but may be
 152         subject to change in the future.
 153
 154 AUTHOR
 155     Robert 'phaylon' Sedlacek, <rs@474.at>
 156
 157     With contributions from, and many thanks to:
 158
 159     Florian Ragwitz
 160     John Napiorkowski
 161
 162 LICENSE
 163     This program is free software; you can redistribute it and/or modify it
 164     under the same terms as perl itself.
 165