-- Hoogle documentation, generated by Haddock
-- See Hoogle, http://www.haskell.org/hoogle/


-- | Support for static URL routing with overlap detection for Happstack.
--   
--   If you have a large routing table in Happstack and want to insert a
--   new handler, you might run into overlap problems (ambiguity). The new
--   handler might not fire because it matches against a URL that is
--   already handled earlier. Or if you put your new handler first, it
--   might steal requests from existing handlers. This Happstack support
--   library allows you to detect overlap cases and build unambiguous
--   routing tables where the order of the handlers is irrelevant.
@package happstack-static-routing
@version 0.3.2


-- | Support for static routing tables in Happstack. The routing tables are
--   order independent as long as:
--   
--   <ul>
--   <li>if any two handlers overlap, one of them handles a more specific
--   path than the other. The more specific handler is then tried
--   first.</li>
--   </ul>
--   
--   Routing tables are constructed from <a>dir</a>, <a>path</a>,
--   <a>remainingPath</a>, <a>choice</a>, and (for now) <a>param</a>.
--   
--   A routing table is compiled by using <a>compile</a>. The result is an
--   overlap report, and a prefix tree that is used to efficiently dispatch
--   requests by means of <a>dispatch</a>.
--   
--   See the file <tt>src/Happstack/StaticRouting/Test.hs</tt> in the
--   distribution for examples.
module Happstack.StaticRouting

-- | Static routing tables consisting of handlers of type <tt>a</tt>.
data Route a

-- | Compile routes, also return possible overlap report. If the overlap
--   report is <a>Nothing</a>, the routing table is order independent. If
--   the overlap report is <tt>Just s</tt>, then <tt>s</tt> is a textual
--   representation of all the paths that are order dependent, suitable for
--   a warning message.
compile :: (MonadIO m, HasRqData m, ServerMonad m, MonadPlus m) => Route (m a) -> (m a, Maybe String)

-- | Combine several route alternatives into one.
choice :: [Route a] -> Route a

-- | Pop a path element if it matches the given string.
dir :: String -> Route a -> Route a

-- | Expect the given method, and exactly <tt>n</tt> more segments, where
--   <tt>n</tt> is the arity of the handler.
path :: Path m hm h r => Method -> (m r -> hm r') -> h -> Route (hm r')

-- | Support for varying number of arguments to <a>path</a> handlers.
class Path m hm h r | h r -> m

-- | Expect zero or more segments.
remainingPath :: Method -> h -> Route h

-- | DEPRECATED. Expect a specific parameter to be present.
param :: String -> Route a -> Route a