cs-binding-generator 1.0.1.dev39__tar.gz → 1.0.1.dev40__tar.gz

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cs_binding_generator
-Version: 1.0.1.dev39
+Version: 1.0.1.dev40
 Summary: Generate C# bindings from C headers using libclang with modern LibraryImport
 Author-email: Robin 'Ruadeil' Degen <mail@ruadeil.lgbt>
 License-Expression: MIT
@@ -50,6 +50,7 @@ The tool is configured primarily through XML configuration files, providing powe
 - **Removal Support**: Filter out unwanted functions, types, or patterns
 - **Compiler Defines**: Pass `-D` flags to libclang via `<define>` to enable optional API blocks and gate platform-specific code paths during parsing
 - **Flag Enum Marking**: Tag auto-discovered C enums with `[Flags]` via `<flags>`, with exact-name or regex matching
+- **UTF-8 Byte Overloads**: Opt in via `<utf8-byte-overloads/>` to emit a second `byte*`-param partial alongside every `string?`-param `[LibraryImport]`, so callers can hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to native code without re-encoding through a managed string
 - **Macro Constants**: Extract C `#define` constants as C# enums (numeric mode) or as UTF-8 `ReadOnlySpan<byte>` members (string mode). Object-like and function-like macros are recursively expanded, and C-style casts in macro values are stripped before the numeric check, so chains like `SDL_BUTTON_MASK(SDL_BUTTON_LEFT)` and values like `((SDL_AudioDeviceID) 0xFFFFFFFFu)` resolve cleanly.
 - **String Handling**: Provides both raw pointer and helper string methods for `char*` returns
 - **Struct Generation**: Creates explicit layout structs with proper field offsets

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/README.md

@@ -21,6 +21,7 @@ The tool is configured primarily through XML configuration files, providing powe
 - **Removal Support**: Filter out unwanted functions, types, or patterns
 - **Compiler Defines**: Pass `-D` flags to libclang via `<define>` to enable optional API blocks and gate platform-specific code paths during parsing
 - **Flag Enum Marking**: Tag auto-discovered C enums with `[Flags]` via `<flags>`, with exact-name or regex matching
+- **UTF-8 Byte Overloads**: Opt in via `<utf8-byte-overloads/>` to emit a second `byte*`-param partial alongside every `string?`-param `[LibraryImport]`, so callers can hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to native code without re-encoding through a managed string
 - **Macro Constants**: Extract C `#define` constants as C# enums (numeric mode) or as UTF-8 `ReadOnlySpan<byte>` members (string mode). Object-like and function-like macros are recursively expanded, and C-style casts in macro values are stripped before the numeric check, so chains like `SDL_BUTTON_MASK(SDL_BUTTON_LEFT)` and values like `((SDL_AudioDeviceID) 0xFFFFFFFFu)` resolve cleanly.
 - **String Handling**: Provides both raw pointer and helper string methods for `char*` returns
 - **Struct Generation**: Creates explicit layout structs with proper field offsets

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.0.1.dev39'
-__version_tuple__ = version_tuple = (1, 0, 1, 'dev39')
+__version__ = version = '1.0.1.dev40'
+__version_tuple__ = version_tuple = (1, 0, 1, 'dev40')
 
-__commit_id__ = commit_id = 'gb6b8a2450'
+__commit_id__ = commit_id = 'g7677f88ad'

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/code_generators.py

@@ -12,12 +12,23 @@ from .type_mapper import TypeMapper
 class CodeGenerator:
     """Generates C# code from libclang AST nodes"""
 
-    def __init__(self, type_mapper: TypeMapper, visibility: str = "public", skip_variadic: bool = False):
+    def __init__(
+        self,
+        type_mapper: TypeMapper,
+        visibility: str = "public",
+        skip_variadic: bool = False,
+        utf8_byte_overloads: bool = False,
+    ):
         self.type_mapper = type_mapper
         self.anonymous_enum_counter = 0
         self.visibility = visibility
         self.skip_variadic = skip_variadic
         self.has_variadic_functions = False
+        # When True, generate_function emits a parallel `byte*`-param overload alongside
+        # the primary `[LibraryImport]` for any function whose original signature contains
+        # a `string?` parameter. Lets callers pass pre-encoded UTF-8 buffers without the
+        # managed-string → UTF-8 re-encode round trip.
+        self.utf8_byte_overloads = utf8_byte_overloads
 
     def generate_function(self, cursor, library_name: str) -> str:
         """Generate C# LibraryImport for a function"""
