alef 0.110.2

Opinionated polyglot binding generator for Rust libraries
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142

use super::files::csharp_file_header;

pub(super) fn generate(namespace: &str, library: &str, prefix: &str, exception: &str) -> String {
    format!(
        r#"{header}using System;
using System.Collections.Generic;
using System.Runtime.InteropServices;
using System.Text.Json;

namespace {namespace};

/// <summary>Verified downloadable native-component management.</summary>
public static class Components
{{
    private const string LibraryName = "{library}";

    /// <summary>Downloads, verifies, loads, and pins a configured component.</summary>
    public static void ComponentLoad(string component)
    {{
        var componentPointer = Marshal.StringToCoTaskMemUTF8(component);
        try
        {{
            if (NativeComponentLoad(componentPointer) != 0)
            {{
                throw LastComponentError();
            }}
        }}
        finally
        {{
            Marshal.FreeCoTaskMem(componentPointer);
        }}
    }}

    /// <summary>Downloads and verifies every configured component.</summary>
    public static IReadOnlyList<string> ComponentPrefetch() => ComponentPrefetch(null);

    /// <summary>Downloads and verifies one configured component.</summary>
    public static IReadOnlyList<string> ComponentPrefetch(string? component)
    {{
        var componentPointer = component is null ? IntPtr.Zero : Marshal.StringToCoTaskMemUTF8(component);
        try
        {{
            var result = NativeComponentPrefetch(componentPointer);
            var json = TakeNativeString(result);
            return JsonSerializer.Deserialize<string[]>(json)
                ?? throw new {exception}("component prefetch returned null JSON");
        }}
        finally
        {{
            if (componentPointer != IntPtr.Zero)
            {{
                Marshal.FreeCoTaskMem(componentPointer);
            }}
        }}
    }}

    /// <summary>Returns ready, cached, not_downloaded, bundled, or unsupported:&lt;reason&gt;.</summary>
    public static string ComponentStatus(string component) => CallNativeString(component, NativeComponentStatus);

    /// <summary>Returns the content-addressed cache path for a configured component.</summary>
    public static string ComponentCachePath(string component) => CallNativeString(component, NativeComponentCachePath);

    private static string CallNativeString(string component, Func<IntPtr, IntPtr> operation)
    {{
        var componentPointer = Marshal.StringToCoTaskMemUTF8(component);
        try
        {{
            return TakeNativeString(operation(componentPointer));
        }}
        finally
        {{
            Marshal.FreeCoTaskMem(componentPointer);
        }}
    }}

    private static string TakeNativeString(IntPtr result)
    {{
        if (result == IntPtr.Zero)
        {{
            throw LastComponentError();
        }}
        try
        {{
            return Marshal.PtrToStringUTF8(result)
                ?? throw new {exception}("component manager returned invalid UTF-8");
        }}
        finally
        {{
            NativeFreeString(result);
        }}
    }}

    private static {exception} LastComponentError()
    {{
        var code = NativeLastErrorCode();
        var context = NativeLastErrorContext();
        var message = context == IntPtr.Zero
            ? "component manager operation failed"
            : Marshal.PtrToStringUTF8(context) ?? "component manager returned invalid error context";
        return new {exception}(code, message);
    }}

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_component_load")]
    private static extern int NativeComponentLoad(IntPtr component);

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_component_prefetch")]
    private static extern IntPtr NativeComponentPrefetch(IntPtr component);

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_component_status")]
    private static extern IntPtr NativeComponentStatus(IntPtr component);

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_component_cache_path")]
    private static extern IntPtr NativeComponentCachePath(IntPtr component);

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_last_error_code")]
    private static extern int NativeLastErrorCode();

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_last_error_context")]
    private static extern IntPtr NativeLastErrorContext();

    [DllImport(LibraryName, CallingConvention = CallingConvention.Cdecl, EntryPoint = "{prefix}_free_string")]
    private static extern void NativeFreeString(IntPtr value);
}}
"#,
        header = csharp_file_header(),
    )
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn emits_csharp_pinvoke_component_manager() {
        let generated = generate("Demo", "demo_ffi", "demo", "DemoException");
        assert!(generated.contains("void ComponentLoad(string component)"));
        assert!(generated.contains("IReadOnlyList<string> ComponentPrefetch()"));
        assert!(generated.contains("string ComponentStatus(string component)"));
        assert!(generated.contains("EntryPoint = \"demo_component_cache_path\""));
        assert!(generated.contains("NativeFreeString(result)"));
    }
}