zigxll

ZigXLL: Excel Custom Functions in Zig

ZigXLL is a Zig package designed to streamline the implementation of custom functions for Excel using the C SDK. This project leverages Zig's powerful C interoperability and compile-time capabilities to enhance the usability of the Excel C SDK.

Key Features

• C Performance Without C Complexity: Achieves high performance while maintaining a higher-level code approach without boilerplate code, enforcing memory handling rules.
• Zero Boilerplate: Saves time and effort by eliminating the need to manually export functions like xlAutoOpen or xlAutoClose; the framework takes care of it automatically.
• Automatic Discovery of Functions: Simplifies the process of adding functions to Excel with ExcelFunction(), making the integration seamless.
• Type Safety: Zig's type system ensures that types convert automatically to and from Excel values, enhancing reliability in data handling.
• Thread-Safe By Default: Functions can be marked as thread-safe, supporting multi-threaded routines without additional configuration.
• UTF-8 String Support: Developers can write Zig code using standard []u8 strings, with the framework managing the conversion to UTF-16 required by Excel.
• Comprehensive Error Handling: Zig's error types automatically translate to #VALUE! errors in Excel, simplifying error management within custom functions.
• Compile-Time Code Generation: Utilizes compile-time features to create concise code without sacrificing performance.

For more detailed information on the mechanics of the framework, refer to the guide on how it works.

Example Implementation

To demonstrate how to use ZigXLL, consider the following setup:

1. Add ZigXLL as a Dependency:

   .dependencies = .{
       .xll = .{
           .url = "https://github.com/alexjreid/zigxll/archive/refs/tags/v0.2.0.tar.gz",
           .hash = "...",
       },
   },
   

2. Create the build.zig File:

   const std = @import("std");
   
   pub fn build(b: *std.Build) void {
       const target = b.resolveTargetQuery(.{
           .cpu_arch = .x86_64,
           .os_tag = .windows,
           .abi = .msvc,
       });
       const optimize = b.standardOptimizeOption(.{ .preferred_optimize_mode = .ReleaseSmall });
       
       const user_module = b.createModule(.{
           .root_source_file = b.path("src/main.zig"),
           .target = target,
           .optimize = optimize,
           .strip = true,
       });
       
       const xll_build = @import("xll");
       const xll = xll_build.buildXll(b, .{
           .name = "my_functions",
           .user_module = user_module,
           .target = target,
           .optimize = optimize,
       });
       
       const install_xll = b.addInstallFile(xll.getEmittedBin(), "lib/my_functions.xll");
       b.getInstallStep().dependOn(&install_xll.step);
   }
   

3. Define Excel Functions in src/my_functions.zig:

   const std = @import("std");
   const xll = @import("xll");
   const ExcelFunction = xll.ExcelFunction;
   const ParamMeta = xll.ParamMeta;
   
   pub const add = ExcelFunction(.{
       .name = "add",
       .description = "Add two numbers",
       .category = "Zig Math",
       .params = &[_]ParamMeta{
           .{ .name = "a", .description = "First number" },
           .{ .name = "b", .description = "Second number" },
       },
       .func = addImpl,
   });
   
   fn addImpl(a: f64, b: f64) !f64 {
       return a + b;
   }
   

Supported Types

ZigXLL supports a variety of parameter and return types, including:

• Parameters: f64, bool, []const u8, [][]const f64, *XLOPER12
• Return Types: Same as parameters, providing robust flexibility for function definitions.

For further examples and built-in functions, refer to src/builtin_functions.zig.

Dependencies

This framework uses Microsoft Excel 2013 XLL SDK headers and libraries, which are necessary for building Excel add-ins. Instructions for obtaining these are included in the README.

ZigXLL is an innovative solution for those looking to harness the capabilities of Zig while enhancing the functionality of Excel through custom functions. For anyone interested in extending Excel with more advanced capabilities, ZigXLL provides the tools necessary to do so efficiently.