NAME
    Wurm - Simple. Easy. Crawls in your teeth. Web framework. Did I mention
    it was a web framework? Another one.

SYNOPSIS
      use Wurm;
      use Data::Dumper;

      # Wurm applications are defined by a structure of anonymous
      # sub-routines that get called based on the incoming request
      # and where they live within the application tree.

      # When a request is received it is first packaged into a
      # C<$meal> which is then dispatched to a series of handlers.
      # Handlers are expected to inspect, filter, and otherwise
      # act on the request until a PSGI response is generated.
      # Once a response is generated, dispatching halts and the
      # response is returned back up the Plack chain.
      # This process is called "folding".

      # The internet really can be a series of tubes.
      sub build_tube {
        my ($name) = @_;

        # Here we create a basic component skeleton which we will use
        # to build our application.  We use closures to capture
        # $name but sub-routines can also simply be copied throughout
        # the dispatch tree to duplicate behavior without creating
        # new sub-routines, modules, classes, or objects.

        return ({
          # Gate handlers are always called first when folding.
          # They are primarily meant for inspection, filtering,
          # and resource setup.

          # They will be called as Wurm traverses the URL path from
          # the request.  Wurm maintains C<PATH_INFO> information in
          # C<$meal->{tube}>.  As a request is dispatched, non-C<'/'>
          # atoms and a trailing C<'/'> are removed and concatenated
          # to C<$meal->{seen}>.  You can check C<$meal->{tube} eq ''>
          # to see if this component will be targeted for further dispatch.
          gate => sub {
            my $meal = shift;
            $meal->{log}->({level => 'debug',
              message => "$name ))) $meal->{tube}"});
            $meal->{vent}{to} = ucfirst $name
              if $meal->{tube} eq '';
            push @{$meal->{grit}{path}}, $name. '/gate';
            return;
          },

          # What is not seen here are Tube handlers.  Tube handlers are
          # what define the path ways within your application for dispatching
          # down C<PATH_INFO>.  Since this is just a skeleton, we will tie the
          # application together with tube handlers later.

          # Neck handlers are called when C<$meal->{tube} eq ''>.
          # Unless more advanced dispatching is performed at run-time,
          # this starts the final dispatch chain.
          neck => sub {
            my $meal = shift;
            push @{$meal->{grit}{path}}, $name. '/neck';
            return;
          },

          # Body handlers are used to dispatch based on the request method.
          # Unlike gate, neck, and tail handlers these require a slightly
          # more complex structure.  You must provide a C<HASH> that
          # contains handlers keyed off of the lower cased request method
          # you would like that code to process.
          body => {
            get => sub {
              my $meal = shift;
              push @{$meal->{grit}{path}}, $name. '/body:get';
              return;
            },
          },

          # Tail handlers are the final possible step in a dispatch chain
          # before a C<404> is generated.  While you can easily return a
          # response from a body handler, tail handlers give you the option
          # of tying multiple body response handling paths into a single spot.
          tail => sub {
            my $meal = shift;
            push @{$meal->{grit}{path}}, $name. '/tail';
            return wrap_it_up($meal);
          },
        })
      };

      # Look ma... modularity.
      # More advanced applications might have a template engine or other
      # data transformers contained in C<$meal->{mind}>.  C<$meal->{grit}>
      # and C<$meal->{vent}> data areas are for your application to use
      # as needed on a per-request basis.
      sub wrap_it_up {
        my $meal = shift;

        my $path = join ', ', @{$meal->{grit}{path}};

        my $text = '';
        $text .= "$meal->{mind}{intro} $meal->{vent}{to},\n";
        $text .= "This is the path I took: $path\n";
        $text .= "This is what is in the tube: $meal->{tube}\n";
        $text .= "This is what I've seen: $meal->{seen}\n";

        # Wurm provides some easy response handlers.
        # They are probably too simple to be useful.
        # Good luck.
        return Wurm::_200('text/plain', $text);
      }


      # Now let's build the app!


      # This is the root "controller".
      my $wurm = build_tube('root');

      # The case routine can be defined to munge the request meal.
      # It is only called once at request entry.
      $wurm->{case} = sub {
        my $meal = shift;
        $meal->{vent}{to}   = 'Nobody';
        $meal->{grit}{path} = [ ];
        return $meal;
      };

      # The pore routine can be defined to munge the response.
      # It is only ever called once at request exit.
      $wurm->{pore} = sub {
        my ($res, $meal) = @_;
        $res->[2][0] = $res->[2][0]
          . ($res->[0] == 200 ? '' : "\n")
          . 'PSGI env: '. Dumper($meal->{env})
        ;
        return $res;
      };


      # Tinker-tubes!

      # Tubes are sub-tree structures that Wurm will re-dispatch to
      # during a request based on elements in the URL path.  They
      # have the exact same structure as described above with the
      # exception that C<case()> and C<pore()> handlers are ignored.

      # When a request begins, the HTTP C<PATH_INFO> information is
      # copied to C<$meal->{tube}> with a leading C<'/'> removed.
      # Wurm will remove a non-C<'/'> atom and trailing C<'/'> from
      # C<$meal->{tube}> during each dispatch cycle and will
      # re-dispatch the request to the folding tree defined under
      # that atom.  If no folding tree is found for a particular atom,
      # a C<404> is returned.

      # This builds a path route for 'wurm/' and 'wurm'.
      $wurm->{tube}{wurm} = build_tube('wurm');

      # This builds more path routes ('wurm/{foo,bar,baz,qux}/').
      $wurm->{tube}{wurm}{tube}{$_} = build_tube($_)
        for qw(foo bar baz qux);

      # Now we have 'foo/' and 'baz/'.
      $wurm->{tube}{$_} = $wurm->{tube}{wurm}{tube}{$_}
        for qw(foo baz);

      # qux is special.
      # It has a gate handler that will always return a 200.
      # This will act like a catch all for 'wurm/qux/*'.
      $wurm->{tube}{wurm}{tube}{qux}{gate} = sub {
        my $meal = shift;
        $meal->{vent}{to} = 'Lord Qux';
        push @{$meal->{grit}{path}}, '*/gate';
        return wrap_it_up($meal);
      };

      # Now turn the closure nightmare into a PSGI application.
      # The second argument to wrapp() is the C<$meal->{mind}>.
      # You can use it to store application-wide state like
      # configuration or other global resources.
      my $app = Wurm::wrapp($wurm, {intro => 'Hello'});
      $app

