Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
53 changes: 53 additions & 0 deletions Snippets/EnvironmentValues/CustomDynamicProperty.swift
Original file line number Diff line number Diff line change
@@ -0,0 +1,53 @@
// Define a property wrapper that derives its value from the environment with `DynamicProperty`.

// snippet.hide
import Calligraphy
import Foundation

// snippet.show
// snippet.wrapper
@propertyWrapper
struct FileExtension: DynamicProperty {

@FileName
private var fileName

var wrappedValue: String? {
guard let fileName, let dot = fileName.lastIndex(of: ".") else {
return nil
}
return String(fileName[fileName.index(after: dot)...])
}

}
// snippet.end

// snippet.usage
struct LicenseHeader: StringComponent {

@FileExtension
private var fileExtension

var body: some StringComponent {
let marker = fileExtension == "sh" ? "#" : "//"
marker + " Copyright (c) 2026"
}

}

let sources = Folder("Sources") {
File("main.swift") {
LicenseHeader()
}
File("build.sh") {
LicenseHeader()
}
}
// main.swift begins with `// Copyright (c) 2026`
// build.sh begins with `# Copyright (c) 2026`
// snippet.end

// snippet.hide
let destination = FileManager.default.temporaryDirectory
try await sources.write(to: destination, shouldOverwrite: true)
print("Wrote Sources to \(destination.path(percentEncoded: false))")
Original file line number Diff line number Diff line change
Expand Up @@ -68,3 +68,13 @@ Optional types do not need an initial value — when omitted, the default is `ni

@Snippet(path: "Calligraphy/Snippets/EnvironmentValues/CustomEnvironmentValues", slice: "optional-entry")

## Defining Custom Dynamic Properties

``Environment`` and ``FileName`` are property wrappers that derive their value from the environment at render time. Calligraphy calls these dynamic properties, and you can define your own by conforming a property wrapper to ``DynamicProperty``. Store the environment values you need as ``Environment`` or ``FileName`` properties, and compute `wrappedValue` from them:

@Snippet(path: "Calligraphy/Snippets/EnvironmentValues/CustomDynamicProperty", slice: "wrapper")

Because the environment is injected after the enclosing component is initialized, `wrappedValue` must be computed rather than stored. Beyond that, the conformance is all that is needed; Calligraphy finds the dynamic properties stored inside your wrapper and resolves them for you. Use the wrapper from any component, modifier, file, or directory, the same way you would use ``Environment``:

@Snippet(path: "Calligraphy/Snippets/EnvironmentValues/CustomDynamicProperty", slice: "usage")

1 change: 1 addition & 0 deletions Sources/Calligraphy/Calligraphy.docc/Calligraphy.md
Original file line number Diff line number Diff line change
Expand Up @@ -94,4 +94,5 @@ Calligraphy's type-safe API and builder patterns make it ideal for code generati
- ``EnvironmentKey``
- ``Entry()``
- ``FileName``
- ``DynamicProperty``

47 changes: 39 additions & 8 deletions Sources/Calligraphy/Environment/Environment.swift
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
/// - Note: SwiftUI declares a property wrapper with the same name. In a file that imports both modules, write `@Calligraphy.Environment` to disambiguate.
@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
@propertyWrapper
public struct Environment<Value>: EnvironmentPropertyWrapper {
public struct Environment<Value>: DynamicProperty {

// MARK: - Initializers

Expand All @@ -59,14 +59,16 @@ public struct Environment<Value>: EnvironmentPropertyWrapper {
read(box.values)
}

// MARK: - Private
// MARK: - DynamicProperty

func inject(
public func _inject(
_ values: EnvironmentValues
) {
box.values = values
}

// MARK: - Private

private let read: (EnvironmentValues) -> Value
private let box = Box()

Expand All @@ -76,21 +78,50 @@ public struct Environment<Value>: EnvironmentPropertyWrapper {

}

/// A property wrapper that derives its value from the surrounding ``EnvironmentValues``.
///
/// ``Environment`` and ``FileName`` are dynamic properties. Conform your own property wrappers to `DynamicProperty` to have Calligraphy resolve them against the environment whenever the component, modifier, file, or directory that declares them is rendered.
///
/// A dynamic property reads the environment through other dynamic properties stored inside it, typically ``Environment``, and computes its `wrappedValue` from them. Because the environment is injected after the enclosing component is initialized, `wrappedValue` must be a computed property:
///
/// @Snippet(path: "Calligraphy/Snippets/EnvironmentValues/CustomDynamicProperty", slice: "wrapper")
///
/// The default implementation of `_inject(_:)` finds every dynamic property stored in the conforming type and injects it, so a conforming type rarely needs to do anything beyond declaring the conformance.
///
/// - Note: SwiftUI declares a protocol with the same name. In a file that imports both modules, write `Calligraphy.DynamicProperty` to disambiguate.
@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
protocol EnvironmentPropertyWrapper {
func inject(
public protocol DynamicProperty {

/// Resolve this property against the environment it is being rendered in.
///
/// You rarely need to implement this method. The default implementation injects every dynamic property stored in `self`. Implement it only when your property reads the environment some other way.
///
/// - Parameter values: The environment values to read during rendering.
func _inject(
_ values: EnvironmentValues
)

}

@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
extension DynamicProperty {

public func _inject(
_ values: EnvironmentValues
) {
values.inject(into: self)
}

}

@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
extension EnvironmentValues {

/// Resolve every ``Environment`` property declared by `subject` against this environment.
/// - Parameter subject: The component, modifier, file, or directory whose wrappers should be injected.
/// Resolve every ``DynamicProperty`` declared by `subject` against this environment.
/// - Parameter subject: The component, modifier, file, directory, or dynamic property whose stored dynamic properties should be injected.
func inject(into subject: Any) {
for child in Mirror(reflecting: subject).children {
(child.value as? (any EnvironmentPropertyWrapper))?.inject(self)
(child.value as? (any DynamicProperty))?._inject(self)
}
}

Expand Down
8 changes: 1 addition & 7 deletions Sources/Calligraphy/Environment/FileEnvironment.swift
Original file line number Diff line number Diff line change
Expand Up @@ -39,7 +39,7 @@ extension EnvironmentValues {
/// The value is `nil` when a component is rendered outside of any file. It is also `nil` when read on a file type itself, which already knows its own ``TextFile/name``; the file name is visible to the file's ``TextFile/body``, not to the file's own properties.
@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
@propertyWrapper
public struct FileName: EnvironmentPropertyWrapper {
public struct FileName: DynamicProperty {

// MARK: - Initializers

Expand All @@ -58,12 +58,6 @@ public struct FileName: EnvironmentPropertyWrapper {
@Environment(\.fileName)
private var fileName

func inject(
_ values: EnvironmentValues
) {
_fileName.inject(values)
}

}

@available(macOS 14.0, macCatalyst 17.0, iOS 17.0, watchOS 10.0, tvOS 17.0, visionOS 1.0, *)
Expand Down
Loading
Loading