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

The 'GI.Gio.Structs.SettingsSchemaSource.SettingsSchemaSource' and 'GI.Gio.Structs.SettingsSchema.SettingsSchema' APIs provide a
mechanism for advanced control over the loading of schemas and a
mechanism for introspecting their content.

Plugin loading systems that wish to provide plugins a way to access
settings face the problem of how to make the schemas for these
settings visible to GSettings.  Typically, a plugin will want to ship
the schema along with itself and it won\'t be installed into the
standard system directories for schemas.

'GI.Gio.Structs.SettingsSchemaSource.SettingsSchemaSource' provides a mechanism for dealing with this by
allowing the creation of a new \'schema source\' from which schemas can
be acquired.  This schema source can then become part of the metadata
associated with the plugin and queried whenever the plugin requires
access to some settings.

Consider the following example:


=== /C code/
>
>typedef struct
>{
>   ...
>   GSettingsSchemaSource *schema_source;
>   ...
>} Plugin;
>
>Plugin *
>initialise_plugin (const gchar *dir)
>{
>  Plugin *plugin;
>
>  ...
>
>  plugin->schema_source =
>    g_settings_schema_source_new_from_directory (dir,
>      g_settings_schema_source_get_default (), FALSE, NULL);
>
>  ...
>
>  return plugin;
>}
>
>...
>
>GSettings *
>plugin_get_settings (Plugin      *plugin,
>                     const gchar *schema_id)
>{
>  GSettingsSchema *schema;
>
>  if (schema_id == NULL)
>    schema_id = plugin->identifier;
>
>  schema = g_settings_schema_source_lookup (plugin->schema_source,
>                                            schema_id, FALSE);
>
>  if (schema == NULL)
>    {
>      ... disable the plugin or abort, etc ...
>    }
>
>  return g_settings_new_full (schema, NULL, NULL);
>}


The code above shows how hooks should be added to the code that
initialises (or enables) the plugin to create the schema source and
how an API can be added to the plugin system to provide a convenient
way for the plugin to access its settings, using the schemas that it
ships.

From the standpoint of the plugin, it would need to ensure that it
ships a gschemas.compiled file as part of itself, and then simply do
the following:


=== /C code/
>
>{
>  GSettings *settings;
>  gint some_value;
>
>  settings = plugin_get_settings (self, NULL);
>  some_value = g_settings_get_int (settings, "some-value");
>  ...
>}


It\'s also possible that the plugin system expects the schema source
files (ie: .gschema.xml files) instead of a gschemas.compiled file.
In that case, the plugin loading system must compile the schemas for
itself before attempting to create the settings source.

/Since: 2.32/
-}

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

module GI.Gio.Structs.SettingsSchema
    ( 

-- * Exported types
    SettingsSchema(..)                      ,
    noSettingsSchema                        ,


 -- * Methods
-- ** getId #method:getId#

#if ENABLE_OVERLOADING
    SettingsSchemaGetIdMethodInfo           ,
#endif
    settingsSchemaGetId                     ,


-- ** getKey #method:getKey#

#if ENABLE_OVERLOADING
    SettingsSchemaGetKeyMethodInfo          ,
#endif
    settingsSchemaGetKey                    ,


-- ** getPath #method:getPath#

#if ENABLE_OVERLOADING
    SettingsSchemaGetPathMethodInfo         ,
#endif
    settingsSchemaGetPath                   ,


-- ** hasKey #method:hasKey#

#if ENABLE_OVERLOADING
    SettingsSchemaHasKeyMethodInfo          ,
#endif
    settingsSchemaHasKey                    ,


-- ** listChildren #method:listChildren#

#if ENABLE_OVERLOADING
    SettingsSchemaListChildrenMethodInfo    ,
#endif
    settingsSchemaListChildren              ,


-- ** listKeys #method:listKeys#

#if ENABLE_OVERLOADING
    SettingsSchemaListKeysMethodInfo        ,
#endif
    settingsSchemaListKeys                  ,


-- ** ref #method:ref#

#if ENABLE_OVERLOADING
    SettingsSchemaRefMethodInfo             ,
#endif
    settingsSchemaRef                       ,


-- ** unref #method:unref#

#if ENABLE_OVERLOADING
    SettingsSchemaUnrefMethodInfo           ,
#endif
    settingsSchemaUnref                     ,




    ) 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

