documentation tweaks

mojolicious · May 11, 2013 · c14ed25 · c14ed25
1 parent 037f2eb
commit c14ed25
Show file tree

Hide file tree

Showing 2 changed files with 48 additions and 56 deletions.
diff --git a/lib/Mojolicious/Routes/Match.pm b/lib/Mojolicious/Routes/Match.pm
@@ -8,35 +8,7 @@ sub match { $_[0]->_match($_[0]->root, $_[1], $_[2]) }
 
 sub path_for {
   my $self = shift;
-
-  # Single argument
-  my (%values, $name);
-  if (@_ == 1) {
-
-    # Hash
-    %values = %{shift()} if ref $_[0] eq 'HASH';
-
-    # Name
-    $name = $_[0] if $_[0];
-  }
-
-  # Multiple arguments
-  elsif (@_ > 1) {
-
-    # Odd
-    if (@_ % 2) { ($name, %values) = (shift, @_) }
-
-    # Even
-    else {
-
-      # Name and hash
-      if (ref $_[1] eq 'HASH') { ($name, %values) = (shift, %{shift()}) }
-
-      # Just values
-      else { %values = @_ }
-
-    }
-  }
+  my ($name, %values) = _values(@_);
 
   # Current route
   my $endpoint;
@@ -57,7 +29,6 @@ sub path_for {
     : $pattern->defaults->{format}
     if $pattern->constraints->{format};
 
-  # Render
   my $path = $endpoint->render('', \%values);
   return wantarray ? ($path, $endpoint->has_websocket) : $path;
 }
@@ -66,17 +37,15 @@ sub _match {
   my ($self, $r, $c, $options) = @_;
 
   # Pattern
-  my $path    = $options->{path};
-  my $pattern = $r->pattern;
+  my $path = $options->{path};
   return
-    unless my $captures = $pattern->match_partial(\$path, $r->is_endpoint);
+    unless my $captures = $r->pattern->match_partial(\$path, $r->is_endpoint);
   local $options->{path} = $path;
   $captures = $self->{captures} = {%{$self->{captures} || {}}, %$captures};
 
   # Method
-  if (my $methods = $r->via) {
-    return unless grep { $_ eq $options->{method} } @$methods;
-  }
+  my $methods = $r->via;
+  return if $methods && !grep { $_ eq $options->{method} } @$methods;
 
   # Conditions
   if (my $over = $r->over) {
@@ -98,12 +67,12 @@ sub _match {
     $empty = 1;
   }
 
-  # Endpoint
+  # Endpoint (or bridge)
   my $endpoint = $r->is_endpoint;
-  if ($r->inline || ($endpoint && $empty)) {
+  if (($endpoint && $empty) || $r->inline) {
     push @{$self->stack}, {%$captures};
-    delete $captures->{$_} for qw(app cb);
     return $self->endpoint($r) if $endpoint && $empty;
+    delete $captures->{$_} for qw(app cb);
   }
 
   # Match children
@@ -120,6 +89,28 @@ sub _match {
   }
 }
 
+sub _values {
+
+  # Single argument
+  if (@_ == 1) {
+
+    # Hash
+    return undef, %{shift()} if ref $_[0] eq 'HASH';
+
+    # Name
+    return $_[0];
+  }
+
+  # Name and values
+  return shift, @_ if @_ % 2;
+
+  # Name and hash
+  return shift, %{shift()} if ref $_[1] eq 'HASH';
+
+  # Just values
+  return undef, @_;
+}
+
 1;
 
 =head1 NAME
@@ -158,7 +149,7 @@ L<Mojolicious::Routes::Match> implements the following attributes.
   my $endpoint = $match->endpoint;
   $match       = $match->endpoint(Mojolicious::Routes::Route->new);
 
-The route endpoint that actually matched.
+The route endpoint that matched.
 
 =head2 root
 
@@ -183,7 +174,7 @@ implements the following new ones.
 
   $match->match(Mojolicious::Controller->new, {method => 'GET', path => '/'});
 
-Match against C<root>.
+Match controller and options against C<root> to find appropriate C<endpoint>.
 
 =head2 path_for
 

diff --git a/lib/Mojolicious/Routes/Pattern.pm b/lib/Mojolicious/Routes/Pattern.pm
@@ -14,8 +14,8 @@ sub new { shift->SUPER::new->parse(@_) }
 
 sub match {
   my ($self, $path, $detect) = @_;
-  my $result = $self->match_partial(\$path, $detect);
-  return !$path || $path eq '/' ? $result : undef;
+  my $captures = $self->match_partial(\$path, $detect);
+  return !$path || $path eq '/' ? $captures : undef;
 }
 
 sub match_partial {
@@ -31,20 +31,20 @@ sub match_partial {
   $$pathref =~ s/$regex//;
 
   # Merge captures
-  my $result = {%{$self->defaults}};
+  my $captures = {%{$self->defaults}};
   for my $placeholder (@{$self->placeholders}) {
     last unless @captures;
     my $capture = shift @captures;
-    $result->{$placeholder} = $capture if defined $capture;
+    $captures->{$placeholder} = $capture if defined $capture;
   }
 
   # Format
   my $constraint = $self->constraints->{format};
-  return $result if !$detect || defined $constraint && !$constraint;
-  if ($$pathref =~ s!^/?$format!!) { $result->{format} = $1 }
-  elsif ($constraint) { return undef unless $result->{format} }
+  return $captures if !$detect || defined $constraint && !$constraint;
+  if ($$pathref =~ s!^/?$format!!) { $captures->{format} = $1 }
+  elsif ($constraint) { return undef unless $captures->{format} }
 
-  return $result;
+  return $captures;
 }
 
 sub parse {
@@ -257,8 +257,8 @@ Mojolicious::Routes::Pattern - Routes pattern engine
   my $pattern = Mojolicious::Routes::Pattern->new('/test/:name');
 
   # Match routes
-  my $result  = $pattern->match('/test/sebastian');
-  say $result->{name};
+  my $captures = $pattern->match('/test/sebastian');
+  say $captures->{name};
 
 =head1 DESCRIPTION
 
@@ -343,7 +343,8 @@ Character indicating a relaxed placeholder, defaults to C<#>.
   my $tree = $pattern->tree;
   $pattern = $pattern->tree([['slash'], ['text', 'foo']]);
 
-Pattern in parsed form.
+Pattern in parsed form. Note that this structure should only be used very
+carefully since it is very dynamic.
 
 =head2 wildcard_start
 
@@ -369,15 +370,15 @@ necessary.
 
 =head2 match
 
-  my $result = $pattern->match('/foo/bar');
-  my $result = $pattern->match('/foo/bar', 1);
+  my $captures = $pattern->match('/foo/bar');
+  my $captures = $pattern->match('/foo/bar', 1);
 
 Match pattern against entire path, format detection is disabled by default.
 
 =head2 match_partial
 
-  my $result = $pattern->match_partial(\$path);
-  my $result = $pattern->match_partial(\$path, 1);
+  my $captures = $pattern->match_partial(\$path);
+  my $captures = $pattern->match_partial(\$path, 1);
 
 Match pattern against path and remove matching parts, format detection is
 disabled by default.