nssharp-objc-parser

name: nssharp-objc-parser description: Parse Objective-C header files into structured AST using the NSSharp tool. Use when working with ObjC headers, generating JSON representations of ObjC APIs, inspecting xcframework contents, or analyzing ObjC type declarations (interfaces, protocols, enums, structs, functions, typedefs, categories, blocks, generics, nullability).

NSSharp ObjC Parser

Parse Objective-C headers into structured JSON or AST using the NSSharp .NET 10 CLI tool. No libclang or native dependencies required. Auto-detects vendor macros via UPPER_SNAKE_CASE heuristic and tracks NS_ASSUME_NONNULL scopes.

Quick Start

# Build (from repo root)
dotnet build NSSharp.slnx

# 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

# Parse a header to C# bindings (default) — via dotnet run or installed tool
dotnet run --project src/NSSharp -- MyHeader.h
nssharp MyHeader.h

# Parse to JSON
nssharp MyHeader.h -f json

# Parse to file
nssharp MyHeader.h -f json -o output.json

# Parse xcframework
nssharp --xcframework MyLib.xcframework -f json

# List xcframework slices
nssharp --xcframework MyLib.xcframework --list-slices

# Parse specific slice
nssharp --xcframework MyLib.xcframework --slice ios-arm64 -f json

# Specify vendor export macros (treated as extern instead of skipped)
nssharp MyHeader.h --extern-macros PSPDF_EXPORT,FB_EXTERN

# Disable macro heuristic (all UPPER_SNAKE_CASE identifiers kept as-is)
nssharp MyHeader.h --no-macro-heuristic

CLI Options

Supported ObjC Constructs

• @interface (classes, categories, extensions, generics, generic superclasses, SWIFT_EXTENSION)
• @protocol (@required / @optional, I-prefixed stubs, [Model] for delegates)
• @property (attributes, nullability, custom getter/setter, weak)
• Instance (-) and class (+) methods
• NS_ENUM / NS_OPTIONS / NS_CLOSED_ENUM / NS_ERROR_ENUM / C enums with backing types
• Structs, typedefs, block types
• C function declarations (extern, static, bare) and extern constants
• Forward declarations (@class, @protocol)
• Nullability annotations (nullable, _Nullable, __nullable, etc.)
• NS_ASSUME_NONNULL_BEGIN/END scope tracking
• Vendor macros auto-detected via UPPER_SNAKE_CASE heuristic

JSON Schema

See references/json-schema.md for the complete JSON output schema and AST node types.

Programmatic Usage in C#

using NSSharp.Lexer;
using NSSharp.Parser;
using NSSharp.Ast;
using NSSharp.Json;

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

// Access AST
foreach (var iface in header.Interfaces)
    Console.WriteLine($"{iface.Name} : {iface.Superclass}");

// Serialize to JSON
string json = ObjCJsonSerializer.Serialize(header, pretty: true);

Project Layout

src/NSSharp/
├── Ast/ObjCNodes.cs              # AST model types
├── Lexer/Token.cs                # TokenKind enum
├── Lexer/ObjCLexer.cs            # Tokenizer (UPPER_SNAKE_CASE macro heuristic)
├── Lexer/ObjCLexerOptions.cs     # Lexer config (heuristic, extern macros)
├── Parser/ObjCParser.cs          # Recursive-descent parser
├── Json/ObjCJsonSerializer.cs    # JSON serializer
├── Binding/                      # C# binding generator (see nssharp-binding-generator skill)
├── XCFrameworkResolver.cs        # XCFramework header discovery
└── Program.cs                    # CLI entry point

Testing

dotnet test NSSharp.slnx

185 tests covering lexer, parser, JSON serializer, binding generator, macro heuristic scenarios, and tests from dotnet/macios sharpie PR #24622.

Known Limitations

• No full C preprocessor — vendor macros auto-detected via UPPER_SNAKE_CASE heuristic; use --extern-macros for export macros
• Enum values with complex expressions preserved as strings, not evaluated
• No C++ support (classes, templates, namespaces)
• No semantic analysis or cross-header type resolution