@@ -1,6 +1,6 @@
11-- |
22-- Module : Text.Inflections
3−-- Description : Rails-like inflections library for common String transformations.
3+-- Description : Rails-like inflections library for common Text transformations.
44-- Copyright : (c) Justin Leitgeb
55-- License : MIT
66--
@@ -8,7 +8,7 @@
88-- Stability : unstable
99-- Portability : portable
1010--
11−-- This module provides methods for common String transformations, similar
11+-- This module provides methods for common 'Text' transformations, similar
1212-- to the Inflections library found in Rails:
1313--
1414-- <http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html>
@@ -17,7 +17,7 @@
1717-- implementations in Rails' ActiveSupport, the philosophy of this library
1818-- is fundamentally different. Where Rails tries to be as permissive as
1919-- possible, and return a String when given any input, this library tries to
20−-- output strings that make sense according to the function that is called.
20+-- output 'Text' that makes sense according to the function that is called.
2121--
2222-- When you look closely at many of the functions in Rails' inflections
2323-- library, you will notice that many of them are partial. That is, they
@@ -33,7 +33,7 @@
3333-- >>> "foo bar".underscore
3434-- "foo bar"
3535--
36−-- The output isn't underscored - it contains a space! It turns out that
36+-- The output isn't underscored — it contains a space! It turns out that
3737-- some of the functions from Inflections in ActiveSupport are /partial/.
3838-- I.e., the outputs are really only specified for a certain range of the
3939-- inputs allowed by the String type.
@@ -42,7 +42,7 @@
4242-- results by separating the parsing of strings into tokens from the
4343-- application of transformations. Let's see an example.
4444--
45−-- First, we tokenize an underscored String using 'parseSnakeCase':
45+-- First, we tokenize an underscored 'Text' using 'parseSnakeCase':
4646--
4747-- >>> parseSnakeCase [] "foo_bar"
4848-- Right [Word "foo",Word "bar"]
@@ -79,14 +79,24 @@
7979{-# LANGUAGE CPP #-}
8080
8181module Text.Inflections
82− ( -- * Parsing
83− parseSnakeCase
82+ ( -- * Types and helpers
83+ Word
84+ , WordType (..)
85+ , mkWord
86+ , mkAcronym
87+ , unWord
88+ , SomeWord (..)
89+ , unSomeWord
90+ , InflectionException (..)
91+ -- * Parsing
92+ , parseSnakeCase
8493 , parseCamelCase
8594 -- * Rendering
8695 , camelize
8796 , camelizeCustom
8897 , dasherize
8998 , humanize
99+ , humanizeCustom
90100 , underscore
91101 , titleize
92102 , Transliterations
@@ -97,28 +107,21 @@ module Text.Inflections
97107 , transliterateCustom
98108 , ordinalize
99109 , ordinal
100− -- * Types and helpers
101− , Word
102− , WordType (..)
103− , mkWord
104− , mkAcronym
105− , unWord
106− , SomeWord (..)
107− , unSomeWord
108− , InflectionException (..)
109110 -- * Often used combinators
110111 , toUnderscore
111112 , toDashed
112113 , toCamelCased
114+ , toHumanized
113115 , betterThrow )
114116where
115117
116118import Control.Monad.Catch (MonadThrow (..))
117119import Data.Text (Text)
120+import Data.Void (Void)
118121import Text.Inflections.Camelize (camelize, camelizeCustom)
119122import Text.Inflections.Dasherize (dasherize)
120123import Text.Inflections.Data (Transliterations, defaultTransliterations)
121−import Text.Inflections.Humanize (humanize)
124+import Text.Inflections.Humanize (humanize, humanizeCustom)
122125import Text.Inflections.Ordinal (ordinal, ordinalize)
123126import Text.Inflections.Parameterize (parameterize, parameterizeCustom)
124127import Text.Inflections.Parse.CamelCase (parseCamelCase)
@@ -139,7 +142,7 @@ import Prelude hiding (Word)
139142--
140143-- >>> toUnderscore "FooBarBazz"
141144-- "foo_bar_bazz"
142−toUnderscore :: Text -> Either (ParseError Char Dec) Text
145+toUnderscore :: Text -> Either (ParseErrorBundle Text Void) Text
143146toUnderscore = fmap underscore . parseCamelCase []
144147
145148-- | Transforms CamelCasedString to snake-cased-string-with-dashes.
@@ -148,26 +151,45 @@ toUnderscore = fmap underscore . parseCamelCase []
148151--
149152-- >>> toDashed "FooBarBazz"
150153-- "foo-bar-bazz"
151−toDashed :: Text -> Either (ParseError Char Dec) Text
154+toDashed :: Text -> Either (ParseErrorBundle Text Void) Text
152155toDashed = fmap dasherize . parseCamelCase []
153156
154157-- | Transforms underscored_text to CamelCasedText. If first argument is
155−-- 'True' then FirstCharacter in result string will be in upper case. If
156−-- 'False' then firstCharacter will be in lower case.
158+-- 'True' then the first character in the result string will be in upper case. If
159+-- 'False' then the first character will be in lower case.
157160--
158−-- > toCamelCased t = fmap (camelizeCustom t) . parseSnakeCase []
161+-- > toCamelCased c = fmap (camelizeCustom c) . parseSnakeCase []
159162--
160163-- >>> toCamelCased True "foo_bar_bazz"
161164-- "FooBarBazz"
162165-- >>> toCamelCased False "foo_bar_bazz"
163166-- "fooBarBazz"
164167toCamelCased
165− :: Bool -- ^ Capitalize the first character
166− -> Text -- ^ Input
167− -> Either (ParseError Char Dec) Text -- ^ Ouput
168−toCamelCased t = fmap (camelizeCustom t) . parseSnakeCase []
168+ :: Bool -- ^ Capitalize the first character
169+ -> Text -- ^ Input
170+ -> Either (ParseErrorBundle Text Void) Text -- ^ Output
171+toCamelCased c = fmap (camelizeCustom c) . parseSnakeCase []
172+
173+-- | Transforms underscored_text to space-separated human-readable text.
174+-- If first argument is 'True' then the first character in the result
175+-- string will be in upper case. If 'False' then the first character will be
176+-- in lower case.
177+--
178+-- > toHumanized c = fmap (humanizeCustom c) . parseSnakeCase []
179+--
180+-- >>> toHumanized True "foo_bar_bazz"
181+-- "Foo bar bazz"
182+-- >>> toHumanized False "foo_bar_bazz"
183+-- "foo bar bazz"
184+--
185+-- /since 0.3.0.0/
186+toHumanized
187+ :: Bool -- ^ Capitalize the first character
188+ -> Text -- ^ Input
189+ -> Either (ParseErrorBundle Text Void) Text -- ^ Output
190+toHumanized c = fmap (humanizeCustom c) . parseSnakeCase []
169191
170−-- | Lift something of type @'Either' ('ParseError' 'Char' 'Dec') a@ to
192+-- | Lift something of type @'Either' ('ParseError' 'Char' 'Void') a@ to
171193-- an instance of 'MonadThrow'. Useful when you want to shortcut on parsing
172194-- failures and you're in an instance of 'MonadThrow'.
173195--
@@ -175,6 +197,6 @@ toCamelCased t = fmap (camelizeCustom t) . parseSnakeCase []
175197--
176198-- /since 0.3.0.0/
177199
178−betterThrow :: MonadThrow m => Either (ParseError Char Dec) a -> m a
200+betterThrow :: MonadThrow m => Either (ParseErrorBundle Text Void) a -> m a
179201betterThrow (Left err) = throwM (InflectionParsingFailed err)
180202betterThrow (Right x) = return x