mcp-vala/src/types/variant_utils.vala

/*
 * Copyright (C) 2025 Mcp-Vala Project
 *
 * This library is free software; you can redistribute it and/or
 * modify it under the terms of the GNU Lesser General Public
 * License as published by the Free Software Foundation; either
 * version 2.1 of the License, or (at your option) any later version.
 *
 * This library is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU
 * Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public
 * License along with this library; if not, write to the Free Software
 * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston, MA  02110-1301  USA
 *
 * Author: Mcp-Vala Project
 */

/**
 * Utility functions for GLib.Variant operations.
 * 
 * This namespace provides helper methods for common Variant operations
 * to reduce code duplication and improve robustness.
 */
namespace Mcp.Types.VariantUtils {
    /**
     * Creates a new empty dictionary variant.
     * 
     * @return A new empty dictionary variant (a{sv})
     */
    public static Variant new_empty_dict () {
        return new Variant ("a{sv}", new VariantBuilder (new VariantType ("a{sv}")));
    }
    
    /**
     * Creates a new dictionary variant with a single key-value pair.
     * 
     * @param key The key for dictionary entry
     * @param value The value for dictionary entry
     * @return A new dictionary variant with key-value pair
     */
    public static Variant new_single_entry_dict (string key, Variant value) {
        var builder = new VariantBuilder (VariantType.VARDICT);
        builder.add ("{sv}", key, value);
        return builder.end ();
    }
    
    /**
     * Creates a new string variant with null checking.
     * 
     * @param str The string value (can be null)
     * @return A new string variant or null if input was null
     */
    public static Variant? new_string_variant (string? str) {
        if (str == null) {
            return null;
        }
        return new Variant.string (str);
    }
    
    /**
     * Safely gets a string value from a variant with null checking.
     * 
     * @param variant The variant to extract from
     * @param key The key to look up
     * @return The string value or null if not found
     */
    public static string? get_string_safe (Variant variant, string key) {
        var value = variant.lookup_value (key, VariantType.STRING);
        return value != null ? value.get_string () : null;
    }
    
    /**
     * Safely gets a boolean value from a variant with null checking.
     * 
     * @param variant The variant to extract from
     * @param key The key to look up
     * @param default_value The default value if not found
     * @return The boolean value
     */
    public static bool get_boolean_safe (Variant variant, string key, bool default_value = false) {
        var value = variant.lookup_value (key, VariantType.BOOLEAN);
        return value != null ? value.get_boolean () : default_value;
    }
    
    /**
     * Safely gets an int64 value from a variant with null checking.
     * 
     * @param variant The variant to extract from
     * @param key The key to look up
     * @param default_value The default value if not found
     * @return The int64 value
     */
    public static int64 get_int64_safe (Variant variant, string key, int64 default_value = 0) {
        var value = variant.lookup_value (key, VariantType.INT64);
        return value != null ? value.get_int64 () : default_value;
    }
    
    /**
     * Safely gets a dictionary value from a variant with null checking.
     * 
     * @param variant The variant to extract from
     * @param key The key to look up
     * @return The dictionary variant or null if not found
     */
    public static Variant? get_dict_safe (Variant variant, string key) {
        return variant.lookup_value (key, VariantType.VARDICT);
    }
    
    /**
     * Adds a string value to a dictionary builder if string is not null.
     * 
     * @param builder The dictionary builder
     * @param key The key for entry
     * @param value The string value (can be null)
     */
    public static void add_string_if_not_null (VariantBuilder builder, string key, string? value) {
        if (value != null) {
            builder.add ("{sv}", key, new Variant.string (value));
        }
    }
    
    /**
     * Adds a variant value to a dictionary builder if variant is not null.
     * 
     * @param builder The dictionary builder
     * @param key The key for entry
     * @param value The variant value (can be null)
     */
    public static void add_variant_if_not_null (VariantBuilder builder, string key, Variant? value) {
        if (value != null) {
            builder.add ("{sv}", key, value);
        }
    }
    
    /**
     * Creates a new array builder for dictionaries.
     * 
     * @return A new array builder for dictionary arrays (aa{sv})
     */
    public static VariantBuilder new_dict_array_builder () {
        return new VariantBuilder (new VariantType ("aa{sv}"));
    }
    
    /**
     * Creates a new dictionary builder.
     * 
     * @return A new dictionary builder (a{sv})
     */
    public static VariantBuilder new_dict_builder () {
        return new VariantBuilder (VariantType.VARDICT);
    }
    
    /**
     * Safely creates a maybe string variant.
     * 
     * @param str The string value (can be null)
     * @return A maybe string variant
     */
    public static Variant new_maybe_string (string? str) {
        if (str == null) {
            return new Variant.maybe (VariantType.STRING, null);
        } else {
            return new Variant.maybe (VariantType.STRING, new Variant.string (str));
        }
    }
    
    /**
     * Checks if a variant is null or represents a null value.
     * 
     * @param variant The variant to check
     * @return True if variant is null or represents null
     */
    public static bool is_null_or_empty (Variant? variant) {
        if (variant == null) {
            return true;
        }
        
        // Check if it's a maybe type and is nothing
        if (variant.is_of_type (new VariantType ("m*"))) {
            return variant.get_maybe () == null;
        }
        
        return false;
    }
    
    /**
     * Creates a response variant with standard structure.
     * 
     * @param data The data to include in response
     * @return A formatted response variant
     */
    public static Variant create_response_variant (Variant data) {
        var builder = new_dict_builder ();
        builder.add ("{sv}", "result", data);
        return builder.end ();
    }
    
    /**
     * Creates an error response variant.
     * 
     * @param code The error code
     * @param message The error message
     * @return An error response variant
     */
    public static Variant create_error_variant (int code, string message) {
        var builder = new_dict_builder ();
        builder.add ("{sv}", "code", new Variant.int32 (code));
        builder.add ("{sv}", "message", new Variant.string (message));
        return builder.end ();
    }
}