ipa-0.3: README.org

* ipa
** About
~ipa~ is a Haskell library for dealing with International Phonetic Alphabet (IPA) transcriptions. It provides a set of datatypes for working with speech segments and suprasegmentals which can be represented using IPA transcription. Speech sounds can be converted to their IPA representations or parsed from text written in IPA notation. It also supports most of the ASCII-only X-SAMPA transcription scheme.
** Usage
IPA values can be created by constructing ~Segment~ or ~Syllable~ values and applying ~toIPA~.
For instance:
#+begin_src haskell
{-# LANGUAGE PatternSynonyms #-}
{-# LANGUAGE OverloadedStrings #-}
    
import           Language.IPA
import qualified Data.Text.IO as T

main :: IO ()                
main = maybe message (T.putStrLn . unIPA) (toIPA b)
  where
    b       = PulmonicConsonant Voiced Bilabial Plosive
    message = T.putStrLn "Invalid or unrepresentable segment!"
     
#+end_src
~Segment~ and ~Syllable~ values can be adorned with additional articulatory information as well, and can further be nested to created more complex structures, e.g.:
#+begin_src haskell
someComplexVowel :: Segment
someComplexVowel = WithSegmentalFeature 
    (WithSegmentalFeature 
     (Length OverLong)
     (WithSegmentalFeature 
      Compressed
      (Vowel Close Back Unrounded))
-- ɯᵝːː
   
#+end_src
~IPA~ is an instance of ~Semigroup~, so values can be concatenated with ~<>~:
#+begin_src haskell
someSyllables :: Maybe IPA
someSyllables = (<>) <$> toIPA syllable1 <*> toIPA syllable2
  where
    syllable1 =
        WithSuprasegmentalFeature Linking
                                  (Syllable [ WithSegmentalFeature 
                                              (Length Long)
                                              (Vowel Close Back Rounded)
                                            ])

    syllable2 = Syllable [ PulmonicConsonant Voiced Palatal Approximant
                         , Vowel OpenMid Front Unrounded
                         , Vowel Mid Central Unrounded
                         ]
-- uː‿jɛə                        

#+end_src
~toIPA~ is a method of the ~ReprIPA~ typeclass; I decided a typeclass was best in order to allow users to create their own instances if the library-supplied ones were insufficient. You could create an instance, for example, for a hypothetical ~Mora~ datatype, etc...
** License
This library is distributed under the BSD 3-Clause revised license.
** TODO TODO
- [ ] Export constant values for common segments
- [ ] Convenience functions for wrapping IPA values in different transcription delimiters (phonemic, phonetic, etc...)
- [X] Support for X-SAMPA transcription
- [X] Support for IPA <-> X-SAMPA conversion
- [X] Parsing and validation of user-supplied IPA and XSampa literals
- [ ] Quasi quoter for making segment construction somewhat less painful