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


-- | Parse/format generic key/value URLs from record data types.
--   
--   Parse/format generic key/value URLs from record data types.
@package url-generic
@version 0.1


-- | The purpose of this package is to associate web pages each with a data
--   type that contains all the necessary parameters for that page, by
--   automatically deriving that representation from the data types
--   themselves. It is an experimental package to test the idea.
--   
--   The data type constructors must be nullary or record, and there should
--   only be one constructor (later this might be revised). The fields of
--   the constructor <i>MUST</i> each be prefixed with the name of the
--   constructor, as per the common idiom when dealing with Haskell data
--   types. This also ensures that no data-type-generated URL can be in
--   conflict with another, code-wise or representation-wise.
--   
--   For example, consider a page displays some conference/event. It ought
--   to be defined thiswise:
--   
--   <pre>
--   data Event = Event { eventId     :: Maybe Integer -- ^ The event id.
--                      , eventScope  :: Bool          -- ^ Show the scope?
--                      , eventLayout :: Layout        -- ^ Layout for the page.
--                      }
--     deriving (Data,Typeable,Show)
--   </pre>
--   
--   And an Enum type for layout:
--   
--   <pre>
--   data Layout =
--     Wide | Thin | Collapsed
--     deriving (Typeable,Data,Show,Enum)
--   </pre>
--   
--   (<tt>Show</tt> is not required, but is included for inspection
--   purposes.)
--   
--   Now I can format that as a URL:
--   
--   <pre>
--   &gt; formatURLPath $ Event (Just 0) False  Wide
--   "/event/id/0/layout/wide"
--   </pre>
--   
--   And parse that URL back in:
--   
--   <pre>
--   &gt; parseURLPath "/event/id/0/layout/wide" :: Maybe Event
--   Just (Event {eventId = Just 0, eventScope = False, eventLayout = Wide})
--   </pre>
--   
--   Nullary data types also work:
--   
--   <pre>
--    data Home = Home
--      deriving (Data,Typeable,Show)
--   
--   &gt; parseURLPath "/home" :: Maybe Home
--    Just Home
--    &gt; formatURLPath Home
--    "/home"
--    &gt; 
--   </pre>
--   
--   The supported types for URL parameters are:
--   
--   <ul>
--   <li>Standard <tt>Integer</tt> type.</li>
--   <li>Standard <tt>Bool</tt> type.</li>
--   <li>Any type with nullary constructors (such as <tt>Layout</tt>
--   above.).</li>
--   <li><tt>Maybe a</tt> where <tt>a</tt> is one of the above. Maybe is
--   useful for optionally omitting parameters from URLs.</li>
--   </ul>
--   
--   Any other types cannot (should not (?)) be serialized at the
--   URL-level.
--   
--   There is the possibility to read/write <tt>String</tt>, but it does
--   make much sense to put arbitrary strings in URLs, so it does no
--   special encoding/decoding for <tt>String</tt>s. There is, however, the
--   use case for encoding slugs, such as blog titles, e.g.
--   <tt>/posts/name/my-blog-title</tt>, and that is why support is
--   included. You must ensure that these are properly normalized yourself.
module Web.URL.Generic

-- | Parse a URL path, e.g. <tt>/foo/id/1</tt>, into its corresponding data
--   type, e.g. <tt>Foo { fooId = 1 }</tt>.
parseURLPath :: Data a => String -> Maybe a

-- | Format a record value, e.g. <tt>Foo { fooId = 1 }</tt>, into its
--   corresponding URL path, e.g. <tt>/foo/id/1</tt>.
formatURLPath :: Data a => a -> String

-- | Simple maybe alias.
type Parse a = Maybe a

-- | Parse a constructor from a string.
parseCons :: Data a => String -> [(String, String)] -> Maybe a

-- | URL string to association list.
urlToAssoc :: String -> [(String, String)]

-- | Parse a URL string into a simple value (integer/bool/string).
fromURLString :: Data a => String -> Maybe a

-- | Parse any constructor. It really only works well for nullary
--   constructors like Enum values, but that in itself is very useful.
parseData :: Data a => String -> Parse a

-- | Parse an integer.
parseInteger :: String -> Parse Integer

-- | Parse a boolean (<tt>true</tt>/<tt>false</tt>).
parseBool :: String -> Parse Bool

-- | Format a constructor value to a URL.
formatCons :: Data a => a -> String

-- | Format a constructor's field value to a URL parameter.
formatURLParamValue :: Data a => a -> String

-- | Show any Haskell (Data instance) constructor e.g. <tt>FooBar</tt> to
--   <tt>foo-bar</tt>. This is only reliable for nullary constructors like
--   Enums and such. But that by itself is very useful, so it's worth
--   including.
showData :: Data a => a -> String

-- | Normalize a record field to a slug-ish name e.g. <tt>fooBarMu</tt>
--   =&gt; <tt>bar-mu</tt>.
fieldToKey :: Show a => a -> String -> String

-- | Convert uppercase <tt>CamelCase to slug-ish camel-case</tt>.
upperToDashes :: [Char] -> [Char]

-- | Convert slug-ish <tt>camel-case</tt> to uppercase <tt>CamelCase</tt>.
dashesToUpper :: [Char] -> [Char]
instance Typeable Home
instance Typeable Layout
instance Typeable Event
instance Data Home
instance Show Home
instance Data Layout
instance Show Layout
instance Data Event
instance Show Event