Update caching and README.

Author: colinc86

README.md

@@ -62,6 +62,18 @@ LaTeX("e^{i\\pi}+1=0")
 
 ![Euler's Identity](./assets/images/euler.png)
 
+##### Equations
+
+`LaTexSwiftUI` can parse and render equations (aside from the entire input string) defined with the following terminators.
+
+| Terminators |
+|-------------|
+| `$...$` |
+| `$$...$$` |
+| `\[...\]` |
+| `\begin{equation}...\end{equation}` |
+| `\begin{equation*}...\end{equation*}` |
+
 #### Image Rendering Mode
 
 You can specify the rendering mode of the rendered equations so that they either take on the style of the surrounding text or display the style rendered by MathJax. The default behavior is to use the `template` rendering mode so that images match surrounding text.
@@ -144,10 +156,35 @@ LaTeX("$x^2<1$")
 For more control over the MathJax rendering, you can pass a `TeXInputProcessorOptions` object to the view.
 
 ```swift
-// Add AMS style equation numbering
-LaTeX("""
-\\begin{equation}
-  e^{i\\pi}+1=0
-\\end{equation}
-""").texOptions(TeXInputProcessorOptions(loadPackages: TeXInputProcessorOptions.Packages.all))
+LaTeX("Hello, $\\LaTeX$!")
+  .texOptions(TeXInputProcessorOptions(loadPackages: [TeXInputProcessorOptions.Packages.base]))
+```
+
+### Caching
+
+`LaTeXSwiftUI` caches its SVG responses from MathJax and the images rendered as a result of the view's environment. If you want to control the cache, then you can access the static `cache` property.
+
+The caches are managed automatically, but if, for example, you wanted to clear the cache manually you may do so.
+
+```swift
+// Clear the SVG data cache.
+LaTeX.dataCache?.removeAll()
+
+// Clear the rendered image cache.
+LaTeX.imageCache.removeAll()
+```
+
+`LaTeXSwiftUI` uses the [caching](https://github.com/kean/Nuke/tree/master/Sources/Nuke/Caching) components of the [Nuke](https://github.com/kean/Nuke) package.
+
+### Preloading
+
+SVGs and images are rendered and cached on demand, but there may be situations where you want to preload the data so that there is no lag when the view appears.
+
+```swift
+VStack {
+  ForEach(expressions, id: \.self) { expression in
+    LaTeX(expression)
+      .preload()
+  }
+}
 ```

Sources/LaTeXSwiftUI/LaTeX.swift

@@ -6,6 +6,8 @@
 //
 
 import HTMLEntities
+import MathJaxSwift
+import Nuke
 import SwiftUI
 
 public struct LaTeX: View {
@@ -48,6 +50,16 @@ public struct LaTeX: View {
     case error
   }
 
+  /// The package's shared data cache.
+  public static var dataCache: DataCache? {
+    Renderer.shared.dataCache
+  }
+  
+  /// The package's shared image cache.
+  public static var imageCache: ImageCache {
+    Renderer.shared.imageCache
+  }
+  
   // MARK: Public properties
 
   /// The view's LaTeX input string.
@@ -105,24 +117,49 @@ public struct LaTeX: View {
   public var body: some View {
     switch blockMode {
     case .alwaysInline:
-      asText(forceInline: true)
+      blocksAsText(blocks, forceInline: true)
     case .blockText:
-      asText(forceInline: false)
+      blocksAsText(blocks)
     case .blockViews:
-      asStack()
+      blocksAsStack(blocks)
     }
   }
 
 }
 
+// MARK: Public methods
+
+extension LaTeX {
+  
+  /// Preloads the view's components.
+  ///
+  /// - Returns: A LaTeX view whose components have been preloaded.
+  @MainActor public func preload() -> LaTeX {
+    switch blockMode {
+    case .alwaysInline:
+      blocksAsText(blocks, forceInline: true)
+    case .blockText:
+      blocksAsText(blocks)
+    case .blockViews:
+      blocksAsStack(blocks)
+    }
+    return self
+  }
+  
+}
+
+// MARK: Private methods
+
 extension LaTeX {
 
   /// The view's input rendered as a text view.
   ///
   /// - Parameter forceInline: Whether or not block equations should be forced
   ///   as inline.
   /// - Returns: A text view.
-  @MainActor private func asText(forceInline: Bool) -> Text {
+  @MainActor
+  @discardableResult
+  private func blocksAsText(_ blocks: [ComponentBlock], forceInline: Bool = false) -> Text {
     blocks.map { block in
       let text = text(for: block)
       return block.isEquationBlock && !forceInline ?
@@ -134,7 +171,9 @@ extension LaTeX {
   /// The view's input rendered as a vertical stack of views.
   ///
   /// - Returns: A stack view.
-  @MainActor private func asStack() -> some View {
+  @MainActor
+  @discardableResult
+  private func blocksAsStack(_ blocks: [ComponentBlock]) -> some View {
     VStack(alignment: .leading, spacing: lineSpacing + 4) {
       ForEach(blocks, id: \.self) { block in
         if block.isEquationBlock,
@@ -188,28 +227,20 @@ extension LaTeX {
 @available(iOS 16.1, *)
 struct LaTeX_Previews: PreviewProvider {
   static var previews: some View {
-//    VStack {
-//      LaTeX("Hello, $\\LaTeX$!")
-//        .font(.title)
-//
-//      LaTeX("Hello, $\\LaTeX$!")
-//        .font(.title2)
-//        .foregroundColor(.cyan)
-//
-//      LaTeX("Hello, $\\LaTeX$!")
-//        .font(.title3)
-//        .foregroundColor(.pink)
-//    }
-//    .fontDesign(.serif)
-//    .previewLayout(.sizeThatFits)
-    
     VStack {
-      LaTeX("This is a block equation with some block after it $$\\text{and this is some text on the next line}$$ with some more text that comes after it!")
-        .lineSpacing(5)
-      Divider()
-      Text("This is a block equation with some block afte and it wraps and this is some text on the next line and blah blah with some more text that comes after it!")
-        .lineSpacing(5)
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title)
+
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title2)
+        .foregroundColor(.cyan)
+
+      LaTeX("Hello, $\\LaTeX$!")
+        .font(.title3)
+        .foregroundColor(.pink)
     }
+    .fontDesign(.serif)
+    .previewLayout(.sizeThatFits)
   }
 
 }

Sources/LaTeXSwiftUI/Models/Renderer.swift

@@ -78,20 +78,25 @@ internal class Renderer {
   private let mathjax: MathJax?
 
   /// The renderer's data cache.
-  private let cache: DataCache?
+  internal let dataCache: DataCache?
+  
+  /// The renderer's image cache.
+  internal let imageCache: ImageCache
 
   // MARK: Initializers
 
   /// Initializes a renderer with a MathJax instance.
   init() {
     do {
-      cache = try DataCache(name: "mathJaxRenderCache")
+      dataCache = try DataCache(name: "mathJaxRenderDataCache")
     }
     catch {
       logError("Error creating DataCache instance: \(error)")
-      cache = nil
+      dataCache = nil
     }
 
+    imageCache = ImageCache()
+    
     do {
       mathjax = try MathJax(preferredOutputFormat: .svg)
     }
@@ -164,7 +169,7 @@ extension Renderer {
     let cacheKey = ImageCacheKey(svg: svg, xHeight: xHeight)
 
     // Check the cache for an image
-    if let imageData = cache?[cacheKey.key()], let image = _Image(imageData: imageData, scale: displayScale) {
+    if let image = imageCache[Nuke.ImageCacheKey(key: cacheKey.key())]?.image {
       return (Image(image: image)
         .renderingMode(renderingMode)
         .antialiased(true)
@@ -181,14 +186,13 @@ extension Renderer {
 #if os(iOS)
     renderer.scale = UIScreen.main.scale
     let image = renderer.image
-    cache?[cacheKey.key()] = image?.pngData()
 #else
     renderer.scale = NSScreen.main?.backingScaleFactor ?? 1
     let image = renderer.image
-    cache?[cacheKey.key()] = image?.tiffRepresentation
 #endif
 
     if let image = image {
+      imageCache[Nuke.ImageCacheKey(key: cacheKey.key())] = ImageContainer(image: image)
       return (Image(image: image)
         .renderingMode(renderingMode)
         .antialiased(true)
@@ -242,7 +246,7 @@ extension Renderer {
         texOptions: texOptions)
 
       // Do we have the SVG in the cache?
-      if let svgData = cache?[cacheKey.key()] {
+      if let svgData = dataCache?[cacheKey.key()] {
         renderedComponents.append(Component(
           text: component.text,
           type: component.type,
@@ -270,7 +274,7 @@ extension Renderer {
 
       // Create the SVG
       let svg = try SVG(svgString: svgString, errorText: errorText)
-      cache?[cacheKey.key()] = try JSONEncoder().encode(svg)
+      dataCache?[cacheKey.key()] = try JSONEncoder().encode(svg)
 
       // Save the rendered component
       renderedComponents.append(Component(

Sources/LaTeXSwiftUI/Views/HorizontalImageScroller.swift

@@ -7,6 +7,7 @@
 
 import SwiftUI
 
+/// A view that contains an image that can be scrolled horizontally.
 internal struct HorizontalImageScroller: View {
 
   /// The image to display.
@@ -15,11 +16,14 @@ internal struct HorizontalImageScroller: View {
   /// The height of the image.
   let height: CGFloat
 
+  /// Whether the scroll view should show its indicators.
+  var showsIndicators: Bool = false
+  
   // MARK: View body
 
   var body: some View {
     GeometryReader { geometry in
-      ScrollView(.horizontal, showsIndicators: false) {
+      ScrollView(.horizontal, showsIndicators: showsIndicators) {
         HStack { image }
           .frame(minWidth: geometry.size.width)
       }