Docs(readme): Show how to read a window, session or pane again

README.md

@@ -234,6 +234,35 @@ matched: demo
 
 `complete` reports no known inconsistency. The read is still not atomic.
 
+### [`Window:snapshot`][ref-window-snapshot]: read one object again
+
+A record is what tmux said when it was read. Lua has no `refresh` that updates
+one in place, as Python libtmux's `.refresh()` does. Call `snapshot` on the
+handle instead: [`Window:snapshot`][ref-window-snapshot] returns a new record
+and leaves the one you hold as it was.
+
+[`Session:snapshot`][ref-session-snapshot] and
+[`Pane:snapshot`][ref-pane-snapshot] work the same way.
+
+This reads a window, renames it with [`Window:rename`][ref-window-rename], and
+reads it again:
+
+<!-- excerpt: examples/api/refresh.lua -->
+
+```lua
+local window = created.window
+local held = must(window:snapshot():await())
+must(window:rename("build"):await())
+local fresh = must(window:snapshot():await())
+assert(held.name == "editor" and fresh.name == "build", "refresh did not read the rename")
+print(held.name .. " " .. fresh.name)
+```
+
+```console
+$ sh examples/api/run.sh examples/api/refresh.lua
+editor build
+```
+
 ## Create sessions, windows and panes
 
 ### [`Session:new_window`][ref-session-new-window]: add a window
@@ -609,6 +638,9 @@ MIT. See [`LICENSE`](LICENSE).
 [ref-observation-watch-pane]: https://libtmux.org/en/lua/latest/reference/libtmux-observation-watch_pane/
 [ref-query]: https://libtmux.org/en/lua/latest/reference/libtmux-query/
 [ref-runtime-connect]: https://libtmux.org/en/lua/latest/reference/libtmux-runtime-connect/
+[ref-window-snapshot]: https://libtmux.org/en/lua/latest/reference/libtmux-window-snapshot/
+[ref-window-rename]: https://libtmux.org/en/lua/latest/reference/libtmux-window-rename/
+[ref-pane-snapshot]: https://libtmux.org/en/lua/latest/reference/libtmux-pane-snapshot/
 [ref-session-snapshot]: https://libtmux.org/en/lua/latest/reference/libtmux-session-snapshot/
 [ref-request]: https://libtmux.org/en/lua/latest/reference/libtmux-request/
 [ref-request-await]: https://libtmux.org/en/lua/latest/reference/libtmux-request-await/

examples/api/manifest.json

@@ -45,6 +45,16 @@
       "description": "Create a named window in a particular session.",
       "stdout": "window: logs\n"
     },
+    {
+      "id": "refresh",
+      "symbols": [
+        "libtmux.Entity:snapshot",
+        "libtmux.Window:rename"
+      ],
+      "file": "examples/api/refresh.lua",
+      "description": "Read a window again after tmux renamed it, keeping the record read before.",
+      "stdout": "editor build\n"
+    },
     {
       "id": "query",
       "symbols": [

examples/api/refresh.lua

@@ -0,0 +1,31 @@
+local adapter = require("libtmux.runtime.luv")
+
+local function must(value, err)
+    if err ~= nil then
+        error(tostring(err), 0)
+    end
+    return value
+end
+
+local binary = assert(os.getenv("TMUX_BIN"), "set TMUX_BIN to an absolute tmux executable")
+local socket = assert(os.getenv("TMUX_SOCKET"), "set TMUX_SOCKET to the private socket")
+
+must(adapter.run(function(runtime)
+    local server = must(runtime:connect({ binary = binary, socket_path = socket }):await())
+    local created = must(server
+        :new_session({
+            name = "demo",
+            window_name = "editor",
+            argv = { "/bin/cat" },
+        })
+        :await())
+    local window = created.window
+    local held = must(window:snapshot():await())
+    must(window:rename("build"):await())
+    local fresh = must(window:snapshot():await())
+    assert(held.name == "editor" and fresh.name == "build", "refresh did not read the rename")
+    print(held.name .. " " .. fresh.name)
+
+    must(server:close():await())
+    return true
+end))

tests/tooling/test_api_examples.py

@@ -14,6 +14,7 @@
     "libtmux.Snapshot.windows", "libtmux.Snapshot.panes", "libtmux.Server:new_session",
     "libtmux.Session:new_window", "libtmux.Server:query", "libtmux.Pane:send_text",
     "libtmux.Pane:send_keys", "libtmux.Pane:capture", "libtmux.Pane:wait_for_text", "libtmux.Error.code", "libtmux.Error.message",
+    "libtmux.Entity:snapshot", "libtmux.Window:rename",
 }
 
 
@@ -31,7 +32,7 @@ def save(self):
 
     def test_complete_programs_cover_their_existing_targets(self):
         manifest = load_examples(self.root, TARGETS)
-        self.assertEqual(len(manifest["examples"]), 9)
+        self.assertEqual(len(manifest["examples"]), 10)
         self.assertEqual({symbol for example in manifest["examples"]
                           for symbol in example["symbols"]}, TARGETS)
         for example in manifest["examples"]: