[catagits/CatalystX-Declare.git] / README

NAME
    CatalystX::Declare - EXPERIMENTAL Declarative Syntax for Catalyst
    Applications

SYNOPSIS
  Application
        use CatalystX::Declare;
    
        application MyApp::Web with Static::Simple {
    
            $CLASS->config(name => 'My Declarative Web Application');
        }

  Controllers
        use CatalystX::Declare;

        controller MyApp::Web::Controller::Foo
              with MyApp::Web::ControllerRole::Bar {
        
            use MooseX::Types::Moose qw( Str );
        
        
            has welcome_message => (
                is          => 'rw',
                isa         => Str,
                required    => 1,
                lazy_build  => 1,
            );
        
            method _build_welcome_message { 'Welcome' }
        
        
            action base as '';
        
            under base {
            
                final action welcome {
                    $ctx->response->body( $self->welcome_message );
                }
            }
        }

  Roles
        use CatalystX::Declare;

        controller_role MyApp::Web::ControllerRole::Bar {

            use MyApp::Types qw( Username );


            around _build_welcome_message { $self->$orig . '!' }

            after welcome (Object $ctx) {

                $ctx->response->body(join "\n",
                    $ctx->response->body,
                    time(),
                );
            }


            final action special_welcome (Username $name) under base {

                $ctx->response->body('Hugs to ' . $name);
            }
        }

DESCRIPTION
    This module provides a declarative syntax for Catalyst applications. Its
    main focus is currently on common and repetitious parts of the
    application, such as the application class itself, controllers, and
    controller roles.

  Not a Source Filter
    The used syntax elements are not parsed via source filter mechanism, but
    through Devel::Declare, which is a much less fragile deal to handle and
    allows extensions to mix without problems. For example, all keywords
    added by this module are separete handlers.

  Syntax Documentation
    The documentation about syntax is in the respective parts of the
    distribution below the "CatalystX::Declare::Keyword::" namespace. Here
    are the manual pages you will be interested in to familiarize yourself
    with this module's syntax extensions:

    CatalystX::Declare::Keyword::Application
    CatalystX::Declare::Keyword::Controller
    CatalystX::Declare::Keyword::Action
    CatalystX::Declare::Keyword::Role

    Things like models, views, roles for request or response objects, can be
    built declaratively with MooseX::Declare, which is used to additionally
    provide keywords for "class", "role", "method" and the available method
    modifier declarations. This allows for constructs such as:

        use CatalystX::Declare;

        class Foo {

            method bar { 23 }
        }

        controller MyApp::Web::Controller::Baz {

            final action qux { 
                $ctx->response->body(Foo->new->bar) 
            }
        }

SEE ALSO
  For Usage Information
    These links are intended for the common user of this module.

    Catalyst::Runtime
    Catalyst::Devel
    Catalyst::Manual
        Although you probably already know Catalyst, since you otherwise
        probably wouldn't be here, I include these links for completeness
        sake.

    Moose
        The powerful modern Perl object orientation implementation that is
        used as basis for Catalyst. MooseX::Declare, on which
        CatalystX::Declare is based, provides a declarative syntax for
        Moose.

    MooseX::Declare
        We inherit almost all functionality from MooseX::Declare to allow
        the declaration of traditional classes, roles, methods, modifiers,
        etc. Refer to this documentation first for syntax elements that
        aren't part of CatalystX::Declare.

    MooseX::Method::Signatures
        This isn't directly used, but MooseX::Declare utilises this to
        provide us with method and modifier declarations. For extended
        information on the usage of methods, especially signatures, refer to
        this module after looking for an answer in the MooseX::Declare
        documentation.

  For Developer Information
    This section contains links relevant to the implementation of this
    module.

    Devel::Declare
        You could call this is the basic machine room that runs the
        interaction with perl. It provides a way to hook into perl's source
        code parsing and change small parts on a per-statement basis.

    MooseX::MethodAttributes
        We use this module to easily communicate the action attributes to
        Catalyst. Currently, this is the easiest solution for now but may be
        subject to change in the future.

AUTHOR
    Robert 'phaylon' Sedlacek, <rs@474.at>

    With contributions from, and many thanks to:

    Florian Ragwitz
    John Napiorkowski

LICENSE
    This program is free software; you can redistribute it and/or modify it
    under the same terms as perl itself.
Commit	Line	Data
a1c42bd6	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