Skip to content
Open
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 5 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
Expand Up @@ -28,6 +28,11 @@ release that first shipped the module.

### Documented

- **Clojure package READMEs show local installation and observation.** Both
packages link their native APIs, and the optional core.async example owns
its observer. Documentation checks reject reflection warnings in resource
scopes. (#149)

- **Clojure has native API references and runnable examples.** The module
READMEs and guides cover captured data, tmux operations, cancellation and
streaming, with source links and examples checked against real tmux. (#20)
Expand Down
22 changes: 11 additions & 11 deletions docs/guide/clojure.md
Original file line number Diff line number Diff line change
Expand Up @@ -141,7 +141,7 @@ submission does not add another tmux transport or alter the captured values.
(System/getProperty "libtmux.docs.socket")
(make-array String 0))]
(with-open [server (tm/open! {:socket-path socket-path})
runtime (async/runtime! {:max-running 3})]
^java.lang.AutoCloseable runtime (async/runtime! {:max-running 3})]
(tm/new-session! server {:name "docs-parallel"})
(let [tasks (mapv (fn [_] (async/submit! runtime #(tm/snapshot! server)))
(range 2))]
Expand All @@ -166,7 +166,7 @@ started. Use a separate `:wait` task for operations that wait for a release.
(System/getProperty "libtmux.docs.socket")
(make-array String 0))]
(with-open [server (tm/open! {:socket-path socket-path})
runtime (async/runtime! {})]
^java.lang.AutoCloseable runtime (async/runtime! {})]
(let [started (promise)
task (async/submit! runtime {:kind :wait}
#(do (deliver started true)
Expand Down Expand Up @@ -309,11 +309,11 @@ remains readable from the same owned stream.
(with-open [server (tm/open! {:socket-path socket-path
:binary (System/getProperty
"libtmux.docs.binary")})
connection (control/attach!
(:tmux/ref (first (tm/sessions! server)))
(Duration/ofSeconds 2))
stream (control/subscribe! connection {:capacity 64
:max-bytes 65536})]
^java.lang.AutoCloseable connection
(control/attach! (:tmux/ref (first (tm/sessions! server)))
(Duration/ofSeconds 2))
^AutoCloseable stream
(control/subscribe! connection {:capacity 64 :max-bytes 65536})]
(let [initial (control/next! stream (Duration/ofMillis 25))
pane (first (:reply/lines
(control/send! connection
Expand All @@ -340,9 +340,9 @@ remains readable from the same owned stream.
(with-open [server (tm/open! {:socket-path socket-path
:binary (System/getProperty
"libtmux.docs.binary")})
connection (control/attach!
(:tmux/ref (first (tm/sessions! server)))
(Duration/ofSeconds 2))]
^java.lang.AutoCloseable connection
(control/attach! (:tmux/ref (first (tm/sessions! server)))
(Duration/ofSeconds 2))]
(let [owner (adapter/observe! connection)
pane (first (:reply/lines
(control/send! connection
Expand Down Expand Up @@ -378,7 +378,7 @@ explicitly when ownership requires it.
(System/getProperty "libtmux.docs.socket")
(make-array String 0))]
(with-open [server (tm/open! {:socket-path socket-path})
runtime (async/runtime! {})]
^java.lang.AutoCloseable runtime (async/runtime! {})]
(tm/new-session! server {:name "docs-manifold"})
(let [task (async/submit! runtime #(tm/snapshot! server))
stage (async/then! runtime task
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -14,6 +14,7 @@
#"(?ms)(?:<!--\s*clojure-snippet:\s*([^>\s]+)\s*-->\s*\n)?^```clojure\s*\n(.*?)^```")
(def ^:private output-line #"(?m)^\s*;;\s*=>\s*(.+?)\s*$")
(def ^:private required-documents ["libtmux-clojure/README.md"
"libtmux-clojure-core-async/README.md"
"docs/guide/clojure.md"
"docs/guide/clojure-reference.md"])
(def ^:private socket-property "libtmux.docs.socket")
Expand Down Expand Up @@ -145,11 +146,19 @@
(defn- evaluate-snippet! [{:keys [document line code expected]} ^Path socket]
(with-fixture-properties socket
#(let [name (symbol (str "libtmux.docs.generated." (UUID/randomUUID)))
namespace (create-ns name)]
namespace (create-ns name)
warnings (java.io.StringWriter.)]
(try
(binding [*ns* namespace]
(binding [*ns* namespace
*warn-on-reflection* true
*err* warnings]
(refer 'clojure.core)
(let [actual (eval (read-string (str "(do\n" code "\n)")))]
(when (str/includes? (str warnings) "Reflection warning")
(throw (ex-info "Clojure documentation emitted reflection warnings"
{:docs/error :compiler-warning
:document document :line line
:warnings (str warnings)})))
(when-not (= expected actual)
(throw (ex-info "Clojure documentation output differs from the evaluated result"
{:docs/error :output-mismatch
Expand Down Expand Up @@ -181,7 +190,9 @@
(let [root (document-root)
snippets (documented-snippets root)]
(is (seq snippets))
(is (= #{"libtmux-clojure/README.md" "docs/guide/clojure.md"}
(is (= #{"libtmux-clojure/README.md"
"libtmux-clojure-core-async/README.md"
"docs/guide/clojure.md"}
(set (map :document snippets))))))

(deftest clojure-readme-has-first-visit-navigation
Expand Down Expand Up @@ -224,8 +235,13 @@

(deftest renamed-imports-and-wrong-displayed-output-fail-the-documentation-gate
(let [root (document-root)
snippet (first (documented-snippets root))
renamed (assoc snippet :code "(require '[libtmux.missing :as tm])")]
snippet (first (filter #(= "fixture" (:directive %))
(documented-snippets root)))
renamed (assoc snippet :code "(require '[libtmux.missing :as tm])")
reflective (assoc snippet :expected 2
:code "(with-open [server (identity (java.io.StringReader. \"\"))] 2)")]
(is (thrown? Throwable (run-snippet! renamed)))
(is (= :compiler-warning
(:docs/error (failure-data #(run-snippet! reflective)))))
(is (= :output-mismatch
(:docs/error (failure-data #(run-snippet! (assoc snippet :expected ::wrong))))))))
92 changes: 80 additions & 12 deletions libtmux-clojure-core-async/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -2,7 +2,7 @@
<div align="center">
<picture>
<source srcset="assets/logo.svg" type="image/svg+xml">
<img src="assets/logo.png" width="128" height="128" alt="libtmux for Clojure">
<img src="assets/logo.png" width="128" height="128" alt="libtmux Clojure core.async adapter">
</picture>
</div>
<!-- /libtmux-logo -->
Expand All @@ -12,7 +12,8 @@
# libtmux-clojure-core-async

Optional [core.async][core-async] integration for
[libtmux-clojure](../libtmux-clojure/README.md). The base façade has no
[libtmux-clojure][facade]: consume pane output through an events channel and
read shutdown through a separate terminal channel. The base façade has no
core.async dependency.

</div>
Expand All @@ -21,36 +22,103 @@ core.async dependency.

This adapter has not shipped. Its Maven coordinate is
`io.github.libtmux:libtmux-clojure-core-async`; there is no public release to
install yet. Build and verify it from this checkout:
install yet. From the repository root, install the adapter and its sibling
modules into your local Maven repository:

```console
$ ./gradlew :libtmux-clojure-core-async:check
$ ./gradlew \
:libtmux:publishToMavenLocal \
:libtmux-clojure:publishToMavenLocal \
:libtmux-clojure-core-async:publishToMavenLocal
```

The [complete consumer setup][program] includes a `deps.edn` with the optional
`:core-async` alias and instructions for an isolated Maven repository. Control
observation requires JDK 25 or newer and tmux 3.7 or newer.

## Quick start

Observe pane output, close the events consumer, and read the terminal result.
The fixture supplies socket and binary properties for a private server with
an existing session. Applications supply their own socket path and tmux binary.

<!-- clojure-snippet: control -->
```clojure
(require '[clojure.core.async :as async]
'[libtmux.control :as control]
'[libtmux.core :as tm]
'[libtmux.core-async :as adapter])
(import '[java.time Duration])

(let [socket-path (java.nio.file.Path/of
(System/getProperty "libtmux.docs.socket")
(make-array String 0))]
(with-open [server (tm/open! {:socket-path socket-path
:binary (System/getProperty
"libtmux.docs.binary")})
^java.lang.AutoCloseable connection
(control/attach! (:tmux/ref (first (tm/sessions! server)))
(Duration/ofSeconds 2))
^java.lang.AutoCloseable owner (adapter/observe! connection)]
(let [pane (first (:reply/lines
(control/send! connection
["new-window" "-P" "-F" "#{pane_id}"
(str "stty -echo; printf docs-async;"
" read stop")])))
timeout (async/timeout 900)
[event port] (async/alts!! [(adapter/events owner) timeout]
:priority true)]
(async/close! (adapter/events owner))
[(and (identical? port (adapter/events owner)) (= pane (:pane/id event)))
(:reason (async/<!! (adapter/terminal owner)))])))
;; => [true :adapter-stopped]
```

The documentation suite executes this example against an isolated tmux server
and checks the displayed result. On tmux below 3.7, it checks the control
capability refusal instead.

## Ownership and backpressure

`observe!` borrows a control connection and owns its subscription, virtual
worker, events channel, and terminal channel. Closing the adapter or its
events channel stops that owned work; it never closes the borrowed connection.
[`observe!`][observe] borrows a control connection and owns its subscription,
virtual worker, events channel, and terminal channel. Closing the adapter or
its events channel stops that work; the borrowed connection stays open.

The adapter defaults to an unbuffered events channel. Choose
`:event-capacity` deliberately, account for its one pending event, and inspect
`:gap` values from the upstream subscription separately from adapter loss.
Do not run blocking control I/O in a `go` block.

The [Clojure guide][guide] contains executable control and core.async examples,
including terminal outcomes and shutdown. See this module's
[native API reference][api] for function arities and ownership contracts,
and its [changelog](CHANGELOG.md) for release history.

The [complete core.async program][program] includes imports, a CLI entry point,
the optional dependency alias, private-server setup and cleanup. It closes its
events consumer, reads the terminal outcome, and reuses the borrowed connection.

The `javadoc` classifier contains native reference HTML and an offline source
browser, generated from this module's var metadata.

## Support and status

Releases are numbered `0.1.N`, and each release increments `N`. The API is
not settled: any release may change or remove exported identifiers, and the
changelog marks each break. Pin an exact version to avoid one.

The adapter is unpublished. Its Clojure 1.12.6 CI runs on JDK 25 and 27 with
tmux 3.3a and 3.7c; the older endpoint checks unsupported control behavior.

## Documentation

- [Adapter API][api] — observation, event and terminal channels, and stop.
- [Clojure guide][guide] — capacity, loss, cancellation, and Java interop.
- [Base façade][facade] — captures, native collection processing, and effects.
- [Changelog](CHANGELOG.md) — module-visible changes.
- [Contributing][contributing] — building and testing.
- [License][license] — MIT.

[api]: ../docs/guide/clojure-core-async-api.md
[contributing]: ../.github/CONTRIBUTING.md
[core-async]: https://clojure.github.io/core.async/clojure.core.async.html
[facade]: ../libtmux-clojure/README.md
[guide]: ../docs/guide/clojure.md
[license]: ../LICENSE
[observe]: ../docs/guide/clojure-core-async-api.md#libtmuxcore-asyncobserve
[program]: ../examples/api/README.md#clojure-programs
37 changes: 26 additions & 11 deletions libtmux-clojure/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -11,31 +11,38 @@

# libtmux-clojure

**libtmux for Clojure:** a data-first façade over
[libtmux-java][java-core]. It acquires tmux state as persistent maps and
vectors, retains a Java handle at `:tmux/ref` for an explicit operation, and
leaves ordinary Clojure collection processing local and unconstrained.
Drive tmux from Clojure: capture sessions, windows, and panes as persistent
maps, filter them with ordinary collection functions, and keep an explicit
Java handle at `:tmux/ref` for operations through [libtmux-java][java-core].

</div>

## Install

The Clojure façade has not shipped. Its Maven coordinate is
`io.github.libtmux:libtmux-clojure`; there is no public release to install yet.
Build and verify it from this checkout:
From the repository root, install the Java core and façade into your local
Maven repository:

```console
$ ./gradlew :libtmux-clojure:check :integration-tests:clojureIntegrationTest
$ ./gradlew \
:libtmux:publishToMavenLocal \
:libtmux-clojure:publishToMavenLocal
```

The façade requires JDK 25 or newer. The project tests tmux 3.3a through
3.7c; [control streaming][guide-streaming] requires tmux 3.7 or newer.
The [consumer setup][programs] includes a `deps.edn`, matching source version,
and instructions for using an isolated Maven repository.

The façade requires JDK 25 or newer. CI tests Clojure 1.12.6 on JDK 25 and 27
with tmux 3.3a and 3.7c. [Control streaming][guide-streaming] requires tmux
3.7 or newer.

## Quick start

`open!` connects to an explicit socket and owns only the local client.
`snapshot!` acquires one captured graph. The `data/windows` and `data/panes`
walks below read that graph; they do not issue another tmux command.
[`open!`][open] connects to an explicit socket and owns only the local client.
[`snapshot!`][snapshot] acquires one captured graph. The
[`data/windows`][windows] and [`data/panes`][panes] walks read that graph
without another tmux command.

The example runner supplies `libtmux.docs.socket` for its private server. In a
REPL, replace that property lookup with the path to your server's socket.
Expand Down Expand Up @@ -129,6 +136,9 @@ with the tmux version, endpoint choice, and the smallest reproducer.
- [Benchmarking guide][benchmarks] — how the Java operation measurements are
run. It does not yet claim a façade-specific benchmark.
- [Changelog](CHANGELOG.md) — module-visible changes once this façade ships.
- [Contributing][contributing] — building, executable documentation, and
owned tmux fixtures.
- [License][license] — MIT.

Every Clojure snippet in this README and the guide runs against an isolated
tmux server in `:integration-tests:clojureIntegrationTest`; no snippet is
Expand All @@ -149,6 +159,11 @@ the generated site starts at `build/docs/clojure/index.html` in this module.
[guide]: ../docs/guide/clojure.md
[guide-streaming]: ../docs/guide/clojure.md
[java-core]: ../libtmux/README.md
[license]: ../LICENSE
[mcp-guide]: ../docs/guide/mcp.md
[open]: ../docs/guide/clojure-api.md#libtmuxcoreopen
[panes]: ../docs/guide/clojure-api.md#libtmuxdatapanes
[programs]: ../examples/api/README.md#clojure-programs
[reference]: ../docs/guide/clojure-reference.md
[snapshot]: ../docs/guide/clojure-api.md#libtmuxcoresnapshot
[windows]: ../docs/guide/clojure-api.md#libtmuxdatawindows
Loading