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


-- | Type-safe slugs for Yesod ecosystem
--   
--   Type-safe slugs for Yesod ecosystem.
@package slug
@version 0.1.3


-- | Type-safe slug implementation for Yesod ecosystem.
module Web.Slug

-- | Slug. Textual value inside is always guaranteed to have the following
--   qualities:
--   
--   <ul>
--   <li>it's not empty;</li>
--   <li>it consists only of alpha-numeric groups of characters (words)
--   separated by <tt>'-'</tt> dashes in such a way that entire slug cannot
--   start or end in a dash and also two dashes in a row cannot be
--   found;</li>
--   <li>every character with defined notion of case is lower-cased.</li>
--   </ul>
--   
--   Slugs are good for semantic URLs and also can be used as identifier of
--   a sort in some cases.
data Slug

-- | Create <a>Slug</a> from <a>Text</a>, all necessary transformations are
--   applied. Argument of this function can be title of an article or
--   something like that.
--   
--   Note that result is inside <a>MonadThrow</a>, that means you can just
--   get it in <a>Maybe</a>, in more complex contexts it will throw
--   <a>SlugException</a> exception using <a>InvalidInput</a> constructor.
--   
--   This function also has a useful property:
--   
--   <pre>
--   mkSlug = mkSlug &gt;=&gt; mkSlug . unSlug
--   </pre>
mkSlug :: MonadThrow m => Text -> m Slug

-- | Get textual representation if <a>Slug</a>.
unSlug :: Slug -> Text

-- | Convert <a>Text</a> into <a>Slug</a> only when it is already valid
--   slug.
--   
--   This function can throw <a>SlugException</a> exception using
--   <a>InvalidSlug</a> constructor.
parseSlug :: MonadThrow m => Text -> m Slug

-- | Ensure that given <a>Slug</a> is not longer than given maximum number
--   of characters. If truncated slug ends in a dash, remove that dash too.
--   (Dash at the end would violate properties described in documentation
--   for <a>Slug</a>.)
--   
--   If the first argument is not a positive number, <a>SlugException</a>
--   is thrown using <a>InvalidLength</a> constructor.
truncateSlug :: MonadThrow m => Int -> Slug -> m Slug

-- | This exception is thrown by <a>mkSlug</a> when its input cannot be
--   converted into proper <a>Slug</a>.
data SlugException

-- | Slug cannot be generated for given text
InvalidInput :: Text -> SlugException

-- | Input is not a valid slug, see <a>parseSlug</a>
InvalidSlug :: Text -> SlugException

-- | Requested slug length is not a positive number
InvalidLength :: Int -> SlugException
instance GHC.Classes.Eq Web.Slug.Slug
instance GHC.Show.Show Web.Slug.SlugException
instance GHC.Exception.Exception Web.Slug.SlugException
instance GHC.Show.Show Web.Slug.Slug
instance GHC.Read.Read Web.Slug.Slug
instance Data.Aeson.Types.ToJSON.ToJSON Web.Slug.Slug
instance Data.Aeson.Types.FromJSON.FromJSON Web.Slug.Slug
instance Database.Persist.Class.PersistField.PersistField Web.Slug.Slug
instance Database.Persist.Sql.Class.PersistFieldSql Web.Slug.Slug
instance Web.PathPieces.PathPiece Web.Slug.Slug