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
    /// [`file_set_contents()`][crate::file_set_contents()].
    ///
    /// If you need stricter guarantees about durability of
    /// the written file than are provided by [`file_set_contents()`][crate::file_set_contents()], use
    /// [`file_set_contents_full()`][crate::file_set_contents_full()] with the return value of
    /// [`to_data()`][Self::to_data()].
    ///
    /// This function can fail for any of the reasons that
    /// [`file_set_contents()`][crate::file_set_contents()] may fail.
    /// ## `filename`
    /// the name of the file to write to
    ///
    /// # Returns
    ///
    /// true if successful, false otherwise
    #[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))
            }
        }
    }

    /// Looks for a key file named @file in the paths returned from
    /// [`user_data_dir()`][crate::user_data_dir()] and [`system_data_dirs()`][crate::system_data_dirs()].
    ///
    /// The search algorithm from [`load_from_dirs()`][Self::load_from_dirs()] is used. If
    /// @file is found, it’s loaded into @self and its full path is returned in
    /// @full_path.
    ///
    /// If the file could not be loaded then either a [`FileError`][crate::FileError] or
    /// [`KeyFileError`][crate::KeyFileError] is returned.
    /// ## `file`
    /// a relative path to a filename to open and parse
    /// ## `flags`
    /// flags from [`KeyFileFlags`][crate::KeyFileFlags]
    ///
    /// # 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 `NULL` to ignore
    #[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))
            }
        }
    }

    /// 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.
    ///
    /// @search_dirs are checked in the order listed in the array, with the highest
    /// priority directory listed first. Within each directory, @file is looked for.
    /// If it’s not found, `-` characters in @file are progressively replaced with
    /// directory separators to search subdirectories of the search directory. If the
    /// file has not been found after all `-` characters have been replaced, the next
    /// search directory in @search_dirs is checked.
    ///
    /// If the file could not be found in any of the @search_dirs,
    /// [error@GLib.KeyFileError.NOT_FOUND] is returned. If
    /// the file is found but the OS returns an error when opening or reading the
    /// file, a [`FileError`][crate::FileError] is returned. If there is a problem parsing the
    /// file, a [`KeyFileError`][crate::KeyFileError] is returned.
    /// ## `file`
    /// a relative path to a filename to open and parse
    /// ## `search_dirs`
    /// `NULL`-terminated
    ///    array of directories to search
    /// ## `flags`
    /// flags from [`KeyFileFlags`][crate::KeyFileFlags]
    ///
    /// # 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 `NULL` to ignore
    #[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))
            }
        }
    }

    /// Outputs @self as a string.
    ///
    /// Note that this function never reports an error.
    ///
    /// # Returns
    ///
    /// a newly allocated string holding the contents of the key file
    ///
    /// ## `length`
    /// return location for the length of the
    ///   returned string, or `NULL` to ignore
    #[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 `NULL`-terminated, so
    /// @length may optionally be `NULL`.
    ///
    /// # Returns
    ///
    /// a newly-allocated
    ///    `NULL`-terminated array of strings. Use `strfreev()` to free it.
    ///
    /// ## `length`
    /// return location for the number of returned groups,
    ///    or `NULL` to ignore
    #[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 `NULL`-terminated, so @length may
    /// optionally be `NULL`. If the @group_name cannot be found,
    /// [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
    /// ## `group_name`
    /// a group name
    ///
    /// # Returns
    ///
    /// a newly-allocated
    ///    `NULL`-terminated array of strings. Use `strfreev()` to free it.
    ///
    /// ## `length`
    /// return location for the number of keys returned,
    ///    or `NULL` to ignore
    #[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 [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. Likewise, if the value associated with @key cannot be interpreted
    /// as a boolean then [error@GLib.KeyFileError.INVALID_VALUE] is returned.
    /// ## `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 [`Error`][crate::Error]
    /// strictly;
    /// the return value both carries meaning and signals an error.  To use
    /// this function, you must pass a [`Error`][crate::Error] pointer in @error, and
    /// check whether it is not `NULL` to see if an error occurred.
    ///
    /// Language bindings should use [`value()`][Self::value()] to test whether
    /// 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 [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. Likewise, if the values associated with @key cannot be interpreted
    /// as booleans then [error@GLib.KeyFileError.INVALID_VALUE] is returned.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///    the values associated with the key as a list of booleans, or `NULL` if the
    ///    key was not found or could not be parsed. The returned list of booleans
    ///    should be freed with `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 [`value()`][Self::value()], this function handles escape
    /// sequences like `\s`.
    ///
    /// If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. If the @group_name cannot be found,
    /// [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    /// a newly allocated string or `NULL` 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.
    ///
    /// If the key cannot be found, [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. If the @group_name cannot be found,
    /// [error@GLib.KeyFileError.GROUP_NOT_FOUND] is returned.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    ///
    /// # Returns
    ///
    ///
    ///  a `NULL`-terminated string array or `NULL` if the specified
    ///  key cannot be found. The array should be freed with `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 `C` then the untranslated value is returned (since GLib 2.84).
    ///
    /// If @locale is `NULL` then the current locale is assumed.
    ///
    /// If @locale is to be non-`NULL`, or if the current locale will change over
    /// the lifetime of the [`KeyFile`][crate::KeyFile], it must be loaded with
    /// [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all
    /// locales.
    ///
    /// If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. 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 `NULL` to use the current locale
    ///
    /// # Returns
    ///
    /// a newly allocated string or `NULL` 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 `C` then the untranslated value is returned (since GLib 2.84).
    ///
    /// If @locale is `NULL` then the current locale is assumed.
    ///
    /// If @locale is to be non-`NULL`, or if the current locale will change over
    /// the lifetime of the [`KeyFile`][crate::KeyFile], it must be loaded with
    /// [flags@GLib.KeyFileFlags.KEEP_TRANSLATIONS] in order to load strings for all
    /// locales.
    ///
    /// If @key cannot be found then [error@GLib.KeyFileError.KEY_NOT_FOUND] is
    /// returned. 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 `NULL`-terminated, so @length may optionally
    /// be `NULL`.
    /// ## `group_name`
    /// a group name
    /// ## `key`
    /// a key
    /// ## `locale`
    /// a locale identifier or `NULL` to use the current locale
    ///
    /// # Returns
    ///
    ///
    ///    a newly allocated `NULL`-terminated string array or `NULL` if the key
    ///    isn’t found. The string array should be freed with `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))
            }
        }
    }
}