DESCRIPTION
    Wurm implements a fold-r Plack web application container. It is meant
    for quickly building PSGI-based applications using a multiple dispatch
    pattern that is driven by anonymous sub-routines. Requests are passed
    down a set of handlers based on "PATH_INFO" and "REQUEST_METHOD". The
    dispatch chain is canceled as soon as a response is generated.

    Applications are defined by a data structure that provides callback
    handlers. Request handlers are called with a context object known as a
    "meal" that contains request and application state. Handlers are
    expected to either return "undef" if dispatching should continue or a
    PSGI response.

MEALS
    Life feeds on life.

    When requests to your application are dispatched, they are first encased
    as a "meal". The "meal" is a simple "HASH" reference with request and
    application state. It can be upgraded with fancier OO-related features
    when using Wurm::mob. See the relevant documentation there for more. In
    its simplest form, it will contain the following:

      {
        env  => $env,
        log  => $log,
        tube => $env->{PATH_INFO},
        seen => '',
        mind => $mind,
        grit => { },
        vent => { },
      }

    * env

      "env" is the PSGI $env as received.

    * log

      "log" is the PSGI logger in "$env->{'psgix.logger'}". If one is not
      present, a stub routine is put in place. This allows you to call
      "$meal->{log}->({...})" without checking for a logger first.

    * tube

      "tube" is the current series of tubes to traverse. As the request is
      dispatched, non-'/' atoms are removed with the trailing slash. The
      default is set to the "PATH_INFO" in the request with the leading '/'
      removed.

    * seen

      "seen" is the opposite of "tube". As atoms are removed from "tube",
      they are concatenated back onto "seen". The combination of these
      should give you an idea of where the request is going and where it has
      been.

    * mind

      "mind" is an application-specific data structure that is passed to
      every request. The value is set when calling "wrapp()" to generate a
      PSGI application. This is typically where things like configuration or
      handles to application-wide resources should be kept.

    * grit

      "grit" is a per-request data area that is used for maintaining state.
      It is meant to be a "clean" area for building up data that may be
      passed to a template engine or data models.

    * vent

      "vent" is a per-request data area that is used for maintaining state.
      It differs from "grit" in that it is meant to house per-request data
      that is typically thrown away at the end of a request. This might
      include things like formatting flags or temporary information that
      should never be applied to a template or data model.

