Data.GI.Base.GVariant

This module contains some helper functions for dealing with GVariant values. The simplest way of dealing with them is by using the IsGVariant typeclass:

str <- fromGVariant variant :: IO (Maybe Text)

assuming that the variant is expected to contain a string in UTF8 encoding. The code becomes even shorter if the type checker can determine the return type for you:

readStringVariant :: GVariant -> IO Text
readStringVariant variant =
  fromGVariant variant >>= \case
     Nothing  -> error "Variant was not a string"
     Just str -> return str

Alternatively, you can use manually the gvariantFrom* and gvariantTo* family of functions.

Documentation

class IsGVariant a where

The typeclass for types that can be automatically marshalled into GVariant using toGVariant and fromGVariant.

Methods

toGVariant :: a -> IO GVariant

Convert a value of the given type into a GVariant.

fromGVariant :: GVariant -> IO (Maybe a)

Try to decode a GVariant into a target type. If the conversion fails we return Nothing. The type that was expected can be obtained by calling toGVariantFormatString, and the actual type as understood by the GVariant code can be obtained by calling gvariantToTypeString.

toGVariantFormatString :: a -> Text

The expected format string for this type (the argument is ignored).

Instances

IsGVariant Int16

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Int16 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Int16)

toGVariantFormatString :: Int16 -> Text

IsGVariant Int32

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Int32 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Int32)

toGVariantFormatString :: Int32 -> Text

IsGVariant Int64

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Int64 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Int64)

toGVariantFormatString :: Int64 -> Text

IsGVariant Word16

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Word16 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Word16)

toGVariantFormatString :: Word16 -> Text

IsGVariant Word32

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Word32 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Word32)

toGVariantFormatString :: Word32 -> Text

IsGVariant Word64

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Word64 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Word64)

toGVariantFormatString :: Word64 -> Text

IsGVariant Word8

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Word8 -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Word8)

toGVariantFormatString :: Word8 -> Text

IsGVariant ByteString

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: ByteString -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe ByteString)

toGVariantFormatString :: ByteString -> Text

IsGVariant GVariant

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariant -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariant)

toGVariantFormatString :: GVariant -> Text

IsGVariant GVariantHandle

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantHandle -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantHandle)

toGVariantFormatString :: GVariantHandle -> Text

IsGVariant GVariantObjectPath

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantObjectPath -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantObjectPath)

toGVariantFormatString :: GVariantObjectPath -> Text

IsGVariant GVariantSignature

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantSignature -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantSignature)

toGVariantFormatString :: GVariantSignature -> Text

IsGVariant Text

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Text -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Text)

toGVariantFormatString :: Text -> Text

IsGVariant ()

The empty tuple GVariant, mostly useful for type checking.

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: () -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe ())

toGVariantFormatString :: () -> Text

IsGVariant Bool

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Bool -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Bool)

toGVariantFormatString :: Bool -> Text

IsGVariant Double

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Double -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe Double)

toGVariantFormatString :: Double -> Text

IsGVariant a => IsGVariant (GVariantSinglet a)

One element tuples.

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantSinglet a -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (GVariantSinglet a))

toGVariantFormatString :: GVariantSinglet a -> Text

IsGVariant a => IsGVariant (Maybe a)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Maybe a -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (Maybe a))

toGVariantFormatString :: Maybe a -> Text

IsGVariant a => IsGVariant [a]

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: [a] -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe [a])

toGVariantFormatString :: [a] -> Text

(IsGVariant a, IsGVariantBasicType a, IsGVariant b) => IsGVariant (Map a b)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: Map a b -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (Map a b))

toGVariantFormatString :: Map a b -> Text

(IsGVariant a, IsGVariantBasicType a, IsGVariant b) => IsGVariant (GVariantDictEntry a b)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantDictEntry a b -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (GVariantDictEntry a b))

toGVariantFormatString :: GVariantDictEntry a b -> Text

