What's new in DiskImageKit

public struct ASIFCreationConfiguration : DiskImage.CreationConfiguration {

    /// Creates a configuration object for a new Apple sparse image format (ASIF) disk image layer.
    ///
    /// Use this factory method to create a configuration that can be used with ``DiskImage/appending(_:)-3pfqg``.
    /// Use the configuration this method returns only for appending to stacked images, not for standalone image creation.
    ///
    /// For more information on ASIF layer creation for stacked images, see ``DiskImage/CreationConfiguration/asifLayer(url:type:)`` .
    ///
    /// - Parameters:
    ///   - url: The <doc://com.apple.documentation/documentation/foundation/url> for a file that's the backing store of the image.
    ///   - type: The ``DiskImage/LayerType`` of the layer to create (a cache or overlay layer with an optional block count).
    /// - Returns: An ``ASIFLayerCreationConfiguration`` that you can use` for stacking operations.
    public static func layer(url: URL, type: DiskImage.LayerType) -> ASIFLayerCreationConfiguration
}

public struct ASIFLayerCreationConfiguration : DiskImage.CreationConfiguration, DiskImage.StackableLayer {
}

public struct CorruptedImageError : Error, LocalizedError {

    /// The underlying error with additional diagnostic details.
    public let underlyingError: any Error

    /// A localized message describing what error occurred.
    public var errorDescription: String? { get }
}

extension DiskImage.BlockSize : Equatable {
}

extension DiskImage.BlockSize : Hashable {
}

extension DiskImage.BlockSize : RawRepresentable {
}

extension DiskImage.CreationConfiguration where Self == ASIFCreationConfiguration {

    /// Returns an Apple sparse image format (ASIF) configuration for standalone or base images.
    ///
    /// Use this initializer when creating a standalone image, or a base image for a stack, using ``DiskImage/init(creating:)``.
    /// To create a cache or overlay layer for a stacked disk image, use ``DiskImage/CreationConfiguration/asifLayer(url:type:)`` instead.
    ///
    /// The following example demonstrates how to create a ASIF disk image:
    /// ```
    /// _ = try DiskImage(creating: .asif(url: imageURL, blockCount: blockCount, blockSize: .bytes512))
    /// ```
    ///
    /// - Parameters:
    ///   - url: The <doc://com.apple.documentation/documentation/foundation/url> for the disk image file.
    ///   - blockCount: Size of the disk image in blocks.
    ///   - blockSize: The ``DiskImage/BlockSize`` to use.
    /// - Returns: An ``ASIFCreationConfiguration`` instance for standalone use.
    public static func asif(url: URL, blockCount: Int, blockSize: DiskImage.BlockSize) -> Self
}

extension DiskImage.CreationConfiguration where Self == ASIFLayerCreationConfiguration {

    /// Returns an Apple sparse image format (ASIF) configuration for stackable layers.
    ///
    /// The following example demonstrates how to append a new cache layer to a base image:
    /// ```
    /// var stackedImage = try baseImage.appending(.asifLayer(url: cacheURL, type: .cache))
    /// ```
    ///
    /// - Parameters:
    ///   - url: The <doc://com.apple.documentation/documentation/foundation/url> for the disk image file.
    ///   - type: The type of layer (cache or overlay).
    /// - Returns: An ``ASIFLayerCreationConfiguration`` instance for stacking use.
    public static func asifLayer(url: URL, type: DiskImage.LayerType) -> Self
}

extension DiskImage.CreationConfiguration where Self == RAWCreationConfiguration {

    /// Returns a RAW configuration for standalone or base images.
    ///
    /// The framework only supports the 512-byte block size for RAW images.
    ///
    /// The following example demonstrates how to create a RAW disk image.
    /// ```
    /// _ = try DiskImage(creating: .raw(url: imageURL, blockCount: blockCount))
    /// ```
    ///
    /// - Parameters:
    ///   - url: The <doc://com.apple.documentation/documentation/foundation/url> for the disk image file.
    ///   - blockCount: Size of the disk image in blocks.
    /// - Returns: A ``RAWCreationConfiguration`` instance.
    public static func raw(url: URL, blockCount: Int) -> Self
}

extension DiskImage.Format : Equatable {
}

extension DiskImage.Format : Hashable {
}

