Crate gvdb

Read and write GVDB files

This crate allows you to read and write GVDB (GLib GVariant database) files. It can also parse GResource XML files and create the corresponding GResource binary

Examples

Load a GResource file from disk with GvdbFile

use std::path::PathBuf;
use gvdb::read::GvdbFile;

pub fn read_gresource_file() {
    let path = PathBuf::from("test-data/test3.gresource");
    let file = GvdbFile::from_file(&path).unwrap();
    let table = file.hash_table().unwrap();

    #[derive(serde::Deserialize, zvariant::Type)]
    struct SvgData {
        size: u32,
        flags: u32,
        content: Vec<u8>
    }
    
    let value = table
        .get_value("/gvdb/rs/test/online-symbolic.svg")
        .unwrap();
    let structure = zvariant::Structure::try_from(value).unwrap();
    let svg = structure.fields();
    let svg1_size = u32::try_from(&svg[0]).unwrap();
    let svg1_flags = u32::try_from(&svg[1]).unwrap();
    let svg1_content = <Vec<u8>>::try_from(svg[2].try_clone().unwrap()).unwrap();
    let svg1_str = std::str::from_utf8(&svg1_content[0..svg1_content.len() - 1]).unwrap();

    println!("{}", svg1_str);
}

Create a simple GVDB file with GvdbFileWriter

use gvdb::write::{GvdbFileWriter, GvdbHashTableBuilder};

fn create_gvdb_file() {
    let mut file_writer = GvdbFileWriter::new();
    let mut table_builder = GvdbHashTableBuilder::new();
    table_builder
           .insert_string("string", "test string")
           .unwrap();

    let mut table_builder_2 = GvdbHashTableBuilder::new();
    table_builder_2
        .insert("int", 42u32)
        .unwrap();

    table_builder
        .insert_table("table", table_builder_2)
        .unwrap();
    let file_data = file_writer.write_to_vec_with_table(table_builder).unwrap();
}

Features

By default, no features are enabled.

mmap

Use the memmap2 crate to read memory-mapped GVDB files.

glib

By default this crate uses the glib crate to allow reading and writing GVariant data to the gvdb files. By enabling this feature you can pass GVariants directly from the glib crate as well.

gresource

To be able to compile GResource files, the gresource feature must be enabled.

Macros

The gvdb-macros crate provides useful macros for GResource file creation.

About this crate

This is an implementation of the glib GVariant database file format in Rust. It includes a GResource XML parser and the ability to create compatible GResource files.

MSRV

The minimum supported rust version of this crate is 1.75.

Breaking changes

0.6

This crate now uses zvariant 4.0 and glib 0.19. The MSRV has been increased accordingly.

0.5

Added the mmap feature, disabled by default.

Example

Create a GResource file

Create a GResource file from XML with GResourceXMLDocument and GResourceBuilder.

Requires the gresource feature to be enabled.

#[cfg(feature = "gresource")]
mod gresource {
    use std::borrow::Cow;
    use std::path::PathBuf;
    use gvdb::gresource::GResourceBuilder;
    use gvdb::gresource::GResourceXMLDocument;
    use gvdb::read::GvdbFile;

    const GRESOURCE_XML: &str = "test-data/gresource/test3.gresource.xml";

    fn create_gresource() {
        let doc = GResourceXMLDocument::from_file(&PathBuf::from(GRESOURCE_XML)).unwrap();
        let builder = GResourceBuilder::from_xml(doc).unwrap();
        let data = builder.build().unwrap();
        
        // To immediately read this data again, we can create a file reader from the data
        let root = GvdbFile::from_bytes(Cow::Owned(data)).unwrap();
    }
}

Create a simple GVDB file with GvdbFileWriter

use gvdb::write::{GvdbFileWriter, GvdbHashTableBuilder};

fn create_gvdb_file() {
    let mut file_writer = GvdbFileWriter::new();
    let mut table_builder = GvdbHashTableBuilder::new();
    table_builder
           .insert_string("string", "test string")
           .unwrap();
    let mut table_builder_2 = GvdbHashTableBuilder::new();
    table_builder_2
        .insert("int", 42u32)
        .unwrap();

    table_builder
        .insert_table("table", table_builder_2)
        .unwrap();
    let file_data = file_writer.write_to_vec_with_table(table_builder).unwrap();
}

Read a GVDB file

The stored data at /gvdb/rs/test/online-symbolic.svg corresponds to the (uuay) GVariant type signature.

use gvdb::read::GvdbFile;
use std::path::PathBuf;

pub fn main() {
    let path = PathBuf::from("test-data/test3.gresource");
    let file = GvdbFile::from_file(&path).unwrap();
    let table = file.hash_table().unwrap();

    #[derive(zvariant::OwnedValue)]
    struct GResourceData {
        size: u32,
        flags: u32,
        content: Vec<u8>,
    }

    let svg1: GResourceData = table.get("/gvdb/rs/test/online-symbolic.svg").unwrap();

    assert_eq!(svg1.size, 1390);
    assert_eq!(svg1.flags, 0);
    assert_eq!(svg1.size as usize, svg1.content.len() - 1);

    // Ensure the last byte is zero because of zero-padding defined in the format
    assert_eq!(svg1.content[svg1.content.len() - 1], 0);
    let svg1_str = std::str::from_utf8(&svg1.content[0..svg1.content.len() - 1]).unwrap();

    println!("{}", svg1_str);
}

License

gvdb and gvdb-macros are available under the MIT license. See the LICENSE.md file for more info.

SVG icon files included in test-data/gresource/icons/ are available under the CC0 license and redistributed from Icon Development Kit. See the LICENSE.Icons.md and file for more info.

Modules

• gresource
  Read GResource XML files and compile a GResource file
• read
  Read GVDB files from a file or from a byte slice
• write
  Create GVDB files