DISPATCHING
    A fully dispatched request flows as follows:

      case ->
  
        gate -> tube -> neck -> body -> tail -> 404
        ^       +-> 404
        +------ +

      -> pore

    The entry point for a request ("case") converts a PSGI request into a
    "meal". The "meal" is then passed as a single parameter to callback
    handlers that may be defined for the named stages above. Each stage
    represents a different type of routing logic or step within the dispatch
    chain.

    Applications may define their own "case" callback which will be called
    after the default one. This allows per-request inspection and filtering
    before any dispatching. It is required that it return a "meal".

      sub case {
        my $meal = shift;
        # fix stuff in $meal here
        return $meal;
      }

      ...

      Wurm::wrap({case => \&case, ...});

    After a request has been cased, it is dispatched according to the
    folding logic embedded in the application structure. If "undef" is
    returned from a handler, dispatching continues. Anything else is treated
    as a PSGI response that will be passed back up the Plack call chain.

    All callback handlers have the same signature which is:

      sub callback {
        my $meal = shift;
        return
          if $dispatching_should_continue;
        return $locally_defined_PSGI_response;
      }

    The following callback handlers may be defined for an application:

    gate
      Gate handlers are always called when present in the dispatch chain.
      This will include handlers for which the "PATH_INFO" may not apply
      directly since these will be called as the path is traversed. If
      "$meal->{tube}" is '', this is the last gate that will be called.

        Wurm::wrapp({..., gate => \&handler, ...});

    tube
      Tube handlers are called when there are tubes to navigate. If
      "$meal->{tube}" is not '', it will be stripped of a leading non-'/'
      atom which will be used as a key for further delegation. If a dispatch
      structure exists for the path element, the request will be
      re-dispatched using this new structure thereby providing path folding.
      If no structure exists, a 404 is generated.

        Wurm::wrapp({...,
          tube => {
            funky  => {gate => sub { }, ...},
            mondo  => {..., body => {get => sub { }}, ...},
            gnarly => {..., tail => sub { }},
          }
        ...});

    neck
      Neck handlers are run in between path matching and request method
      delegation. While multiple gate handlers can be called, only one neck
      handler should be called for any given request chain. It can be used
      for filtering or setting up requests prior to dispatching the request
      to body handlers.

        Wurm::wrapp({..., neck => \&handler, ...});

    body
      Body handlers represent "REQUEST_METHOD" dispatching. The lower-cased
      value of the current request's method is used to choose which handler
      is used for delegatation. No restriction is made on the name so even
      esoteric methods like "OPTIONS" and "CONNECT" can be defined.

        Wurm::wrapp({...,
          body => {
            get  => \&handler,
            lost => \&handler,
            head => \&handler,
            post => \&handler,
            man  => \&handler,
          }
        ...});

    tail
      Tail handlers are the last possible handler to be called in any
      dispatch chain. They can be used to bundle the response packaging
      logic of a busy chain into a single place. If a tail handler does not
      generate a response, a 404 response is returned.

        Wurm::wrapp({..., tail => \&handler, ...});

    The exit point ("pore") is responsible for the final packaging of a
    proper PSGI response that is then passed back up the Plack call chain.
    The default will check for blessed response objects and call
    "finalize()" on them for you. Applications may define their own which
    will be called prior to the default:

      sub pore {
        my ($cast, $meal) = @_;
        # $cast is the PSGI response generated by the dispatch
        # $meal is what generated $cast and is probably filthy
        return $cast;
      }

      ...

      Wurm::wrapp({..., pore => \&pore});

FUNCTIONS
    Wurm::wrapp($wurm, $mind)
      Converts a set of folding rules into a PSGI application. The $wurm
      parameter must be a "HASH" reference which can be configured according
      to the dispatch principles outlined above. If $mind is provided, it
      will be attached to each incoming request as "$meal->{mind}".

    Wurm::fold($meal, $wurm)
      Dispatches a "meal" according to a set of folding rules. This is what
      performs all the work and is not meant to be called directly. Unless
      of course you need that much power. Use it wisely.

    Wurm::bend($meal)
      Removes a non-'/' atom and '/' from "$meal->{tube}". If no atom is
      available, "undef" is returned. Otherwise the atom and a '/' are
      concatenated to "$meal->{seen}" and the atom is returned.

    Wurm::_200($content_type, $content)
      Very simplistic status code 200 generator. Sets the 'Content-Type'
      header and body content to the values provided and not much else.

    Wurm::_201($location)
      Generates a 201 redirect response with the location header set to the
      given value.

    Wurm::_204()
      Generates an empty 204 (No Content) response.

    Wurm::_301($location)
      Generates a 301 redirect response with the location header set to the
      given value.

    Wurm::_302($location)
      Generates a 302 redirect response with the location header set to the
      given value.

    Wurm::_400()
      Generates an empty 400 (Bad Request) response.

    Wurm::_404()
      Generates an empty 404 (Not Found) response.

    Wurm::_500()
      Generates an empty 500 (Internal Server Error) response.

SEE ALSO
    Wurm::mob
    Wurm::let
    Wurm::Grub::REST

DISCLAIMER
    This software is known to The State of California to be experimental.

AUTHOR
    jason hord <pravus@cpan.org>

LICENSE
    This software is information. It is subject only to local laws of
    physics.