public struct IncompatibleStackingError : Error, LocalizedError {

    /// A description of why the stacking operation failed.
    public let reason: String

    /// A localized message describing what error occurred.
    public var errorDescription: String? { get }
}

public struct InvalidBlockCountError : Error, LocalizedError {

    /// A localized message describing what error occurred.
    public var errorDescription: String? { get }
}

public struct OpenConfiguration : OpenConfigurationProtocol {

    /// Open modes for disk images.
    public enum Mode {

        /// Try to open the disk image as read-write, and fallback to read-only if there's no read-write access.
        case automatic

        /// Open the disk image in read-only mode.
        ///
        /// Use this mode when opening the base image of a stacked disk image.
        case readOnly

        /// Open the disk-image with read-write permissions.
        ///
        /// Fails if there's no permission to open the image in this mode.
        case readWrite

        /// Returns a Boolean value indicating whether two values are equal.
        ///
        /// Equality is the inverse of inequality. For any values `a` and `b`,
        /// `a == b` implies that `a != b` is `false`.
        ///
        /// - Parameters:
        ///   - lhs: A value to compare.
        ///   - rhs: Another value to compare.
        public static func == (a: OpenConfiguration.Mode, b: OpenConfiguration.Mode) -> Bool

        /// Hashes the essential components of this value by feeding them into the
        /// given hasher.
        ///
        /// Implement this method to conform to the `Hashable` protocol. The
        /// components used for hashing must be the same as the components compared
        /// in your type's `==` operator implementation. Call `hasher.combine(_:)`
        /// with each of these components.
        ///
        /// - Important: In your implementation of `hash(into:)`,
        ///   don't call `finalize()` on the `hasher` instance provided,
        ///   or replace it with a different instance.
        ///   Doing so may become a compile-time error in the future.
        ///
        /// - Parameter hasher: The hasher to use when combining the components
        ///   of this instance.
        public func hash(into hasher: inout Hasher)

        /// The hash value.
        ///
        /// Hash values are not guaranteed to be equal across different executions of
        /// your program. Do not save hash values to use during a future execution.
        ///
        /// - Important: `hashValue` is deprecated as a `Hashable` requirement. To
        ///   conform to `Hashable`, implement the `hash(into:)` requirement instead.
        ///   The compiler provides an implementation for `hashValue` for you.
        public var hashValue: Int { get }
    }

    /// The URL of the disk image to open.
    public let url: URL

    /// The mode in which to open the disk image.
    public let mode: OpenConfiguration.Mode

    /// Creates a configuration for opening a disk image.
    ///
    /// - Parameters:
    ///   - url: The <doc://com.apple.documentation/documentation/foundation/url> of the disk image file to open.
    ///   - mode: The mode in which to open the image (read-only or read-write).
    public init(url: URL, mode: OpenConfiguration.Mode = .automatic)
}

extension OpenConfiguration.Mode : Equatable {
}

extension OpenConfiguration.Mode : Hashable {
}

public protocol OpenConfigurationProtocol {

    /// The URL of the disk image to open.
    var url: URL { get }

    /// The ``OpenConfiguration/Mode`` in which to open the disk image.
    var mode: OpenConfiguration.Mode { get }
}

extension OpenConfigurationProtocol where Self == OpenConfiguration {

    /// Returns a configuration to use for opening a disk image.
    ///
    /// The following example demonstrates how to open a disk image.
    /// ```
    /// let image = try DiskImage(opening: .open(url: imageURL))
    /// ```
    ///
    /// - Parameters:
    ///   - url: A <doc://com.apple.documentation/documentation/foundation/url>  of the disk image file to open.
    ///   - mode: Mode in which to open the image (read-only or read-write).
    /// - Returns: An ``OpenConfiguration`` instance.
    public static func open(url: URL, mode: OpenConfiguration.Mode = .automatic) -> Self
}

public struct RAWCreationConfiguration : DiskImage.CreationConfiguration {
}

public protocol StackedImage : DiskImage {

    /// An array of all layers in the stack, from base (index 0) to top.
    var layers: [DiskImage] { get }
}

public struct UnsupportedFormatError : Error, LocalizedError {

    /// The underlying error with additional diagnostic details.
    public let underlyingError: any Error

    /// A localized message describing what error occurred.
    public var errorDescription: String? { get }
}