<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/lua/pane/get_metadata.md - fork/wezterm @ vtparse-0.7.0</title>
<meta name="description" content="docs/config/lua/pane/get_metadata.md in fork/wezterm at vtparse-0.7.0.">
<meta property="og:title" content="docs/config/lua/pane/get_metadata.md - fork/wezterm @ vtparse-0.7.0">
<meta property="og:description" content="docs/config/lua/pane/get_metadata.md in fork/wezterm at vtparse-0.7.0.">
<meta property="og:type" content="website">
<meta property="og:site_name" content="git.julia.blue">
<link rel="stylesheet" href="/css/style.css?v=62">
<script type="module" src="/js/main.js?v=62"></script>
</head>
<body>
<main data-ref="vtparse-0.7.0" data-tip="3bfe6df191af37bc33fe5fe6de12a40f7067f101">
<noscript>
  <div class="callout">
    <p>
      hey! this is a static git repo viewer. commit diffs, file history,
      older commits and other revisions won't load without javascript.
    </p>
    <p>
      you are still able to view source files on branch/tag tips,
      but the experience is degraded.
    </p>
  </div>
</noscript>
<header class="repo"><div>
<h1>fork/wezterm</h1>
</div>
<pre class="clone">git clone https://git.julia.blue/fork/wezterm</pre>
</header>
<p class="snapshot-commit"><span class="commit-author">Wez Furlong</span><span class="commit-message" data-commit="40081cb5737da32058a3c87e14b84d8f2bfefdc4">docs: update a bunch of since lines to new macro</span><span class="snapshot-sha sha" data-commit="40081cb5737da32058a3c87e14b84d8f2bfefdc4">40081cb57</span><time datetime="2023-03-20T22:01:24-07:00" title="2023-03-20 22:01:24 -0700">2023-03-20</time></p>
<header class="topbar"><details class="switcher"><summary>vtparse-0.7.0</summary><div class="menu"><strong>branches</strong><a href="/fork/wezterm/ref/main/">main</a><strong>tags</strong><a href="/fork/wezterm/ref/termiz-0.23.1/">termiz-0.23.1</a><a href="/fork/wezterm/ref/termiz-0.23.2/">termiz-0.23.2</a><a href="/fork/wezterm/ref/termiz-0.23.3/">termiz-0.23.3</a><a href="/fork/wezterm/ref/termwiz-0.23.0/">termwiz-0.23.0</a><a href="/fork/wezterm/ref/termwiz-0.23.1/">termwiz-0.23.1</a><a href="/fork/wezterm/ref/termwiz-0.23.2/">termwiz-0.23.2</a><a href="/fork/wezterm/ref/termwiz-0.23.3/">termwiz-0.23.3</a><a class="current" href="/fork/wezterm/ref/vtparse-0.7.0/">vtparse-0.7.0</a><a class="all" href="/fork/wezterm/refs">all refs →</a></div></details><nav class="crumbs"><a href="/fork/wezterm/">wezterm</a> / <a href="/fork/wezterm/ref/vtparse-0.7.0/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/vtparse-0.7.0/tree/docs/config/">config</a> / <a href="/fork/wezterm/ref/vtparse-0.7.0/tree/docs/config/lua/">lua</a> / <a href="/fork/wezterm/ref/vtparse-0.7.0/tree/docs/config/lua/pane/">pane</a> / <span class="cur">get_metadata.md</span></nav>
<span class="view-stats"><span>2.0 KiB</span><span>74 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/6f4ca544e1f8302e4392909e37f2acd537da48d4/docs/config/lua/pane/get_metadata.md">raw</a></span></header>
<div class="markdown-view"><input type="radio" name="markdown-view" id="markdown-rendered" checked><label for="markdown-rendered">rendered</label><input type="radio" name="markdown-view" id="markdown-code"><label for="markdown-code">code</label><section class="readme rendered"><h1><code>pane:get_metadata()</code></h1>
<p>{{since('20220903-194523-3bb1ed61')}}</p>
<p>Returns metadata about a pane. The return value depends on the instance of the
underlying pane. If the pane doesn't support this method, <code>nil</code> will be returned.
Otherwise, the value is a lua table with the metadata contained in table fields.</p>
<p>To consume this value, it is recommend to use logic like this to obtain a table
value even if the pane doesn't support this method:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>meta</a-v> = <a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>()</a-p> <a-k>or</a-k> <a-cr>{}</a-cr></pre>
<p>The following metadata keys may be present:</p>
<h2>password_input</h2>
<p>A boolean value that is populated only for local panes.
It is set to true if it appears as though the local PTY is
configured for password entry (local echo disabled, canonical
input mode enabled).</p>
<p>This example demonstrates how to change the color scheme
to exaggerate when a password is being input:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>