@@ -100,6 +111,40 @@ class CodeGenerator:
             code = f"""    [LibraryImport("{library_name}", EntryPoint = "{original_func_name}", StringMarshalling = StringMarshalling.Utf8)]
     [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
 {return_marshal}    {self.visibility} static partial {result_type} {func_name}({params_str});
+"""
+
+        # Optional byte*-param overload. Emitted only when (a) the opt-in flag is set,
+        # (b) the function isn't variadic, and (c) at least one parameter was mapped to
+        # `string?`. The overload swaps every `string?` param for `byte*`, letting callers
+        # pass pre-encoded UTF-8 buffers (u8 literals, pinned spans) without re-encoding.
+        # The C# compiler picks between the two overloads by argument type at the call site.
+        if self.utf8_byte_overloads and not is_variadic_for_generation:
+            byte_params: list[str] = []
+            has_string_param = False
+            for i, arg in enumerate(cursor.get_arguments()):
+                arg_type = self.type_mapper.map_type(arg.type, is_return_type=False)
+                if arg_type is None:
+                    # If the primary emit accepted these params, the secondary should too.
+                    # Skip silently rather than emit a half-built overload.
+                    byte_params = []
+                    has_string_param = False
+                    break
+                arg_name = arg.spelling or f"param{i}"
+                arg_name = self._escape_keyword(arg_name)
+                if arg_type == "string?":
+                    has_string_param = True
+                    byte_params.append(f"byte* {arg_name}")
+                elif arg_type == "bool":
+                    byte_params.append(f"[MarshalAs(UnmanagedType.I1)] {arg_type} {arg_name}")
+                else:
+                    byte_params.append(f"{arg_type} {arg_name}")
+
+            if has_string_param:
+                byte_params_str = ", ".join(byte_params)
+                code += f"""
+    [LibraryImport("{library_name}", EntryPoint = "{original_func_name}", StringMarshalling = StringMarshalling.Utf8)]
+    [UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+{return_marshal}    {self.visibility} static partial {result_type} {func_name}({byte_params_str});
 """
 
         # Add helper function for char* return types (skip for variadic functions)

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/config.py

@@ -20,6 +20,7 @@ class BindingConfig:
     visibility: str = "public"
     global_constants: list[tuple[str, str, str, bool]] = field(default_factory=list)
     global_defines: list[tuple[str, str | None]] = field(default_factory=list)
+    utf8_byte_overloads: bool = False
 
 
 def parse_config_file(config_path):
@@ -103,6 +104,13 @@ def parse_config_file(config_path):
                 ((const_name or "").strip(), const_pattern.strip(), const_type, const_flags)
             )
 
+        # Opt-in: for every function that has at least one `string?` parameter (mapped
+        # from a C char* arg), emit a parallel byte*-param overload alongside the primary
+        # P/Invoke. Lets callers pass pre-encoded UTF-8 buffers (u8 literals, pinned spans)
+        # without the round trip through Encoding.UTF8 → marshaller → native.
+        if root.find("utf8-byte-overloads") is not None:
+            config.utf8_byte_overloads = True
+
         for library in root.findall("library"):
             library_name = library.get("name")
             if not library_name:

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/generator.py

@@ -779,6 +779,7 @@ class CSharpBindingsGenerator:
         visibility: str = "public",
         global_constants: Optional[list[tuple[str, str, str, bool]]] = None,
         global_defines: Optional[list[tuple[str, Optional[str]]]] = None,
