From e0efd19a9c1c34103125e8227ff0db6b12a7a247 Mon Sep 17 00:00:00 2001
From: onionpancakes <639985+onionpancakes@users.noreply.github.com>
Date: Wed, 21 Feb 2024 14:14:35 -0800
Subject: [PATCH] added readme on runtime compile
---
README.md | 35 +++++++++++++++++++++++++++++++++++
1 file changed, 35 insertions(+)
diff --git a/README.md b/README.md
index cc9b9d3..d0b59ab 100644
--- a/README.md
+++ b/README.md
@@ -736,6 +736,41 @@ Symbols referring to **constant** values are **var resolved** during compilation
#object[dev.onionpancakes.chassis.core.RawString 0x7fb21735 "foo bar
"]
```
+## Runtime Compilation
+
+Chassis provides two analogous compile functions, `compile-node` and `compile-node*`, for compiling HTML tree at runtime. They are useful for compiling static HTML pages or components.
+
+Because compiling happens at runtime, list and functions calls are no longer compilation barriers and ambiguous attributes are are not possible.
+
+Runtime compilation is similar to calling `c/html` with a few key differences:
+
+* The return values are `raw` strings, allowing the result to be embedded in other HTML components without being escaped.
+* Stateful values, such as functions and derefs, are not realized.
+
+```clojure
+(defn current-time []
+ (java.time.LocalTime/now))
+
+(defmethod c/resolve-alias ::CurrentTime
+ [_ _ _ _]
+ [:p "Current time is: " current-time])
+
+(def static-page
+ (cc/compile-node
+ [::CurrentTime]))
+
+;; Results in:
+[#object[dev.onionpancakes.chassis.core.RawString 0x7a702aaf "Current time is: "]
+ ;; Notice current-time function is not yet called.
+ #object[user$current_time 0x584d9dc4 "user$current_time@584d9dc4"]
+ #object[dev.onionpancakes.chassis.core.RawString 0x1c59c510 "
"]]
+
+;; Stateful values realized on call to c/html
+(c/html static-page)
+
+;; "Current time is: 13:48:14.228299269
"
+```
+
# Performance
At this time, benchmarks shows Chassis to be 2x faster (and often more!) when compared to other Clojure HTML templating libraries on equivalent benchmark examples.