Support lazy context data

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
 

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

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
+  }
+}

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)
       }
     }
 

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"
+  }
 }

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
 ~~~~~~~