{- |
Copyright  : Will Thompson, Iñaki García Etxebarria and Jonas Platte
License    : LGPL-2.1
Maintainer : Iñaki García Etxebarria (inaki@blueleaf.cc)
-}

#define ENABLE_OVERLOADING (MIN_VERSION_haskell_gi_overloading(1,0,0) \
       && !defined(__HADDOCK_VERSION__))

module GI.GtkSource.Functions
    ( 

 -- * Methods
-- ** utilsEscapeSearchText #method:utilsEscapeSearchText#

    utilsEscapeSearchText                   ,


-- ** utilsUnescapeSearchText #method:utilsUnescapeSearchText#

    utilsUnescapeSearchText                 ,




    ) where

import Data.GI.Base.ShortPrelude
import qualified Data.GI.Base.ShortPrelude as SP
import qualified Data.GI.Base.Overloading as O
import qualified Prelude as P

import qualified Data.GI.Base.Attributes as GI.Attributes
import qualified Data.GI.Base.ManagedPtr as B.ManagedPtr
import qualified Data.GI.Base.GClosure as B.GClosure
import qualified Data.GI.Base.GError as B.GError
import qualified Data.GI.Base.GVariant as B.GVariant
import qualified Data.GI.Base.GValue as B.GValue
import qualified Data.GI.Base.GParamSpec as B.GParamSpec
import qualified Data.GI.Base.CallStack as B.CallStack
import qualified Data.GI.Base.Properties as B.Properties
import qualified Data.Text as T
import qualified Data.ByteString.Char8 as B
import qualified Data.Map as Map
import qualified Foreign.Ptr as FP
import qualified GHC.OverloadedLabels as OL


-- function gtk_source_utils_unescape_search_text
-- Args : [Arg {argCName = "text", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the text to unescape.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TBasicType TUTF8)
-- throws : False
-- Skip return : False

foreign import ccall "gtk_source_utils_unescape_search_text" gtk_source_utils_unescape_search_text :: 
    CString ->                              -- text : TBasicType TUTF8
    IO CString

{- |
Use this function before 'GI.GtkSource.Objects.SearchSettings.searchSettingsSetSearchText', to
unescape the following sequences of characters: @\\n@, @\\r@, @\\t@ and @\\\\@.
The purpose is to easily write those characters in a search entry.

Note that unescaping the search text is not needed for regular expression
searches.

See also: 'GI.GtkSource.Functions.utilsEscapeSearchText'.

/Since: 3.10/
-}
utilsUnescapeSearchText ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    T.Text
    {- ^ /@text@/: the text to unescape. -}
    -> m T.Text
    {- ^ __Returns:__ the unescaped /@text@/. -}
utilsUnescapeSearchText text = liftIO $ do
    text' <- textToCString text
    result <- gtk_source_utils_unescape_search_text text'
    checkUnexpectedReturnNULL "utilsUnescapeSearchText" result
    result' <- cstringToText result
    freeMem result
    freeMem text'
    return result'


-- function gtk_source_utils_escape_search_text
-- Args : [Arg {argCName = "text", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the text to escape.", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TBasicType TUTF8)
-- throws : False
-- Skip return : False

foreign import ccall "gtk_source_utils_escape_search_text" gtk_source_utils_escape_search_text :: 
    CString ->                              -- text : TBasicType TUTF8
    IO CString

{- |
Use this function to escape the following characters: @\\n@, @\\r@, @\\t@ and @\\@.

For a regular expression search, use 'GI.GLib.Functions.regexEscapeString' instead.

One possible use case is to take the 'GI.Gtk.Objects.TextBuffer.TextBuffer'\'s selection and put it in a
search entry. The selection can contain tabulations, newlines, etc. So it\'s
better to escape those special characters to better fit in the search entry.

See also: 'GI.GtkSource.Functions.utilsUnescapeSearchText'.

\<warning>
Warning: the escape and unescape functions are not reciprocal! For example,
escape (unescape (\\)) = \\. So avoid cycles such as: search entry -> unescape
-> search settings -> escape -> search entry. The original search entry text
may be modified.
\<\/warning>

/Since: 3.10/
-}
utilsEscapeSearchText ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    T.Text
    {- ^ /@text@/: the text to escape. -}
    -> m T.Text
    {- ^ __Returns:__ the escaped /@text@/. -}
utilsEscapeSearchText text = liftIO $ do
    text' <- textToCString text
    result <- gtk_source_utils_escape_search_text text'
    checkUnexpectedReturnNULL "utilsEscapeSearchText" result
    result' <- cstringToText result
    freeMem result
    freeMem text'
    return result'