(IsGVariant a, IsGVariant b) => IsGVariant (a, b)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: (a, b) -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (a, b))

toGVariantFormatString :: (a, b) -> Text

(IsGVariant a, IsGVariant b, IsGVariant c) => IsGVariant (a, b, c)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: (a, b, c) -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (a, b, c))

toGVariantFormatString :: (a, b, c) -> Text

(IsGVariant a, IsGVariant b, IsGVariant c, IsGVariant d) => IsGVariant (a, b, c, d)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: (a, b, c, d) -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (a, b, c, d))

toGVariantFormatString :: (a, b, c, d) -> Text

(IsGVariant a, IsGVariant b, IsGVariant c, IsGVariant d, IsGVariant e) => IsGVariant (a, b, c, d, e)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: (a, b, c, d, e) -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (a, b, c, d, e))

toGVariantFormatString :: (a, b, c, d, e) -> Text

class Ord a => IsGVariantBasicType a

The typeclass for basic type GVariant types, i.e. those that are not containers.

Instances

IsGVariantBasicType Int16

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Int32

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Int64

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Word16

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Word32

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Word64

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Word8

Defined in Data.GI.Base.GVariant

IsGVariantBasicType GVariantHandle

Defined in Data.GI.Base.GVariant

IsGVariantBasicType GVariantObjectPath

Defined in Data.GI.Base.GVariant

IsGVariantBasicType GVariantSignature

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Text

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Bool

Defined in Data.GI.Base.GVariant

IsGVariantBasicType Double

Defined in Data.GI.Base.GVariant

noGVariant :: Maybe GVariant

An alias for Nothing :: Maybe GVariant to save some typing.

gvariantGetTypeString :: GVariant -> IO Text

Get the expected type of a GVariant, in GVariant notation. See https://developer.gnome.org/glib/stable/glib-GVariantType.html for the meaning of the resulting format string.

Type wrappers

Some GVariant types are isomorphic to Haskell types, but they carry some extra information. For example, there is a tuple singlet type, which is isomorphic to a single Haskell value with the added bit of information that it is wrapped in a tuple container. In order to use these values you can use the following wrappers, which allow the IsGVariant instance to disambiguate the requested type properly.

newtype GVariantSinglet a

Haskell has no notion of one element tuples, but GVariants do, so the following allows for marshalling one element tuples properly using fromGVariant and toGVariant. For instance, to construct a single element tuple containing a string, you could do

toGVariant (GVariantSinglet "Test")

Constructors

GVariantSinglet a

Instances

Show a => Show (GVariantSinglet a)

Defined in Data.GI.Base.GVariant

Methods

showsPrec :: Int -> GVariantSinglet a -> ShowS

show :: GVariantSinglet a -> String

showList :: [GVariantSinglet a] -> ShowS

Eq a => Eq (GVariantSinglet a)

Defined in Data.GI.Base.GVariant

Methods

(==) :: GVariantSinglet a -> GVariantSinglet a -> Bool

(/=) :: GVariantSinglet a -> GVariantSinglet a -> Bool

IsGVariant a => IsGVariant (GVariantSinglet a)

One element tuples.

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantSinglet a -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (GVariantSinglet a))

toGVariantFormatString :: GVariantSinglet a -> Text

data GVariantDictEntry key value

A DictEntry GVariant is isomorphic to a two-tuple. Wrapping the values into a GVariantDictentry allows the IsGVariant instance to do the right thing.

Constructors

GVariantDictEntry key value

Instances

(Show key, Show value) => Show (GVariantDictEntry key value)

Defined in Data.GI.Base.GVariant

Methods

showsPrec :: Int -> GVariantDictEntry key value -> ShowS

show :: GVariantDictEntry key value -> String

showList :: [GVariantDictEntry key value] -> ShowS

(Eq key, Eq value) => Eq (GVariantDictEntry key value)

Defined in Data.GI.Base.GVariant

