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


-- | OpenCC bindings
--   
--   Open Chinese Convert (OpenCC, 開放中文轉換) is an opensource project for
--   conversions between Traditional Chinese, Simplified Chinese and
--   Japanese Kanji (Shinjitai). It supports character-level and
--   phrase-level conversion, character variant conversion and regional
--   idioms among Mainland China, Taiwan and Hong Kong. This library is the
--   Haskell bindings.
@package opencc
@version 0.1.0.0


-- | This module defines the raw bindings to the OpenCC library. Currently,
--   <tt>opencc_convert_utf8_to_buffer</tt> is missing.
module Text.OpenCC.Raw

-- | Raw representation of the OpenCC handle.
type RawOpenCC = Ptr ()
_openccOpen :: CString -> IO RawOpenCC
_openccClose :: RawOpenCC -> IO ()
_openccClosePtr :: FunPtr (RawOpenCC -> IO ())
_openccConvertUtf8 :: RawOpenCC -> CString -> CSize -> IO CString
_openccConvertUtf8Free :: CString -> IO ()
_openccConvertUtf8FreePtr :: FunPtr (CString -> IO ())

-- | Return value is `const char *`, do NOT free!
_openccError :: IO CString


-- | This module exposes higher-level binding to OpenCC than
--   <a>Text.OpenCC.Raw</a>. OpenCC resources are managed automatically,
--   and large string objects are passed without being copied.
--   
--   There are three sets of higher-level bindings.
--   
--   <ol>
--   <li>IO handles. You work in <a>IO</a> monad and work with
--   <a>OpenCC</a> handles directly.</li>
--   <li>One-shot. <a>convert1</a> directly converts a <a>String</a>.</li>
--   <li>Monadic. You work in <a>OpenCCM</a> monad where you can use
--   <a>convert</a>.</li>
--   </ol>
--   
--   <b>Caveat</b>: the one-shot interface is unsafe, but as long as OpenCC
--   is not shared or you don't care about errors, you will be fine.
--   
--   <a>defaultTradToSimp</a> and <a>defaultSimpToTrad</a> are suggested by
--   OpenCC.
module Text.OpenCC

-- | Do a one-shot conversion. Note that this might affect the outcome of
--   <a>lastError</a>, and thus unsafe (despite the pureness suggested by
--   the signature).
--   
--   <pre>
--   convert1 defaultSimpToTrad "头发发财"
--   </pre>
convert1 :: String -> Text -> Maybe Text

-- | OpenCC handle plus the finalizer. The OpenCC instance will be
--   finalized when the object is garbage collected.
type OpenCC = ForeignPtr ()

-- | Open a new OpenCC session with specified configuration. <a>Nothing</a>
--   is returned if error happens, and the error message can be retrieved
--   from <a>lastError</a>.
open :: String -> MaybeT IO OpenCC

-- | Return the last error message. This function is NOT thread-safe.
lastError :: IO Text

-- | Use an OpenCC handle to do the conversion. The result is a UTF-8
--   encoded text.
convertIO :: OpenCC -> Text -> IO Text

-- | The OpenCC environment. In this environment, any conversion happens
--   within a single <a>OpenCC</a> instance created by <a>withOpenCC</a>.
data OpenCCM a

-- | Open an OpenCC environment (which is <a>MonadIO</a>), where
--   <a>convert</a> is available.
withOpenCC :: String -> OpenCCM a -> MaybeT IO a

-- | Same as <a>withOpenCC</a> but the result is not <a>IO</a>. This is
--   unsafe, and the same safety conditions as <a>convert1</a> apply here.
unsafeWithOpenCC :: String -> OpenCCM a -> Maybe a

-- | Convert a string in the current environment.
convert :: Text -> OpenCCM Text

-- | Filename of default Simplified to Traditional configuration
defaultSimpToTrad :: String

-- | Filename of default Traditional to Simplified configuration
defaultTradToSimp :: String
instance Control.Monad.IO.Class.MonadIO Text.OpenCC.OpenCCM
instance GHC.Base.Monad Text.OpenCC.OpenCCM
instance GHC.Base.Applicative Text.OpenCC.OpenCCM
instance GHC.Base.Functor Text.OpenCC.OpenCCM