...

README.md

@@ -31,17 +31,18 @@ Run `bin/run` (or <kbd>Ctrl+Shift+B</kbd> in VSCode). This runs the clock exampl
     - [x] or, investigate https://hackage.haskell.org/package/ghci-websockets
 - [x] Multi-websocket-client support
 - [ ] Refactor Server.hs
-- [ ] Publish Data.LVar to Hackage
+- [ ] Static site generation mode
+- [ ] add common examples,
+  - [x] filesystem watcher
+  - [ ] docs site for self (w/ sidebar and possibly even search)
 
 pre-announce,
 - [ ] plan features / messaging, re: hakyll
   - Safer and simpler routes system
   - Template system?
 - [ ] CLI UX (opts, logging, etc.)
-- [ ] add common examples,
-  - [x] filesystem watcher
-  - [ ] docs site for self (w/ sidebar and possibly even search)
 - [ ] documentation ([howto](https://documentation.divio.com/))
+- [ ] Publish Data.LVar to Hackage
 
 doc notes,
 - use async:race to avoid ghcid ghosts

src/Ema/App.hs

@@ -16,7 +16,7 @@ import GHC.IO.Handle (BufferMode (LineBuffering), hSetBuffering)
 -- | Pure version of @runEma@ (i.e with no model).
 --
 -- Due to purity, there is no impure state, and thus no time-varying model. The
--- render function consequently takes only the route as argument.
+-- render function consequently takes only the @route@ as argument.
 runEmaPure ::
   forall route.
   (IsRoute route, Show route) =>
@@ -27,21 +27,26 @@ runEmaPure render = do
   emptyModel <- LVar.empty
   runEma emptyModel (const render)
 
--- | Run Ema live server
---
--- Continually observe the world, with a concomitant incremental update of the
--- model so as to hot-reload the browser view.
+-- | Run Ema live dev server
 runEma ::
   forall model route.
   (Show route, IsRoute route) =>
-  -- | Your site model
+  -- | Your site model type, as a @LVar@ in order to support modifications over
+  -- time (for hot-reload).
+  --
+  -- Use @Data.LVar.new@ to create it, and then -- over time -- @Data.LVar.set@
+  -- or @Data.LVar.modify@ to modify it. Ema will automatically hot-reload your
+  -- site as this model data changes.
   LVar model ->
-  -- | Your site render function
+  -- | Your site render function. Takes the current @model@ value, and the page
+  -- @route@ type as arguments. It must return the raw HTML to render to browser
+  -- or generate on disk.
   (model -> route -> LByteString) ->
   IO ()
 runEma model render = do
   -- TODO: Use a logging library, in place of managing buffering and using putStrLn
   hSetBuffering stdout LineBuffering
   hSetBuffering stderr LineBuffering
-  putStrLn "Launching Ema at http://localhost:8000"
-  Server.runServerWithWebSocketHotReload model render
+  let port = 8000
+  putStrLn $ "Launching Ema at http://localhost:" <> show port
+  Server.runServerWithWebSocketHotReload port model render

src/Ema/Server.hs

@@ -21,11 +21,12 @@ import qualified Network.WebSockets as WS
 runServerWithWebSocketHotReload ::
   forall model route.
   (Show route, IsRoute route) =>
+  Int ->
   LVar model ->
   (model -> route -> LByteString) ->
   IO ()
-runServerWithWebSocketHotReload model render = do
-  let settings = Warp.setPort 8000 Warp.defaultSettings
+runServerWithWebSocketHotReload port model render = do
+  let settings = Warp.setPort port Warp.defaultSettings
   Warp.runSettings settings $ WaiWs.websocketsOr WS.defaultConnectionOptions wsApp httpApp
   where
     wsApp pendingConn = do