Methods

(==) :: GVariantDictEntry key value -> GVariantDictEntry key value -> Bool

(/=) :: GVariantDictEntry key value -> GVariantDictEntry key value -> Bool

(IsGVariant a, IsGVariantBasicType a, IsGVariant b) => IsGVariant (GVariantDictEntry a b)

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantDictEntry a b -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe (GVariantDictEntry a b))

toGVariantFormatString :: GVariantDictEntry a b -> Text

newtype GVariantHandle

Constructors

GVariantHandle Int32

Instances

Show GVariantHandle

Defined in Data.GI.Base.GVariant

Methods

showsPrec :: Int -> GVariantHandle -> ShowS

show :: GVariantHandle -> String

showList :: [GVariantHandle] -> ShowS

Eq GVariantHandle

Defined in Data.GI.Base.GVariant

Methods

(==) :: GVariantHandle -> GVariantHandle -> Bool

(/=) :: GVariantHandle -> GVariantHandle -> Bool

Ord GVariantHandle

Defined in Data.GI.Base.GVariant

Methods

compare :: GVariantHandle -> GVariantHandle -> Ordering

(<) :: GVariantHandle -> GVariantHandle -> Bool

(<=) :: GVariantHandle -> GVariantHandle -> Bool

(>) :: GVariantHandle -> GVariantHandle -> Bool

(>=) :: GVariantHandle -> GVariantHandle -> Bool

max :: GVariantHandle -> GVariantHandle -> GVariantHandle

min :: GVariantHandle -> GVariantHandle -> GVariantHandle

IsGVariant GVariantHandle

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantHandle -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantHandle)

toGVariantFormatString :: GVariantHandle -> Text

IsGVariantBasicType GVariantHandle

Defined in Data.GI.Base.GVariant

data GVariantObjectPath

An object representing a DBus object path, which is a particular type of GVariant too. (Just a string with some specific requirements.) In order to construct/deconstruct a GVariantObjectPath one can use newGVariantObjectPath and gvariantObjectPathToText.

Instances

Show GVariantObjectPath

Defined in Data.GI.Base.GVariant

Methods

showsPrec :: Int -> GVariantObjectPath -> ShowS

show :: GVariantObjectPath -> String

showList :: [GVariantObjectPath] -> ShowS

Eq GVariantObjectPath

Defined in Data.GI.Base.GVariant

Methods

(==) :: GVariantObjectPath -> GVariantObjectPath -> Bool

(/=) :: GVariantObjectPath -> GVariantObjectPath -> Bool

Ord GVariantObjectPath

Defined in Data.GI.Base.GVariant

Methods

compare :: GVariantObjectPath -> GVariantObjectPath -> Ordering

(<) :: GVariantObjectPath -> GVariantObjectPath -> Bool

(<=) :: GVariantObjectPath -> GVariantObjectPath -> Bool

(>) :: GVariantObjectPath -> GVariantObjectPath -> Bool

(>=) :: GVariantObjectPath -> GVariantObjectPath -> Bool

max :: GVariantObjectPath -> GVariantObjectPath -> GVariantObjectPath

min :: GVariantObjectPath -> GVariantObjectPath -> GVariantObjectPath

IsGVariant GVariantObjectPath

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantObjectPath -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantObjectPath)

toGVariantFormatString :: GVariantObjectPath -> Text

IsGVariantBasicType GVariantObjectPath

Defined in Data.GI.Base.GVariant

newGVariantObjectPath :: Text -> Maybe GVariantObjectPath

Try to construct a DBus object path. If the passed string is not a valid object path Nothing will be returned.

gvariantObjectPathToText :: GVariantObjectPath -> Text

Return the Text representation of a GVariantObjectPath.

data GVariantSignature

An object representing a DBus signature, which is a particular type of GVariant too. (Just a string with some specific requirements.) In order to construct/deconstruct a GVariantSignature one can use newGVariantSignature and gvariantSignatureToText.

