retoor
819bbd5091
Add three new example scripts demonstrating the fswatch, sysinfo, and udp modules with file watching, system metrics, and UDP echo server/client patterns. Reorder the manual API sidebar navigation to list modules alphabetically, removing deprecated entries like websocket, tls, net, json, regex, jinja, os, signal, subprocess, sqlite, and timer while adding argparse, dataset, fswatch, and html.
300 lines
15 KiB
HTML
300 lines
15 KiB
HTML
<!DOCTYPE html>
|
|
<!-- retoor <retoor@molodetz.nl> -->
|
|
<html lang="en">
|
|
<head>
|
|
<meta charset="UTF-8">
|
|
<meta name="viewport" content="width=device-width, initial-scale=1.0">
|
|
<title>html - Wren-CLI Manual</title>
|
|
<link rel="stylesheet" href="../css/style.css">
|
|
</head>
|
|
<body>
|
|
<button class="mobile-menu-toggle">Menu</button>
|
|
<div class="container">
|
|
<aside class="sidebar">
|
|
<div class="sidebar-header">
|
|
<h1><a href="../index.html">Wren-CLI</a></h1>
|
|
<div class="version">v0.4.0</div>
|
|
</div>
|
|
<nav class="sidebar-nav">
|
|
<div class="section">
|
|
<span class="section-title">Getting Started</span>
|
|
<ul>
|
|
<li><a href="../getting-started/index.html">Overview</a></li>
|
|
<li><a href="../getting-started/installation.html">Installation</a></li>
|
|
<li><a href="../getting-started/first-script.html">First Script</a></li>
|
|
<li><a href="../getting-started/repl.html">Using the REPL</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<span class="section-title">Language</span>
|
|
<ul>
|
|
<li><a href="../language/index.html">Syntax Overview</a></li>
|
|
<li><a href="../language/classes.html">Classes</a></li>
|
|
<li><a href="../language/methods.html">Methods</a></li>
|
|
<li><a href="../language/control-flow.html">Control Flow</a></li>
|
|
<li><a href="../language/fibers.html">Fibers</a></li>
|
|
<li><a href="../language/modules.html">Modules</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<span class="section-title">API Reference</span>
|
|
<ul>
|
|
<li><a href="index.html">Overview</a></li>
|
|
<li><a href="string.html">String</a></li>
|
|
<li><a href="number.html">Num</a></li>
|
|
<li><a href="argparse.html">argparse</a></li>
|
|
<li><a href="base64.html">base64</a></li>
|
|
<li><a href="crypto.html">crypto</a></li>
|
|
<li><a href="dataset.html">dataset</a></li>
|
|
<li><a href="datetime.html">datetime</a></li>
|
|
<li><a href="dns.html">dns</a></li>
|
|
<li><a href="env.html">env</a></li>
|
|
<li><a href="fswatch.html">fswatch</a></li>
|
|
<li><a href="html.html" class="active">html</a></li>
|
|
<li><a href="http.html">http</a></li>
|
|
<li><a href="io.html">io</a></li>
|
|
<li><a href="jinja.html">jinja</a></li>
|
|
<li><a href="json.html">json</a></li>
|
|
<li><a href="markdown.html">markdown</a></li>
|
|
<li><a href="math.html">math</a></li>
|
|
<li><a href="net.html">net</a></li>
|
|
<li><a href="os.html">os</a></li>
|
|
<li><a href="pathlib.html">pathlib</a></li>
|
|
<li><a href="regex.html">regex</a></li>
|
|
<li><a href="scheduler.html">scheduler</a></li>
|
|
<li><a href="signal.html">signal</a></li>
|
|
<li><a href="sqlite.html">sqlite</a></li>
|
|
<li><a href="subprocess.html">subprocess</a></li>
|
|
<li><a href="sysinfo.html">sysinfo</a></li>
|
|
<li><a href="tempfile.html">tempfile</a></li>
|
|
<li><a href="timer.html">timer</a></li>
|
|
<li><a href="tls.html">tls</a></li>
|
|
<li><a href="udp.html">udp</a></li>
|
|
<li><a href="uuid.html">uuid</a></li>
|
|
<li><a href="wdantic.html">wdantic</a></li>
|
|
<li><a href="web.html">web</a></li>
|
|
<li><a href="websocket.html">websocket</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<span class="section-title">Tutorials</span>
|
|
<ul>
|
|
<li><a href="../tutorials/index.html">Tutorial List</a></li>
|
|
<li><a href="../tutorials/http-client.html">HTTP Client</a></li>
|
|
<li><a href="../tutorials/websocket-chat.html">WebSocket Chat</a></li>
|
|
<li><a href="../tutorials/database-app.html">Database App</a></li>
|
|
<li><a href="../tutorials/template-rendering.html">Templates</a></li>
|
|
<li><a href="../tutorials/cli-tool.html">CLI Tool</a></li>
|
|
</ul>
|
|
</div>
|
|
<div class="section">
|
|
<span class="section-title">How-To Guides</span>
|
|
<ul>
|
|
<li><a href="../howto/index.html">How-To List</a></li>
|
|
<li><a href="../howto/http-requests.html">HTTP Requests</a></li>
|
|
<li><a href="../howto/json-parsing.html">JSON Parsing</a></li>
|
|
<li><a href="../howto/regex-patterns.html">Regex Patterns</a></li>
|
|
<li><a href="../howto/file-operations.html">File Operations</a></li>
|
|
<li><a href="../howto/async-operations.html">Async Operations</a></li>
|
|
<li><a href="../howto/error-handling.html">Error Handling</a></li>
|
|
</ul>
|
|
</div>
|
|
</nav>
|
|
</aside>
|
|
<main class="content">
|
|
<nav class="breadcrumb">
|
|
<a href="../index.html">Home</a>
|
|
<span class="separator">/</span>
|
|
<a href="index.html">API Reference</a>
|
|
<span class="separator">/</span>
|
|
<span>html</span>
|
|
</nav>
|
|
|
|
<article>
|
|
<h1>html</h1>
|
|
|
|
<p>The <code>html</code> module provides utilities for HTML and URL encoding/decoding, slug generation, and query string handling.</p>
|
|
|
|
<pre><code>import "html" for Html</code></pre>
|
|
|
|
<h2>Html Class</h2>
|
|
|
|
<div class="class-header">
|
|
<h3>Html</h3>
|
|
<p>HTML and URL encoding utilities</p>
|
|
</div>
|
|
|
|
<h3>Static Methods</h3>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.urlencode</span>(<span class="param">string</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>URL-encodes a string for use in URLs and query parameters. Spaces become <code>+</code>, special characters become percent-encoded.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - The string to encode</li>
|
|
<li><span class="returns">Returns:</span> URL-encoded string</li>
|
|
</ul>
|
|
<pre><code>System.print(Html.urlencode("hello world")) // hello+world
|
|
System.print(Html.urlencode("a=b&c=d")) // a\%3Db\%26c\%3Dd
|
|
System.print(Html.urlencode("café")) // caf\%C3\%A9</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.urldecode</span>(<span class="param">string</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Decodes a URL-encoded string. Converts <code>+</code> to space and decodes percent-encoded characters.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - The URL-encoded string</li>
|
|
<li><span class="returns">Returns:</span> Decoded string</li>
|
|
</ul>
|
|
<pre><code>System.print(Html.urldecode("hello+world")) // hello world
|
|
System.print(Html.urldecode("caf\%C3\%A9")) // café</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.slugify</span>(<span class="param">string</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Converts a string to a URL-friendly slug. Lowercase, alphanumeric characters with hyphens.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - The string to slugify</li>
|
|
<li><span class="returns">Returns:</span> URL-friendly slug</li>
|
|
</ul>
|
|
<pre><code>System.print(Html.slugify("Hello World")) // hello-world
|
|
System.print(Html.slugify("My Blog Post!")) // my-blog-post
|
|
System.print(Html.slugify(" Multiple Spaces ")) // multiple-spaces</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.quote</span>(<span class="param">string</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Escapes HTML special characters to prevent XSS attacks.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - The string to escape</li>
|
|
<li><span class="returns">Returns:</span> HTML-escaped string</li>
|
|
</ul>
|
|
<pre><code>System.print(Html.quote("<script>alert('xss')</script>"))
|
|
// &lt;script&gt;alert(&#39;xss&#39;)&lt;/script&gt;
|
|
|
|
System.print(Html.quote("A & B")) // A &amp; B
|
|
System.print(Html.quote("\"quoted\"")) // &quot;quoted&quot;</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.unquote</span>(<span class="param">string</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Unescapes HTML entities back to their original characters.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - The HTML-escaped string</li>
|
|
<li><span class="returns">Returns:</span> Unescaped string</li>
|
|
</ul>
|
|
<pre><code>System.print(Html.unquote("&lt;div&gt;")) // <div>
|
|
System.print(Html.unquote("A &amp; B")) // A & B</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.encodeParams</span>(<span class="param">params</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Encodes a map of key-value pairs into a URL query string.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">params</span> <span class="param-type">(Map)</span> - Map of parameters to encode</li>
|
|
<li><span class="returns">Returns:</span> URL-encoded query string</li>
|
|
</ul>
|
|
<pre><code>var params = {"name": "John Doe", "age": 30}
|
|
System.print(Html.encodeParams(params)) // name=John+Doe&age=30
|
|
|
|
var search = {"q": "wren lang", "page": 1}
|
|
System.print(Html.encodeParams(search)) // q=wren+lang&page=1</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Html.decodeParams</span>(<span class="param">string</span>) → <span class="type">Map</span>
|
|
</div>
|
|
<p>Decodes a URL query string into a map of key-value pairs.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">string</span> <span class="param-type">(String)</span> - URL-encoded query string</li>
|
|
<li><span class="returns">Returns:</span> Map of decoded parameters</li>
|
|
</ul>
|
|
<pre><code>var params = Html.decodeParams("name=John+Doe&age=30")
|
|
System.print(params["name"]) // John Doe
|
|
System.print(params["age"]) // 30</code></pre>
|
|
|
|
<h2>Entity Reference</h2>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>Character</th>
|
|
<th>Entity</th>
|
|
</tr>
|
|
<tr>
|
|
<td>&</td>
|
|
<td>&amp;</td>
|
|
</tr>
|
|
<tr>
|
|
<td><</td>
|
|
<td>&lt;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>></td>
|
|
<td>&gt;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>"</td>
|
|
<td>&quot;</td>
|
|
</tr>
|
|
<tr>
|
|
<td>'</td>
|
|
<td>&#39;</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2>Examples</h2>
|
|
|
|
<h3>Building URLs</h3>
|
|
<pre><code>import "html" for Html
|
|
|
|
var baseUrl = "https://api.example.com/search"
|
|
var params = {
|
|
"query": "wren programming",
|
|
"limit": 10,
|
|
"offset": 0
|
|
}
|
|
|
|
var url = baseUrl + "?" + Html.encodeParams(params)
|
|
System.print(url)
|
|
// https://api.example.com/search?query=wren+programming&limit=10&offset=0</code></pre>
|
|
|
|
<h3>Safe HTML Output</h3>
|
|
<pre><code>import "html" for Html
|
|
|
|
var userInput = "<script>alert('xss')</script>"
|
|
var safeHtml = "<div class=\"comment\">" + Html.quote(userInput) + "</div>"
|
|
System.print(safeHtml)</code></pre>
|
|
|
|
<h3>Generating Slugs for URLs</h3>
|
|
<pre><code>import "html" for Html
|
|
|
|
var title = "How to Build Web Apps with Wren!"
|
|
var slug = Html.slugify(title)
|
|
var url = "/blog/" + slug
|
|
System.print(url) // /blog/how-to-build-web-apps-with-wren</code></pre>
|
|
|
|
<h3>Parsing Query Strings</h3>
|
|
<pre><code>import "html" for Html
|
|
|
|
var queryString = "category=books&sort=price&order=asc"
|
|
var params = Html.decodeParams(queryString)
|
|
|
|
for (key in params.keys) {
|
|
System.print("%(key): %(params[key])")
|
|
}</code></pre>
|
|
|
|
<div class="admonition warning">
|
|
<div class="admonition-title">Warning</div>
|
|
<p>Always use <code>Html.quote()</code> when inserting user-provided content into HTML to prevent cross-site scripting (XSS) attacks.</p>
|
|
</div>
|
|
</article>
|
|
|
|
<footer class="page-footer">
|
|
<a href="fswatch.html" class="prev">fswatch</a>
|
|
<a href="http.html" class="next">http</a>
|
|
</footer>
|
|
</main>
|
|
</div>
|
|
<script src="../js/main.js"></script>
|
|
</body>
|
|
</html>
|