glib/

key_file.rs

// Take a look at the license at the top of the repository in the LICENSE file.

use std::{mem, path, ptr};

use crate::{ffi, translate::*, Error, GString, GStringPtr, KeyFile, KeyFileFlags, PtrSlice};

impl KeyFile {
    /// Writes the contents of @self to @filename using
    /// g_file_set_contents(). If you need stricter guarantees about durability of
    /// the written file than are provided by g_file_set_contents(), use
    /// g_file_set_contents_full() with the return value of g_key_file_to_data().
    ///
    /// This function can fail for any of the reasons that
    /// g_file_set_contents() may fail.
    /// ## `filename`
    /// the name of the file to write to
    ///
    /// # Returns
    ///
    /// [`true`] if successful, else [`false`] with @error set
    #[doc(alias = "g_key_file_save_to_file")]
    pub fn save_to_file<T: AsRef<std::path::Path>>(&self, filename: T) -> Result<(), Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let _ = ffi::g_key_file_save_to_file(
                self.to_glib_none().0,
                filename.as_ref().to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(())
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// This function looks for a key file named @file in the paths
    /// returned from g_get_user_data_dir() and g_get_system_data_dirs(),
    /// loads the file into @self and returns the file's full path in
    /// @full_path.  If the file could not be loaded then an `error` is
    /// set to either a #GFileError or #GKeyFileError.
    /// ## `file`
    /// a relative path to a filename to open and parse
    /// ## `flags`
    /// flags from #GKeyFileFlags
    ///
    /// # Returns
    ///
    /// [`true`] if a key file could be loaded, [`false`] otherwise
    ///
    /// ## `full_path`
    /// return location for a string containing the full path
    ///   of the file, or [`None`]
    #[doc(alias = "g_key_file_load_from_data_dirs")]
    pub fn load_from_data_dirs<T: AsRef<std::path::Path>>(
        &self,
        file: T,
        flags: KeyFileFlags,
    ) -> Result<path::PathBuf, Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let mut full_path: *mut libc::c_char = ptr::null_mut();
            let _ = ffi::g_key_file_load_from_data_dirs(
                self.to_glib_none().0,
                file.as_ref().to_glib_none().0,
                &mut full_path,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                let path: GString = from_glib_full(full_path);
                Ok(path::PathBuf::from(&path))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// This function looks for a key file named @file in the paths
    /// specified in @search_dirs, loads the file into @self and
    /// returns the file's full path in @full_path.
    ///
    /// If the file could not be found in any of the @search_dirs,
    /// [`KeyFileError::NotFound`][crate::KeyFileError::NotFound] is returned. If
    /// the file is found but the OS returns an error when opening or reading the
    /// file, a `G_FILE_ERROR` is returned. If there is a problem parsing the file, a
    /// `G_KEY_FILE_ERROR` is returned.
    /// ## `file`
    /// a relative path to a filename to open and parse
    /// ## `search_dirs`
    /// [`None`]-terminated array of directories to search
    /// ## `flags`
    /// flags from #GKeyFileFlags
    ///
    /// # Returns
    ///
    /// [`true`] if a key file could be loaded, [`false`] otherwise
    ///
    /// ## `full_path`
    /// return location for a string containing the full path
    ///   of the file, or [`None`]
    #[doc(alias = "g_key_file_load_from_dirs")]
    pub fn load_from_dirs<T: AsRef<std::path::Path>, U: AsRef<std::path::Path>>(
        &self,
        file: T,
        search_dirs: &[U],
        flags: KeyFileFlags,
    ) -> Result<path::PathBuf, Error> {
        unsafe {
            let search_dirs: Vec<&std::path::Path> =
                search_dirs.iter().map(AsRef::as_ref).collect();
            let mut error = ptr::null_mut();
            let mut full_path: *mut libc::c_char = ptr::null_mut();
            let _ = ffi::g_key_file_load_from_dirs(
                self.to_glib_none().0,
                file.as_ref().to_glib_none().0,
                search_dirs.to_glib_none().0,
                &mut full_path,
                flags.into_glib(),
                &mut error,
            );
            if error.is_null() {
                let path: GString = from_glib_full(full_path);
                Ok(path::PathBuf::from(&path))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// This function outputs @self as a string.
    ///
    /// Note that this function never reports an error,
    /// so it is safe to pass [`None`] as @error.
    ///
    /// # Returns
    ///
    /// a newly allocated string holding
    ///   the contents of the #GKeyFile
    ///
    /// ## `length`
    /// return location for the length of the
    ///   returned string, or [`None`]
    #[doc(alias = "g_key_file_to_data")]
    pub fn to_data(&self) -> GString {
        unsafe {
            let ret =
                ffi::g_key_file_to_data(self.to_glib_none().0, ptr::null_mut(), ptr::null_mut());
            from_glib_full(ret)
        }
    }

    /// Returns all groups in the key file loaded with @self.
    /// The array of returned groups will be [`None`]-terminated, so
    /// @length may optionally be [`None`].
    ///
    /// # Returns
    ///
    /// a newly-allocated [`None`]-terminated array of strings.
    ///   Use g_strfreev() to free it.
    ///
    /// ## `length`
    /// return location for the number of returned groups, or [`None`]
    #[doc(alias = "g_key_file_get_groups")]
    #[doc(alias = "get_groups")]
    pub fn groups(&self) -> PtrSlice<GStringPtr> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();
            let ret = ffi::g_key_file_get_groups(self.to_glib_none().0, length.as_mut_ptr());
            FromGlibContainer::from_glib_full_num(ret, length.assume_init() as _)
        }
    }

    /// Returns all keys for the group name @group_name.  The array of
    /// returned keys will be [`None`]-terminated, so @length may
    /// optionally be [`None`]. In the event that the @group_name cannot
    /// be found, [`None`] is returned and @error is set to
    /// [`KeyFileError::GroupNotFound`][crate::KeyFileError::GroupNotFound].
    /// ## `group_name`
    /// a group name
    ///
    /// # Returns
    ///
    /// a newly-allocated [`None`]-terminated array of strings.
    ///     Use g_strfreev() to free it.
    ///
    /// ## `length`
    /// return location for the number of keys returned, or [`None`]
    #[doc(alias = "g_key_file_get_keys")]
    #[doc(alias = "get_keys")]
    pub fn keys(&self, group_name: &str) -> Result<PtrSlice<GStringPtr>, crate::Error> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_keys(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibContainer::from_glib_full_num(
                    ret,
                    length.assume_init() as _,
                ))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the value associated with @key under @group_name as a
    /// boolean.
    ///
    /// If @key cannot be found then [`false`] is returned and @error is set
    /// to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the value
    /// associated with @key cannot be interpreted as a boolean then [`false`]
    /// is returned and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// the value associated with the key as a boolean,
    ///    or [`false`] if the key was not found or could not be parsed.
    #[doc(alias = "g_key_file_get_boolean")]
    #[doc(alias = "get_boolean")]
    pub fn boolean(&self, group_name: &str, key: &str) -> Result<bool, Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_boolean(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Looks whether the key file has the key @key in the group
    /// @group_name.
    ///
    /// Note that this function does not follow the rules for #GError strictly;
    /// the return value both carries meaning and signals an error.  To use
    /// this function, you must pass a #GError pointer in @error, and check
    /// whether it is not [`None`] to see if an error occurred.
    ///
    /// Language bindings should use g_key_file_get_value() to test whether
    /// or not a key exists.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key name
    ///
    /// # Returns
    ///
    /// [`true`] if @key is a part of @group_name, [`false`] otherwise
    #[doc(alias = "g_key_file_has_key")]
    pub fn has_key(&self, group_name: &str, key: &str) -> Result<bool, Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_has_key(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib(ret))
            } else {
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the values associated with @key under @group_name as
    /// booleans.
    ///
    /// If @key cannot be found then [`None`] is returned and @error is set to
    /// [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. Likewise, if the values associated
    /// with @key cannot be interpreted as booleans then [`None`] is returned
    /// and @error is set to [`KeyFileError::InvalidValue`][crate::KeyFileError::InvalidValue].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///    the values associated with the key as a list of booleans, or [`None`] if the
    ///    key was not found or could not be parsed. The returned list of booleans
    ///    should be freed with g_free() when no longer needed.
    #[doc(alias = "g_key_file_get_boolean_list")]
    #[doc(alias = "get_boolean_list")]
    pub fn boolean_list(&self, group_name: &str, key: &str) -> Result<Vec<bool>, Error> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_boolean_list(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if !error.is_null() {
                return Err(from_glib_full(error));
            }
            Ok(FromGlibContainer::from_glib_container_num(
                ret,
                length.assume_init() as _,
            ))
        }
    }

    /// Returns the string value associated with @key under @group_name.
    /// Unlike g_key_file_get_value(), this function handles escape sequences
    /// like \s.
    ///
    /// In the event the key cannot be found, [`None`] is returned and
    /// @error is set to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound].  In the
    /// event that the @group_name cannot be found, [`None`] is returned
    /// and @error is set to [`KeyFileError::GroupNotFound`][crate::KeyFileError::GroupNotFound].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// a newly allocated string or [`None`] if the specified
    ///   key cannot be found.
    #[doc(alias = "g_key_file_get_string")]
    #[doc(alias = "get_string")]
    pub fn string(&self, group_name: &str, key: &str) -> Result<GString, Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_string(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                ffi::g_free(ret as *mut _);
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the values associated with @key under @group_name.
    ///
    /// In the event the key cannot be found, [`None`] is returned and
    /// @error is set to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound].  In the
    /// event that the @group_name cannot be found, [`None`] is returned
    /// and @error is set to [`KeyFileError::GroupNotFound`][crate::KeyFileError::GroupNotFound].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///  a [`None`]-terminated string array or [`None`] if the specified
    ///  key cannot be found. The array should be freed with g_strfreev().
    #[doc(alias = "g_key_file_get_string_list")]
    #[doc(alias = "get_string_list")]
    pub fn string_list(&self, group_name: &str, key: &str) -> Result<PtrSlice<GStringPtr>, Error> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_string_list(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibContainer::from_glib_full_num(
                    ret,
                    length.assume_init() as _,
                ))
            } else {
                ffi::g_strfreev(ret);
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the value associated with @key under @group_name
    /// translated in the given @locale if available.  If @locale is
    /// [`None`] then the current locale is assumed.
    ///
    /// If @locale is to be non-[`None`], or if the current locale will change over
    /// the lifetime of the #GKeyFile, it must be loaded with
    /// [`KeyFileFlags::KEEP_TRANSLATIONS`][crate::KeyFileFlags::KEEP_TRANSLATIONS] in order to load strings for all locales.
    ///
    /// If @key cannot be found then [`None`] is returned and @error is set
    /// to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. If the value associated
    /// with @key cannot be interpreted or no suitable translation can
    /// be found then the untranslated value is returned.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `locale`
    /// a locale identifier or [`None`]
    ///
    /// # Returns
    ///
    /// a newly allocated string or [`None`] if the specified
    ///   key cannot be found.
    #[doc(alias = "g_key_file_get_locale_string")]
    #[doc(alias = "get_locale_string")]
    pub fn locale_string(
        &self,
        group_name: &str,
        key: &str,
        locale: Option<&str>,
    ) -> Result<GString, Error> {
        unsafe {
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_locale_string(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                locale.to_glib_none().0,
                &mut error,
            );
            if error.is_null() {
                Ok(from_glib_full(ret))
            } else {
                ffi::g_free(ret as *mut _);
                Err(from_glib_full(error))
            }
        }
    }

    /// Returns the values associated with @key under @group_name
    /// translated in the given @locale if available.  If @locale is
    /// [`None`] then the current locale is assumed.
    ///
    /// If @locale is to be non-[`None`], or if the current locale will change over
    /// the lifetime of the #GKeyFile, it must be loaded with
    /// [`KeyFileFlags::KEEP_TRANSLATIONS`][crate::KeyFileFlags::KEEP_TRANSLATIONS] in order to load strings for all locales.
    ///
    /// If @key cannot be found then [`None`] is returned and @error is set
    /// to [`KeyFileError::KeyNotFound`][crate::KeyFileError::KeyNotFound]. If the values associated
    /// with @key cannot be interpreted or no suitable translations
    /// can be found then the untranslated values are returned. The
    /// returned array is [`None`]-terminated, so @length may optionally
    /// be [`None`].
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `locale`
    /// a locale identifier or [`None`]
    ///
    /// # Returns
    ///
    /// a newly allocated [`None`]-terminated string array
    ///   or [`None`] if the key isn't found. The string array should be freed
    ///   with g_strfreev().
    #[doc(alias = "g_key_file_get_locale_string_list")]
    #[doc(alias = "get_locale_string_list")]
    pub fn locale_string_list(
        &self,
        group_name: &str,
        key: &str,
        locale: Option<&str>,
    ) -> Result<PtrSlice<GStringPtr>, Error> {
        unsafe {
            let mut length = mem::MaybeUninit::uninit();
            let mut error = ptr::null_mut();
            let ret = ffi::g_key_file_get_locale_string_list(
                self.to_glib_none().0,
                group_name.to_glib_none().0,
                key.to_glib_none().0,
                locale.to_glib_none().0,
                length.as_mut_ptr(),
                &mut error,
            );
            if error.is_null() {
                Ok(FromGlibContainer::from_glib_full_num(
                    ret,
                    length.assume_init() as _,
                ))
            } else {
                ffi::g_strfreev(ret);
                Err(from_glib_full(error))
            }
        }
    }
}