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


-- | Inflections library for Haskell
--   
--   Inflections provides methods for singularization, pluralization,
--   dasherizing, etc. The library is based on Rails' inflections library.
@package inflections
@version 0.4.0.4


-- | This module provides methods for common <a>Text</a> transformations,
--   similar to the Inflections library found in Rails:
--   
--   <a>http://api.rubyonrails.org/classes/ActiveSupport/Inflector.html</a>
--   
--   While many of the functions in this library are the same as in
--   implementations in Rails' ActiveSupport, the philosophy of this
--   library is fundamentally different. Where Rails tries to be as
--   permissive as possible, and return a String when given any input, this
--   library tries to output <a>Text</a> that makes sense according to the
--   function that is called.
--   
--   When you look closely at many of the functions in Rails' inflections
--   library, you will notice that many of them are partial. That is, they
--   only have well-defined output for some of the possible inputs to the
--   function allowed by the type system. As an example, let's take the
--   <tt>underscore</tt> function. In Rails, it works like this:
--   
--   <pre>
--   &gt;&gt;&gt; "fooBar".underscore
--   "foo_bar"
--   </pre>
--   
--   Looks OK so far. However, it's also easy to produce less expected
--   results:
--   
--   <pre>
--   &gt;&gt;&gt; "foo bar".underscore
--   "foo bar"
--   </pre>
--   
--   The output isn't underscored — it contains a space! It turns out that
--   some of the functions from Inflections in ActiveSupport are
--   <i>partial</i>. I.e., the outputs are really only specified for a
--   certain range of the inputs allowed by the String type.
--   
--   In the Haskell inflections library, we aim to deliver more predictable
--   results by separating the parsing of strings into tokens from the
--   application of transformations. Let's see an example.
--   
--   First, we tokenize an underscored <a>Text</a> using
--   <a>parseSnakeCase</a>:
--   
--   <pre>
--   &gt;&gt;&gt; parseSnakeCase [] "foo_bar"
--   Right [Word "foo",Word "bar"]
--   </pre>
--   
--   We can chain together the tokenization of the input String and the
--   transformation to CamelCase by using <a>fmap</a>:
--   
--   <pre>
--   &gt;&gt;&gt; camelize &lt;$&gt; parseSnakeCase [] "foo_bar"
--   Right "FooBar"
--   </pre>
--   
--   By separating out the tokenization from the application of
--   inflections, we also end up with useful libraries for validating input
--   which can be used independently:
--   
--   <pre>
--   &gt;&gt;&gt; parseSnakeCase [] "fooBar"
--   1:4:
--   unexpected 'B'
--   expecting '_', end of input, or lowercase letter
--   </pre>
--   
--   As of version 0.3.0.0, we don't permit creation of invalid
--   <a>Word</a>s by using of the smart constructors <a>mkWord</a> and
--   <a>mkAcronym</a>. This is done because not every <a>Text</a> value is
--   a valid <a>Word</a>, as it should not contain whitespace, for example.
--   Normal words have the type <tt><a>Word</a> <a>Normal</a></tt>, while
--   acronyms have the type <tt><a>Word</a> <a>Acronym</a></tt>. If you
--   need to have several words/acronyms in a single list, use the
--   existential wrapper <a>SomeWord</a>. Parsing functions now produce
--   <a>SomeWord</a>s.
--   
--   This library is still a work-in-progress, and contributions are
--   welcome for missing pieces and to fix bugs. Please see the Github page
--   to contribute with code or bug reports:
--   
--   <a>https://github.com/stackbuilders/inflections-hs</a>
module Text.Inflections

-- | A <a>Text</a> value that should be kept whole through applied
--   inflections.
data Word (t :: WordType)

-- | A type-level tag for words.
--   
--   <i>since 0.3.0.0</i>
data WordType
Normal :: WordType
Acronym :: WordType

