C# API

method libtmux-dotnet latest

QueryExtensions.Matching

Namespace L.Query LibTmux.Query

Filters a snapshot with a declarative predicate.

Source and package

Module: LibTmux.Query
Declared in: QueryExtensions
Package: LibTmux
Source: src/LibTmux/Query/QueryExtensions.cs

Matching ( source : IEnumerable<T> , predicate : Expression<Func<T, bool>> ) → IReadOnlyList<T> ( source : IEnumerable<T> , document : QueryDocument ) → IReadOnlyList<T> ( source : IEnumerable<T> , document : QueryDocument , cancellationToken : CancellationToken ) → IReadOnlyList<T> methodstaticoverload3 overloads [source] ¶

Examples#

Compare LINQ with translated expression and document predicates, preserve cancellation, and capture the hierarchy before filtering its children. 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.csproj: View source

<Project Sdk="Microsoft.NET.Sdk">
  <PropertyGroup>
    <OutputType>Exe</OutputType>
    <TargetFrameworks>net8.0;net10.0</TargetFrameworks>
    <LangVersion>12.0</LangVersion>
    <Nullable>enable</Nullable>
    <ImplicitUsings>disable</ImplicitUsings>
    <EnableDefaultCompileItems>false</EnableDefaultCompileItems>
    <TreatWarningsAsErrors>true</TreatWarningsAsErrors>
    <AnalysisLevel>10-recommended</AnalysisLevel>
  </PropertyGroup>
  <ItemGroup>
    <Compile Include="Program.cs" />
    <PackageReference Include="LibTmux" Version="[0.0.0-alpha.20]" />
  </ItemGroup>
</Project>

Save this complete program as Program.cs. It creates a private server; await using disposes its owned scopes after success, cancellation or failure. The complete file contains explicit imports, a top-level async entry point and a cancellation deadline. View source

using System;
using System.Collections.Generic;
using System.Linq;
using System.Threading;
using LibTmux;
using System.Linq.Expressions;
using LibTmux.Query;

if (OperatingSystem.IsWindows())
{
    throw new PlatformNotSupportedException("This example requires tmux on Linux or macOS.");
}

using CancellationTokenSource deadline = new(TimeSpan.FromSeconds(10));
CancellationToken token = deadline.Token;
string binary = Environment.GetEnvironmentVariable("LIBTMUX_TMUX") ?? "tmux";
string socketName = "csharp-serverqueries-" + Guid.NewGuid().ToString("N");
ServerConnectionOptions options = new()
{
    SocketName = socketName,
    ConfigurationFile = "/dev/null",
    TmuxBinaryPath = binary,
};

await using OwnedServerScope owned = await Server.CreateOwnedAsync(options, token);
await using OwnedSessionScope demo = await owned.Value.CreateOwnedSessionAsync(
    new NewSessionRequest { Name = "demo", WindowName = "shell", Command = "/bin/cat" }, token);
await using OwnedSessionScope worker = await owned.Value.CreateOwnedSessionAsync(
    new NewSessionRequest { Name = "worker", WindowName = "jobs", Command = "/bin/cat" }, token);
Server server = await Server.ConnectAsync(options, token);
IReadOnlyList<Session> sessions = await server.GetSessionsAsync(token);

// LINQ and portable predicates operate on these rows; neither reads tmux.
Session native = sessions.Where(session => session.Name == "demo").Single();
Expression<Func<Session, bool>> predicate = session => session.Name == "demo";
QueryDocument document = QueryExtensions.Translate(predicate);
Session expressionMatch = sessions.Matching(predicate).Single();
Session documentMatch = sessions.Matching(document).Single();
Session cancellableMatch = sessions.Matching(document, token).Single();
if (new[] { native, expressionMatch, documentMatch, cancellableMatch }
    .Any(session => session.Id != demo.Value.Id))
{
    throw new InvalidOperationException("The native and portable predicates selected different sessions.");
}

// A predicate that traverses children requires an explicitly captured hierarchy.
Server captured = await server.CaptureSnapshotAsync(SnapshotDepth.Panes, token);
Session parent = captured.Sessions.Matching(session =>
    session.Windows.Any(window => window.Name == "shell" && window.Panes.Any(pane => pane.CurrentCommand == "cat"))).Single();
if (parent.Id != demo.Value.Id)
{
    throw new InvalidOperationException("The hierarchy predicate selected an unexpected parent.");
}

using CancellationTokenSource cancelled = new();
cancelled.Cancel();
try
{
    _ = sessions.Matching(document, cancelled.Token);
    throw new InvalidOperationException("Cancelled filtering must throw.");
}
catch (OperationCanceledException)
{
    Console.WriteLine("Cancelled filtering remains OperationCanceledException.");
}
Console.WriteLine($"LINQ, expression and document filters: {native.Name}; captured parent: {parent.Name}");

Build the exact source package 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/LibTmux.csproj --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 restore Example.csproj --configfile NuGet.config && \
  dotnet build Example.csproj --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:

Cancelled filtering remains OperationCanceledException.
LINQ, expression and document filters: demo; captured parent: demo

Parameters

source ( IEnumerable<T> ) – The captured elements.
predicate ( Expression<Func<T, bool>> ) – The predicate to translate and apply. (for Matching(source, predicate))
document ( QueryDocument ) – The translated document. (for Matching(source, document); Matching(source, document, cancellationToken))
cancellationToken ( CancellationToken ) – Stops enumeration and predicate evaluation. (for Matching(source, document, cancellationToken))

Returns

The matching elements.

Scripting & web

Compiled & native

JVM

.NET

tmux

QueryExtensions.Matching

Examples#

Examples#

Related types#