Slug

newtype Slug

A Slug is usually created for article titles and other resources which need a human-readable resource name in a URL, typically with spaces replaced by a dash separator and all other non-alphanumeric characters removed.

A Slug is guaranteed to be non-empty, and when generated using the generate function is also guaranteed to have the following qualities:

• it consists of alphanumeric groups of characters separated by - dashes, where the slug cannot begin or end with a dash, and there can never be two dashes in a row.
• every character with a defined notion of case is lower-cased
• its string value (got by toString) can be successfully parsed with the parse function

Example: Slug "this-is-an-article-slug"

See generateWithOptions and parseWithOptions if you need to customize the behavior of Slug generation and parsing.

Instances

• Eq Slug
• Ord Slug
• Semigroup Slug
• Show Slug
• EncodeJson Slug
• DecodeJson Slug

type Options = { keepIf :: CodePoint -> Boolean, lowerCase :: Boolean, replacement :: String, stripApostrophes :: Boolean }

Configure generateWithOptions and parseWithOptions to create a Slug from a string with custom options.

• replacement is used to replace spaces (default is "-").
• keepIf is a function that determines which characters are allowed in the slug (default is isAlphaNum && isLatin1).
• lowerCase determines whether the slug should be lower-cased (default is true).
• stripApostrophes determines whether apostrophes should be removed before generating the slug (default is true).

defaultOptions :: Options

generate :: String -> Maybe Slug

Create a Slug from a string. This will transform the input string to be a valid slug (if it is possible to do so) by separating words with - dashes, ensuring the string does not begin or end with a dash, and ensuring there are never two dashes in a row.

> Slug.generate "My article title!"
> Just (Slug "my-article-title")

> Slug.generate "¬¬¬{}¬¬¬"
> Nothing

generateWithOptions :: Options -> String -> Maybe Slug

Create a Slug from a string with custom options.

> slugifyOptions = Slug.defaultOptions { keepIf = isLatin1, lowerCase = false, stripApostrophes = false }
> slugify = Slug.generateWithOptions slugifyOptions

> slugify "This is my article's title!"
> Just (Slug "This-is-my-article's-title!")

parse :: String -> Maybe Slug

Parse a valid slug (as a string) into a Slug. This will fail if the string is not a valid slug and does not provide the same behavior as generate.

> Slug.parse "my-article-title"
> Just (Slug "my-article-title")

> Slug.parse "My article"
> Nothing

parseWithOptions :: Options -> String -> Maybe Slug

Parse a valid slug (as a string) into a Slug with custom options. This will fail if the string is not a valid slug and does not provide the same behavior as generateWithOptions given the same Options.

> myOptions = Slug.defaultOptions { replacement = "_" }
> Slug.parseWithOptions myOptions "my_article_title"
> Just (Slug "my_article_title")

> Slug.parseWithOptions myOptions "My article"
> Nothing

toString :: Slug -> String

Unwrap a Slug into the string contained within, without performing any transformations.

> Slug.toString (mySlug :: Slug)
> "my-slug-i-generated"

truncate :: Int -> Slug -> Maybe Slug

Ensure a Slug is no longer than a given number of characters. If the last character is a dash, it will also be removed. Providing a non-positive number as the length will return Nothing.

> Slug.generate "My article title is long!" >>= Slug.truncate 3
> Just (Slug "my")