import {-# SOURCE #-} qualified GI.Gio.Structs.SettingsSchemaKey as Gio.SettingsSchemaKey

-- | Memory-managed wrapper type.
newtype SettingsSchema = SettingsSchema (ManagedPtr SettingsSchema)
foreign import ccall "g_settings_schema_get_type" c_g_settings_schema_get_type :: 
    IO GType

instance BoxedObject SettingsSchema where
    boxedType _ = c_g_settings_schema_get_type

-- | A convenience alias for `Nothing` :: `Maybe` `SettingsSchema`.
noSettingsSchema :: Maybe SettingsSchema
noSettingsSchema = Nothing


#if ENABLE_OVERLOADING
instance O.HasAttributeList SettingsSchema
type instance O.AttributeList SettingsSchema = SettingsSchemaAttributeList
type SettingsSchemaAttributeList = ('[ ] :: [(Symbol, *)])
#endif

-- method SettingsSchema::get_id
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", 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 "g_settings_schema_get_id" g_settings_schema_get_id :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO CString

{- |
Get the ID of /@schema@/.
-}
settingsSchemaGetId ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m T.Text
    {- ^ __Returns:__ the ID -}
settingsSchemaGetId schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    result <- g_settings_schema_get_id schema'
    checkUnexpectedReturnNULL "settingsSchemaGetId" result
    result' <- cstringToText result
    touchManagedPtr schema
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaGetIdMethodInfo
instance (signature ~ (m T.Text), MonadIO m) => O.MethodInfo SettingsSchemaGetIdMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaGetId

#endif

-- method SettingsSchema::get_key
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "name", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the name of a key", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TInterface (Name {namespace = "Gio", name = "SettingsSchemaKey"}))
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_get_key" g_settings_schema_get_key :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    CString ->                              -- name : TBasicType TUTF8
    IO (Ptr Gio.SettingsSchemaKey.SettingsSchemaKey)

{- |
Gets the key named /@name@/ from /@schema@/.

It is a programmer error to request a key that does not exist.  See
'GI.Gio.Structs.SettingsSchema.settingsSchemaListKeys'.

/Since: 2.40/
-}
settingsSchemaGetKey ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> T.Text
    {- ^ /@name@/: the name of a key -}
    -> m Gio.SettingsSchemaKey.SettingsSchemaKey
    {- ^ __Returns:__ the 'GI.Gio.Structs.SettingsSchemaKey.SettingsSchemaKey' for /@name@/ -}
settingsSchemaGetKey schema name = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    name' <- textToCString name
    result <- g_settings_schema_get_key schema' name'
    checkUnexpectedReturnNULL "settingsSchemaGetKey" result
    result' <- (wrapBoxed Gio.SettingsSchemaKey.SettingsSchemaKey) result
    touchManagedPtr schema
    freeMem name'
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaGetKeyMethodInfo
instance (signature ~ (T.Text -> m Gio.SettingsSchemaKey.SettingsSchemaKey), MonadIO m) => O.MethodInfo SettingsSchemaGetKeyMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaGetKey

#endif

-- method SettingsSchema::get_path
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", 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 "g_settings_schema_get_path" g_settings_schema_get_path :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO CString

{- |
Gets the path associated with /@schema@/, or 'Nothing'.

Schemas may be single-instance or relocatable.  Single-instance
schemas correspond to exactly one set of keys in the backend
database: those located at the path returned by this function.

Relocatable schemas can be referenced by other schemas and can
threfore describe multiple sets of keys at different locations.  For
relocatable schemas, this function will return 'Nothing'.

/Since: 2.32/
-}
settingsSchemaGetPath ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m T.Text
    {- ^ __Returns:__ the path of the schema, or 'Nothing' -}
settingsSchemaGetPath schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    result <- g_settings_schema_get_path schema'
    checkUnexpectedReturnNULL "settingsSchemaGetPath" result
    result' <- cstringToText result
    touchManagedPtr schema
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaGetPathMethodInfo
instance (signature ~ (m T.Text), MonadIO m) => O.MethodInfo SettingsSchemaGetPathMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaGetPath

#endif

-- method SettingsSchema::has_key
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing},Arg {argCName = "name", argType = TBasicType TUTF8, direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "the name of a key", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TBasicType TBoolean)
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_has_key" g_settings_schema_has_key :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    CString ->                              -- name : TBasicType TUTF8
    IO CInt

{- |
Checks if /@schema@/ has a key named /@name@/.

/Since: 2.40/
-}
settingsSchemaHasKey ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> T.Text
    {- ^ /@name@/: the name of a key -}
    -> m Bool
    {- ^ __Returns:__ 'True' if such a key exists -}
settingsSchemaHasKey schema name = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    name' <- textToCString name
    result <- g_settings_schema_has_key schema' name'
    let result' = (/= 0) result
    touchManagedPtr schema
    freeMem name'
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaHasKeyMethodInfo
instance (signature ~ (T.Text -> m Bool), MonadIO m) => O.MethodInfo SettingsSchemaHasKeyMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaHasKey

#endif

-- method SettingsSchema::list_children
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TCArray True (-1) (-1) (TBasicType TUTF8))
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_list_children" g_settings_schema_list_children :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO (Ptr CString)

{- |
Gets the list of children in /@schema@/.

You should free the return value with 'GI.GLib.Functions.strfreev' when you are done
with it.

/Since: 2.44/
-}
settingsSchemaListChildren ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m [T.Text]
    {- ^ __Returns:__ a list of the children on /@settings@/ -}
settingsSchemaListChildren schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    result <- g_settings_schema_list_children schema'
    checkUnexpectedReturnNULL "settingsSchemaListChildren" result
    result' <- unpackZeroTerminatedUTF8CArray result
    mapZeroTerminatedCArray freeMem result
    freeMem result
    touchManagedPtr schema
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaListChildrenMethodInfo
instance (signature ~ (m [T.Text]), MonadIO m) => O.MethodInfo SettingsSchemaListChildrenMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaListChildren

