Nssharp Binding Generator

NSSharp C# Binding Generator

Generate Xamarin/MAUI-style C# binding API definitions from Objective-C headers. Supports category merging, NS_ASSUME_NONNULL scope-aware nullability, weak→NullAllowed inference, [Field] for extern constants, and configurable vendor macro handling.

Quick Start

# Build and run during development
dotnet build NSSharp.slnx
dotnet run --project src/NSSharp -- MyHeader.h

# Or install as a dotnet tool
dotnet pack src/NSSharp/NSSharp.csproj -c Release
dotnet tool install -g --add-source src/NSSharp/bin/Release ASTools.NSSharp
# Or from NuGet.org
dotnet tool install -g ASTools.NSSharp

# C# bindings to stdout (default format)
nssharp MyHeader.h

# To file
nssharp MyHeader.h -o ApiDefinition.cs

# From xcframework
nssharp --xcframework MyLib.xcframework -o Bindings.cs

# Specific slice
nssharp --xcframework MyLib.xcframework --slice ios-arm64 -o Bindings.cs

# One .cs file per header (requires output directory)
nssharp --xcframework MyLib.xcframework --split-by-header -o GeneratedBindings/

# Add namespace
nssharp --xcframework MyLib.xcframework --namespace MyCompany.Bindings -o Bindings.cs

# With vendor export macros
nssharp --xcframework MyLib.xcframework --extern-macros PSPDF_EXPORT -o Bindings.cs

# Include C functions and extern constants in output
nssharp MyHeader.h --emit-c-bindings -o Bindings.cs

Binding Rules

Type Mapping

See references/type-mapping.md for the complete ObjC→C# type mapping table (70+ types).

Key Mappings

Programmatic Usage

using NSSharp.Lexer;
using NSSharp.Parser;
using NSSharp.Binding;

var source = File.ReadAllText("MyHeader.h");
var options = new ObjCLexerOptions
{
    ExternMacros = ["PSPDF_EXPORT"],
};
var tokens = new ObjCLexer(source, options).Tokenize();
var header = new ObjCParser(tokens).Parse("MyHeader.h");

var generator = new CSharpBindingGenerator();
string csharpBindings = generator.Generate(header);

// Include C functions and extern constants:
string withCBindings = generator.Generate(header, emitCBindings: true);

// For xcframeworks, merge categories across headers before generating:
var headers = new List<ObjCHeader> { header1, header2 };
CSharpBindingGenerator.MergeCategories(headers);

Source Files

Key Methods in ObjCTypeMapper

• MapType(string objcType) → C# type string
• MapEnumBackingType(string? objcType) → C# enum backing type
• IsNativeEnum(string? objcType) → whether [Native] attribute is needed
• SelectorToMethodName(string selector, bool isProtocolMethod) → Smart method name: first part only, strips trailing prepositions, strips sender prefix for protocols (multi-part and embedded single-part), renames Block→Action, handles isEqualTo pattern, normalizes acronyms (URL→Url, PDF→Pdf, UID→Uid, XMP→Xmp, etc.)
• PascalCase(string name) → PascalCase conversion with acronym normalization
• SetTypedefMap(Dictionary<string, string>) → Sets typedef resolution map
• ResolveTypedef(string typeName) → Resolves typedef aliases to base types

Key Methods in CSharpBindingGenerator

• Generate(ObjCHeader header) → full C# binding output (merges categories in-place)
• MergeCategories(List<ObjCHeader> headers) → static cross-header category merging
• IsObjectPointerType(string type) → checks if type is an object pointer
• BuildTypedefMap(List<ObjCHeader>) → builds typedef resolution map from parsed headers

Notes

• Generated bindings are a starting point; manual review may be needed
• Namespace behavior: single-header input has no namespace by default; xcframework input defaults namespace to the xcframework name unless --namespace is specified
• Enum prefix stripping: MyStatusOK → OK when enum is MyStatus
• Constructor detection: methods with init prefix returning instancetype (including nonnull instancetype) become NativeHandle Constructor(...)
• NS_DESIGNATED_INITIALIZER emits [DesignatedInitializer] attribute
• NS_REQUIRES_SUPER is consumed without corrupting selectors
• Block-type properties (void (^name)(params)) are correctly parsed with the block name extracted
• Properties with copy/strong/retain/assign/weak get ArgumentSemantic annotations
• Object pointer properties without explicit semantic: readwrite infer ArgumentSemantic.Strong; readonly get no inference
• Non-primitive value type properties (enums) without explicit semantic: readwrite infer ArgumentSemantic.Assign
• out NSError parameters always get [NullAllowed]
• Category properties are decomposed into getter/setter methods (not C# properties)
• [DisableDefaultCtor] only emitted when init is explicitly unavailable via macros (e.g., PSPDF_EMPTY_INIT_UNAVAILABLE), not inferred
• The lexer whitelists macros containing INIT_UNAVAILABLE or EMPTY_INIT, preserving them for the parser
• Static factory methods returning instancetype get Create<Name> prefix instead of Get<Name>
• Block in method names is renamed to Action at word boundaries (e.g., performBlock: → PerformAction)
• isEqualTo<ClassName>: selectors are simplified to IsEqualTo (class name suffix stripped)
• Selector naming special-cases: collapse trailing ForPageAtIndex / OnPageAtIndex; preserve InContext, WithTransform, and ForEvent
• Weak properties always get [NullAllowed]
• Inside NS_ASSUME_NONNULL scope: only explicitly nullable types get [NullAllowed]; outside scope: all object pointers get [NullAllowed]
• ObjC categories are merged into parent class interfaces when the parent is available (including SWIFT_EXTENSION categories)
• Each @protocol emits an interface IProtocolName {} stub before the protocol definition
• Protocols ending in Delegate or DataSource get [Protocol, Model] + [BaseType(typeof(NSObject))]
• Protocol properties are decomposed differently based on @required/@optional:
  • @required properties get [Abstract] and stay as C# properties with [Bind("isX")] for custom getters
  • @optional properties are decomposed into getter/setter method pairs (custom getter selectors used when available)
• NSNotificationName typed extern constants get [Notification] attribute
• Methods with completion handler parameters (ending in completion:, completionHandler:, completionBlock:) get [Async] — only on class methods, not protocol methods
• Acronyms in method names are normalized: URL→Url, PDF→Pdf, HUD→Hud, HTML→Html, JSON→Json, UID→Uid, XMP→Xmp
• Typedef aliases are resolved to their base types for correct C# type mapping
• Both leading and trailing const qualifiers are stripped during type mapping
• Preprocessor directives (#if, #endif) inside protocol conformance lists are skipped
• PSPDFKitUI benchmark (current DemoFramework): 88.9% exact export parity vs sharpie (489/550 common exports)

Converted and distributed by TomeVault — claim your Tome and manage your conversions.