purescript-slug

Type-safe slugs for PureScript.

spago install slug

This package provides a Slug type and related type classes & helper functions to help you construct and use type-safe slugs. By default (when using a Slug constructed via the generate and parse functions) you're guaranteed that the following properties hold:

• it isn't empty
• it only contains groups of alpha-numeric characters in the Latin-1 character set separated by dashes (-)
• it does not start or end with a dash
• there are never two dashes in a row
• every character is lower cased

For generating and parsing slugs with different properties see generateWithOptions and parseWithOptions in the Options section below.

Create a slug with Slug.generate:

generate :: String -> Maybe Slug

> Slug.generate "This is an article!"
(Just (Slug "this-is-an-article"))

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

Parse a string that is (supposedly) already a slug with Slug.parse:

parse :: String -> Either SlugError Slug

> Slug.parse "this-is-an-article"
(Just (Slug "this-is-an-article"))

> Slug.parse "-this-is--not-"
Nothing

Recover a string from a valid Slug with Slug.toString:

toString :: Slug -> String

> map Slug.toString (mySlug :: Slug)
(Just "this-is-an-article")

Generate and parse a slug with custom Options.

type Options =
  { replacement :: String           -- used to replace spaces 
  , keepIf :: CodePoint -> Boolean  -- which characters are allowed in the slug
  , lowerCase :: Boolean            -- transform characters to lower-case
  , stripApostrophes :: Boolean     -- remove apostrophes (to avoid unnecessary word-breaks)
  }

Options can be constructed from scratch, or by modifying the default options (which are used in parse and generate)

defaultOptions :: Options
defaultOptions =
  { replacement: "-"
  , keepIf: isAlphaNum && isLatin1
  , lowerCase: true
  , stripApostrophes: true
  }

Custom Options can be useful when working with slugs generated by other libraries, for example, the popular slugify package on npm.

> slugifyOptions = Slug.defaultOptions { keepIf = isLatin1, lowerCase = false, stripApostrophes = false }
> parse = Slug.parseWithOptions slugifyOptions

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

Or just using a different separator than the default "-".

> myOptions = Slug.defaultOptions { replacement = "_" }
> Slug.generateWithOptions myOptions "My article title"
(Just (Slug "my_article_title"))

Read the contribution guidelines to get started and see helpful related resources.

Inspired by the Haskell slug library by @mrkkrp. Some naming conventions mirror elm-slug.