Add Accessor control (#21)

This pull request introduces a new way to control access levels for
generated parsing and printing extensions in the `@ParseStruct` and
`@ParseEnum` macros, allowing users to specify custom access modifiers.

Author: FlickerSoul

.github/workflows/deploy-docc.yml

@@ -26,7 +26,10 @@ jobs:
           xcrun swift build
           xcrun swift package --allow-writing-to-directory ./docs \
             generate-documentation \
+            --enable-experimental-combined-documentation \
             --target BinaryParseKit \
+            --target BinaryParseKitCommons \
+            --target BinaryParsing \
             --output-path ./docs \
             --transform-for-static-hosting
       - name: Upload artifact

Package.swift

@@ -21,12 +21,10 @@ let package = Package(
     dependencies: [
         .package(url: "https://github.com/swiftlang/swift-syntax.git", .upToNextMajor(from: "602.0.0")),
         .package(url: "https://github.com/FlickerSoul/swift-binary-parsing", branch: "main"),
-        .package(
-            url: "https://github.com/apple/swift-collections.git",
-            .upToNextMinor(from: "1.1.0"),
-        ),
+        .package(url: "https://github.com/apple/swift-collections.git", from: "1.1.0"),
         .package(url: "https://github.com/apple/swift-docc-plugin", from: "1.4.5"),
         .package(url: "https://github.com/pointfreeco/swift-macro-testing.git", from: "0.6.4"),
+        // .package(url: "https://github.com/stackotter/swift-macro-toolkit.git", from: "0.7.2"),
     ],
     targets: [
         .macro(
@@ -37,6 +35,7 @@ let package = Package(
                 .product(name: "BinaryParsing", package: "swift-binary-parsing"),
                 .product(name: "Collections", package: "swift-collections"),
                 .target(name: "BinaryParseKitCommons"),
+                // .product(name: "MacroToolkit", package: "swift-macro-toolkit"),
             ],
         ),
         .target(
@@ -77,13 +76,13 @@ let package = Package(
                 "BinaryParseKitMacros",
                 .product(name: "SwiftSyntaxMacrosTestSupport", package: "swift-syntax"),
                 .product(name: "MacroTesting", package: "swift-macro-testing"),
+                "BinaryParseKitCommons",
             ],
         ),
         .testTarget(
             name: "BinaryParseKitTests",
             dependencies: [
                 "BinaryParseKit",
-                "BinaryParseKitCommons",
             ],
         ),
     ],

Sources/BinaryParseKit/BinaryParseKit.swift

@@ -60,7 +60,7 @@ public macro parse() = #externalMacro(module: "BinaryParseKitMacros", type: "Emp
 /// Use this macro when you need to parse a field with a specific byte order
 /// (big-endian or little-endian). The field type must conform to ``EndianParsable``.
 ///
-/// - Parameter endianness: The byte order to use for parsing (``Endianness/big`` or ``Endianness/little``)
+/// - Parameter endianness: The byte order to use for parsing (`.big` or `.little`)
 ///
 /// - Note: This macro has no effect on its own unless used alongside `@ParseStruct` on struct fields.
 ///
@@ -164,7 +164,7 @@ public macro parse(byteCount: ByteCount, endianness: Endianness) = #externalMacr
 ///
 /// - Parameters:
 ///   - byteCountOf: A KeyPath to another field whose value determines the byte count
-///   - endianness: The byte order to use for parsing (``Endianness/big`` or ``Endianness/little``)
+///   - endianness: The byte order to use for parsing (`.big` or `.little`)
 ///
 /// - Note: This macro has no effect on its own unless used alongside `@ParseStruct` on struct fields.
 ///
@@ -219,7 +219,7 @@ public macro parseRest() = #externalMacro(
 /// Like `parseRest()`, but applies endianness conversion to the remaining data.
 /// The field type must conform to ``EndianSizedParsable``.
 ///
-/// - Parameter endianness: The byte order to use for parsing (``Endianness/big`` or ``Endianness/little``)
+/// - Parameter endianness: The byte order to use for parsing (`.big` or `.little`)
 ///
 /// - Note: This macro must be used alongside `@ParseStruct` on struct fields.
 ///
@@ -255,8 +255,11 @@ public macro parseRest(endianness: Endianness) = #externalMacro(
 /// - Proper error handling for parsing failures
 /// - A ``Printable`` conformance
 ///
-/// - Note: All fields except those with accessors (`get` and `set`) must be parsed must be marked with `@parse`
-/// variants.
+/// - Parameters:
+///   - parsingAccessor: The accessor level for the generated `Parsable` conformance (default is `.follow`)
+///   - printingAccessor: The accessor level for the generated `Printable` conformance (default is `.follow`)
+///
+/// - Note: All fields except those with accessors (`get` and `set`) must be marked with `@parse` variants.
 ///
 /// Example:
 /// ```swift
@@ -278,7 +281,10 @@ public macro parseRest(endianness: Endianness) = #externalMacro(
 /// let header = try FileHeader(parsing: data)
 /// ```
 @attached(extension, conformances: BinaryParseKit.Parsable, BinaryParseKit.Printable, names: arbitrary)
-public macro ParseStruct() = #externalMacro(
+public macro ParseStruct(
+    parsingAccessor: ExtensionAccessor = .follow,
+    printingAccessor: ExtensionAccessor = .follow,
+) = #externalMacro(
     module: "BinaryParseKitMacros",
     type: "ConstructStructParseMacro",
 )
@@ -295,12 +301,19 @@ public macro ParseStruct() = #externalMacro(
 /// - A ``Parsable`` conformance
 /// - A ``Printable`` conformance
 ///
+/// - Parameters:
+///   - parsingAccessor: The accessor level for the generated `Parsable` conformance (default is `.follow`)
+///   - printingAccessor: The accessor level for the generated `Printable` conformance (default is `.follow`)
+///
 /// - Note: All enum cases must be marked with `@match` variants, which is intentional by design, which I don't think is
-/// necessary and is possible to be lifted int the future.
+/// necessary and is possible to be lifted in the future.
 /// - Note: Only one `@matchDefault` case is allowed per enum, and has to be declared at the end of all other cases.
 /// - Note: any `match` macro has to proceed `parse` and `skip` macros.
 @attached(extension, conformances: BinaryParseKit.Parsable, BinaryParseKit.Printable, names: arbitrary)
-public macro ParseEnum() = #externalMacro(
+public macro ParseEnum(
+    parsingAccessor: ExtensionAccessor = .follow,
+    printingAccessor: ExtensionAccessor = .follow,
+) = #externalMacro(
     module: "BinaryParseKitMacros",
     type: "ConstructEnumParseMacro",
 )

