swift-gen

🎱 Gen

Introduction

swift-gen is a versatile and user-friendly library for generating randomness in Swift applications. Designed to be composable, transformable, and controllable, it enhances Swift’s existing randomness functionalities, allowing developers to build customized random value generators. It simplifies the process of creating complex types of randomness from simpler ones, advancing beyond what Swift’s native APIs offer.

Motivation

The motivation behind swift-gen stems from the limitations of Swift’s native randomness API. While Swift provides a range of simple randomness functions, such as generating random numbers or shuffling arrays, it does not offer an easy way to extend these capabilities or compose random generators. swift-gen addresses this by wrapping Swift’s randomness API in a composable manner, enabling more complex randomization tasks such as generating random passwords or random points in a coordinate space.

Key Features

Composable Generators

The core of swift-gen is its composability feature. It allows developers to create random generators that can be combined or transformed into new generators. For example:

let digit = Gen.int(in: 0...9)           // Gen<Int>
let stringDigit = digit.map(String.init) // Gen<String>

Custom Randomness

swift-gen provides static functions aligning with Swift’s randomness methods but with an added layer of flexibility. Developers can create custom random values using simple map, flatMap, and zip functions:

let password = Gen.letterOrNumber
  .string(of: .always(6))
  .array(of: .always(3))
  .map { $0.joined(separator: "-") }

Controlled Randomness

One of the significant advantages of swift-gen is its ability to delay the creation of random values until explicitly needed, making it suitable for testing where deterministic outputs are required. By utilizing Swift’s RandomNumberGenerator protocol, developers can seed random number generators for predictable results in tests:

var xoshiro = Xoshiro(seed: 0)
Gen.int(in: 0...9).run(using: &xoshiro) // always produces the same sequence

Examples

To illustrate the applicability, consider these examples:

1. Boolean Generation: Rather than generating a boolean value directly, use Gen.bool to describe the randomness, producing values upon calling run().

2. Point Creation: Use zip to combine multiple generator functions to generate complex structures like points:

   let randomPoint = zip(.int(in: -10...10), .int(in: -10...10))
     .map(CGPoint.init(x:y:))
   

Installation

Incorporating swift-gen into a project using Swift Package Manager (SwiftPM) is straightforward. Add it under the dependencies section in Package.swift:

dependencies: [
  .package(url: "https://github.com/pointfreeco/swift-gen.git", from: "0.4.0")
]

Learning More

To explore the capabilities of swift-gen further, the Point-Free video series offers an in-depth examination of its design and use in practical scenarios. Episodes cover topics like composable and predictable randomness and generative art.

Conclusion

swift-gen is a powerful tool that extends the capabilities of Swift’s randomness API, providing flexibility, composability, and control necessary for complex randomization tasks in your applications. Released under the MIT license, it is accessible and open for all developers to integrate into their Swift projects.