Parse Bitmask

[FlickerSoul]

This PR adds bitmask parsing support

Goal

The design of bitmask parsing is to achieve

• allow parsing bit masks directly in @ParseEnum and @ParseStruct
• allow bitmasks to be grouped in declaration using @ParseBitmask
• bitmask is currently only parsed as MSB (BE). LSB (LE) parsing support will be added in the next PR
• allow parsed bitmasks to be printed in printer
• consecutive bitmasks that are not full multiple of bytes are padded automatically (e.g. 7 bit mask will consume 1 byte where the last bit is padded (discarded)

Design

We assume that is that each single bitmask are usually less than 64/128 bits. Therefore, when parsing bitmask, we extract bits into integers, and parse based on the extracted integers.

The package provides ExpressibleByRawBits protocol which requires a constructor taking in a FixedWidthInteger.

Types who conform to this type can be used with @mask(bitCount:) macro. If the type additionally conforms to BitCountProviding, it can be used with @mask() where bitCount is inferred from BitCountProviding.bitCount, or @mask(bitCount:) (where the provided bitCount has to be greater than or equal to BitCountProviding.bitCount).

@mask can be used in @ParseEnum, @ParseStruct, and the new @ParseBitmask.

@ParseBitmask can be applied on a struct and automatically generate ExpressibleByRawBits conformance.

Consecutive bitmasks are parsed "together" and any remaining bits of an unfinished byte will be dropped/padded automatically. That is, say

@mask(bitCount: 3) var flag: Flag
@mask var sequence: Sequence // bitCount = 7

will take two bytes, where the first 3 bits parsed into Flag; the following 7 bits parsed into Sequence, and the remaining 6 bits dropped.

[Copilot]

Pull request overview

This PR adds comprehensive bitmask parsing support to BinaryParseKit, enabling bit-level field parsing and manipulation for binary protocols. The implementation provides three main macros (@mask(bitCount:), @mask(), and @ParseBitmask) along with supporting infrastructure for MSB-first bit parsing, printing, and round-trip serialization.

Key Changes

• Introduced RawBits type for arbitrary-width bit storage and manipulation
• Added protocols (ExpressibleByRawBits, BitCountProviding, RawBitsConvertible) for bit-level parsing
• Implemented macro support for bitmask parsing in structs and enums with automatic grouping and padding

Reviewed changes

Copilot reviewed 56 out of 57 changed files in this pull request and generated no comments.

Show a summary per file

File	Description
Sources/BinaryParseKit/Types/RawBits.swift	Core bit manipulation type with slicing, equality, and bitwise operations
Sources/BinaryParseKit/Protocols/BitmaskParsable.swift	Protocol definitions for bit-level parsing and conversion
Sources/BinaryParseKitMacros/Macros/ParseBitmask/*.swift	Macro implementation for @ParseBitmask struct parsing
Sources/BinaryParseKitMacros/Macros/Supports/MaskMacroInfo.swift	Metadata and parsing logic for @mask attributes
Sources/BinaryParseKitMacros/Macros/Supports/Utilities.swift	Utility functions for generating mask parsing and printing code
Sources/BinaryParseKit/Extensions/ExpressibleByRawBits+.swift	Built-in conformances for Bool, UInt8, Int8
Tests/BinaryParseKitTests/*.swift	Comprehensive test coverage for RawBits, parsing, and printing

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 80 out of 81 changed files in this pull request and generated no new comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.