Instances

Show GVariantSignature

Defined in Data.GI.Base.GVariant

Methods

showsPrec :: Int -> GVariantSignature -> ShowS

show :: GVariantSignature -> String

showList :: [GVariantSignature] -> ShowS

Eq GVariantSignature

Defined in Data.GI.Base.GVariant

Methods

(==) :: GVariantSignature -> GVariantSignature -> Bool

(/=) :: GVariantSignature -> GVariantSignature -> Bool

Ord GVariantSignature

Defined in Data.GI.Base.GVariant

Methods

compare :: GVariantSignature -> GVariantSignature -> Ordering

(<) :: GVariantSignature -> GVariantSignature -> Bool

(<=) :: GVariantSignature -> GVariantSignature -> Bool

(>) :: GVariantSignature -> GVariantSignature -> Bool

(>=) :: GVariantSignature -> GVariantSignature -> Bool

max :: GVariantSignature -> GVariantSignature -> GVariantSignature

min :: GVariantSignature -> GVariantSignature -> GVariantSignature

IsGVariant GVariantSignature

Defined in Data.GI.Base.GVariant

Methods

toGVariant :: GVariantSignature -> IO GVariant

fromGVariant :: GVariant -> IO (Maybe GVariantSignature)

toGVariantFormatString :: GVariantSignature -> Text

IsGVariantBasicType GVariantSignature

Defined in Data.GI.Base.GVariant

newGVariantSignature :: Text -> Maybe GVariantSignature

Try to construct a DBus object path. If the passed string is not a valid DBus signature Nothing will be returned.

gvariantSignatureToText :: GVariantSignature -> Text

Return the Text representation of a GVariantSignature.

Manual memory management

wrapGVariantPtr :: Ptr GVariant -> IO GVariant

Take ownership of a passed in Ptr (typically created just for us, so if it is floating we sink it).

newGVariantFromPtr :: Ptr GVariant -> IO GVariant

Construct a Haskell wrapper for the given GVariant, without assuming ownership.

unrefGVariant :: GVariant -> IO ()

Remove a reference to the given GVariant.

disownGVariant :: GVariant -> IO (Ptr GVariant)

Disown a GVariant, i.e. do not unref the underlying object when the Haskell object is garbage collected.

Manual conversions

Basic types

The use of these should be fairly self-explanatory. If you want to convert a Haskell type into a GVariant, use gvariantTo*. If you want to convert a GVariant into a Haskell type, use gvariantFrom*. The conversion can fail if the GVariant is not of the expected type (if you want to convert a GVariant containing a Int16 into a Text value, say), in which case Nothing will be returned.

gvariantToBool :: GVariant -> IO (Maybe Bool)

gvariantFromBool :: Bool -> IO GVariant

gvariantToWord8 :: GVariant -> IO (Maybe Word8)

gvariantFromWord8 :: Word8 -> IO GVariant

gvariantToInt16 :: GVariant -> IO (Maybe Int16)

gvariantFromInt16 :: Int16 -> IO GVariant

gvariantToWord16 :: GVariant -> IO (Maybe Word16)

gvariantFromWord16 :: Word16 -> IO GVariant

gvariantToInt32 :: GVariant -> IO (Maybe Int32)

gvariantFromInt32 :: Int32 -> IO GVariant

gvariantToWord32 :: GVariant -> IO (Maybe Word32)

gvariantFromWord32 :: Word32 -> IO GVariant

gvariantToInt64 :: GVariant -> IO (Maybe Int64)

gvariantFromInt64 :: Int64 -> IO GVariant

gvariantToWord64 :: GVariant -> IO (Maybe Word64)

gvariantFromWord64 :: Word64 -> IO GVariant

gvariantToHandle :: GVariant -> IO (Maybe Int32)

Extract the DBus handle (an Int32) inside a GVariant.

gvariantFromHandle :: Int32 -> IO GVariant

