F# API

enum libtmux-fsharp latest

CaptureState

Namespace L.FSharp LibTmux.FSharp

Distinguishes captured state from a relation the snapshot did not read.

View as Markdown

Source and package

Module: LibTmux.FSharp
Package: LibTmux.FSharp
Source: src/LibTmux.FSharp/Library.fsi

type CaptureState<'T> enum [source] ¶

Examples#

Pattern match CaptureState before reading relations or active entities, and option before using nullable pane fields. Capturing returns a fresh handle; a captured empty relation is different from an uncaptured one. Use Linux or macOS with Git, tmux 3.2a or newer, .NET SDK 10.0.303, and the .NET 8 and 10 runtimes. In an empty directory, fetch the documented library revision:

$ git clone https://github.com/libtmux/libtmux-dotnet.git libtmux-source && \
  git -C libtmux-source checkout --detach cf34b255c896d19a97e7d7fabea58609c916012d

Save this complete consumer setup as global.json: View source

{
  "sdk": {
    "version": "10.0.303",
    "rollForward": "disable",
    "allowPrerelease": false
  },
  "test": {
    "runner": "Microsoft.Testing.Platform"
  }
}

Save this complete consumer setup as NuGet.config: View source

<?xml version="1.0" encoding="utf-8"?>
<configuration>
  <packageSources>
    <clear />
    <add key="libtmux-source" value="libtmux-source/artifacts/api-example-packages" />
    <add key="nuget.org" value="https://api.nuget.org/v3/index.json" />
  </packageSources>
  <packageSourceMapping>
    <clear />
    <packageSource key="libtmux-source">
      <package pattern="LibTmux" />
      <package pattern="LibTmux.*" />
    </packageSource>
    <packageSource key="nuget.org">
      <package pattern="*" />
    </packageSource>
  </packageSourceMapping>
</configuration>

Save this complete consumer setup as Example.fsproj: View source

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
    <LangVersion>10.0</LangVersion>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <DisableImplicitFSharpCoreReference>true</DisableImplicitFSharpCoreReference>
    <DisableImplicitLibraryPacksFolder>true</DisableImplicitLibraryPacksFolder>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Program.fs" />
    <PackageReference Include="FSharp.Core" Version="[10.1.303]" />
    <PackageReference Include="LibTmux.FSharp" Version="[0.0.0-alpha.20]" />
  </ItemGroup>
</Project>

Save this complete program as Program.fs. It creates a private server with LibTmux.Server.CreateOwnedAsync; use! disposes owned scopes after success, cancellation or failure. The F# facade has no separate server constructor. View source

open System
open System.Threading
open LibTmux
open LibTmux.FSharp

let runAsync () =
    task {
        use deadline = new CancellationTokenSource(TimeSpan.FromSeconds 10.)
        let token = deadline.Token

        let options =
            ServerConnectionOptions(
                SocketName = "fsharp-snapshot-" + Guid.NewGuid().ToString("N"),
                ConfigurationFile = "/dev/null"
            )

        use! owned = options |> Server.createOwned token

        // A relation is either captured, holding what tmux reported, or not read at all.
        let describe (relation: CapturedRelation<'T>) =
            match relation |> Snapshot.relation with
            | Captured items -> "captured " + string items.Count
            | Uncaptured _ -> "not captured"

        let! server =
            task {
                use! session =
                    owned.Value.CreateOwnedSessionAsync(NewSessionRequest(Name = "demo", Command = "/bin/cat"), token)

                let server = owned.Value
                printfn "Connected handle's sessions: %s" (describe server.Sessions)

                let! captured = server |> Server.capture token SnapshotDepth.Panes
                printfn "Captured handle's sessions: %s" (describe captured.Sessions)

                match captured.Sessions |> Snapshot.relation with
                | Captured sessions ->
                    match (Seq.exactlyOne sessions).ActivePane |> Snapshot.value with
                    | Captured pane ->
                        printfn
                            "Active pane reports a path: %b; a command: %b"
                            (pane |> Pane.currentPath |> Option.isSome)
                            (pane |> Pane.currentCommand |> Option.isSome)
                    | Uncaptured _ -> printfn "Active pane: not captured"
                | Uncaptured _ -> ()

                // Capturing returns a new handle; the one it was taken from is unchanged.
                printfn "Original handle's sessions: %s" (describe server.Sessions)

                // Keep this private server alive after its only session is disposed.
                do! server.Options |> Options.set token (TmuxOptionKey.Flag "exit-empty") false
                return server
            }

        let! empty = server |> Server.capture token SnapshotDepth.Sessions
        printfn "Empty server's sessions: %s" (describe empty.Sessions)
    }

runAsync().GetAwaiter().GetResult()

Build the exact source packages and the saved consumer, then run both supported frameworks. The local package feed prevents an unrelated published package from satisfying the restore. Each program checks its result and exits unsuccessfully after an unhandled error:

$ export NUGET_PACKAGES="$PWD/packages" && \
  dotnet restore libtmux-source/src/LibTmux.FSharp/LibTmux.FSharp.fsproj --locked-mode && \
  dotnet pack libtmux-source/src/LibTmux/LibTmux.csproj \
    --configuration Release --no-restore -p:ContinuousIntegrationBuild=true \
    --output "$PWD/libtmux-source/artifacts/api-example-packages" && \
  dotnet pack libtmux-source/src/LibTmux.FSharp/LibTmux.FSharp.fsproj \
    --configuration Release --no-restore -p:ContinuousIntegrationBuild=true \
    --output "$PWD/libtmux-source/artifacts/api-example-packages" && \
  dotnet restore Example.fsproj --configfile NuGet.config && \
  dotnet build Example.fsproj --configuration Release --no-restore --warnaserror && \
  export LIBTMUX_TMUX="$(command -v tmux)" && \
  export TMUX_TMPDIR=/tmp/libtmux-dotnet-dev && \
  mkdir -p "$TMUX_TMPDIR" && \
  unset TMUX TMUX_PANE && \
  dotnet bin/Release/net8.0/Example.dll && \
  dotnet bin/Release/net10.0/Example.dll

Expected program output from each framework:

Connected handle's sessions: not captured
Captured handle's sessions: captured 1
Active pane reports a path: true; a command: true
Original handle's sessions: not captured
Empty server's sessions: captured 0

Members2 members#

Other members2 members#

Captured constant Contains the captured value, including an observed empty collection.
Uncaptured constant Names the unread relation and the depth the snapshot reached.

Scripting & web

Compiled & native

JVM

.NET

tmux

CaptureState

Examples#

Members2 members#

Other members2 members#