From 1072e919a3ae489a703f5f8fe7b7c04f26ae8b68 Mon Sep 17 00:00:00 2001 From: David Jennes Date: Thu, 28 Jul 2022 00:33:36 +0200 Subject: [PATCH 1/3] Create mechanism for providing lazily evaluated context data --- Sources/Stencil/Context.swift | 18 ++++--- Sources/Stencil/LazyValueWrapper.swift | 69 ++++++++++++++++++++++++++ Sources/Stencil/Variable.swift | 2 + 3 files changed, 81 insertions(+), 8 deletions(-) create mode 100644 Sources/Stencil/LazyValueWrapper.swift diff --git a/Sources/Stencil/Context.swift b/Sources/Stencil/Context.swift index 07136f58..21b2a4ef 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 00000000..fc9cd350 --- /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 5fe5c102..1948f4e3 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) } } From 07d36651bfadad6538829844672c828c236f45e9 Mon Sep 17 00:00:00 2001 From: David Jennes Date: Thu, 28 Jul 2022 02:15:06 +0200 Subject: [PATCH 2/3] Tests --- Tests/StencilTests/ContextSpec.swift | 69 ++++++++++++++++++++++++++++ 1 file changed, 69 insertions(+) diff --git a/Tests/StencilTests/ContextSpec.swift b/Tests/StencilTests/ContextSpec.swift index 926c0ecb..9c9fe5e3 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" + } } From 5f0c01809d679854b976a187061258a70d9d10f2 Mon Sep 17 00:00:00 2001 From: David Jennes Date: Thu, 28 Jul 2022 02:30:25 +0200 Subject: [PATCH 3/3] Docs & changelog entry --- CHANGELOG.md | 3 +++ docs/templates.rst | 9 ++++++++- 2 files changed, 11 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ab70214..149299f9 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/docs/templates.rst b/docs/templates.rst index c242b4bc..c57a3a50 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 ~~~~~~~