Convert a DBus handle (an Int32) into a GVariant.

gvariantToDouble :: GVariant -> IO (Maybe Double)

gvariantFromDouble :: Double -> IO GVariant

gvariantToText :: GVariant -> IO (Maybe Text)

Decode an UTF-8 encoded string GVariant into Text.

gvariantFromText :: Text -> IO GVariant

Encode a Text into an UTF-8 encoded string GVariant.

gvariantToObjectPath :: GVariant -> IO (Maybe Text)

Extract a GVariantObjectPath from a GVariant, represented as its underlying Text representation.

gvariantFromObjectPath :: GVariantObjectPath -> IO GVariant

Construct a GVariant containing an object path. In order to build a GVariantObjectPath value see newGVariantObjectPath.

gvariantToSignature :: GVariant -> IO (Maybe Text)

Extract a GVariantSignature from a GVariant, represented as Text.

gvariantFromSignature :: GVariantSignature -> IO GVariant

Construct a GVariant containing an DBus signature. In order to build a GVariantSignature value see newGVariantSignature.

Container type conversions

gvariantToGVariant :: GVariant -> IO (Maybe GVariant)

Unbox a GVariant contained inside another GVariant.

gvariantFromGVariant :: GVariant -> IO GVariant

Box a GVariant inside another GVariant.

gvariantToBytestring :: GVariant -> IO (Maybe ByteString)

Extract a zero terminated list of bytes into a ByteString.

gvariantFromBytestring :: ByteString -> IO GVariant

Encode a ByteString into a list of bytes GVariant.

gvariantFromMaybe :: forall a. IsGVariant a => Maybe a -> IO GVariant

Convert a Maybe value into a corresponding GVariant of maybe type.

gvariantToMaybe :: forall a. IsGVariant a => GVariant -> IO (Maybe (Maybe a))

Try to decode a maybe GVariant into the corresponding Maybe type. If the conversion is successful this returns Just x, where x itself is of Maybe type. So, in particular, Just Nothing indicates a successful call, and means that the GVariant of maybe type was empty.

gvariantFromDictEntry :: (IsGVariant key, IsGVariantBasicType key, IsGVariant value) => key -> value -> IO GVariant

Construct a GVariant of type DictEntry from the given key and value. The key must be a basic GVariant type, i.e. not a container. This is determined by whether it belongs to the IsGVariantBasicType typeclass. On the other hand value is an arbitrary GVariant, and in particular it can be a container type.

gvariantToDictEntry :: forall key value. (IsGVariant key, IsGVariantBasicType key, IsGVariant value) => GVariant -> IO (Maybe (key, value))

Unpack a DictEntry variant into key and value, which are returned as a two element tuple in case of success.

gvariantFromMap :: (IsGVariant key, IsGVariantBasicType key, IsGVariant value) => Map key value -> IO GVariant

Pack a Map into a GVariant for dictionary type, which is just an array of GVariantDictEntry.

gvariantToMap :: forall key value. (IsGVariant key, IsGVariantBasicType key, IsGVariant value) => GVariant -> IO (Maybe (Map key value))

Unpack a GVariant into a Map. Notice that this assumes that all the elements in the GVariant array of GVariantDictEntry are of the same type, which is not necessary for a generic GVariant, so this is somewhat restrictive. For the general case it is necessary to use gvariantToList plus gvariantToDictEntry directly.

gvariantFromList :: forall a. IsGVariant a => [a] -> IO GVariant

Given a list of elements construct a GVariant array containing them.

gvariantToList :: forall a. IsGVariant a => GVariant -> IO (Maybe [a])

Unpack a GVariant array into its elements.

gvariantFromTuple :: [GVariant] -> IO GVariant

Given a list of GVariant, construct a GVariant tuple containing the elements in the list.

gvariantToTuple :: GVariant -> IO (Maybe [GVariant])

Extract the children of a GVariant tuple into a list.