<!doctype html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width, initial-scale=1">
<title>docs/config/lua/wezterm/GLOBAL.md - fork/wezterm @ termwiz-0.23.3</title>
<meta name="description" content="docs/config/lua/wezterm/GLOBAL.md in fork/wezterm at termwiz-0.23.3.">
<meta property="og:title" content="docs/config/lua/wezterm/GLOBAL.md - fork/wezterm @ termwiz-0.23.3">
<meta property="og:description" content="docs/config/lua/wezterm/GLOBAL.md in fork/wezterm at termwiz-0.23.3.">
<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="termwiz-0.23.3" data-tip="4bf28e253c0167102f07bfc7e7199c13eed98012">
<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="84f7fb9f3b0deb192d45ee36257e5f329584b1fc">docs: add tags to a number of pages</span><span class="snapshot-sha sha" data-commit="84f7fb9f3b0deb192d45ee36257e5f329584b1fc">84f7fb9f3</span><time datetime="2023-04-08T07:48:40-07:00" title="2023-04-08 07:48:40 -0700">2023-04-08</time></p>
<header class="topbar"><details class="switcher"><summary>termwiz-0.23.3</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 class="current" href="/fork/wezterm/ref/termwiz-0.23.3/">termwiz-0.23.3</a><a 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/termwiz-0.23.3/tree/docs/">docs</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/">config</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/lua/">lua</a> / <a href="/fork/wezterm/ref/termwiz-0.23.3/tree/docs/config/lua/wezterm/">wezterm</a> / <span class="cur">GLOBAL.md</span></nav>
<span class="view-stats"><span>2.4 KiB</span><span>83 lines</span></span><span class="actions"><a class="raw" href="/fork/wezterm/raw/b999418ae9644b98b94e144867b437ec5efcca69/docs/config/lua/wezterm/GLOBAL.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"><hr />
<p>title: wezterm.GLOBAL
tags:</p>
<ul>
<li>utility</li>
</ul>
<hr />
<h1><code>wezterm.GLOBAL</code></h1>
<p>{{since('20220624-141144-bd1b7c5d')}}</p>
<p>Provides global, in-process, in-memory, data storage for json-like variables
that persists across config reloads.</p>
<p>wezterm's lua files may be re-loaded and re-evaluated multiple times in
different contexts or in different threads. If you'd like to keep track
of state that lasts for the lifetime of your wezterm process then you
cannot simply use global variables in the lua script.</p>
<p><code>wezterm.GLOBAL</code> is a special userdata value that acts like a table.
Writing to keys will copy the data that you assign into a global in-memory
table and allow it to be read back later.</p>
<p>Reads and writes from/to <code>wezterm.GLOBAL</code> are thread-safe but don't currently
provide synchronization primitives for managing read-modify-write operations.</p>
<p>The following example shows the number of times that the config has been
loaded in the right status bar. Watch it increase when you press the
<a href="/fork/wezterm/ref/termwiz-0.23.3/blob/docs/config/lua/keyassignment/ReloadConfiguration.md">ReloadConfiguration</a> key assignment
(<code>CTRL-SHIFT-R</code>):</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-c>-- Count how many times the lua config has been loaded</a-c>
<a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</a-v> = <a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</a-v> <a-k>or</a-k> <a-n>0</a-n><a-p>)</a-p> <a-o>+</a-o> <a-n>1</a-n>