Sources/BinaryParseKit/Documentation.docc/Articles/GetStarted.md

@@ -28,7 +28,7 @@ dependencies: [
 
 ## Parsing
 
-We have two parsing macros: ``ParseStruct()`` and ``ParseEnum()``. They work together with decorative macros such as ``parse()``, ``match()``, ``skip(byteCount:because:)``, etc.
+We have two parsing macros: ``ParseStruct(parsingAccessor:printingAccessor:)`` and ``ParseEnum(parsingAccessor:printingAccessor:)``. They work together with decorative macros such as ``parse()``, ``match()``, ``skip(byteCount:because:)``, etc.
 
 ### Parse Struct
 

Sources/BinaryParseKit/Documentation.docc/BinaryParseKit.md

@@ -19,7 +19,7 @@ BinaryParseKit provides a convenient and type-safe way to parse binary data in S
 
 ### Struct Parsing Macros
 
-- ``ParseStruct()``
+- ``ParseStruct(parsingAccessor:printingAccessor:)``
 - ``parse()``
 - ``parse(byteCount:)``
 - ``parse(endianness:)``
@@ -32,7 +32,7 @@ BinaryParseKit provides a convenient and type-safe way to parse binary data in S
 
 ### Enum Parsing Macros
 
-- ``ParseEnum()``
+- ``ParseEnum(parsingAccessor:printingAccessor:)``
 - ``match()``
 - ``match(byte:)``
 - ``match(bytes:)``

Sources/BinaryParseKitCommons/ExtensionAccessor.swift

@@ -0,0 +1,58 @@
+//
+//  ExtensionAccessor.swift
+//  BinaryParseKit
+//
+//  Created by Larry Zeng on 11/26/25.
+//
+
+/// This enum represents the access level of an extension in Swift, with a few extra cases
+public enum ExtensionAccessor: ExpressibleByUnicodeScalarLiteral, Sendable, Codable {
+    public typealias UnicodeScalarLiteralType = String
+
+    /// Same as public keyword
+    case `public`
+    /// Same as package keyword
+    case package
+    /// Same as internal keyword
+    case `internal`
+    /// Same as fileprivate keyword
+    case `fileprivate`
+    /// Same as private keyword
+    case `private`
+    /// This specifier indicates that the extension should follow the access level of the type it extends
+    case follow
+    /// Represents an unknown or unsupported access level, which will be raised as macro error.
+    case unknown(String)
+
+    /// All allowed cases for ExtensionAccessor
+    ///
+    /// This includes all the defined access levels except for the ``ExtensionAccessor/unknown(_:)`` case.
+    public static var allowedCases: [ExtensionAccessor] {
+        [.public, .package, .internal, .fileprivate, .private, .follow]
+    }
+
+    /// A textual representation of the access level.
+    public var description: String {
+        switch self {
+        case .public: "public"
+        case .package: "package"
+        case .internal: "internal"
+        case .fileprivate: "fileprivate"
+        case .private: "private"
+        case .follow: "follow"
+        case let .unknown(value): "unknown(\(value))"
+        }
+    }
+
+    /// Initializes an `ExtensionAccessor` from a unicode scalar literal.
+    ///
+    /// - Note: It tries to match the provided string with valid levels specified in ``ExtensionAccessor/allowedCases``,
+    /// or default to ``ExtensionAccessor/unknown(_:)``.
+    public init(unicodeScalarLiteral value: String) {
+        self = ExtensionAccessor
+            .allowedCases
+            .first { access in
+                access.description == value
+            } ?? .unknown(value)
+    }
+}

Sources/BinaryParseKitMacros/Macros/Extensions/ExtensionAccessor+.swift

@@ -0,0 +1,23 @@
+//
+//  ExtensionAccessor+.swift
+//  BinaryParseKit
+//
+//  Created by Larry Zeng on 11/26/25.
+//
+
+import BinaryParseKitCommons
+import SwiftSyntax
+
+extension ExtensionAccessor {
+    func getAccessorToken(defaultAccessor: TokenKind) -> TokenKind? {
+        switch self {
+        case .public: .keyword(.public)
+        case .package: .keyword(.package)
+        case .internal: .keyword(.internal)
+        case .fileprivate: .keyword(.fileprivate)
+        case .private: .keyword(.private)
+        case .follow: defaultAccessor
+        case .unknown: nil
+        }
+    }
+}

Sources/BinaryParseKitMacros/Macros/ParseEnum/ConsructParseEnumMacro.swift

@@ -13,7 +13,7 @@ import SwiftSyntaxMacros
 
 public struct ConstructEnumParseMacro: ExtensionMacro {
     public static func expansion(
-        of _: SwiftSyntax.AttributeSyntax,
+        of attributeNode: SwiftSyntax.AttributeSyntax,
         attachedTo declaration: some SwiftSyntax.DeclGroupSyntax,
         providingExtensionsOf type: some SwiftSyntax.TypeSyntaxProtocol,
         conformingTo _: [SwiftSyntax.TypeSyntax],
@@ -23,6 +23,12 @@ public struct ConstructEnumParseMacro: ExtensionMacro {
             throw ParseEnumMacroError.onlyEnumsAreSupported
         }
 
+        let accessorInfo = try extractAccessor(
+            from: attributeNode,
+            attachedTo: enumDeclaration,
+            in: context,
+        )
+
         let visitor = ParseEnumCase(context: context)
         visitor.walk(enumDeclaration)
         try visitor.validate()
@@ -31,12 +37,10 @@ public struct ConstructEnumParseMacro: ExtensionMacro {
             throw ParseEnumMacroError.unexpectedError(description: "Macro analysis finished without info")
         }
 
-        let modifiers = declaration.modifiers
-
         let parsingExtension =
             try ExtensionDeclSyntax("extension \(type): \(raw: Constants.Protocols.parsableProtocol)") {
                 try InitializerDeclSyntax(
-                    "\(modifiers)init(parsing span: inout \(raw: Constants.BinaryParsing.parserSpan)) throws(\(raw: Constants.BinaryParsing.thrownParsingError))",
+                    "\(accessorInfo.parsingAccessor) init(parsing span: inout \(raw: Constants.BinaryParsing.parserSpan)) throws(\(raw: Constants.BinaryParsing.thrownParsingError))",
                 ) {
                     for caseParseInfo in parseInfo.caseParseInfo {
                         let toBeMatched = caseParseInfo.bytesToMatch(of: type)
@@ -102,7 +106,7 @@ public struct ConstructEnumParseMacro: ExtensionMacro {
 
         let printerExtension =
             try ExtensionDeclSyntax("extension \(type): \(raw: Constants.Protocols.printableProtocol)") {
-                try FunctionDeclSyntax("\(modifiers)func printerIntel() throws -> PrinterIntel") {
+                try FunctionDeclSyntax("\(accessorInfo.printingAccessor) func printerIntel() throws -> PrinterIntel") {
                     try SwitchExprSyntax("switch self") {
                         for caseParseInfo in parseInfo.caseParseInfo {
                             var parseSkipMacroInfo: [PrintableFieldInfo] = []

Sources/BinaryParseKitMacros/Macros/ParseStruct/ConstructParseStructMacro.swift

@@ -11,27 +11,32 @@ import SwiftSyntaxMacros
 
 public struct ConstructStructParseMacro: ExtensionMacro {
     public static func expansion(
-        of _: SwiftSyntax.AttributeSyntax,
+        of attributeNode: SwiftSyntax.AttributeSyntax,
         attachedTo declaration: some SwiftSyntax.DeclGroupSyntax,
         providingExtensionsOf type: some SwiftSyntax.TypeSyntaxProtocol,
         conformingTo _: [SwiftSyntax.TypeSyntax],
         in context: some SwiftSyntaxMacros.MacroExpansionContext,
     ) throws -> [SwiftSyntax.ExtensionDeclSyntax] {
         guard let structDeclaration = declaration.as(StructDeclSyntax.self) else {
-            let error = ParseStructMacroError.onlyStructsAreSupported
-            throw error
+            throw ParseStructMacroError.onlyStructsAreSupported
         }
+
+        let accessorInfo = try extractAccessor(
+            from: attributeNode,
+            attachedTo: structDeclaration,
+            in: context,
+        )
+
         let structFieldInfo = ParseStructField(context: context)
         structFieldInfo.walk(structDeclaration)
         try structFieldInfo.validate(for: structDeclaration)
 
         let type = TypeSyntax(type)
-        let modifiers = declaration.modifiers
 
         let extensionSyntax =
             try ExtensionDeclSyntax("extension \(type): \(raw: Constants.Protocols.parsableProtocol)") {
                 try InitializerDeclSyntax(
-                    "\(modifiers)init(parsing span: inout \(raw: Constants.BinaryParsing.parserSpan)) throws(\(raw: Constants.BinaryParsing.thrownParsingError))",
+                    "\(accessorInfo.parsingAccessor) init(parsing span: inout \(raw: Constants.BinaryParsing.parserSpan)) throws(\(raw: Constants.BinaryParsing.thrownParsingError))",
                 ) {
                     for (variableName, variableInfo) in structFieldInfo.variables {
                         for action in variableInfo.parseActions {
@@ -53,7 +58,7 @@ public struct ConstructStructParseMacro: ExtensionMacro {
 
         let printerExtension =
             try ExtensionDeclSyntax("extension \(type): \(raw: Constants.Protocols.printableProtocol)") {
-                try FunctionDeclSyntax("\(modifiers)func printerIntel() throws -> PrinterIntel") {
+                try FunctionDeclSyntax("\(accessorInfo.printingAccessor) func printerIntel() throws -> PrinterIntel") {
                     var parseSkipMacroInfo: [PrintableFieldInfo] = []
 
                     for (variableName, variableInfo) in structFieldInfo.variables {