#endif

-- method SettingsSchema::list_keys
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TCArray True (-1) (-1) (TBasicType TUTF8))
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_list_keys" g_settings_schema_list_keys :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO (Ptr CString)

{- |
Introspects the list of keys on /@schema@/.

You should probably not be calling this function from \"normal\" code
(since you should already know what keys are in your schema).  This
function is intended for introspection reasons.

/Since: 2.46/
-}
settingsSchemaListKeys ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m [T.Text]
    {- ^ __Returns:__ a list of the keys on
  /@schema@/ -}
settingsSchemaListKeys schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    result <- g_settings_schema_list_keys schema'
    checkUnexpectedReturnNULL "settingsSchemaListKeys" result
    result' <- unpackZeroTerminatedUTF8CArray result
    mapZeroTerminatedCArray freeMem result
    freeMem result
    touchManagedPtr schema
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaListKeysMethodInfo
instance (signature ~ (m [T.Text]), MonadIO m) => O.MethodInfo SettingsSchemaListKeysMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaListKeys

#endif

-- method SettingsSchema::ref
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Just (TInterface (Name {namespace = "Gio", name = "SettingsSchema"}))
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_ref" g_settings_schema_ref :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO (Ptr SettingsSchema)

{- |
Increase the reference count of /@schema@/, returning a new reference.

/Since: 2.32/
-}
settingsSchemaRef ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m SettingsSchema
    {- ^ __Returns:__ a new reference to /@schema@/ -}
settingsSchemaRef schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    result <- g_settings_schema_ref schema'
    checkUnexpectedReturnNULL "settingsSchemaRef" result
    result' <- (wrapBoxed SettingsSchema) result
    touchManagedPtr schema
    return result'

#if ENABLE_OVERLOADING
data SettingsSchemaRefMethodInfo
instance (signature ~ (m SettingsSchema), MonadIO m) => O.MethodInfo SettingsSchemaRefMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaRef

#endif

-- method SettingsSchema::unref
-- method type : OrdinaryMethod
-- Args : [Arg {argCName = "schema", argType = TInterface (Name {namespace = "Gio", name = "SettingsSchema"}), direction = DirectionIn, mayBeNull = False, argDoc = Documentation {rawDocText = Just "a #GSettingsSchema", sinceVersion = Nothing}, argScope = ScopeTypeInvalid, argClosure = -1, argDestroy = -1, argCallerAllocates = False, transfer = TransferNothing}]
-- Lengths : []
-- returnType : Nothing
-- throws : False
-- Skip return : False

foreign import ccall "g_settings_schema_unref" g_settings_schema_unref :: 
    Ptr SettingsSchema ->                   -- schema : TInterface (Name {namespace = "Gio", name = "SettingsSchema"})
    IO ()

{- |
Decrease the reference count of /@schema@/, possibly freeing it.

/Since: 2.32/
-}
settingsSchemaUnref ::
    (B.CallStack.HasCallStack, MonadIO m) =>
    SettingsSchema
    {- ^ /@schema@/: a 'GI.Gio.Structs.SettingsSchema.SettingsSchema' -}
    -> m ()
settingsSchemaUnref schema = liftIO $ do
    schema' <- unsafeManagedPtrGetPtr schema
    g_settings_schema_unref schema'
    touchManagedPtr schema
    return ()

#if ENABLE_OVERLOADING
data SettingsSchemaUnrefMethodInfo
instance (signature ~ (m ()), MonadIO m) => O.MethodInfo SettingsSchemaUnrefMethodInfo SettingsSchema signature where
    overloadedMethod _ = settingsSchemaUnref

#endif

#if ENABLE_OVERLOADING
type family ResolveSettingsSchemaMethod (t :: Symbol) (o :: *) :: * where
    ResolveSettingsSchemaMethod "hasKey" o = SettingsSchemaHasKeyMethodInfo
    ResolveSettingsSchemaMethod "listChildren" o = SettingsSchemaListChildrenMethodInfo
    ResolveSettingsSchemaMethod "listKeys" o = SettingsSchemaListKeysMethodInfo
    ResolveSettingsSchemaMethod "ref" o = SettingsSchemaRefMethodInfo
    ResolveSettingsSchemaMethod "unref" o = SettingsSchemaUnrefMethodInfo
    ResolveSettingsSchemaMethod "getId" o = SettingsSchemaGetIdMethodInfo
    ResolveSettingsSchemaMethod "getKey" o = SettingsSchemaGetKeyMethodInfo
    ResolveSettingsSchemaMethod "getPath" o = SettingsSchemaGetPathMethodInfo
    ResolveSettingsSchemaMethod l o = O.MethodResolutionFailed l o

instance (info ~ ResolveSettingsSchemaMethod t SettingsSchema, O.MethodInfo info SettingsSchema p) => OL.IsLabel t (SettingsSchema -> p) where
#if MIN_VERSION_base(4,10,0)
    fromLabel = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#else
    fromLabel _ = O.overloadedMethod (O.MethodProxy :: O.MethodProxy info)
#endif

#endif