<a-v>wezterm</a-v><a-p>.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-right-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-v>window</a-v><a-p>:</a-p><a-f>set_right_status</a-f><a-p>(</a-p><a-s>&#39;Reloads=&#39;</a-s> <a-o>..</a-o> <a-f>tostring</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</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>
<p>Note that the reload counter goes up by more than 1 when you reload: that is
because the config is evaluated multiple times in different threads as part of
safely validating and setting up the configuration.</p>
<p>You may store values with the following types:</p>
<ul>
<li>string</li>
<li>number</li>
<li>table</li>
<li>boolean</li>
</ul>
<p>Attempting to assign other types will raise an error.</p>
<h2>Note about referencing table values</h2>
<p>Accessing <code>wezterm.GLOBAL</code> returns a copy of the data that you'd read, making
it cumbersome to perform read/modify/write updates; for example this:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v><a-p>[</a-p><a-s>&#39;T0&#39;</a-s><a-p>]</a-p> = <a-s>&#39;Test&#39;</a-s></pre>
<p>will not result in <code>wezterm.GLOBAL.tab_titles.T0</code> being set, and you need
to explicitly break it apart into:</p>
<pre class="language-lua"><a-k>local</a-k> <a-v>tab_titles</a-v> = <a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v>
<a-v>tab_titles</a-v><a-p>[</a-p><a-s>&#39;T0&#39;</a-s><a-p>]</a-p> = <a-s>&#39;Test&#39;</a-s>
<a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v> = <a-v>tab_titles</a-v></pre>
<p>{{since('20230320-124340-559cb7b0')}}</p>
<p>You no longer need to split apart read/modify/write and the simple assignment
now works as you would expect:</p>
<pre class="language-lua"><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v><a-p>[</a-p><a-s>&#39;T0&#39;</a-s><a-p>]</a-p> = <a-s>&#39;Test&#39;</a-s></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></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L2" href="#L2">2</a><span class="code-text"><a-pr>title</a-pr><a-p>:</a-p> <a-s>wezterm.GLOBAL</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L3" href="#L3">3</a><span class="code-text"><a-pr>tags</a-pr><a-p>:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L4" href="#L4">4</a><span class="code-text"> <a-p>-</a-p> <a-s>utility</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L5" href="#L5">5</a><span class="code-text"><a-p>---</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L6" href="#L6">6</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L7" href="#L7">7</a><span class="code-text"><a-p>#</a-p> <a-tt>`wezterm.GLOBAL`</a-tt></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">{{since(&#39;20220624-141144-bd1b7c5d&#39;)}}</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L10" href="#L10">10</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L11" href="#L11">11</a><span class="code-text">Provides global, in-process, in-memory, data storage for json-like variables</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L12" href="#L12">12</a><span class="code-text">that persists across config reloads.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L13" href="#L13">13</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L14" href="#L14">14</a><span class="code-text">wezterm&#39;s lua files may be re-loaded and re-evaluated multiple times in</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L15" href="#L15">15</a><span class="code-text">different contexts or in different threads. If you&#39;d like to keep track</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L16" href="#L16">16</a><span class="code-text">of state that lasts for the lifetime of your wezterm process then you</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L17" href="#L17">17</a><span class="code-text">cannot simply use global variables in the lua script.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L18" href="#L18">18</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L19" href="#L19">19</a><span class="code-text">`wezterm.GLOBAL` is a special userdata value that acts like a table.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L20" href="#L20">20</a><span class="code-text">Writing to keys will copy the data that you assign into a global in-memory</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L21" href="#L21">21</a><span class="code-text">table and allow it to be read back later.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L22" href="#L22">22</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L23" href="#L23">23</a><span class="code-text">Reads and writes from/to `wezterm.GLOBAL` are thread-safe but don&#39;t currently</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L24" href="#L24">24</a><span class="code-text">provide synchronization primitives for managing read-modify-write operations.</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L25" href="#L25">25</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L26" href="#L26">26</a><span class="code-text">The following example shows the number of times that the config has been</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L27" href="#L27">27</a><span class="code-text">loaded in the right status bar. Watch it increase when you press the</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L28" href="#L28">28</a><span class="code-text">[ReloadConfiguration](../keyassignment/ReloadConfiguration.md) key assignment</span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L29" href="#L29">29</a><span class="code-text">(`CTRL-SHIFT-R`):</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>```</a-p><a-tl>lua</a-tl></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>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="L33" href="#L33">33</a><span class="code-text"></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>-- Count how many times the lua config has been loaded</a-p></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>wezterm.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</a-v><a-p> = (</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</a-v><a-p> </a-p><a-k>or</a-k><a-p> </a-p><a-n>0</a-n><a-p>) </a-p><a-o>+</a-o><a-p> </a-p><a-n>1</a-n></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L36" href="#L36">36</a><span class="code-text"></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>wezterm.</a-p><a-f>on</a-f><a-p>(</a-p><a-s>&#39;update-right-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="L38" href="#L38">38</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-s>&#39;Reloads=&#39;</a-s><a-p> </a-p><a-o>..</a-o><a-p> </a-p><a-f>tostring</a-f><a-p>(</a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>parse_count</a-v><a-p>))</a-p></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>end)</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L41" href="#L41">41</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="L42" href="#L42">42</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L43" href="#L43">43</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L44" href="#L44">44</a><span class="code-text"><a-p>Note that the reload counter goes up by more than 1 when you reload: that is</a-p></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>because the config is evaluated multiple times in different threads as part of</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L46" href="#L46">46</a><span class="code-text"><a-p>safely validating and setting up the configuration.</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L47" href="#L47">47</a><span class="code-text"></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>You may store values with the following types:</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"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L50" href="#L50">50</a><span class="code-text"><a-p>* string</a-p></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>* number</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"><a-p>* table</a-p></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>* boolean</a-p></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>Attempting to assign other types will raise an error.</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"></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>## </a-p><a-tt>Note about referencing table values</a-tt></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>Accessing `wezterm.GLOBAL` returns a copy of the data that you&#39;d read, making</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"><a-p>it cumbersome to perform read/modify/write updates; for example this:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L61" href="#L61">61</a><span class="code-text"></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>```</a-p><a-tl>lua</a-tl></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L63" href="#L63">63</a><span class="code-text"><a-p>wezterm.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v><a-p>[</a-p><a-s>&#39;T0&#39;</a-s><a-p>] = </a-p><a-s>&#39;Test&#39;</a-s></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>```</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"></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>will not result in `wezterm.GLOBAL.tab_titles.T0` being set, and you need</a-p></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>to explicitly break it apart into:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L68" href="#L68">68</a><span class="code-text"></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-tl>lua</a-tl></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>local </a-p><a-v>tab_titles</a-v><a-p> = </a-p><a-v>wezterm</a-v><a-p>.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L71" href="#L71">71</a><span class="code-text"><a-p>tab_titles[</a-p><a-s>&#39;T0&#39;</a-s><a-p>] = </a-p><a-s>&#39;Test&#39;</a-s></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>wezterm.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v><a-p> = </a-p><a-v>tab_titles</a-v></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 class="code-break">
</span></span><span class="code-line"><a class="ln" id="L75" href="#L75">75</a><span class="code-text"><a-p>{{since(&#39;20230320-124340-559cb7b0&#39;)}}</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L76" href="#L76">76</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L77" href="#L77">77</a><span class="code-text"><a-p>You no longer need to split apart read/modify/write and the simple assignment</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L78" href="#L78">78</a><span class="code-text"><a-p>now works as you would expect:</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L79" href="#L79">79</a><span class="code-text"></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L80" href="#L80">80</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="L81" href="#L81">81</a><span class="code-text"><a-p>wezterm.</a-p><a-v>GLOBAL</a-v><a-p>.</a-p><a-v>tab_titles</a-v><a-p>[</a-p><a-s>&#39;T0&#39;</a-s><a-p>] = </a-p><a-s>&#39;Test&#39;</a-s></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L82" href="#L82">82</a><span class="code-text"><a-p>```</a-p></span><span class="code-break">
</span></span><span class="code-line"><a class="ln" id="L83" href="#L83">83</a><span class="code-text"></span></span></pre></div></div>
</main>
</body>
</html>