+        utf8_byte_overloads: bool = False,
     ) -> dict[str, str]:
         """Generate C# bindings from C header file(s)
 
@@ -798,8 +799,10 @@ class CSharpBindingsGenerator:
         # Store visibility setting
         self.visibility = visibility
 
-        # Initialize code generator with visibility and skip_variadic flag
-        self.code_generator = CodeGenerator(self.type_mapper, visibility, skip_variadic)
+        # Initialize code generator with visibility, skip_variadic, and byte-overload flag
+        self.code_generator = CodeGenerator(
+            self.type_mapper, visibility, skip_variadic, utf8_byte_overloads
+        )
 
         # Store library class names
         self.library_class_names = library_class_names or {}

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator/main.py

@@ -126,6 +126,7 @@ Examples:
             visibility=config.visibility,
             global_constants=config.global_constants,
             global_defines=config.global_defines,
+            utf8_byte_overloads=config.utf8_byte_overloads,
         )
     except Exception as e:
         import traceback

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: cs_binding_generator
-Version: 1.0.1.dev39
+Version: 1.0.1.dev40
 Summary: Generate C# bindings from C headers using libclang with modern LibraryImport
 Author-email: Robin 'Ruadeil' Degen <mail@ruadeil.lgbt>
 License-Expression: MIT
@@ -50,6 +50,7 @@ The tool is configured primarily through XML configuration files, providing powe
 - **Removal Support**: Filter out unwanted functions, types, or patterns
 - **Compiler Defines**: Pass `-D` flags to libclang via `<define>` to enable optional API blocks and gate platform-specific code paths during parsing
 - **Flag Enum Marking**: Tag auto-discovered C enums with `[Flags]` via `<flags>`, with exact-name or regex matching
+- **UTF-8 Byte Overloads**: Opt in via `<utf8-byte-overloads/>` to emit a second `byte*`-param partial alongside every `string?`-param `[LibraryImport]`, so callers can hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to native code without re-encoding through a managed string
 - **Macro Constants**: Extract C `#define` constants as C# enums (numeric mode) or as UTF-8 `ReadOnlySpan<byte>` members (string mode). Object-like and function-like macros are recursively expanded, and C-style casts in macro values are stripped before the numeric check, so chains like `SDL_BUTTON_MASK(SDL_BUTTON_LEFT)` and values like `((SDL_AudioDeviceID) 0xFFFFFFFFu)` resolve cleanly.
 - **String Handling**: Provides both raw pointer and helper string methods for `char*` returns
 - **Struct Generation**: Creates explicit layout structs with proper field offsets

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/cs_binding_generator.egg-info/SOURCES.txt

@@ -60,5 +60,6 @@ tests/test_removal.py
 tests/test_renaming.py
 tests/test_type_mapper.py
 tests/test_type_mapping_extended.py
+tests/test_utf8_byte_overloads.py
 tests/test_variadic_functions.py
 tests/test_xml_config.py

{cs_binding_generator-1.0.1.dev39 → cs_binding_generator-1.0.1.dev40}/docs/XML_CONFIG.md

@@ -240,6 +240,55 @@ public enum WindowFlags : ulong
 }
 ```
 
+### UTF-8 Byte Overloads: `<utf8-byte-overloads/>`
+
+Opt in to a second `[LibraryImport]` partial method for every non-variadic function
+whose primary signature contains at least one `string?` parameter. The overload
+swaps every `string?` for `byte*`, letting callers pass pre-encoded UTF-8 buffers
+(u8 literals, pinned `ReadOnlySpan<byte>`, `byte[]` via `fixed`) to native code
+without the `string` → marshaller → UTF-8 round trip.
+
+**Attributes:** none. Presence of the element enables the feature.
+
+```xml
+<bindings>
+    <utf8-byte-overloads/>
+    <library name="SDL3" namespace="MyApp">
+        <include file="/usr/include/SDL3/SDL.h"/>
+    </library>
+</bindings>
+```
+
+**Example:**
+
+Input C:
+```c
+int SDL_SetStringProperty(unsigned int props, const char* name, const char* value);
+```
+
+Generated C# (both partials reference the same native symbol):
+```csharp
+[LibraryImport("SDL3", EntryPoint = "SDL_SetStringProperty", StringMarshalling = StringMarshalling.Utf8)]
+[UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+public static partial int SDL_SetStringProperty(uint props, string? name, string? value);
+
+[LibraryImport("SDL3", EntryPoint = "SDL_SetStringProperty", StringMarshalling = StringMarshalling.Utf8)]
+[UnmanagedCallConv(CallConvs = [typeof(CallConvCdecl)])]
+public static partial int SDL_SetStringProperty(uint props, byte* name, byte* value);
+```
+
+Caller:
+```csharp
+fixed (byte* p = "SDL.gpu.shader.create.name"u8)
+fixed (byte* v = nameBytes)
+    SDL_SetStringProperty(props, p, v);
+```
+
+The C# compiler resolves overloads by argument type. The overload is only emitted
+for non-variadic functions that have at least one `string?` param — functions with
+no string params are left as-is. Non-string parameters (including bool with its
+`[MarshalAs(UnmanagedType.I1)]` attribute) are forwarded verbatim into the overload.
+
 ### Flag Enums: `<flags>`
 
 Mark **auto-discovered** C enums (those declared as `typedef enum { ... } Name;`

cs_binding_generator-1.0.1.dev40/tests/test_utf8_byte_overloads.py

@@ -0,0 +1,161 @@
+"""Tests for the opt-in byte*-param overload feature.
+
+When ``<utf8-byte-overloads/>`` is present in the XML config, every non-variadic
+function whose primary `[LibraryImport]` has at least one ``string?`` parameter
+gets a parallel partial method with each of those parameters retyped as ``byte*``.
+Lets callers hand pre-encoded UTF-8 buffers (u8 literals, pinned spans) to the
+native side without re-encoding through a managed string.
+"""
+
+import pytest
+from pathlib import Path
+
+from cs_binding_generator.config import parse_config_file
+from cs_binding_generator.generator import CSharpBindingsGenerator
+
+
+class TestUtf8ByteOverloadsXMLParsing:
+    """The XML config exposes the feature as a presence-only ``<utf8-byte-overloads/>``."""
+
+    def test_presence_sets_flag(self, tmp_path):
+        config_file = tmp_path / "cfg.xml"
+        config_file.write_text(
+            """
+            <bindings>
+                <utf8-byte-overloads/>
+                <library name="testlib">
+                    <include file="/tmp/test.h"/>
+                </library>
+            </bindings>
+            """
+        )
+        config = parse_config_file(str(config_file))
+        assert config.utf8_byte_overloads is True
+
+    def test_absence_keeps_default(self, tmp_path):
+        config_file = tmp_path / "cfg.xml"
+        config_file.write_text(
+            """
+            <bindings>
+                <library name="testlib">
+                    <include file="/tmp/test.h"/>
+                </library>
+            </bindings>
+            """
+        )
+        config = parse_config_file(str(config_file))
+        assert config.utf8_byte_overloads is False
+
+
+class TestUtf8ByteOverloadsEmit:
+    """End-to-end checks against the generated `.cs`."""
+
+    def _generate(self, tmp_path, header_src, *, opt_in: bool):
+        """Helper: produce a one-library binding from `header_src`."""
+        header = tmp_path / "test.h"
+        header.write_text(header_src)
+        opt_in_xml = "<utf8-byte-overloads/>" if opt_in else ""
+        config_xml = tmp_path / "cs-bindings.xml"
+        config_xml.write_text(
+            f"""
+            <bindings>
+                {opt_in_xml}
+                <library name="testlib" namespace="Test" class="Native">
+                    <include file="{header}"/>
+                </library>
+            </bindings>
+            """
+        )
+        config = parse_config_file(str(config_xml))
+        generator = CSharpBindingsGenerator()
+        result = generator.generate(
+            config.header_library_pairs,
+            output=str(tmp_path),
+            include_dirs=[str(tmp_path)],
+            library_namespaces=config.library_namespaces,
+            library_class_names=config.library_class_names,
+            utf8_byte_overloads=config.utf8_byte_overloads,
+        )
+        return result["testlib.cs"]
+
+    def test_disabled_emits_only_primary(self, tmp_path):
+        # Baseline: a function with a string? param produces ONLY the primary P/Invoke.
+        header = """
+            void log_message(const char* message);
+        """
+        output = self._generate(tmp_path, header, opt_in=False)
+        # Primary present.
+        assert "public static partial void log_message(string? message);" in output
+        # No byte* overload.
+        assert "byte* message" not in output
+
+    def test_enabled_emits_byte_overload_for_single_string_param(self, tmp_path):
+        header = """
+            void log_message(const char* message);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        # Primary still emitted.
+        assert "public static partial void log_message(string? message);" in output
+        # Plus a byte* overload.
+        assert "public static partial void log_message(byte* message);" in output
+        # Both reference the same native entry point.
+        assert output.count('EntryPoint = "log_message"') == 2
+
+    def test_enabled_swaps_every_string_param(self, tmp_path):
+        # Two char* params should both become byte* in the overload.
+        header = """
+            int set_string_property(unsigned int props, const char* name, const char* value);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        assert (
+            "public static partial int set_string_property(uint props, string? name, string? value);"
+            in output
+        )
+        assert (
+            "public static partial int set_string_property(uint props, byte* name, byte* value);"
+            in output
+        )
+
+    def test_enabled_preserves_non_string_params(self, tmp_path):
+        # Non-string params should be passed through verbatim in the overload.
+        header = """
+            int frobnicate(int count, const char* label, float weight);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        # The overload keeps `int count` and `float weight` intact.
+        assert (
+            "public static partial int frobnicate(int count, byte* label, float weight);"
+            in output
+        )
+
+    def test_enabled_skips_functions_without_string_params(self, tmp_path):
+        # Functions with no char* params get no overload — there's nothing to swap.
+        header = """
+            int add_numbers(int a, int b);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        # Exactly one partial method declaration.
+        assert output.count("public static partial int add_numbers") == 1
+
+    def test_enabled_preserves_bool_marshalling_on_overload(self, tmp_path):
+        # A bool param needs its MarshalAs attribute on BOTH the primary and the overload.
+        header = """
+            unsigned char set_flag(const char* name, _Bool enabled);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        # The byte* overload also keeps `[MarshalAs(UnmanagedType.I1)] bool enabled`.
+        assert (
+            "public static partial byte set_flag(byte* name, "
+            "[MarshalAs(UnmanagedType.I1)] bool enabled);"
+        ) in output
+
+    def test_enabled_does_not_duplicate_when_overload_already_unique(self, tmp_path):
+        # Two unrelated functions, only one of which has a string param. Only that one
+        # gets the overload.
+        header = """
+            void with_string(const char* s);
+            int without_string(int x);
+        """
+        output = self._generate(tmp_path, header, opt_in=True)
+        assert output.count("public static partial void with_string") == 2
+        assert output.count("public static partial int without_string") == 1