QizhMacroKit

A Swift package providing a collection of powerful macros for enhanced enum handling and code generation.

Overview

QizhMacroKit uses Swift Macros (introduced in Swift 5.9) and requires Swift 6.2+ to generate compile-time code, reducing boilerplate and enhancing enum ergonomics. All macros are powered by SwiftSyntax and execute during compilation with zero runtime overhead.

Features

Macro	Type	Description
@CaseName	Attached	Generates a caseName property returning the case name as a String
@CaseValue	Attached	Generates properties to extract associated values from cases
@IsCase	Attached	Generates is<CaseName> boolean properties and membership checking
@IsNotCase	Attached	Generates isNot<CaseName> boolean properties
@OptionSet<RawType>	Attached	Creates an OptionSet from a struct with nested Options enum
#stringify	Freestanding	Converts an expression to its source text
#dictionarify	Freestanding	Returns a key-value pair with source text and evaluated value

Requirements

• Swift: 6.2+
• Platforms: iOS 17+, macOS 14+, Mac Catalyst 14+
• Dependencies: swift-syntax 602.0.0+

Installation

Swift Package Manager

Add QizhMacroKit to your Package.swift:

dependencies: [
    .package(url: "https://github.com/qizh/QizhMacroKit.git", from: "1.1.0")
]

Then add the dependency to your target:

targets: [
    .target(
        name: "YourTarget",
        dependencies: ["QizhMacroKit"]
    )
]

Xcode Project

1. File → Add Package Dependencies...
2. Enter: https://github.com/qizh/QizhMacroKit.git
3. Select version requirements
4. Add to your target

Quick Start

Import the Package

import QizhMacroKit

@CaseName — Get Case Names as Strings

@CaseName
enum Status {
    case idle
    case loading
    case success(Data)
    case failure(Error)
}

let status = Status.loading
print(status.caseName)  // "loading"

@IsCase — Boolean Case Checking

@IsCase
enum NetworkState {
    case disconnected
    case connecting
    case connected(session: Session)
}

let state = NetworkState.connecting

// Boolean properties
if state.isConnecting {
    showLoadingIndicator()
}

// Membership checking
if state.isAmong(.disconnected, .connecting) {
    retryConnection()
}

@IsNotCase — Negated Case Checking

@IsNotCase
enum Permission {
    case granted
    case denied
    case notDetermined
}

let permission = Permission.notDetermined

if permission.isNotGranted {
    requestPermission()
}

@CaseValue — Extract Associated Values

@CaseValue
enum Result {
    case success(data: Data)
    case failure(error: Error)
}

let result = Result.success(data: responseData)

// Optional extraction
if let data = result.successData {
    process(data)
}

#stringify — Expression to String

let x = 42
let text = #stringify(x * 2 + 1)
print(text)  // "x * 2 + 1"

#dictionarify — Expression with Value

let pair = #dictionarify(2 + 2)
print(pair.key)    // "2 + 2"
print(pair.value)  // 4

Documentation

Detailed documentation for each component:

Macros

• CaseName — Case name as string
• CaseValue — Associated value extraction
• IsCase — Boolean case checking
• IsNotCase — Negated case checking
• Stringify Macros — #stringify and #dictionarify

Internal Utilities

• String Helpers — Case conversion, keyword escaping, backtick handling

Project Status

• Known Issues — Current limitations and workarounds
• TODO / Roadmap — Planned features and improvements

Project Structure

QizhMacroKit/
├── Sources/
│   ├── QizhMacroKit/           # Public API (macro declarations)
│   ├── QizhMacroKitMacros/     # Macro implementations (SwiftSyntax)
│   │   └── Helpers/            # String manipulation utilities
│   └── QizhMacroKitClient/     # Example usage
├── Tests/
│   ├── CaseNameTests/          # @CaseName macro tests
│   ├── CaseValueTests/         # @CaseValue macro tests
│   ├── IsCaseTests/            # @IsCase macro tests
│   ├── IsNotCaseTests/         # @IsNotCase macro tests
│   ├── OptionSetTests/         # @OptionSet macro tests
│   ├── StringifyTests/         # #stringify / #dictionarify tests
│   ├── DiagnosticTests/        # Diagnostic types tests
│   └── HelperTests/            # String helper extension tests
├── Docs/                       # Documentation
├── Package.swift               # SPM manifest
├── KNOWN_ISSUES.md             # Current limitations
├── TODO.md                     # Roadmap
├── AGENTS.md                   # Agent instructions
└── README.md                   # This file

Building

# Build all targets
swift build

# Build library only (works on Linux)
swift build --target QizhMacroKit

# Run tests
swift test

# Run tests with verbose output
swift test --parallel --verbose

Contributing

Contributions are welcome! Please:

1. Check TODO.md for planned work
2. Review KNOWN_ISSUES.md for bugs to fix
3. Open an issue to discuss significant changes
4. Submit a PR with tests for new functionality