<a-v>wezterm</a-v><a-p>.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-status&#39;</a-s><a-p>,</a-p> <a-k>function</a-k><a-p>(</a-p><a-v>window</a-v><a-p>,</a-p> <a-v>pane</a-v><a-p>)</a-p>
  <a-k>local</a-k> <a-v>meta</a-v> = <a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>()</a-p> <a-k>or</a-k> <a-cr>{}</a-cr>
  <a-k>local</a-k> <a-v>overrides</a-v> = <a-v>window</a-v><a-p>:</a-p><a-f>get_config_overrides</a-f><a-p>()</a-p> <a-k>or</a-k> <a-cr>{}</a-cr>
  <a-k>if</a-k> <a-v>meta</a-v><a-p>.</a-p><a-v>password_input</a-v> <a-k>then</a-k>
    <a-v>overrides</a-v><a-p>.</a-p><a-v>color_scheme</a-v> = <a-s>&#39;Red Alert&#39;</a-s>
  <a-k>else</a-k>
    <a-v>overrides</a-v><a-p>.</a-p><a-v>color_scheme</a-v> = <a-co>nil</a-co>
  <a-k>end</a-k>
  <a-v>window</a-v><a-p>:</a-p><a-f>set_config_overrides</a-f><a-p>(</a-p><a-v>overrides</a-v><a-p>)</a-p>
<a-k>end</a-k><a-p>)</a-p>

<a-k>return</a-k> <a-cr>{}</a-cr></pre>
<h2>is_tardy</h2>
<p>A boolean value that is populated only for multiplexer client panes.
It is set to true if wezterm is waiting for a response from the multiplexer
server.</p>
<p>This can be used in conjunction with <code>since_last_response_ms</code> below.</p>
<h2>since_last_response_ms</h2>
<p>An integer value that is populated only for multiplexer client panes.
It is set to the number of elapsed milliseconds since the most recent
response from the multiplexer server.</p>
<p>This example shows how to put mux latency information into the status area:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>wezterm</a-v> = <a-f>require</a-f> <a-s>&#39;wezterm&#39;</a-s>