-- | Create a word from given <a>Text</a>. The input should consist of only
--   alpha-numeric characters (no white spaces or punctuation)
--   <a>InflectionInvalidWord</a> will be thrown.
--   
--   <i>since 0.3.0.0</i>
mkWord :: MonadThrow m => Text -> m (Word  'Normal)

-- | Create an acronym from given <a>Text</a>. The input should consist of
--   only alpha-numeric characters <a>InflectionInvalidAcronym</a> will be
--   thrown. Acronym is different from normal word by that it may not be
--   transformed by inflections (also see <a>unSomeWord</a>).
--   
--   <i>since 0.3.0.0</i>
mkAcronym :: MonadThrow m => Text -> m (Word  'Acronym)

-- | Get a <a>Text</a> value from <a>Word</a>.
--   
--   <i>since 0.3.0.0</i>
unWord :: Word t -> Text

-- | An existential wrapper that allows to keep words and acronyms in
--   single list for example. The only thing that receiver of
--   <a>SomeWord</a> can do is to apply <a>unWord</a> on it, of course.
--   This is faciliated by <a>unSomeWord</a>.
--   
--   <i>since 0.3.0.0</i>
data SomeWord
[SomeWord] :: (Transformable (Word t), Show (Word t)) => Word t -> SomeWord

-- | Extract <a>Text</a> from <a>SomeWord</a> and apply given function only
--   if the word inside wasn't an acronym.
--   
--   <i>since 0.3.0.0</i>
unSomeWord :: (Text -> Text) -> SomeWord -> Text

-- | The exceptions that is thrown when parsing of input fails.
--   
--   <i>since 0.3.0.0</i>
data InflectionException
InflectionParsingFailed :: ParseErrorBundle Text Void -> InflectionException
InflectionInvalidWord :: Text -> InflectionException
InflectionInvalidAcronym :: Text -> InflectionException

-- | Parse a snake_case string.
--   
--   <pre>
--   &gt;&gt;&gt; bar &lt;- mkAcronym "bar"
--   
--   &gt;&gt;&gt; parseSnakeCase [bar] "foo_bar_bazz"
--   Right [Word "foo",Acronym "bar",Word "bazz"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseSnakeCase [] "fooBarBazz"
--   1:4:
--   unexpected 'B'
--   expecting '_', end of input, or lowercase letter
--   </pre>
parseSnakeCase :: (Foldable f, Functor f) => f (Word  'Acronym) -> Text -> Either (ParseErrorBundle Text Void) [SomeWord]

-- | Parse a CamelCase string.
--   
--   <pre>
--   &gt;&gt;&gt; bar &lt;- mkAcronym "bar"
--   
--   &gt;&gt;&gt; parseCamelCase [bar] "FooBarBazz"
--   Right [Word "Foo",Acronym "Bar",Word "Bazz"]
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; parseCamelCase [] "foo_bar_bazz"
--   1:4:
--   unexpected '_'
--   expecting end of input, lowercase letter, or uppercase letter
--   </pre>
parseCamelCase :: (Foldable f, Functor f) => f (Word  'Acronym) -> Text -> Either (ParseErrorBundle Text Void) [SomeWord]

-- | Turn an input word list in into CamelCase.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; camelize [foo,bar,bazz]
--   "FoobarBazz"
--   </pre>
camelize :: [SomeWord] -> Text

-- | Turn an input word list into a CamelCase String.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; camelizeCustom False [foo,bar,bazz]
--   "foobarBazz"
--   </pre>
camelizeCustom :: Bool -> [SomeWord] -> Text

-- | Produce a string with words separated by dashes (hyphens).
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; dasherize [foo,bar,bazz]
--   "foo-bar-bazz"
--   </pre>
dasherize :: [SomeWord] -> Text

-- | Capitalize the first word and separate words with spaces. Like
--   <a>titleize</a>, this is meant for creating pretty output.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; humanize [foo,bar,bazz]
--   "Foo bar bazz"
--   </pre>
humanize :: [SomeWord] -> Text

-- | Separate words with spaces, optionally capitalizing the first word.
--   Like <a>titleize</a>, this is meant for creating pretty output.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; humanizeCustom True [foo,bar,bazz]
--   "Foo bar bazz"
--   
--   &gt;&gt;&gt; humanizeCustom False [foo,bar,bazz]
--   "foo bar bazz"
--   </pre>
--   
--   <i>since 0.3.0.0</i>
humanizeCustom :: Bool -> [SomeWord] -> Text

-- | Separate given words by underscores.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; underscore [foo,bar,bazz]
--   "foo_bar_bazz"
--   </pre>
underscore :: [SomeWord] -> Text

-- | Capitalize all the <a>SomeWord</a> words in the input list.
--   
--   <pre>
--   &gt;&gt;&gt; foo  &lt;- SomeWord &lt;$&gt; mkWord "foo"
--   
--   &gt;&gt;&gt; bar  &lt;- SomeWord &lt;$&gt; mkAcronym "bar"
--   
--   &gt;&gt;&gt; bazz &lt;- SomeWord &lt;$&gt; mkWord "bazz"
--   
--   &gt;&gt;&gt; titleize [foo,bar,bazz]
--   "Foo bar Bazz"
--   </pre>
titleize :: [SomeWord] -> Text

-- | A <a>HashMap</a> containing mappings from international characters to
--   sequences approximating these characters within the ASCII range.
type Transliterations = HashMap Char String

-- | These default transliterations are stolen from the Ruby i18n library -
--   see
--   <a>https://github.com/svenfuchs/i18n/blob/master/lib/i18n/backend/transliterator.rb#L41:L69</a>.
--   
--   NOTE: before version 0.3.0.0 this was called <tt>defaultMap</tt>.
defaultTransliterations :: Transliterations

-- | Replace special characters in a string so that it may be used as part
--   of a <tt>pretty</tt> URL. Uses the <a>defaultTransliterations</a>.
parameterize :: Text -> Text

-- | Transliterate <a>Text</a> with a custom transliteration table.
parameterizeCustom :: Transliterations -> Text -> Text

-- | Returns a <a>Text</a> after default approximations for changing
--   Unicode characters to a valid ASCII range are applied. If you want to
--   supplement the default approximations with your own, you should use
--   the <a>transliterateCustom</a> function instead of
--   <a>transliterate</a>.
transliterate :: Text -> Text

-- | Returns a <a>Text</a> after default approximations for changing
--   Unicode characters to a valid ASCII range are applied.
transliterateCustom :: String -> Transliterations -> Text -> Text

-- | Turns a number into an ordinal string used to denote the position in
--   an ordered sequence such as 1st, 2nd, 3rd, 4th.
--   
--   <pre>
--   &gt;&gt;&gt; ordinalize 1
--   "1st"
--   
--   &gt;&gt;&gt; ordinalize 2
--   "2nd"
--   
--   &gt;&gt;&gt; ordinalize 10
--   "10th"
--   </pre>
ordinalize :: (Integral a, Show a) => a -> Text

-- | Returns the suffix that should be added to a number to denote the
--   position in an ordered sequence such as 1st, 2nd, 3rd, 4th.
--   
--   <pre>
--   &gt;&gt;&gt; ordinal 1
--   "st"
--   
--   &gt;&gt;&gt; ordinal 2
--   "nd"
--   
--   &gt;&gt;&gt; ordinal 10
--   "th"
--   </pre>
ordinal :: Integral a => a -> Text

-- | Transforms CamelCasedString to snake_cased_string_with_underscores.
--   
--   <pre>
--   toUnderscore = fmap underscore . parseCamelCase []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; toUnderscore "FooBarBazz"
--   "foo_bar_bazz"
--   </pre>
toUnderscore :: Text -> Either (ParseErrorBundle Text Void) Text

-- | Transforms CamelCasedString to snake-cased-string-with-dashes.
--   
--   <pre>
--   toDashed = fmap dasherize . parseCamelCase []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; toDashed "FooBarBazz"
--   "foo-bar-bazz"
--   </pre>
toDashed :: Text -> Either (ParseErrorBundle Text Void) Text

-- | Transforms underscored_text to CamelCasedText. If first argument is
--   <a>True</a> then the first character in the result string will be in
--   upper case. If <a>False</a> then the first character will be in lower
--   case.
--   
--   <pre>
--   toCamelCased c = fmap (camelizeCustom c) . parseSnakeCase []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; toCamelCased True "foo_bar_bazz"
--   "FooBarBazz"
--   
--   &gt;&gt;&gt; toCamelCased False "foo_bar_bazz"
--   "fooBarBazz"
--   </pre>
toCamelCased :: Bool -> Text -> Either (ParseErrorBundle Text Void) Text

-- | Transforms underscored_text to space-separated human-readable text. If
--   first argument is <a>True</a> then the first character in the result
--   string will be in upper case. If <a>False</a> then the first character
--   will be in lower case.
--   
--   <pre>
--   toHumanized c = fmap (humanizeCustom c) . parseSnakeCase []
--   </pre>
--   
--   <pre>
--   &gt;&gt;&gt; toHumanized True "foo_bar_bazz"
--   "Foo bar bazz"
--   
--   &gt;&gt;&gt; toHumanized False "foo_bar_bazz"
--   "foo bar bazz"
--   </pre>
--   
--   <i>since 0.3.0.0</i>
toHumanized :: Bool -> Text -> Either (ParseErrorBundle Text Void) Text

-- | Lift something of type <tt><a>Either</a> (<a>ParseError</a>
--   <a>Char</a> <a>Void</a>) a</tt> to an instance of <a>MonadThrow</a>.
--   Useful when you want to shortcut on parsing failures and you're in an
--   instance of <a>MonadThrow</a>.
--   
--   This throws <a>InflectionParsingFailed</a> if given value is inside
--   <a>Left</a>.
--   
--   <i>since 0.3.0.0</i>
betterThrow :: MonadThrow m => Either (ParseErrorBundle Text Void) a -> m a
