+doc add more detailed PathDirectives documentation

akka-docs-dev/rst/java/http/routing-dsl/directives/index.rst

@@ -46,7 +46,7 @@ MethodDirectives
 MiscDirectives
   Contains directives that validate a request by user-defined logic.
 
-PathDirectives
+:ref:`PathDirectives-java`
   Contains directives to match and filter on the URI path of the incoming request.
 
 RangeDirectives
@@ -58,4 +58,9 @@ SchemeDirectives
 WebsocketDirectives
   Contains directives to support answering Websocket requests.
 
+.. toctree::
+  :maxdepth: 1
+
+  path-directives
+
 .. _`RFC 7234`: http://tools.ietf.org/html/rfc7234

akka-docs-dev/rst/java/http/routing-dsl/directives/path-directives.rst

@@ -0,0 +1,95 @@
+.. _PathDirectives-java:
+
+PathDirectives
+==============
+
+Path directives are the most basic building blocks for routing requests depending on the URI path.
+
+When a request (or rather the respective ``RequestContext`` instance) enters the route structure it has an
+"unmatched path" that is identical to the ``request.uri.path``. As it descends the routing tree and passes through one
+or more ``pathPrefix`` or ``path`` directives the "unmatched path" progressively gets "eaten into" from the
+left until, in most cases, it eventually has been consumed completely.
+
+The two main directives are ``path`` and ``pathPrefix``. The ``path`` directive tries to match the complete remaining
+unmatched path against the specified "path matchers", the ``pathPrefix`` directive only matches a prefix and passes the
+remaining unmatched path to nested directives. Both directives automatically match a slash from the beginning, so
+that matching slashes in a hierarchy of nested ``pathPrefix`` and ``path`` directives is usually not needed.
+
+Path directives take a variable amount of arguments. Each argument must be a ``PathMatcher`` or a string (which is
+automatically converted to a path matcher using ``PathMatchers.segment``). In the case of ``path`` and ``pathPrefix``,
+if multiple arguments are supplied, a slash is assumed between any of the supplied path matchers. The ``rawPathX``
+variants of those directives on the other side do no such preprocessing, so that slashes must be matched manually.
+
+Path Matchers
+-------------
+
+A path matcher is a description of a part of a path to match. The simplest path matcher is ``PathMatcher.segment`` which
+matches exactly one path segment against the supplied constant string.
+
+Other path matchers defined in ``PathMatchers`` match the end of the path (``PathMatchers.END``), a single slash
+(``PathMatchers.SLASH``), or nothing at all (``PathMatchers.NEUTRAL``).
+
+Many path matchers are hybrids that can both match (by using them with one of the PathDirectives) and extract values,
+i.e. they are :ref:`request-vals-java`. Extracting a path matcher value (i.e. using it with ``handleWithX``) is only
+allowed if it nested inside a path directive that uses that path matcher and so specifies at which position the value
+should be extracted from the path.
+
+Predefined path matchers allow extraction of various types of values:
+
+``PathMatchers.segment(String)``
+  Strings simply match themselves and extract no value.
+  Note that strings are interpreted as the decoded representation of the path, so if they include a '/' character
+  this character will match "%2F" in the encoded raw URI!
+
+``PathMatchers.regex``
+  You can use a regular expression instance as a path matcher, which matches whatever the regex matches and extracts
+  one ``String`` value. A ``PathMatcher`` created from a regular expression extracts either the complete match (if the
+  regex doesn't contain a capture group) or the capture group (if the regex contains exactly one capture group).
+  If the regex contains more than one capture group an ``IllegalArgumentException`` will be thrown.
+
+``PathMatchers.SLASH``
+  Matches exactly one path-separating slash (``/``) character.
+
+``PathMatchers.END``
+  Matches the very end of the path, similar to ``$`` in regular expressions.
+
+``PathMatchers.Segment``
+  Matches if the unmatched path starts with a path segment (i.e. not a slash).
+  If so the path segment is extracted as a ``String`` instance.
+
+``PathMatchers.Rest``
+  Matches and extracts the complete remaining unmatched part of the request's URI path as an (encoded!) String.
+  If you need access to the remaining *decoded* elements of the path use ``RestPath`` instead.
+
+``PathMatchers.intValue``
+  Efficiently matches a number of decimal digits (unsigned) and extracts their (non-negative) ``Int`` value. The matcher
+  will not match zero digits or a sequence of digits that would represent an ``Int`` value larger than ``Integer.MAX_VALUE``.
+
+``PathMatchers.longValue``
+  Efficiently matches a number of decimal digits (unsigned) and extracts their (non-negative) ``Long`` value. The matcher
+  will not match zero digits or a sequence of digits that would represent an ``Long`` value larger than ``Long.MAX_VALUE``.
+
+``PathMatchers.hexIntValue``
+  Efficiently matches a number of hex digits and extracts their (non-negative) ``Int`` value. The matcher will not match
+  zero digits or a sequence of digits that would represent an ``Int`` value larger than ``Integer.MAX_VALUE``.
+
+``PathMatchers.hexLongValue``
+  Efficiently matches a number of hex digits and extracts their (non-negative) ``Long`` value. The matcher will not
+  match zero digits or a sequence of digits that would represent an ``Long`` value larger than ``Long.MAX_VALUE``.
+
+``PathMatchers.uuid``
+  Matches and extracts a ``java.util.UUID`` instance.
+
+``PathMatchers.NEUTRAL``
+  A matcher that always matches, doesn't consume anything and extracts nothing.
+  Serves mainly as a neutral element in ``PathMatcher`` composition.
+
+``PathMatchers.segments``
+  Matches all remaining segments as a list of strings. Note that this can also be "no segments" resulting in the empty
+  list. If the path has a trailing slash this slash will *not* be matched, i.e. remain unmatched and to be consumed by
+  potentially nested directives.
+
+Here's a collection of path matching examples:
+
+.. includecode:: ../../../code/docs/http/javadsl/PathDirectiveExampleTest.java
+  :include: path-examples