X-Git-Url: http://git.cielonegro.org/gitweb.cgi?a=blobdiff_plain;f=Network%2FHTTP%2FLucu%2FAbortion.hs;h=0a42d71353b552bdbff1fc7231f0f0d39f87756b;hb=a827a5e1ba744d89c5b2396bb195e344ae892306;hp=6f09f534429afc9a0f0428d228161e50c1b05744;hpb=40c0d61e88920807a91b8f3c4419b08032988d76;p=Lucu.git

diff --git a/Network/HTTP/Lucu/Abortion.hs b/Network/HTTP/Lucu/Abortion.hs
index 6f09f53..0a42d71 100644
--- a/Network/HTTP/Lucu/Abortion.hs
+++ b/Network/HTTP/Lucu/Abortion.hs
@@ -1,9 +1,13 @@
+-- #prune
+
+-- | Aborting the computation of 'Network.HTTP.Lucu.Resource.Resource'
+-- in any IO monads or arrows.
 module Network.HTTP.Lucu.Abortion
     ( Abortion(..)
-    , abort      -- MonadIO m => StatusCode -> [ (String, String) ] -> Maybe String -> m a
-    , abortSTM   -- StatusCode -> [ (String, String) ] -> Maybe String -> STM a
-    , abortA     -- ArrowIO a => StatusCode -> [ (String, String) ] -> Maybe String -> a b c
-    , abortPage  -- Config -> Maybe Request -> Maybe Response -> Abortion -> String
+    , abort
+    , abortSTM
+    , abortA
+    , abortPage
     )
     where
 
@@ -33,7 +37,29 @@ data Abortion = Abortion {
     , aboMessage :: Maybe String
     } deriving (Show, Typeable)
 
-
+-- | Computation of @'abort' status headers msg@ aborts the
+-- 'Network.HTTP.Lucu.Resource.Resource' monad with given status,
+-- additional response headers, and optional message string.
+--
+-- What this really does is to just throw a special DynException. The
+-- exception will be caught by the system.
+--
+-- 1. If the 'Network.HTTP.Lucu.Resource.Resource' is in the /Deciding
+--    Header/ or any precedent states, it is possible to use the
+--    @status@ and such like as a HTTP response to be sent to the
+--    client.
+--
+-- 2. Otherwise the HTTP response can't be modified anymore so the
+--    only possible thing the system can do is to dump it to the
+--    stderr. See
+--    'Network.HTTP.Lucu.Config.cnfDumpTooLateAbortionToStderr'.
+--
+-- Note that the status code doesn't have to be an error code so you
+-- can use this action for redirection as well as error reporting e.g.
+--
+-- > abort MovedPermanently
+-- >       [("Location", "http://example.net/")]
+-- >       (Just "It has been moved to example.net")
 abort :: MonadIO m => StatusCode -> [ (String, String) ] -> Maybe String -> m a
 abort status headers msg
     = let abo = Abortion status headers msg
@@ -41,23 +67,24 @@ abort status headers msg
       in
         liftIO $ throwIO exc
 
-
+-- | Computation of @'abortSTM' status headers msg@ just computes
+-- 'abort' in a STM monad.
 abortSTM :: StatusCode -> [ (String, String) ] -> Maybe String -> STM a
 abortSTM status headers msg
     = unsafeIOToSTM $ abort status headers msg
 
-
-abortA :: ArrowIO a => StatusCode -> [ (String, String) ] -> Maybe String -> a b c
-abortA status headers msg
-    = arrIO0 $ abort status headers msg
+-- | Computation of @'abortA' -< (status, (headers, msg))@ just
+-- computes 'abort' in an ArrowIO.
+abortA :: ArrowIO a => a (StatusCode, ([ (String, String) ], Maybe String)) c
+abortA 
+    = arrIO3 abort
 
 
 -- aboMessage が Just なら單に mkDefaultPage に渡すだけで良いので樂だが、
 -- Nothing の場合は getDefaultPage を使ってデフォルトのメッセージを得な
--- ければならない。しかもその時は resM から Response を捏造までする必要
--- がある。
-abortPage :: Config -> Maybe Request -> Maybe Response -> Abortion -> String
-abortPage conf reqM resM abo
+-- ければならない。
+abortPage :: Config -> Maybe Request -> Response -> Abortion -> String
+abortPage conf reqM res abo
     = case aboMessage abo of
         Just msg
             -> let [html] = unsafePerformIO 
@@ -68,15 +95,9 @@ abortPage conf reqM resM abo
                in
                  html
         Nothing
-            -> let res' = case resM of
-                            Just res -> res { resStatus = aboStatus abo }
-                            Nothing  -> Response {
-                                          resVersion = HttpVersion 1 1
-                                        , resStatus  = aboStatus abo
-                                        , resHeaders = []
-                                        }
-                   res  = foldl (.) id [setHeader name value
-                                            | (name, value) <- aboHeaders abo]
-                          $ res'
+            -> let res'  = res { resStatus = aboStatus abo }
+                   res'' = foldl (.) id [setHeader name value
+                                             | (name, value) <- aboHeaders abo]
+                           $ res'
                in
-                 getDefaultPage conf reqM res
+                 getDefaultPage conf reqM res''