-- 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.7.0.1


-- | 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 <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 or return overlap report. Returns 'Left e' in case of
--   order-dependent overlap between handlers, where <tt>e</tt> describes
--   the overlap. Returns 'Right h', where h is a compiled handler that
--   returns <a>Nothing</a> in case no matching handler was found,
--   otherwise 'Just response'.
compile :: ServerMonad m => Route (m r) -> Either String (m (Maybe r))

-- | 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

-- | Pop a path element, and store it to use with handler
param :: 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 :: forall m hm h r r'. 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 -> m r

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