<a-v>wezterm</a-v><a-p>.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-status&#39;</a-s><a-p>,</a-p> <a-k>function</a-k><a-p>(</a-p><a-v>window</a-v><a-p>,</a-p> <a-v>pane</a-v><a-p>)</a-p>
  <a-k>local</a-k> <a-v>meta</a-v> = <a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>()</a-p> <a-k>or</a-k> <a-cr>{}</a-cr>
  <a-k>if</a-k> <a-v>meta</a-v><a-p>.</a-p><a-v>is_tardy</a-v> <a-k>then</a-k>
    <a-k>local</a-k> <a-v>secs</a-v> = <a-v>meta</a-v><a-p>.</a-p><a-v>since_last_response_ms</a-v> <a-o>/</a-o> <a-n>1000.0</a-n>
    <a-v>window</a-v><a-p>:</a-p><a-f>set_right_status</a-f><a-p>(</a-p><a-v>string</a-v><a-p>.</a-p><a-f>format</a-f><a-p>(</a-p><a-s>&#39;tardy: %5.1fs⏳&#39;</a-s><a-p>,</a-p> <a-v>secs</a-v><a-p>))</a-p>
  <a-k>end</a-k>
<a-k>end</a-k><a-p>)</a-p>

<a-k>return</a-k> <a-cr>{}</a-cr></pre>
</section><div class="code-panel"><pre class="code src language-markdown"><span class="code-line"><a class="ln" id="L1" href="#L1">1</a><span class="code-text"><a-p>#</a-p> <a-tt>`pane:get_metadata()`</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text">{{since(&#39;20220903-194523-3bb1ed61&#39;)}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text">Returns metadata about a pane. The return value depends on the instance of the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text">underlying pane. If the pane doesn&#39;t support this method, `nil` will be returned.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text">Otherwise, the value is a lua table with the metadata contained in table fields.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L8" href="#L8">8</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L9" href="#L9">9</a><span class="code-text">To consume this value, it is recommend to use logic like this to obtain a table</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text">value even if the pane doesn&#39;t support this method:</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"><a-p>local </a-p><a-v>meta</a-v><a-p> = </a-p><a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>() </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text"><a-p>The following metadata keys may be present:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"><a-p>## </a-p><a-tt>password_input</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text"><a-p>A boolean value that is populated only for local panes.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text"><a-p>It is set to true if it appears as though the local PTY is</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"><a-p>configured for password entry (local echo disabled, canonical</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text"><a-p>input mode enabled).</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"><a-p>This example demonstrates how to change the color scheme</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text"><a-p>to exaggerate when a password is being input:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L30" href="#L30">30</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L31" href="#L31">31</a><span class="code-text"><a-p>wezterm.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-status&#39;</a-s><a-p>, </a-p><a-k>function</a-k><a-p>(</a-p><a-v>window</a-v><a-p>, </a-p><a-v>pane</a-v><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L32" href="#L32">32</a><span class="code-text"><a-p>  </a-p><a-k>local</a-k><a-p> </a-p><a-v>meta</a-v><a-p> = </a-p><a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>() </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L33" href="#L33">33</a><span class="code-text"><a-p>  </a-p><a-k>local</a-k><a-p> </a-p><a-v>overrides</a-v><a-p> = </a-p><a-v>window</a-v><a-p>:</a-p><a-f>get_config_overrides</a-f><a-p>() </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L34" href="#L34">34</a><span class="code-text"><a-p>  </a-p><a-k>if</a-k><a-p> </a-p><a-v>meta</a-v><a-p>.</a-p><a-v>password_input</a-v><a-p> </a-p><a-k>then</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L35" href="#L35">35</a><span class="code-text"><a-p>    </a-p><a-v>overrides</a-v><a-p>.</a-p><a-v>color_scheme</a-v><a-p> = </a-p><a-s>&#39;Red Alert&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"><a-p>  </a-p><a-k>else</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L37" href="#L37">37</a><span class="code-text"><a-p>    </a-p><a-v>overrides</a-v><a-p>.</a-p><a-v>color_scheme</a-v><a-p> = </a-p><a-co>nil</a-co></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L38" href="#L38">38</a><span class="code-text"><a-p>  </a-p><a-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L39" href="#L39">39</a><span class="code-text"><a-p>  </a-p><a-v>window</a-v><a-p>:</a-p><a-f>set_config_overrides</a-f><a-p>(</a-p><a-v>overrides</a-v><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L40" href="#L40">40</a><span class="code-text"><a-p>end)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L42" href="#L42">42</a><span class="code-text"><a-p>return </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L45" href="#L45">45</a><span class="code-text"><a-p>## </a-p><a-tt>is_tardy</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"><a-p>A boolean value that is populated only for multiplexer client panes.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L48" href="#L48">48</a><span class="code-text"><a-p>It is set to true if wezterm is waiting for a response from the multiplexer</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L49" href="#L49">49</a><span class="code-text"><a-p>server.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L51" href="#L51">51</a><span class="code-text"><a-p>This can be used in conjunction with `since_last_response_ms` below.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L52" href="#L52">52</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L53" href="#L53">53</a><span class="code-text"><a-p>## </a-p><a-tt>since_last_response_ms</a-tt></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L54" href="#L54">54</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L55" href="#L55">55</a><span class="code-text"><a-p>An integer value that is populated only for multiplexer client panes.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L56" href="#L56">56</a><span class="code-text"><a-p>It is set to the number of elapsed milliseconds since the most recent</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L57" href="#L57">57</a><span class="code-text"><a-p>response from the multiplexer server.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L58" href="#L58">58</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L59" href="#L59">59</a><span class="code-text"><a-p>This example shows how to put mux latency information into the status area:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L60" href="#L60">60</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"><a-p>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L62" href="#L62">62</a><span class="code-text"><a-p>local </a-p><a-v>wezterm</a-v><a-p> = </a-p><a-f>require</a-f><a-p> </a-p><a-s>&#39;wezterm&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L64" href="#L64">64</a><span class="code-text"><a-p>wezterm.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-status&#39;</a-s><a-p>, </a-p><a-k>function</a-k><a-p>(</a-p><a-v>window</a-v><a-p>, </a-p><a-v>pane</a-v><a-p>)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L65" href="#L65">65</a><span class="code-text"><a-p>  </a-p><a-k>local</a-k><a-p> </a-p><a-v>meta</a-v><a-p> = </a-p><a-v>pane</a-v><a-p>:</a-p><a-f>get_metadata</a-f><a-p>() </a-p><a-k>or</a-k><a-p> </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L66" href="#L66">66</a><span class="code-text"><a-p>  </a-p><a-k>if</a-k><a-p> </a-p><a-v>meta</a-v><a-p>.</a-p><a-v>is_tardy</a-v><a-p> </a-p><a-k>then</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L67" href="#L67">67</a><span class="code-text"><a-p>    </a-p><a-k>local</a-k><a-p> </a-p><a-v>secs</a-v><a-p> = </a-p><a-v>meta</a-v><a-p>.</a-p><a-v>since_last_response_ms</a-v><a-p> </a-p><a-o>/</a-o><a-p> </a-p><a-n>1000.0</a-n></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"><a-p>    </a-p><a-v>window</a-v><a-p>:</a-p><a-f>set_right_status</a-f><a-p>(</a-p><a-v>string</a-v><a-p>.</a-p><a-f>format</a-f><a-p>(</a-p><a-s>&#39;tardy: %5.1fs⏳&#39;</a-s><a-p>, </a-p><a-v>secs</a-v><a-p>))</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L69" href="#L69">69</a><span class="code-text"><a-p>  </a-p><a-k>end</a-k></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L70" href="#L70">70</a><span class="code-text"><a-p>end)</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L72" href="#L72">72</a><span class="code-text"><a-p>return </a-p><a-cr>{}</a-cr></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L73" href="#L73">73</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L74" href="#L74">74</a><span class="code-text"></span></span></pre></div></div>
</main>
</body>
</html>
