Merge pull request #12 from colinc86/v1.1

v1.1

Author: colinc86

Package.resolved

@@ -17,7 +17,7 @@ let package = Package(
   dependencies: [
      .package(url: "https://github.com/colinc86/MathJaxSwift", from: "3.2.2"),
      .package(url: "https://github.com/exyte/SVGView", from: "1.0.4"),
-     .package(url: "https://github.com/kean/Nuke", from: "11.3.1"),
+     .package(url: "https://github.com/kean/Nuke", from: "12.1.0"),
      .package(url: "https://github.com/Kitura/swift-html-entities", from: "4.0.1")
   ],
   targets: [

Package.swift

@@ -1,31 +1,50 @@
 # LaTeXSwiftUI
 
-A SwiftUI view that renders LaTeX.
+A SwiftUI view that renders LaTeX equations.
 
 ![Swift Version](https://img.shields.io/badge/Swift-5.7-orange?logo=swift) ![iOS Version](https://img.shields.io/badge/iOS-16-informational) ![macOS Version](https://img.shields.io/badge/macOS-13-informational)
 
-<center><img src="./assets/images/device.png" width="362" height="707"></center>
+<center><img src="./assets/images/device.png" width="362"></center>
 
 ## 📖 Contents
 
+- [About](#ℹ️-about)
 - [Installation](#📦-installation)
 - [Usage](#⌨️-usage)
   - [Modifiers](#⚙️-modifiers)
     - [Parsing Mode](#🔤-parsing-mode)
     - [Image Rendering Mode](#🌄-image-rendering-mode)
     - [Error Mode](#🚨-error-mode)
     - [Block Rendering Mode](#🧱-block-rendering-mode)
+    - [Numbered Block Equations](#🔢-numbered-block-equations)
+      - [Equation Number Mode](#equation-number-mode)
+      - [Equation Number Start](#equation-number-start)
+      - [Equation Number Offset](#equation-number-offset)
     - [Unencode HTML](#🔗-unencode-html)
-    - [TeX Options](#♾️-tex-options)
   - [Caching](#🗄️-caching)
   - [Preloading](#🏃‍♀️-preloading)
+  
+## ℹ️ About
+
+`LaTexSwiftUI` is a package that exposes a view named `LaTeX` that can parse and render TeX and LaTeX equations which contain math-mode marcos.
+
+The view utilizes the [MathJaxSwift](https://www.github.com/colinc86/MathJaxSwift) package to render equations with [MathJax](https://www.mathjax.org). Thus, the limitations of the view are heavily influenced by the [limitations](https://docs.mathjax.org/en/v2.7-latest/tex.html#differences) of MathJax.
+
+It will
+- render TeX and LaTeX equations (math-mode macros),
+- render the `\text{}` macro within equations,
+- attempt to render block equations as a Tex or LaTeX engine would,
+- and number block equations (if desired).
+
+It won't
+- render TeX and LaTeX documents (text-mode macros, with the exception of the rule above).
 
 ## 📦 Installation
 
 Add the dependency to your package manifest file.
 
 ```swift
-.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.0.4")
+.package(url: "https://github.com/colinc86/LaTeXSwiftUI", from: "1.1.0")
 ```
 
 ## ⌨️ Usage
@@ -62,7 +81,7 @@ Along with supporting the built-in SwiftUI modifies, `LaTeXSwiftUI` defines more
 
 #### 🔤 Parsing Mode
 
-`LaTexSwiftUI` can parse and render equations (aside from the entire input string) defined with the following terminators.
+Text input can either be completely rendered, or the view can search for top-level equations delimited by the following terminators.
 
 | Terminators |
 |-------------|
@@ -72,15 +91,20 @@ Along with supporting the built-in SwiftUI modifies, `LaTeXSwiftUI` defines more
 | `\begin{equation}...\end{equation}` |
 | `\begin{equation*}...\end{equation*}` |
 
-Text input can either be completely rendered, or `LaTeXSwiftUI` can search for top-level equations. The default behavior is to only render equations with `onlyEquations`. Use the `parsingMode` modifier to change the default behavior.
+ The default behavior is to only render equations with `onlyEquations`. Use the `parsingMode` modifier to change the default behavior.
 
 ```swift
+// Only parse equations (default)
+LaTeX("Euler's identity is $e^{i\\pi}+1=0$.")
+  .font(.system(size: 18))
+  .parsingMode(.onlyEquations)
+
 // Parse the entire input
-LaTeX("e^{i\\pi}+1=0")
+LaTeX("\\text{Euler's identity is } e^{i\\pi}+1=0\\text{.}")
   .parsingMode(.all)
 ```
 
-> <img src="./assets/images/euler.png" width="75" height="19.5">
+> <img src="./assets/images/euler.png" width="293" height="80">
 
 #### 🌄 Image Rendering Mode
 
@@ -102,6 +126,8 @@ LaTeX("Hello, ${\\color{red} \\LaTeX}$!")
 
 When an error occurs while parsing the input the view will display the original LaTeX. You can change this behavior by modifying the view's `errorMode`.
 
+> Note: when the `rendered` mode is used, MathJax is instructed to load the `noerrors` and `noundefined` packages. In the other two modes, `original` and `error`, these packages are not loaded by MathJax and errors are either displayed in the view, or caught and replaced with the original text.
+
 ```swift
 // Display the original text instead of the equation
 LaTeX("$\\asdf$")
@@ -144,6 +170,41 @@ LaTeX("The quadratic formula is $$x=\\frac{-b\\pm\\sqrt{b^2-4ac}}{2a}$$ and it h
 
 > <img src="./assets/images/blocks.png" width="430" height="350">
 
+#### 🔢 Numbered Block Equations
+
+The `LaTeX` view can do simple numbering of block equations with the `blockViews` block mode.
+
+##### Equation Number Mode
+
+Use the `equationNumberMode` modifier to change between `left`, `right` and `none`.
+
+##### Equation Number Start
+
+The default starting number is `1`, but if you need to start at a different value, you can specify it with the `equationNumberStart` modifier.
+
+##### Equation Number Offset
+
+To change the left or right offset of the equation number, use the `equationNumberOffset` modifier.
+
+```swift
+// Don't number block equations (default)
+LaTeX("$$a + b = c$$")
+  .equationNumberMode(.none)
+
+// Add left numbers and a leading offset
+LaTeX("$$d + e = f$$")
+  .equationNumberMode(.left)
+  .equationNumberOffset(10)
+
+// Add right numbers, a leading offset, and start at 2
+LaTeX("$$h + i = j$$ $$k + l = m$$")
+  .equationNumberMode(.right)
+  .equationNumberStart(2)
+  .equationNumberOffset(20)
+```
+
+> <img src="./assets/images/numbers.png" width="428" height="152">
+
 #### 🔗 Unencode HTML
 
 Input may contain HTML entities such as `&lt;` which will not be parsed by LaTeX as anything meaningful. In this case, you may use the `unencoded` modifier.
@@ -152,25 +213,16 @@ Input may contain HTML entities such as `&lt;` which will not be parsed by LaTeX
 LaTeX("$x^2&lt;1$")
   .errorMode(.error)
 
-// Replace "lt;" with "<"
+// Replace "&lt;" with "<"
 LaTeX("$x^2&lt;1$")
   .unencoded()
 ```
 
 > <img src="./assets/images/unencoded.png" width="72.5" height="34">
 
-#### ♾️ TeX Options
-
-For more control over the MathJax rendering, you can pass a `TeXInputProcessorOptions` object to the view.
-
-```swift
-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.
+`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 `dataCache` and `imageCache` properties.
 
 The caches are managed automatically, but if, for example, you wanted to clear the cache manually you may do so.
 
@@ -188,10 +240,17 @@ LaTeX.imageCache.removeAll()
 
 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 minimal lag when the view appears.
 
+SVGs and images are rendered as a result of the view's environment, so it is important to call the `preload` method last in the view's modifier chain if you use it.
+
 ```swift
 VStack {
   ForEach(expressions, id: \.self) { expression in
     LaTeX(expression)
+      .font(.caption2)
+      .foregroundColor(.green)
+      .unencoded()
+      .errorMode(.error)
+      .processEscapes()
       .preload()
   }
 }

README.md

@@ -46,8 +46,20 @@ private struct BlockModeKey: EnvironmentKey {
   static let defaultValue: LaTeX.BlockMode = .blockViews
 }
 
-private struct TeXInputProcessorOptionsKey: EnvironmentKey {
-  static let defaultValue: TeXInputProcessorOptions = TeXInputProcessorOptions(loadPackages: TeXInputProcessorOptions.Packages.all)
+private struct ProcessEscapesKey: EnvironmentKey {
+  static let defaultValue: Bool = false
+}
+
+private struct EquationNumberModeKey: EnvironmentKey {
+  static let defaultValue: LaTeX.EquationNumberMode = .none
+}
+
+private struct EquationNumberStartKey: EnvironmentKey {
+  static let defaultValue: Int = 1
+}
+
+private struct EquationNumberOffsetKey: EnvironmentKey {
+  static let defaultValue: CGFloat = 0.0
 }
 
 extension EnvironmentValues {
@@ -82,10 +94,28 @@ extension EnvironmentValues {
     set { self[BlockModeKey.self] = newValue }
   }
 
-  /// The TeX options of this environment.
-  var texOptions: TeXInputProcessorOptions {
-    get { self[TeXInputProcessorOptionsKey.self] }
-    set { self[TeXInputProcessorOptionsKey.self] = newValue }
+  /// The processEscapes value of this environment.
+  var processEscapes: Bool {
+    get { self[ProcessEscapesKey.self] }
+    set { self[ProcessEscapesKey.self] = newValue }
+  }
+  
+  /// The equation number mode of this environment.
+  var equationNumberMode: LaTeX.EquationNumberMode {
+    get { self[EquationNumberModeKey.self] }
+    set { self[EquationNumberModeKey.self] = newValue }
+  }
+  
+  /// The equation starting number of this environment.
+  var equationNumberStart: Int {
+    get { self[EquationNumberStartKey.self] }
+    set { self[EquationNumberStartKey.self] = newValue }
+  }
+  
+  /// The equation number offset of this environment.
+  var equationNumberOffset: CGFloat {
+    get { self[EquationNumberOffsetKey.self] }
+    set { self[EquationNumberOffsetKey.self] = newValue }
   }
 
 }

Sources/LaTeXSwiftUI/Extensions/EnvironmentValues+Extensions.swift

@@ -28,6 +28,31 @@ import SwiftUI
 
 public extension View {
 
+  /// Preloads a `LaTeX` view's SVG and image data.
+  ///
+  /// This method should be called last in the view's modifier chain (if at
+  /// all).
+  ///
+  /// - Example:
+  ///
+  /// ```
+  /// LaTeX("Hello, $\\LaTeX$!")
+  ///   .font(.title)
+  ///   .processEscapes()
+  ///   .preload()
+  /// ```
+  ///
+  /// - Note: If the receiver isn't a `LaTeX` view, then this method does
+  ///   nothing.
+  ///
+  /// - Returns: A preloaded view.
+  @MainActor func preload() -> some View {
+    if let latex = self as? LaTeX {
+      latex.preload()
+    }
+    return self
+  }
+  
   /// Sets the image rendering mode for images rendered by MathJax.
   ///
   /// - Parameter mode: The template rendering mode.
@@ -47,9 +72,10 @@ public extension View {
 
   /// Unencodes HTML input text.
   ///
+  /// - Parameter unencode: Whether the variable should be set to true or false.
   /// - Returns: A view that displays unencoded text.
-  func unencoded() -> some View {
-    environment(\.unencodeHTML, true)
+  func unencoded(_ unencode: Bool = true) -> some View {
+    environment(\.unencodeHTML, unencode)
   }
 
   /// Sets the parsing mode to use when parsing LaTeX input.
@@ -68,14 +94,47 @@ public extension View {
     environment(\.blockMode, mode)
   }
 
-  /// Sets the TeX options for any images rendered with MathJax in this
-  /// environment.
-  ///
-  /// - Parameter options: The TeX input processor options.
-  /// - Returns: A view that uses the given TeX input processor options to
-  ///   render images in its view.
-  func texOptions(_ options: TeXInputProcessorOptions) -> some View {
-    environment(\.texOptions, options)
+  /// When set to `true`, you may use `\$` to represent a literal dollar sign,
+  /// rather than using it as a math delimiter, and `\\` to represent a literal
+  /// backslash (so that you can use `\\\$` to get a literal `\$` or `\\$...$`
+  /// to get a backslash just before in-line math).
+  ///
+  /// When `false`, `\$` will not be altered, and its dollar sign may be
+  /// considered part of a math delimiter. Typically this is set to `true` if
+  /// you enable the `$ ... $` in-line delimiters, so you can type `\$` and
+  /// MathJax will convert it to a regular dollar sign in the rendered document.
+  ///
+  /// - Reference: [Option Descriptions](https://docs.mathjax.org/en/latest/options/input/tex.html#option-descriptions)
+  ///
+  /// - Parameter process: Whether escapes should be processed.
+  /// - Returns: A view that processes escapes in its text input.
+  func processEscapes(_ process: Bool = true) -> some View {
+    environment(\.processEscapes, process)
+  }
+  
+  /// Sets whether block view equation numbers should be hidden, displayed on
+  /// the left side of an equation, or displayed on the right side.
+  ///
+  /// - Parameter mode: The equation number mode.
+  /// - Returns: A view that numbers its equations.
+  func equationNumberMode(_ mode: LaTeX.EquationNumberMode) -> some View {
+    environment(\.equationNumberMode, mode)
+  }
+  
+  /// Sets the starting value for equation numbers in this view.
+  ///
+  /// - Parameter value: The starting value.
+  /// - Returns: A view that numbers its equations.
+  func equationNumberStart(_ value: Int) -> some View {
+    environment(\.equationNumberStart, value)
+  }
+  
+  /// Sets the number's left or right offset.
+  ///
+  /// - Parameter offset: The offset to set.
+  /// - Returns: A view that numbers its equations.
+  func equationNumberOffset(_ offset: CGFloat) -> some View {
+    environment(\.equationNumberOffset, offset)
   }
 
 }