NAME

MVC::Neaf - Not Even A (Web Application) Framework

OVERVIEW

Neaf [ni:f] stands for Not Even A Framework.

The Model is assumed to be just a regular Perl module, no restrictions are imposed on it.

The View is an object with one method, render, receiving a hashref and returning rendered content as string plus optional content-type header.

The Controller is broken down into handlers associated with URI paths. Each such handler receives a MVC::Neaf::Request object containing all it needs to know about the outside world, and returns a simple \%hashref which is forwarded to View.

Please see the example directory in this distribution that demonstrates the features of Neaf.

SYNOPSIS

The following application, outputting a greeting, is ready to run as a CGI script, PSGI application, or Apache handler.

    use strict;
    use warnings;
    use MVC::Neaf qw(:sugar);

    get+post '/app' => sub {
        my $req = shift;

        my $name = $req->param( name => qr/[-'\w\s]+/ ) || "Mystical stranger";
        return {
            name  => $name,
        };
    }, default => {
        -view     => 'TT',
        -type     => "text/plain",
        -template => \"Hello, [% name %]",
    };

    neaf->run;

A neaf app has some command-line interface built in:

    perl myapp.pl --list

Will give a summary of available routes.

    perl myapp.pl --listen :31415

Will start a default plackup server (plackup myapp.pl works as well)

    perl myapp.pl --post --upload foo=/path/to/file /bar?life=42 --view Dumper

Will run just one request and stop right before template processing, dumping stash instead.

CREATING AN APPLICATION

THE CONTROLLER

The handler sub receives an MVC::Neaf::Request object and outputs a \%hashref.

It may also die, which will be interpreted as an error 500, UNLESS error message starts with 3 digits and a whitespace, in which case this is considered the return status. E.g. die 404; is a valid method to return a configurable "Not Found" page right away.

Handlers are set using the route( path => CODEREF ); method discussed below.

THE REQUEST

The Request object is similar to the OO interface of CGI or Plack::Request with some minor differences:

    # What was requested:
    http(s)://server.name:1337/mathing/route/some/more/slashes?foo=1&bar=2

    # What is being returned:
    $req->http_version; # = HTTP/1.0 or HTTP/1.1
    $req->scheme      ; # = http or https
    $req->method      ; # = GET
    $req->hostname    ; # = server.name
    $req->port        ; # = 1337
    $req->path        ; # = /mathing/route/some/more/slashes
    $req->script_name ; # = /mathing/route
    $req->path_info   ; # = /some/more/slashes

    $req->param( foo => '\d+' ); # = 1
    $req->get_cookie( session => '.+' ); # = whatever it was set to before

One major difference is that there's no (easy) way to fetch query parameters or cookies without validation. Just use qr/.*/ if you know better.

Also there are some methods that affect the reply, mainly the headers, like set_cookie or redirect. This is a step towards a know-it-all God object, however, mapping those properties into a hashref turned out to be too cumbersome.

THE RESPONSE

The response may contain regular keys, typically alphanumeric, as well as a predefined set of dash-prefixed keys to control Neaf itself.

-Note -that -dash-prefixed -options -look -antique even to the author of this writing. However, it is a concise and visible way to separate auxiliary parameters from users's data, without requiring a more complex return structure (two hashes, array of arrays etc).

The small but growing list of these -options is as follows:

-content - Return raw data and skip view processing. E.g. display generated image.
-continue - A callback that receives the Request object. It will be executed AFTER the headers and pre-generated content are served to the client, and may use $req->write( $data ); and $req->close; to output more data.
-headers - Pass a hash or array of values for header generation. This is an alternative to MVC::Neaf::Request's push_header method.
-jsonp - Used by JS view module as a callback name to produce a jsonp response. Callback MUST be a set of identifiers separated by dots. Otherwise it's ignored for security reasons.
-location - HTTP Location: header for 3xx statuses. This is set by $request->redirect(...).
-serial - if present, the JS view will render this instead of the whole response hash. This can be used e.g. to return non-hash data in REST API. EXPERIMENTAL. Name and meaning may change in the future.
-status - HTTP status (200, 404, 500 etc). Default is 200 if the app managed to live through, and 500 if it died.
-template - Set template name for TT (Template-based view).
-type - Content-type HTTP header. View module may set this parameter if unset. Default: "text/html".
-view - select View module. Views are initialized lazily and cached by the framework. TT, JS, Full::Module::Name, and $view_predefined_object are currently supported. New short aliases may be created by MVC::Neaf->load_view( "name" => $your_view ); (see below).

The default is the JS aka MVC::Neaf::View::JS engine. Adding -template key will cause switching to MVC::Neaf::View::TT, but it is deprecated and will go away in v.0.20.

Though more dash-prefixed parameters may be returned and will be passed to the View module as of current, they are not guaranteed to work in the future. Please either avoid them, or send patches.

MAIN API

These methods are generally called during the setup phase of the application.

Although MVC::Neaf can be instantiated more than once, having many of them inside one Perl interpreter is of little use yet.

For brevity, a prototyped neaf() function invokes all kind of methods on the default instance, or just returns it if called without arguments.

get '/path' => sub { ... }, %options

post '/path' => sub { ... }, %options

get+post '/path' => sub { ... }, %options

neaf route => '/path' => sub { ... }, %options

This needs a method => [ ... ] or it's just a 'GET + POST' by default.

$neaf->route( '/path' => CODEREF, %options )

Set up an URI handler in the application. Any incoming request to uri matching /path (/path/something/else too, but NOT /pathology) will now be directed to CODEREF.

Longer paths are GUARANTEED to be checked first.

Dies if the same method and path combination is given again. Multiple methods may be given for the same path.

Exactly one leading slash will be prepended no matter what you do. (path, /path and /////path are all the same).

The CODEREF MUST accept exactly one argument, referred to as $request or $req hereafter, and return un unblessed hashref with response data.

%options may include:

method - list of allowed HTTP methods. Default is [GET, POST]. Multiple handles can be defined for the same path, provided that methods do not intersect. HEAD method is automatically handled if GET is present, however, one MAY define a separate HEAD handler explicitly.
path_info_regex => qr/.../ - allow URI subpaths to be handled by this handler.

A 404 error will be generated unless path_info_regex is present and PATH_INFO matches the regex (without the leading slashes).

If path_info_regex matches, it will be available in the controller as $req->path_info.

If capture groups are present in said regular expression, their content will also be available as $req->path_info_split.

EXPERIMENTAL. Name and semantics MAY change in the future.
param_regex => { name => qr/.../, name2 => '\d+' }

Add predefined regular expression validation to certain request parameters, so that they can be queried by name only. See param() in MVC::Neaf::Request.

EXPERIMENTAL. Name and semantics MAY change in the future.
view - default View object for this Controller. Must be an object with a render method, or a CODEREF receiving hashref and returning a list of two scalars (content and content-type).

DEPRECATED. Use -view instead, semantics are the same.
cache_ttl - if set, set Expires: HTTP header accordingly.

EXPERIMENTAL. Name and semantics MAY change in the future.
default - a \%hash of values that will be added to results EVERY time the handler returns. Consider using neaf default ... below if you need these added to multiple handlers.
description - just for information, has no action on execution. This will be displayed if application called with --list (see MVC::Neaf::CLI).

Also, any number of dash-prefixed keys MAY be present. This is totally the same as putting them into default hash.

NOTE For some reason ability to add multicomponent paths like (foo => bar => \&code) was added in the past, resulting in "/foo/bar" => \&code.

It was never documented, will issue a warning, and will be killed for good it v.0.25.

neaf static => '/path' => ...

static( $req_path => $file_path, %options )

Serve static content located under $file_path.

%options may include:

buffer => nnn - buffer size for reading/writing files. Default is 4096. Smaller values may be set, but are NOT recommended.
cache_ttl => nnn - if given, files below the buffer size will be stored in memory for cache_ttl seconds.

EXPERIMENTAL. Cache API is not yet established.
allow_dots => 1|0 - if true, serve files/directories starting with a dot (.git etc), otherwise give a 404.

EXPERIMENTAL
dir_index => 1|0 - if true, generate index for a directory; otherwise a 404 is returned, and deliberately so, for security reasons.

EXPERIMENTAL
dir_template - specify template for directory listing (with images etc). A sane default is provided.

EXPERIMENTAL
view - specify view object for rendering dir template. By default a localized TT instance is used.

EXPERIMENTAL Name MAY be changed (dir_view etc).
description - comment. The default is "Static content at $dir"

The content is really handled by MVC::Neaf::X::Files.

File type detection is based on extention. This MAY change in the future. Known file types are listed in %MVC::Neaf::X::Files::ExtType hash. Patches welcome.

Generally it is probably a bad idea to serve files in production using a web application framework. Use a real web server instead.

However, this method may come in handy when testing the application in standalone mode, e.g. under plack web server. This is the intended usage.

neaf default => '/path' => \%values

set_path_defaults ( '/path' => \%values )

Use given values as defaults for ANY handler below given path. A value of '/' means global.

Longer paths override shorter ones; route-specific defaults override these; and anything defined inside handler takes over once again.

neaf "phase" => sub { ... }, path => [ ... ], exclude => [ ... ]

add_hook ( phase => CODEREF, %options )

Set hook that will be executed on a given request processing phase.

Valid phases include:

pre_route [die]
pre_logic [die]
pre_content
pre_render [die]
pre_reply [reverse]
pre_cleanup [reverse]

See REQUEST PROCESSING PHASES AND HOOKS below for detailed discussion of each phase.

The CODEREF receives one and only argument - the $request object. Return value is ignored.

Use $request's session, reply, and stash methods for communication between hooks.

dieing in a hook may cause interruption of request processing or merely a warning, depending on the phase.

%options may include:

path => '/path' - where the hook applies. Default is '/'. Multiple locations may be supplied via [ /foo, /bar ...]
exclude => '/path/dont' - don't apply to these locations, even if under '/path'. Multiple locations may be supplied via [ /foo, /bar ...]
method => 'METHOD' || [ list ] List of request HTTP methods to which given hook applies.
prepend => 0|1 - all other parameters being equal, hooks will be executed in order of adding. This option allows to override this and run given hook first. Note that this does NOT override path bubbling order.

neaf alias $newpath => $oldpath

alias( $newpath => $oldpath )

Create a new name for already registered route. The handler will be executed as is, but the hooks and defaults will be re-calculated. So be careful.

Returns self.

neaf view => 'name' => 'Driver::Class' => %options;

load_view( $name, $object || coderef || ($module_name, %options) )

Setup view under name $name. Subsequent requests with -view = $name wouldbe processed by that view object.

Use get_view to fetch the object itself.

if object is given, just save it.
if module name + parameters is given, try to load module and create new() instance.

Short aliases JS, TT, and Dumper may be used for MVC::Neaf::View::*
if coderef is given, use it as a render method.

neaf session => $engine => %options

set_session_handler( %options )

Set a handler for managing sessions.

If such handler is set, the request object will provide session(), save_session(), and delete_session() methods to manage cross-request user data.

% options may include:

engine (required in OO form, first argument in DSL form) - an object providing the storage primitives;
ttl - time to live for session (default is 0, which means until browser is closed);
cookie - name of cookie storing session id. The default is "session".
view_as - if set, add the whole session into data hash under this name before view processing.

The engine MUST provide the following methods (see MVC::Neaf::X::Session for details):

session_ttl (implemented in MVC::Neaf::X::Session);
session_id_regex (implemented in MVC::Neaf::X::Session);
get_session_id (implemented in MVC::Neaf::X::Session);
create_session (implemented in MVC::Neaf::X::Session);
save_session (required);
load_session (required);
delete_session (implemented in MVC::Neaf::X::Session);

neaf form => name => $validator

neaf form => name => \%spec, engine => ...

add_form( name => $validator )

Create a named form for future data validation.

Form is created once and applied to different sets of data, returning an object containing collected valid data, errors (if any), and an is_valid flag.

Consider the following script:

    use MVC::Neaf qw(:sugar);
    neaf form => my => { foo => '\d+', bar => '[yn]' };
    get '/check' => sub {
        my $req = shift;
        my $in = $req->form("my");
        return $in->is_valid ? { ok => $in->data } : { error => $in->error };
    };
    neaf->run

And by running this one gets

    bash$ curl http://localhost:5000/check?bar=xxx
    {"error":{"bar":"BAD_FORMAT"}}
    bash$ curl http://localhost:5000/check?bar=y
    {"ok":{"bar":"y"}}
    bash$ curl http://localhost:5000/check?bar=yy
    {"error":{"bar":"BAD_FORMAT"}}
    bash$ curl http://localhost:5000/check?foo=137\&bar=n
    {"ok":{"bar":"n","foo":"137"}}
    bash$ curl http://localhost:5000/check?foo=leet
    {"error":{"foo":"BAD_FORMAT"}}

See more in MVC::Neaf::X::Form.

engine parameter has predefined values Neaf (the default), LIVR, and Wildcard (all case-insensitive) that will point towards built-in validation classes. You are encouraged to use LIVR (See Validator::LIVR and LIVR grammar) for anything except super-basic regexp checks.

neaf 403 => sub { ... }

set_error_handler ( status => CODEREF( $req, %options ) )

Set custom error handler.

Status must be a 3-digit number (as in HTTP). Other allowed keys MAY appear in the future.

The following options will be passed to coderef:

status - status being returned (500 in case of 'view');
caller - file:line where the route was set up; This is DEPRECATED and will silently disappear around version 0.25 Use $request->endpoint_origin instead.
error - exception, if there was one.

The coderef MUST return an unblessed hash just like a normal controller does.

In case of exception or unexpected return format default JSON-based error will be returned.

set_error_handler ( status => \%hash )

Return a static template as { %options, %hash }. This is a synonym to sub { +{ ... } }.

on_error( sub { my ($req, $err) = @_ } )

Install custom error handler for dying controller. Neaf's own exceptions and die \d\d\d status returns will NOT trigger it.

E.g. write to log, or something.

Return value from this callback is ignored. If it dies, only a warning is emitted.

neaf->run()

run()

Run the applicaton. This should be the last statement in your appication main file.

If called in void context, assumes execution as CGI and prints results to STDOUT. If command line options are present at the moment, enters debug mode via MVC::Neaf::CLI.

Otherwise returns a PSGI-compliant coderef. This will also happen if you application is require'd, meaning that it returns a true value and actually serves nothing until run() is called again.

Running under mod_perl requires setting a handler with MVC::Neaf::Request::Apache2.

REQUEST PROCESSING PHASES AND HOOKS

Hooks are subroutines executed during various phases of request processing. Each hook is characterized by phase, code to be executed, path, and method. Multiple hooks MAY be added for the same phase/path/method combination. ALL hooks matching a given route will be executed, either short to long or long to short (aka "event bubbling"), depending on the phase.

CAUTION Don't overuse hooks. This may lead to a convoluted, hard to follow application. Use hooks for repeated auxiliary tasks such as checking permissions or writing down statistics, NOT for primary application logic.

Hook return values are discarded, and deliberately so. In absense of an explicit return, Perl will interpret the last statement in the code as such. Therefore writers of hooks would have to be extremely careful to avoid breaking the execution chain. On the other hand, proper exception handling is required anyway for implementing any kind of callbacks.

As a rule of thumb, the following primitives should be used to maintain state accross hooks and the main controller:

Use session if you intend to share data between requests.
Use reply if you intend to render the data for the user.
Use stash as a last resort for temporary, private data.

The following list of phases MAY change in the future. Current request processing diagram looks as follows:

   [*] request created
    . <- pre_route [no path] [can die]
    |
    * route - select handler
    |
    . <- pre_logic [can die]
   [*] execute main handler
    * apply path-based defaults - reply() is populated now
    |
    . <- pre_content
    ? checking whether content already generated
    |\
    | . <- pre_render [can die - template error produced]
    | [*] render - -content is present now
    |/
    * generate default headers (content type & length, cookies, etc)
    . <- pre_reply [path traversal long to short]
    |
   [*] headers sent out, no way back!
    * output the rest of reply (if -continue specified)
    * execute postponed actions (if any)
    |
    . <- pre_cleanup [path traversal long to short] [no effect on headers]
   [*] request destroyed

pre_route

Executed AFTER the event has been received, but BEFORE the path has been resolved and handler found.

Dying in this phase stops both further hook processing and controller execution. Instead, the corresponding error handler is executed right away.

Options path and exclude are not available on this stage.

May be useful for mangling path. Use $request->set_path($new_path) if you need to.

pre_logic

Executed AFTER finding the correct route, but BEFORE processing the main handler code (one that returns \%hash, see route above).

Hooks are executed in order, shorted paths to longer. reply is not available at this stage, as the controller has not been executed yet.

Dying in this phase stops both further hook processing and controller execution. Instead, the corresponding error handler is executed right away.

EXAMPLE: use this hook to produce a 403 error if the user is not logged in and looking for a restricted area of the site:

    MVC::Neaf->set_hook( pre_logic => sub {
        my $request = shift;
        $request->session->{user_id} or die 403;
    }, path => '/admin', exclude => '/admin/static' );

pre_content

This hook is run AFTER the main handler has returned or died, but BEFORE content rendering/serialization is performed.

reply() hash is available at this stage.

Dying is ignored, only producing a warning.

pre_render

This hook is run BEFORE content rendering is performed, and ONLY IF the content is going to be rendered, i.e. no -content key set in response hash on previous stages.

Dying will stop rendering, resulting in a template error instead.

pre_reply

This hook is run AFTER the headers have been generated, but BEFORE the reply is actually sent to client. This is the last chance to amend something.

Hooks are executed in REVERSE order, from longer to shorter paths.

reply() hash is available at this stage.

Dying is ignored, only producing a warning.

pre_cleanup

This hook is run AFTER all postponed actions set up in controller (via -continue etc), but BEFORE the request object is actually destroyed. This can be useful to deinitialize something or write statistics.

The client conection MAY be closed at this point and SHOULD NOT be relied upon.

Hooks are executed in REVERSE order, from longer to shorter paths.

Dying is ignored, only producing a warning.

EXPORTED FUNCTIONS

Neaf tries hard to keep user's namespace clean, however, some helper functions are needed.

neaf_err $error

Rethrow Neaf's internal exceptions immediately, do nothing otherwise.

If no argument if given, acts on current $@ value.

Currently Neaf uses exception mechanism for internal signalling, so this function may be of use if there's a lot of eval blocks in the controller. E.g.

    use MVC::Neaf qw(neaf_err);

    # somewhere in controller
    eval {
        check_permissions()
            or $req->error(403);
        do_something()
            and $req->redirect("/success");
    };

    if (my $err = $@) {
        neaf_err;
        # do the rest of error handling
    };

neaf->...

Returns default Neaf instance ($MVC::Neaf::Inst), so that neaf->method_name is the equivalent of MVC::Neaf->method_name.

neaf shortcut => @options;

Shorter alias to methods described above. Currently supported:

route - route
error - set_error_handler
view - load_view
hook - add_hook
session - set_session_handler
default - set_path_defaults
alias - alias
static - static

Also, passing a 3-digit number will trigger set_error_handler, and passing a hook phase (see below) will result in setting a hook.

get '/path' => sub { ... }, ...

head '/path' => sub { ... }, ...

post '/path' => sub { ... }, ...

put '/path' => sub { ... }, ...

Set request method handler. c<get + post @args> is equivalent to get @args; post @args.

Other methods and combinations (e.g. PATCH) are available via

    neaf route '/path' => sub { ... }, method => [ 'PATCH', 'DELETE' ], ...;

DEVELOPMENT AND DEBUGGING METHODS

run_test( \%PSGI_ENV, %options )

run_test( "/path?param=value", %options )

Run a PSGI request and return a list of ($status, HTTP::Headers, $whole_content ).

Returns just the content in scalar context.

Just as the name suggests, useful for testing only (it reduces boilerplate).

Continuation responses are supported, but will be returned in one chunk.

%options may include:

method - set method (default is GET)
cookie = \%hash - force HTTP_COOKIE header
header = \%hash - override some headers This gets overridden by type, cookie etc. in case of conflict
body = 'DATA' - force body in request
type - content-type of body
uploads - a hash of MVC::Neaf::Upload objects.
secure = 0|1 - http vs https
override = \%hash - force certain data in ENV Gets overridden by all of the above.

get_routes

Returns a hash with ALL routes for inspection. This should NOT be used by application itself.

set_forced_view( $view )

If set, this view object will be user instead of ANY other view.

See load_view.

Returns self.

server_stat ( MVC::Neaf::X::ServerStat->new( ... ) )

Record server performance statistics during run.

The interface of ServerStat is as follows:

    my $stat = MVC::Neaf::X::ServerStat->new (
        write_threshold_count => 100,
        write_threshold_time  => 1,
        on_write => sub {
            my $array_of_arrays = shift;

            foreach (@$array_of_arrays) {
                # @$_ = (script_name, http_status,
                #       controller_duration, total_duration, start_time)
                # do something with this data
                warn "$_->[0] returned $_->[1] in $_->[3] sec\n";
            };
        },
    );

on_write will be executed as soon as either count data points are accumulated, or time is exceeded by difference between first and last request in batch.

Returns self.

INTERNAL API

CAVEAT EMPTOR.

The following methods are generally not to be used, unless you want something very strange.

new(%options)

Constructor. Usually, instantiating Neaf is not required. But it's possible.

Options are not checked whatsoever.

Just in case you're curious, $MVC::Neaf::Inst is the default instance that handles neaf ... requests.

handle_request( MVC::Neaf::Request->new )

This is the CORE of this module. Should not be called directly - use run() instead.

get_view( "name" )

Fetch view object by name.

Uses load_view ( name => name ) if needed.

This is for internal usage.

If set_forced_view was called, return its argument instead.

get_form( "name" )

Fetch form named "name". No magic here. See add_form.

MORE EXAMPLES

See the examples directory in this distro or at https://github.com/dallaylaen/perl-mvc-neaf/tree/master/example for complete working examples. These below are just code snippets.

All of them are supposed to start and end with:

    use strict;
    use warnings;
    use MVC::Neaf qw(:sugar);

    # ... snippet here

    neaf->run;

Static content

    neaf->static( '/images' => "/local/images" );
    neaf->static( '/favicon.ico' => "/local/images/icon_32x32.png" );

Form submission

    # You're still encouraged to use LIVR for more detailed validation
    my %profile = (
        name => [ required => '\w+' ],
        age  => '\d+',
    );
    neaf form my_form => \%profile;

    get+post '/submit' => sub {
        my $req = shift;

        my $form = $req->form( "my_form" );
        if ($req->is_post and $form->is_valid) {
            my $id = do_something( $form->data );
            $req->redirect( "/result/$id" );
        };

        return {
            -template   => 'form.tt',
            errors      => $form->error,
            fill_values => $form->raw,
        };
    };

Adding JSONP callbacks

    neaf pre_render => sub {
        my $req = shift;
        $req->reply->{-jsonp} = $req->param("callback" => '.*');
        # Even if you put no restriction here, no XSS comes through
        #    as JS View has its own default filter
    }, path => '/js/api';

More examples to follow as usage (hopefuly) accumulates.

THE NEAF PRINCIPLES

Data in, data out.

A function should receive an argument and return a value or die. Everything else should be confined within the function. This applies to both Neaf's own methods and the user code.

A notable exception is the session mechanism which is naturally stateful and thus hard to implement in functional style.
Sane defaults.

Everything can be configured, nothing needs to be. TT view needs work in this respect.
It's not software unless you can run it.

Don't rely on a specific server environment. Be ready to run as a standalone program or inside a test script.
Trust nobody.

Validate incoming data. This is not yet enforced for HTTP headers and body.
Unicode inside the perimeter.

This is not yet implemented (but planned) for body and file uploads which may well be binary data.

DEPRECATED METHODS

Some methods become obsolete during Neaf development. Anything that is considered deprecated will continue to be supported for at least three minor versions after official deprecation and a corresponding warning being added.

Please keep an eye on Changes though.

pre_route( sub { ... } )

Mangle request before serving it. E.g. canonize uri or read session cookie.

Return value from callback is ignored.

Dying in callback is treated the same way as in normal controller sub.

DEPRECATED. Use Neaf->add_hook( pre_route => ... ) instead.

error_template( ... )

DEPRECATED. Use set_error_handler or neaf \d\d\d = sub { ... }> instead.

set_default ( key => value, ... )

Set some default values that would be appended to data hash returned from any controller on successful operation. Controller return always overrides these values.

Returns self.

DEPRECATED. Use MVC::Neaf->set_path_defaults( '/', { ... } ); instead.

BUGS

This software is still in BETA stage.

Test coverage is maintained at >80% currently, but who knows what lurks in the other 20%.

See the TODO file in this distribution for a list of bugs and missing features.

Please report any bugs or feature requests to https://github.com/dallaylaen/perl-mvc-neaf/issues.

Alternatively, email them to bug-mvc-neaf at rt.cpan.org, or report through the web interface at http://rt.cpan.org/NoAuth/ReportBug.html?Queue=MVC-Neaf.

Feedback and/or critique are welcome.

SUPPORT

Feel free to email the author to get instant help! Or you can comment the announce at the Perlmonks forum.

You can find documentation for this module with the perldoc command.

    perldoc MVC::Neaf
    perldoc MVC::Neaf::Request

You can also look for information at:

Github: https://github.com/dallaylaen/perl-mvc-neaf
MetaCPAN: https://metacpan.org/pod/MVC::Neaf
RT: CPAN's request tracker (report bugs here)

http://rt.cpan.org/NoAuth/Bugs.html?Dist=MVC-Neaf
AnnoCPAN: Annotated CPAN documentation

http://annocpan.org/dist/MVC-Neaf
CPAN Ratings

http://cpanratings.perl.org/d/MVC-Neaf
Search CPAN

http://search.cpan.org/dist/MVC-Neaf/

ACKNOWLEDGEMENTS

Ideas were shamelessly stolen from Catalyst, Dancer, PSGI, and sinatra.rb.

The CGI.pm was used heavily in the beginning of development, though Neaf was PSGI-ready from the start.

Thanks to Eugene Ponizovsky for introducing me to the MVC concept.

Thanks to Alexander Kuklev for early feedback and great insights about pure functions and side effects.

Thanks to Akzhan Abdullin for driving me towards proper hooks model.

Thanks to Cono for early feedback and feature proposals.

Thanks to Alexey Kuznetsov for requesting multiple methods.

LICENSE AND COPYRIGHT

This program is free software; you can redistribute it and/or modify it under the terms of either: the GNU General Public License as published by the Free Software Foundation; or the Artistic License.

See http://dev.perl.org/licenses/ for more information.

To install MVC::Neaf, copy and paste the appropriate command in to your terminal.

cpanm

cpanm MVC::Neaf

CPAN shell

perl -MCPAN -e shell
install MVC::Neaf

For more information on module installation, please visit the detailed CPAN module installation guide.

	Global
`s`	Focus search bar
`?`	Bring up this help dialog

	GitHub
`g` `p`	Go to pull requests
`g` `i`	go to github issues (only if github is preferred repository)

	POD
`g` `a`	Go to author
`g` `c`	Go to changes
`g` `i`	Go to issues
`g` `d`	Go to dist
`g` `r`	Go to repository/SCM
`g` `s`	Go to source
`g` `b`	Go to file browse

	Search terms
module: (e.g. module:Plugin)
distribution: (e.g. distribution:Dancer auth)
author: (e.g. author:SONGMU Redis)
version: (e.g. version:1.00)

NAME

OVERVIEW

SYNOPSIS

CREATING AN APPLICATION

THE CONTROLLER

THE REQUEST

THE RESPONSE

MAIN API

get '/path' => sub { ... }, %options

post '/path' => sub { ... }, %options

get+post '/path' => sub { ... }, %options

neaf route => '/path' => sub { ... }, %options

$neaf->route( '/path' => CODEREF, %options )

neaf static => '/path' => ...

static( $req_path => $file_path, %options )

neaf default => '/path' => \%values

set_path_defaults ( '/path' => \%values )

neaf "phase" => sub { ... }, path => [ ... ], exclude => [ ... ]

add_hook ( phase => CODEREF, %options )

neaf alias $newpath => $oldpath

alias( $newpath => $oldpath )

neaf view => 'name' => 'Driver::Class' => %options;

load_view( $name, $object || coderef || ($module_name, %options) )

neaf session => $engine => %options

set_session_handler( %options )

neaf form => name => $validator

neaf form => name => \%spec, engine => ...

add_form( name => $validator )

neaf 403 => sub { ... }

set_error_handler ( status => CODEREF( $req, %options ) )

set_error_handler ( status => \%hash )

on_error( sub { my ($req, $err) = @_ } )

neaf->run()

run()

REQUEST PROCESSING PHASES AND HOOKS

pre_route

pre_logic

pre_content

pre_render

pre_reply

pre_cleanup

EXPORTED FUNCTIONS

neaf_err $error

neaf->...

neaf shortcut => @options;

get '/path' => sub { ... }, ...

head '/path' => sub { ... }, ...

post '/path' => sub { ... }, ...

put '/path' => sub { ... }, ...

DEVELOPMENT AND DEBUGGING METHODS

run_test( \%PSGI_ENV, %options )

run_test( "/path?param=value", %options )

get_routes

set_forced_view( $view )

server_stat ( MVC::Neaf::X::ServerStat->new( ... ) )

INTERNAL API

new(%options)

handle_request( MVC::Neaf::Request->new )

get_view( "name" )

get_form( "name" )

MORE EXAMPLES

Static content

Form submission

Adding JSONP callbacks

THE NEAF PRINCIPLES

DEPRECATED METHODS

pre_route( sub { ... } )

error_template( ... )

set_default ( key => value, ... )

BUGS

SUPPORT

SEE ALSO

ACKNOWLEDGEMENTS

LICENSE AND COPYRIGHT

Module Install Instructions