diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ab7021..149299f 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -41,6 +41,9 @@ [David Jennes](https://github.com/djbe) [#164](https://github.com/stencilproject/Stencil/pull/164) [#325](https://github.com/stencilproject/Stencil/pull/325) +- Allow providing lazily evaluated context data, using the `LazyValueWrapper` structure. + [David Jennes](https://github.com/djbe) + [#324](https://github.com/stencilproject/Stencil/pull/324) ### Deprecations diff --git a/Sources/Stencil/Context.swift b/Sources/Stencil/Context.swift index 07136f5..21b2a4e 100644 --- a/Sources/Stencil/Context.swift +++ b/Sources/Stencil/Context.swift @@ -11,19 +11,21 @@ public class Context { /// The context's environment, such as registered extensions, classes, … public let environment: Environment + init(dictionaries: [[String: Any?]], environment: Environment) { + self.dictionaries = dictionaries + self.environment = environment + } + /// Create a context from a dictionary (and an env.) /// /// - Parameters: /// - dictionary: The context's data /// - environment: Environment such as extensions, … - public init(dictionary: [String: Any] = [:], environment: Environment? = nil) { - if !dictionary.isEmpty { - dictionaries = [dictionary] - } else { - dictionaries = [] - } - - self.environment = environment ?? Environment() + public convenience init(dictionary: [String: Any] = [:], environment: Environment? = nil) { + self.init( + dictionaries: dictionary.isEmpty ? [] : [dictionary], + environment: environment ?? Environment() + ) } /// Access variables in this context by name diff --git a/Sources/Stencil/LazyValueWrapper.swift b/Sources/Stencil/LazyValueWrapper.swift new file mode 100644 index 0000000..fc9cd35 --- /dev/null +++ b/Sources/Stencil/LazyValueWrapper.swift @@ -0,0 +1,69 @@ +// +// Stencil +// Copyright © 2022 Stencil +// MIT Licence +// + +/// Used to lazily set context data. Useful for example if you have some data that requires heavy calculations, and may +/// not be used in every render possiblity. +public final class LazyValueWrapper { + private let closure: (Context) throws -> Any + private let context: Context? + private var cachedValue: Any? + + /// Create a wrapper that'll use a **reference** to the current context. + /// This means when the closure is evaluated, it'll use the **active** context at that moment. + /// + /// - Parameters: + /// - closure: The closure to lazily evaluate + public init(closure: @escaping (Context) throws -> Any) { + self.context = nil + self.closure = closure + } + + /// Create a wrapper that'll create a **copy** of the current context. + /// This means when the closure is evaluated, it'll use the context **as it was** when this wrapper was created. + /// + /// - Parameters: + /// - context: The context to use during evaluation + /// - closure: The closure to lazily evaluate + /// - Note: This will use more memory than the other `init` as it needs to keep a copy of the full context around. + public init(copying context: Context, closure: @escaping (Context) throws -> Any) { + self.context = Context(dictionaries: context.dictionaries, environment: context.environment) + self.closure = closure + } + + /// Shortcut for creating a lazy wrapper when you don't need access to the Stencil context. + /// + /// - Parameters: + /// - closure: The closure to lazily evaluate + public init(_ closure: @autoclosure @escaping () throws -> Any) { + self.context = nil + self.closure = { _ in try closure() } + } +} + +extension LazyValueWrapper { + func value(context: Context) throws -> Any { + if let value = cachedValue { + return value + } else { + let value = try closure(self.context ?? context) + cachedValue = value + return value + } + } +} + +extension LazyValueWrapper: Resolvable { + public func resolve(_ context: Context) throws -> Any? { + let value = try self.value(context: context) + return try (value as? Resolvable)?.resolve(context) ?? value + } +} + +extension LazyValueWrapper: Normalizable { + public func normalize() -> Any? { + (cachedValue as? Normalizable)?.normalize() ?? cachedValue + } +} diff --git a/Sources/Stencil/Variable.swift b/Sources/Stencil/Variable.swift index 5fe5c10..1948f4e 100644 --- a/Sources/Stencil/Variable.swift +++ b/Sources/Stencil/Variable.swift @@ -78,6 +78,8 @@ public struct Variable: Equatable, Resolvable { if current == nil { return nil + } else if let lazyCurrent = current as? LazyValueWrapper { + current = try lazyCurrent.value(context: context) } } diff --git a/Tests/StencilTests/ContextSpec.swift b/Tests/StencilTests/ContextSpec.swift index 926c0ec..9c9fe5e 100644 --- a/Tests/StencilTests/ContextSpec.swift +++ b/Tests/StencilTests/ContextSpec.swift @@ -94,4 +94,73 @@ final class ContextTests: XCTestCase { } } } + + func testContextLazyEvaluation() { + let ticker = Ticker() + var context = Context() + var wrapper = LazyValueWrapper("") + + describe("Lazy evaluation") { test in + test.before { + ticker.count = 0 + wrapper = LazyValueWrapper(ticker.tick()) + context = Context(dictionary: ["name": wrapper]) + } + + test.it("Evaluates lazy data") { + let template = Template(templateString: "{{ name }}") + let result = try template.render(context) + try expect(result) == "Kyle" + try expect(ticker.count) == 1 + } + + test.it("Evaluates lazy only once") { + let template = Template(templateString: "{{ name }}{{ name }}") + let result = try template.render(context) + try expect(result) == "KyleKyle" + try expect(ticker.count) == 1 + } + + test.it("Does not evaluate lazy data when not used") { + let template = Template(templateString: "{{ 'Katie' }}") + let result = try template.render(context) + try expect(result) == "Katie" + try expect(ticker.count) == 0 + } + } + } + + func testContextLazyAccessTypes() { + it("Supports evaluation via context reference") { + let context = Context(dictionary: ["name": "Kyle"]) + context["alias"] = LazyValueWrapper { $0["name"] ?? "" } + let template = Template(templateString: "{{ alias }}") + + try context.push(dictionary: ["name": "Katie"]) { + let result = try template.render(context) + try expect(result) == "Katie" + } + } + + it("Supports evaluation via context copy") { + let context = Context(dictionary: ["name": "Kyle"]) + context["alias"] = LazyValueWrapper(copying: context) { $0["name"] ?? "" } + let template = Template(templateString: "{{ alias }}") + + try context.push(dictionary: ["name": "Katie"]) { + let result = try template.render(context) + try expect(result) == "Kyle" + } + } + } +} + +// MARK: - Helpers + +private final class Ticker { + var count: Int = 0 + func tick() -> String { + count += 1 + return "Kyle" + } } diff --git a/docs/templates.rst b/docs/templates.rst index c242b4b..c57a3a5 100644 --- a/docs/templates.rst +++ b/docs/templates.rst @@ -50,6 +50,14 @@ For example, if you have the following context: The result of {{ item[key] }} will be the same as {{ item.name }}. It will first evaluate the result of {{ key }}, and only then evaluate the lookup expression. +You can use the `LazyValueWrapper` type to have values in your context that will be lazily evaluated. The provided value will only be evaluated when it's first accessed in your template, and will be cached afterwards. For example: + +.. code-block:: swift + + [ + "magic": LazyValueWrapper(myHeavyCalculations()) + ] + Boolean expressions ------------------- @@ -60,7 +68,6 @@ For example, this will output string `true` if variable is equal to 1 and `false {{ variable == 1 }} - Filters ~~~~~~~