Add order to route patterns

Changes

@@ -3,6 +3,7 @@ Revision history for Kelp
 {{$NEXT}}
             [New Interface]
             - Added after_unrendered hook to Kelp
+            - Added order key to routes
 
             [Changes]
             - Hooks are now run conditionally on controller objects and fall back to main app object

lib/Kelp/Manual.pod

@@ -402,6 +402,19 @@ route in line to be processed.
 
 See L<Kelp::Routes/BRIDGES> for more information.
 
+=head3 Route order
+
+Routes will be executed in order that will usually be the one you want. Bridges
+will execute before normal routes, and the routes will be sorted by patterns
+using Perl C<cmp>. However, you can sometimes run into trouble with their ordering.
+
+In that case, you can use special key C<order> to sort it out. All routes have
+default C<order> of C<0>. If you want some of them to execute earlier, reduce
+their order value. Late routes can be marked with positive order.
+
+Of course, even if you specify order, bridges will still always come before
+regular routes.
+
 =head3 URL building
 
 Each path can be given a name and later a URL can be built using that name and

lib/Kelp/Routes.pm

@@ -296,7 +296,7 @@ sub match
         # chain. If the patterns are not the same, their order will be changed
         # by string sorting by patterns.
         @$routes =
-            sort { $b->bridge <=> $a->bridge || $a->pattern cmp $b->pattern }
+            sort { $a->compare($b) }
             grep { $_->match($path, $method) } @{$self->routes};
 
         $self->cache->set($key, $routes);

lib/Kelp/Routes/Pattern.pm

@@ -12,6 +12,7 @@ attr name => sub { $_[0]->pattern };
 attr check => sub { {} };
 attr defaults => sub { {} };
 attr bridge => 0;
+attr order => 0;
 attr regex => sub { $_[0]->_build_regex };
 attr named => sub { {} };
 attr param => sub { [] };
@@ -226,6 +227,15 @@ sub match
     return 1;
 }
 
+sub compare
+{
+    my ($self, $other) = @_;
+
+    return $other->bridge <=> $self->bridge
+        || $self->order <=> $other->order
+        || $self->pattern cmp $other->pattern;
+}
+
 1;
 
 __END__
@@ -331,6 +341,11 @@ of them, it will be used in case the placeholder value is missing.
 A True/False value. Specifies if the route is a bridge. For more information
 about bridges, please see L<Kelp::Routes/BRIDGES>
 
+=head2 order
+
+A numeric order of this route. Default order is C<0>, so if you want some
+routes to take priority, you can use C<-1>. Lower is earlier.
+
 =head2 regex
 
 We recommend that you stick to using patterns, because they are simpler and
@@ -403,6 +418,12 @@ should be built like this:
 If the pattern contains more than one unnamed items, then you should
 probably give them some names.
 
+=head2 compare
+
+C<$compare( $other )>
+
+Compares two routes. Used for sorting matched routes in a router.
+
 =head1 ACKNOWLEDGEMENTS
 
 This module was inspired by L<Routes::Tiny>.

t/routes_match.t

@@ -46,13 +46,13 @@ my $r = Kelp::Routes->new;
 # Similar routes with checks
 {
     $r->clear;
-    $r->add('/:a/:b' => 'a#b');
+    $r->add('/:a/:b' => {to => 'a#b', order => 10});
     $r->add('/:a/:b' => {to => 'a#c', check => {b => '\d+'}});
-    $r->add('/:a/:b' => {to => 'a#d', check => {a => '\d+'}});
+    $r->add('/:a/:b' => {to => 'a#d', check => {a => '\d+'}, order => -1});
     is_deeply _d($r->match('/aa/bb'), 'to'), [{to => 'A::b'}];
-    is_deeply _d($r->match('/aa/22'), 'to'), [{to => 'A::b'}, {to => 'A::c'}];
-    is_deeply _d($r->match('/11/bb'), 'to'), [{to => 'A::b'}, {to => 'A::d'}];
-    is_deeply _d($r->match('/11/22'), 'to'), [{to => 'A::b'}, {to => 'A::c'}, {to => 'A::d'}];
+    is_deeply _d($r->match('/aa/22'), 'to'), [{to => 'A::c'}, {to => 'A::b'}];
+    is_deeply _d($r->match('/11/bb'), 'to'), [{to => 'A::d'}, {to => 'A::b'}];
+    is_deeply _d($r->match('/11/22'), 'to'), [{to => 'A::d'}, {to => 'A::c'}, {to => 'A::b'}];
 }
 
 # Different routes (same beginning)