it's nice to have a README in the repo

diff --git a/Makefile.PL b/Makefile.PL
index 59796f5..7d673a3 100644 (file)
--- a/Makefile.PL
+++ b/Makefile.PL
@@ -5,7 +5,7 @@ author          'Robert Sedlacek <rs@474.at>';
 license         'perl';
 
 all_from        'lib/CatalystX/Declare.pm';
-readme_from     'lib/CatalystX/Declare.pm', 'clean';
+readme_from     'lib/CatalystX/Declare.pm';
 
 author_tests    'xt';
 

diff --git a/README b/README
new file mode 100644 (file)
index 0000000..a2ef93e
--- /dev/null
+++ b/README
@@ -0,0 +1,165 @@
+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.
+