SwiftFormat Documentation

Expressions are optimized by default (e.g., replacing constants with literals or inlining pure functions).

Performance Guidelines:

1. Use constants for fixed values: Pass constant values via the constants or arrays arguments instead of the symbols dictionary. This allows the optimizer to inline them.
2. Use pureSymbols for custom logic: If your custom functions or operators are pure (no side effects, same output for same input), set the pureSymbols option. This allows the optimizer to inline them when all arguments are constant.
3. Handle complex lookups: For values that are constant but require computation (like hex colors or deep key paths), use the init(pureSymbols:) initializer to decode or look up values.

Disabling Optimization: If an expression is only evaluated once or twice, you may want to disable optimization to save initialization time using the .noOptimize option.

When using labelled consumers, Consumer uses the Label type's description to explain what was expected in an error message. To provide user-friendly, localizable descriptions instead of raw enum values, make your Label type conform to CustomStringConvertible and implement the description property.

Similarly, implement CustomStringConvertible for your custom error types thrown during the transform phase to provide meaningful error messages.

// For Label types
enum JSONLabel: String, CustomStringConvertible {
    case string
    case array
    case json
    
    var description: String {
        switch self {
        case .string: return "a string"
        case .array: return "an array"
        case .json: return "a json value"
        }
    }
}

// For custom transform errors
enum JSONError: Error, CustomStringConvertible {
    case invalidNumber(String)
    case invalidCodePoint(String)
    
    var description: String {
        switch self {
        case let .invalidNumber(string):
            return "invalid numeric literal '\(string)'"
        case let .invalidCodePoint(string):
            return "invalid unicode code point '\(string)'"
        }
    }
}

To create reusable UI components that use Layout internally, subclass UIView (or UIControl, UIButton, etc.) and conform to the LayoutLoading protocol. This allows you to load XML layouts directly into the view.

Important Notes:

• The root view defined in the XML is loaded as a subview of your class and automatically sized to match.
• Do not attempt to load a view inside itself (e.g., loading MyView.xml inside MyView class), as this causes an infinite loading loop and a runtime error.
• To support dynamic sizing, override intrinsicContentSize to return the layoutNode?.frame.size and update the frame in layoutSubviews.

class MyView: UIView, LayoutLoading {

    override init(frame: CGRect) {
        super.init(frame: frame)

        loadLayout(
            named: "MyView.xml",
            state: ..., // your state object
            constants: ..., // your constants
        )
    }
    
    override func layoutSubviews() {
        super.layoutSubviews()

        // Ensure layout is updated after screen rotation, etc
        self.layoutNode?.view.frame = self.bounds
        
        // Update frame to match layout if it has dynamic size
        self.frame.size = self.intrinsicContentSize
    }

    public override var intrinsicContentSize: CGSize {
        return layoutNode?.frame.size ?? .zero
    }
}

To make enum cases or OptionSet values available in Layout expressions, extend the RuntimeType class with @objc static let properties. The property name should match the type name with a lowercase prefix.

For enums, provide a dictionary mapping string names to the actual enum cases. For OptionSet, do the same with the option values.

extension RuntimeType {

    @objc static let myStructType = RuntimeType(MyStructType.self)

    @objc static let nsTextAlignment = RuntimeType([
        "left": .left,
        "right": .right,
        "center": .center,
        "justified": .justified,
        "natural": .natural,
    ] as [String: NSTextAlignment])

    @objc static let uiDataDetectorTypes = RuntimeType([
        "phoneNumber": .phoneNumber,
        "link": .link,
        "address": .address,
        "calendarEvent": .calendarEvent,
        "all": .all,
    ] as [String: UIDataDetectorTypes])
}

By default, Expression caches parsed expressions in an unlimited-size cache.

To clear the cache:

• Clear everything: Expression.flushCache()
• Clear a specific expression: Expression.flushCache(for: "foo + bar")

To avoid caching: If you want fine-grained control or want to avoid the global cache, pre-parse the expression with usingCache: false and then initialize the Expression instance from the parsed result.

Parsing embedded expressions: You can use a variant of Expression.parse() that accepts a String.UnicodeScalarView.SubSequence and a delimiter to extract and parse an expression from within a larger string.

// Clear all cached expressions
Expression.flushCache()

// Clear a specific expression
Expression.flushCache(for: "foo + bar")

// Parse without caching
let expressionString = "foo + bar"
let parsedExpression = Expression.parse(expressionString, usingCache: false)
let expression = Expression(parsedExpression, constants: ["foo": 4, "bar": 5])