presenterm/features/code/execution.html
2025-05-03 20:25:36 +00:00

370 lines
21 KiB
HTML

<!DOCTYPE HTML>
<html lang="en" class="navy sidebar-visible" dir="ltr">
<head>
<!-- Book generated using mdBook -->
<meta charset="UTF-8">
<title>Execution - presenterm documentation</title>
<!-- Custom HTML head -->
<meta name="description" content="">
<meta name="viewport" content="width=device-width, initial-scale=1">
<meta name="theme-color" content="#ffffff">
<link rel="icon" href="../../favicon.svg">
<link rel="shortcut icon" href="../../favicon.png">
<link rel="stylesheet" href="../../css/variables.css">
<link rel="stylesheet" href="../../css/general.css">
<link rel="stylesheet" href="../../css/chrome.css">
<link rel="stylesheet" href="../../css/print.css" media="print">
<!-- Fonts -->
<link rel="stylesheet" href="../../FontAwesome/css/font-awesome.css">
<link rel="stylesheet" href="../../fonts/fonts.css">
<!-- Highlight.js Stylesheets -->
<link rel="stylesheet" href="../../highlight.css">
<link rel="stylesheet" href="../../tomorrow-night.css">
<link rel="stylesheet" href="../../ayu-highlight.css">
<!-- Custom theme stylesheets -->
<!-- Provide site root to javascript -->
<script>
var path_to_root = "../../";
var default_theme = window.matchMedia("(prefers-color-scheme: dark)").matches ? "navy" : "navy";
</script>
<!-- Start loading toc.js asap -->
<script src="../../toc.js"></script>
</head>
<body>
<div id="body-container">
<!-- Work around some values being stored in localStorage wrapped in quotes -->
<script>
try {
var theme = localStorage.getItem('mdbook-theme');
var sidebar = localStorage.getItem('mdbook-sidebar');
if (theme.startsWith('"') && theme.endsWith('"')) {
localStorage.setItem('mdbook-theme', theme.slice(1, theme.length - 1));
}
if (sidebar.startsWith('"') && sidebar.endsWith('"')) {
localStorage.setItem('mdbook-sidebar', sidebar.slice(1, sidebar.length - 1));
}
} catch (e) { }
</script>
<!-- Set the theme before any content is loaded, prevents flash -->
<script>
var theme;
try { theme = localStorage.getItem('mdbook-theme'); } catch(e) { }
if (theme === null || theme === undefined) { theme = default_theme; }
const html = document.documentElement;
html.classList.remove('navy')
html.classList.add(theme);
html.classList.add("js");
</script>
<input type="checkbox" id="sidebar-toggle-anchor" class="hidden">
<!-- Hide / unhide sidebar before it is displayed -->
<script>
var sidebar = null;
var sidebar_toggle = document.getElementById("sidebar-toggle-anchor");
if (document.body.clientWidth >= 1080) {
try { sidebar = localStorage.getItem('mdbook-sidebar'); } catch(e) { }
sidebar = sidebar || 'visible';
} else {
sidebar = 'hidden';
}
sidebar_toggle.checked = sidebar === 'visible';
html.classList.remove('sidebar-visible');
html.classList.add("sidebar-" + sidebar);
</script>
<nav id="sidebar" class="sidebar" aria-label="Table of contents">
<!-- populated by js -->
<mdbook-sidebar-scrollbox class="sidebar-scrollbox"></mdbook-sidebar-scrollbox>
<noscript>
<iframe class="sidebar-iframe-outer" src="../../toc.html"></iframe>
</noscript>
<div id="sidebar-resize-handle" class="sidebar-resize-handle">
<div class="sidebar-resize-indicator"></div>
</div>
</nav>
<div id="page-wrapper" class="page-wrapper">
<div class="page">
<div id="menu-bar-hover-placeholder"></div>
<div id="menu-bar" class="menu-bar sticky">
<div class="left-buttons">
<label id="sidebar-toggle" class="icon-button" for="sidebar-toggle-anchor" title="Toggle Table of Contents" aria-label="Toggle Table of Contents" aria-controls="sidebar">
<i class="fa fa-bars"></i>
</label>
<button id="theme-toggle" class="icon-button" type="button" title="Change theme" aria-label="Change theme" aria-haspopup="true" aria-expanded="false" aria-controls="theme-list">
<i class="fa fa-paint-brush"></i>
</button>
<ul id="theme-list" class="theme-popup" aria-label="Themes" role="menu">
<li role="none"><button role="menuitem" class="theme" id="light">Light</button></li>
<li role="none"><button role="menuitem" class="theme" id="rust">Rust</button></li>
<li role="none"><button role="menuitem" class="theme" id="coal">Coal</button></li>
<li role="none"><button role="menuitem" class="theme" id="navy">Navy</button></li>
<li role="none"><button role="menuitem" class="theme" id="ayu">Ayu</button></li>
</ul>
<button id="search-toggle" class="icon-button" type="button" title="Search. (Shortkey: s)" aria-label="Toggle Searchbar" aria-expanded="false" aria-keyshortcuts="S" aria-controls="searchbar">
<i class="fa fa-search"></i>
</button>
</div>
<h1 class="menu-title">presenterm documentation</h1>
<div class="right-buttons">
<a href="../../print.html" title="Print this book" aria-label="Print this book">
<i id="print-button" class="fa fa-print"></i>
</a>
<a href="https://github.com/mfontanini/presenterm" title="Git repository" aria-label="Git repository">
<i id="git-repository-button" class="fa fa-github"></i>
</a>
</div>
</div>
<div id="search-wrapper" class="hidden">
<form id="searchbar-outer" class="searchbar-outer">
<input type="search" id="searchbar" name="searchbar" placeholder="Search this book ..." aria-controls="searchresults-outer" aria-describedby="searchresults-header">
</form>
<div id="searchresults-outer" class="searchresults-outer hidden">
<div id="searchresults-header" class="searchresults-header"></div>
<ul id="searchresults">
</ul>
</div>
</div>
<!-- Apply ARIA attributes after the sidebar and the sidebar toggle button are added to the DOM -->
<script>
document.getElementById('sidebar-toggle').setAttribute('aria-expanded', sidebar === 'visible');
document.getElementById('sidebar').setAttribute('aria-hidden', sidebar !== 'visible');
Array.from(document.querySelectorAll('#sidebar a')).forEach(function(link) {
link.setAttribute('tabIndex', sidebar === 'visible' ? 0 : -1);
});
</script>
<div id="content" class="content">
<main>
<style>
.mdbook-alerts {
padding: 8px 16px;
margin-bottom: 16px;
border-left: 0.25em solid var(--mdbook-alerts-color);
}
.mdbook-alerts > *:first-child {
margin-top: 0;
}
.mdbook-alerts > *:last-child {
margin-bottom: 0;
}
.mdbook-alerts-title {
display: flex;
font-weight: 600;
align-items: center;
line-height: 1;
color: var(--mdbook-alerts-color);
text-transform: capitalize;
}
.mdbook-alerts-icon {
display: inline-block;
width: 1em;
height: 1em;
margin-right: 0.2em;
background-color: currentColor;
-webkit-mask: no-repeat center / 100%;
mask: no-repeat center / 100%;
-webkit-mask-image: var(--mdbook-alerts-icon);
mask-image: var(--mdbook-alerts-icon);
}
.mdbook-alerts-note {
--mdbook-alerts-color: rgb(9, 105, 218);
/* https://icon-sets.iconify.design/material-symbols/info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16v-4q0-.425-.288-.712T12 11q-.425 0-.712.288T11 12v4q0 .425.288.713T12 17m0-8q.425 0 .713-.288T13 8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8q0 .425.288.713T12 9m0 13q-2.075 0-3.9-.788t-3.175-2.137q-1.35-1.35-2.137-3.175T2 12q0-2.075.788-3.9t2.137-3.175q1.35-1.35 3.175-2.137T12 2q2.075 0 3.9.788t3.175 2.137q1.35 1.35 2.138 3.175T22 12q0 2.075-.788 3.9t-2.137 3.175q-1.35 1.35-3.175 2.138T12 22m0-2q3.35 0 5.675-2.325T20 12q0-3.35-2.325-5.675T12 4Q8.65 4 6.325 6.325T4 12q0 3.35 2.325 5.675T12 20m0-8"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-tip {
--mdbook-alerts-color: rgb(26, 127, 55);
/* https://icon-sets.iconify.design/material-symbols/lightbulb-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 22q-.825 0-1.412-.587T10 20h4q0 .825-.587 1.413T12 22m-3-3q-.425 0-.712-.288T8 18q0-.425.288-.712T9 17h6q.425 0 .713.288T16 18q0 .425-.288.713T15 19zm-.75-3q-1.725-1.025-2.738-2.75T4.5 9.5q0-3.125 2.188-5.312T12 2q3.125 0 5.313 2.188T19.5 9.5q0 2.025-1.012 3.75T15.75 16zm.6-2h6.3q1.125-.8 1.738-1.975T17.5 9.5q0-2.3-1.6-3.9T12 4Q9.7 4 8.1 5.6T6.5 9.5q0 1.35.613 2.525T8.85 14M12 14"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-important {
--mdbook-alerts-color: rgb(130, 80, 223);
/* https://icon-sets.iconify.design/material-symbols/chat-info-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 7q.425 0 .713-.288T13 6q0-.425-.288-.712T12 5q-.425 0-.712.288T11 6q0 .425.288.713T12 7m0 8q.425 0 .713-.288T13 14v-4q0-.425-.288-.712T12 9q-.425 0-.712.288T11 10v4q0 .425.288.713T12 15m-6 3l-2.3 2.3q-.475.475-1.088.213T2 19.575V4q0-.825.588-1.412T4 2h16q.825 0 1.413.588T22 4v12q0 .825-.587 1.413T20 18zm-.85-2H20V4H4v13.125zM4 16V4z"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-warning {
--mdbook-alerts-color: rgb(154, 103, 0);
/* https://icon-sets.iconify.design/material-symbols/warning-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M2.725 21q-.275 0-.5-.137t-.35-.363q-.125-.225-.137-.488t.137-.512l9.25-16q.15-.25.388-.375T12 3q.25 0 .488.125t.387.375l9.25 16q.15.25.138.513t-.138.487q-.125.225-.35.363t-.5.137zm1.725-2h15.1L12 6zM12 18q.425 0 .713-.288T13 17q0-.425-.288-.712T12 16q-.425 0-.712.288T11 17q0 .425.288.713T12 18m0-3q.425 0 .713-.288T13 14v-3q0-.425-.288-.712T12 10q-.425 0-.712.288T11 11v3q0 .425.288.713T12 15m0-2.5"%2F%3E%3C%2Fsvg%3E');
}
.mdbook-alerts-caution {
--mdbook-alerts-color: rgb(207, 34, 46);
/* https://icon-sets.iconify.design/material-symbols/brightness-alert-outline-rounded/ */
--mdbook-alerts-icon: url('data:image/svg+xml,%3Csvg xmlns="http%3A%2F%2Fwww.w3.org%2F2000%2Fsvg" width="24" height="24" viewBox="0 0 24 24"%3E%3Cpath fill="currentColor" d="M12 17q.425 0 .713-.288T13 16q0-.425-.288-.712T12 15q-.425 0-.712.288T11 16q0 .425.288.713T12 17m0-4q.425 0 .713-.288T13 12V8q0-.425-.288-.712T12 7q-.425 0-.712.288T11 8v4q0 .425.288.713T12 13m-3.35 7H6q-.825 0-1.412-.587T4 18v-2.65L2.075 13.4q-.275-.3-.425-.662T1.5 12q0-.375.15-.737t.425-.663L4 8.65V6q0-.825.588-1.412T6 4h2.65l1.95-1.925q.3-.275.663-.425T12 1.5q.375 0 .738.15t.662.425L15.35 4H18q.825 0 1.413.588T20 6v2.65l1.925 1.95q.275.3.425.663t.15.737q0 .375-.15.738t-.425.662L20 15.35V18q0 .825-.587 1.413T18 20h-2.65l-1.95 1.925q-.3.275-.662.425T12 22.5q-.375 0-.737-.15t-.663-.425zm.85-2l2.5 2.5l2.5-2.5H18v-3.5l2.5-2.5L18 9.5V6h-3.5L12 3.5L9.5 6H6v3.5L3.5 12L6 14.5V18zm2.5-6"%2F%3E%3C%2Fsvg%3E');
}
</style>
<h1 id="snippet-execution"><a class="header" href="#snippet-execution">Snippet execution</a></h1>
<h2 id="executing-code-blocks"><a class="header" href="#executing-code-blocks">Executing code blocks</a></h2>
<p>Annotating a code block with a <code>+exec</code> attribute will make it executable. Pressing <code>control+e</code> when viewing a slide that
contains an executable block, the code in the snippet will be executed and the output of the execution will be displayed
on a box below it. The code execution is stateful so if you switch to another slide and then go back, you will still see
the output.</p>
<pre><code class="language-markdown">```bash +exec
echo hello world
```
</code></pre>
<p>Code execution <strong>must be explicitly enabled</strong> by using either:</p>
<ul>
<li>The <code>-x</code> command line parameter when running <em>presenterm</em>.</li>
<li>Setting the <code>snippet.exec.enable</code> property to <code>true</code> in your <a href="../../configuration/settings.html#snippet-execution"><em>presenterm</em> config
file</a>.</li>
</ul>
<p>Refer to <a href="highlighting.html#code-highlighting">the table in the highlighting page</a> for the list of languages for which
code execution is supported.</p>
<hr />
<p><a href="https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr"><img src="https://asciinema.org/a/BbAY817esxagCgPtnKUwgYnHr.svg" alt="asciicast" /></a></p>
<div class="mdbook-alerts mdbook-alerts-warning">
<p class="mdbook-alerts-title">
<span class="mdbook-alerts-icon"></span>
warning
</p>
<p>Run code in presentations at your own risk! Especially if you're running someone else's presentation. Don't blindly
enable snippet execution!</p>
</div>
<h2 id="executing-and-replacing"><a class="header" href="#executing-and-replacing">Executing and replacing</a></h2>
<p>Similar to <code>+exec</code>, <code>+exec_replace</code> causes a snippet to be executable but:</p>
<ul>
<li>Execution happens automatically without user intervention.</li>
<li>The snippet will be automatically replaced with its execution output.</li>
</ul>
<p>This can be useful to run programs that generate some form of ASCII art that you'd like to generate dynamically.</p>
<p><a href="https://asciinema.org/a/hklQARZKb5sP5mavL4cGgbYXD"><img src="https://asciinema.org/a/hklQARZKb5sP5mavL4cGgbYXD.svg" alt="asciicast" /></a></p>
<p>Because of the risk involved in <code>+exec_replace</code>, where code gets automatically executed when running a presentation,
this requires users to explicitly opt in to it. This can be done by either passing in the <code>-X</code> command line parameter
or setting the <code>snippet.exec_replace.enable</code> flag in your configuration file to <code>true</code>.</p>
<h2 id="code-to-image-conversions"><a class="header" href="#code-to-image-conversions">Code to image conversions</a></h2>
<p>The <code>+image</code> attribute behaves like <code>+exec_replace</code> but also assumes the output of the executed snippet will be an
image, and it will render it as such. For this to work, the code <strong>must only emit an image in jpg/png formats</strong> and
nothing else.</p>
<p>For example, this would render the demo presentation's image:</p>
<pre><code class="language-markdown">```bash +image
cat examples/doge.png
```
</code></pre>
<p>This attribute carries the same risks as <code>+exec_replace</code> and therefore needs to be enabled via the same flags.</p>
<h2 id="executing-snippets-that-need-a-tty"><a class="header" href="#executing-snippets-that-need-a-tty">Executing snippets that need a TTY</a></h2>
<p>If you're trying to execute a program like <code>top</code> that needs to run on a TTY as it renders text, clears the screen, etc,
you can use the <code>+acquire_terminal</code> modifier on a code already marked as executable with <code>+exec</code>. Executing snippets
tagged with these two attributes will cause <em>presenterm</em> to suspend execution, the snippet will be invoked giving it the
raw terminal to do whatever it needs, and upon its completion <em>presenterm</em> will resume its execution.</p>
<p><a href="https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT"><img src="https://asciinema.org/a/AHfuJorCNRR8ZEnfwQSDR5vPT.svg" alt="asciicast" /></a></p>
<h2 id="styled-execution-output"><a class="header" href="#styled-execution-output">Styled execution output</a></h2>
<p>Snippets that generate output which contains escape codes that change the colors or styling of the text will be parsed
and displayed respecting those styles. Do note that you may need to force certain tools to use colored output as they
will likely not use it by default.</p>
<p>For example, to get colored output when invoking <code>ls</code> you can use:</p>
<pre><code class="language-markdown">```bash +exec
ls /tmp --color=always
```
</code></pre>
<p>The parameter or way to enable this will depend on the tool being invoked.</p>
<h2 id="hiding-code-lines"><a class="header" href="#hiding-code-lines">Hiding code lines</a></h2>
<p>When you mark a code snippet as executable via the <code>+exec</code> flag, you may not be interested in showing <em>all the lines</em> to
your audience, as some of them may not be necessary to convey your point. For example, you may want to hide imports,
non-essential functions, initialization of certain variables, etc. For this purpose, <em>presenterm</em> supports a prefix
under certain programming languages that let you indicate a line should be executed when running the code but should not
be displayed in the presentation.</p>
<p>For example, in the following code snippet only the print statement will be displayed but the entire snippet will be
ran:</p>
<pre><code class="language-markdown">```rust
# fn main() {
println!("Hello world!");
# }
```
</code></pre>
<p>Rather than blindly relying on a prefix that may have a meaning in a language, prefixes are chosen on a per language
basis. The languages that are supported and their prefix is:</p>
<ul>
<li>rust: <code># </code>.</li>
<li>python/bash/fish/shell/zsh/kotlin/java/javascript/typescript/c/c++/go: <code>/// </code>.</li>
</ul>
<p>This means that any line in a rust code snippet that starts with <code># </code> will be hidden, whereas all lines in, say, a
golang code snippet that starts with a <code>/// </code> will be hidden.</p>
<h2 id="pre-rendering"><a class="header" href="#pre-rendering">Pre-rendering</a></h2>
<p>Some languages support pre-rendering. This means the code block is transformed into something else when the presentation
is loaded. The languages that currently support this are <em>mermaid</em>, <em>LaTeX</em>, and <em>typst</em> where the contents of the code
block is transformed into an image, allowing you to define formulas as text in your presentation. This can be done by
using the <code>+render</code> attribute on a code block.</p>
<p>See the <a href="latex.html">LaTeX and typst</a> and <a href="mermaid.html">mermaid</a> docs for more information.</p>
</main>
<nav class="nav-wrapper" aria-label="Page navigation">
<!-- Mobile navigation buttons -->
<a rel="prev" href="../../features/code/highlighting.html" class="mobile-nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../../features/code/mermaid.html" class="mobile-nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
<div style="clear: both"></div>
</nav>
</div>
</div>
<nav class="nav-wide-wrapper" aria-label="Page navigation">
<a rel="prev" href="../../features/code/highlighting.html" class="nav-chapters previous" title="Previous chapter" aria-label="Previous chapter" aria-keyshortcuts="Left">
<i class="fa fa-angle-left"></i>
</a>
<a rel="next prefetch" href="../../features/code/mermaid.html" class="nav-chapters next" title="Next chapter" aria-label="Next chapter" aria-keyshortcuts="Right">
<i class="fa fa-angle-right"></i>
</a>
</nav>
</div>
<script>
window.playground_copyable = true;
</script>
<script src="../../elasticlunr.min.js"></script>
<script src="../../mark.min.js"></script>
<script src="../../searcher.js"></script>
<script src="../../clipboard.min.js"></script>
<script src="../../highlight.js"></script>
<script src="../../book.js"></script>
<!-- Custom JS scripts -->
</div>
</body>
</html>