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.
449 lines
19 KiB
HTML
449 lines
19 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>markdown - 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">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" class="active">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>markdown</span>
|
|
</nav>
|
|
|
|
<article>
|
|
<h1>markdown</h1>
|
|
|
|
<p>The <code>markdown</code> module provides bidirectional conversion between Markdown and HTML. It supports common Markdown syntax including headings, emphasis, code blocks, lists, links, and images.</p>
|
|
|
|
<pre><code>import "markdown" for Markdown</code></pre>
|
|
|
|
<h2>Markdown Class</h2>
|
|
|
|
<div class="class-header">
|
|
<h3>Markdown</h3>
|
|
<p>Markdown to HTML converter</p>
|
|
</div>
|
|
|
|
<h3>Static Methods</h3>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Markdown.toHtml</span>(<span class="param">text</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Converts Markdown text to HTML.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">text</span> <span class="param-type">(String)</span> - Markdown text</li>
|
|
<li><span class="returns">Returns:</span> HTML string</li>
|
|
</ul>
|
|
<pre><code>var html = Markdown.toHtml("# Hello World")
|
|
System.print(html) // <h1>Hello World</h1></code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Markdown.toHtml</span>(<span class="param">text</span>, <span class="param">options</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Converts Markdown text to HTML with options.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">text</span> <span class="param-type">(String)</span> - Markdown text</li>
|
|
<li><span class="param-name">options</span> <span class="param-type">(Map)</span> - Conversion options</li>
|
|
<li><span class="returns">Returns:</span> HTML string</li>
|
|
</ul>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Markdown.fromHtml</span>(<span class="param">html</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Converts HTML to Markdown text.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">html</span> <span class="param-type">(String)</span> - HTML string</li>
|
|
<li><span class="returns">Returns:</span> Markdown text</li>
|
|
</ul>
|
|
<pre><code>var md = Markdown.fromHtml("<h1>Hello World</h1>")
|
|
System.print(md) // # Hello World</code></pre>
|
|
|
|
<div class="method-signature">
|
|
<span class="method-name">Markdown.fromHtml</span>(<span class="param">html</span>, <span class="param">options</span>) → <span class="type">String</span>
|
|
</div>
|
|
<p>Converts HTML to Markdown text with options.</p>
|
|
<ul class="param-list">
|
|
<li><span class="param-name">html</span> <span class="param-type">(String)</span> - HTML string</li>
|
|
<li><span class="param-name">options</span> <span class="param-type">(Map)</span> - Conversion options</li>
|
|
<li><span class="returns">Returns:</span> Markdown text</li>
|
|
</ul>
|
|
|
|
<h2>Options</h2>
|
|
|
|
<h3>toHtml Options</h3>
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>safeMode</code></td>
|
|
<td>Bool</td>
|
|
<td><code>false</code></td>
|
|
<td>Escape HTML in input to prevent XSS</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h3>fromHtml Options</h3>
|
|
<table>
|
|
<tr>
|
|
<th>Option</th>
|
|
<th>Type</th>
|
|
<th>Default</th>
|
|
<th>Description</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code>stripUnknown</code></td>
|
|
<td>Bool</td>
|
|
<td><code>true</code></td>
|
|
<td>Strip unknown HTML tags, keeping their content</td>
|
|
</tr>
|
|
</table>
|
|
|
|
<h2>Supported Syntax</h2>
|
|
|
|
<h3>Headings</h3>
|
|
<pre><code># Heading 1
|
|
## Heading 2
|
|
### Heading 3
|
|
#### Heading 4
|
|
##### Heading 5
|
|
###### Heading 6</code></pre>
|
|
<p>Converts to <code><h1></code> through <code><h6></code> tags.</p>
|
|
|
|
<h3>Emphasis</h3>
|
|
<pre><code>*italic* or _italic_
|
|
**bold** or __bold__
|
|
~~strikethrough~~</code></pre>
|
|
<p>Converts to <code><em></code>, <code><strong></code>, and <code><del></code> tags.</p>
|
|
|
|
<h3>Code</h3>
|
|
<pre><code>Inline `code` here
|
|
|
|
```
|
|
Code block
|
|
Multiple lines
|
|
```</code></pre>
|
|
<p>Inline code uses <code><code></code>, blocks use <code><pre><code></code>.</p>
|
|
|
|
<h3>Lists</h3>
|
|
<pre><code>Unordered:
|
|
- Item 1
|
|
- Item 2
|
|
* Also works
|
|
+ And this
|
|
|
|
Ordered:
|
|
1. First
|
|
2. Second
|
|
3. Third</code></pre>
|
|
<p>Creates <code><ul></code> and <code><ol></code> with <code><li></code> items.</p>
|
|
|
|
<h3>Links and Images</h3>
|
|
<pre><code>[Link text](https://example.com)
|
|
</code></pre>
|
|
<p>Creates <code><a href="..."></code> and <code><img src="..." alt="..."></code>.</p>
|
|
|
|
<h3>Blockquotes</h3>
|
|
<pre><code>> This is a quote
|
|
> Multiple lines</code></pre>
|
|
<p>Creates <code><blockquote></code> with <code><p></code> content.</p>
|
|
|
|
<h3>Horizontal Rule</h3>
|
|
<pre><code>---
|
|
***
|
|
___</code></pre>
|
|
<p>Creates <code><hr></code> tag.</p>
|
|
|
|
<h3>Paragraphs</h3>
|
|
<p>Text separated by blank lines becomes <code><p></code> elements.</p>
|
|
|
|
<h2>HTML to Markdown Conversions</h2>
|
|
|
|
<p>The <code>fromHtml</code> method converts the following HTML elements to Markdown:</p>
|
|
|
|
<table>
|
|
<tr>
|
|
<th>HTML</th>
|
|
<th>Markdown</th>
|
|
</tr>
|
|
<tr>
|
|
<td><code><h1></code> to <code><h6></code></td>
|
|
<td><code>#</code> to <code>######</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><strong></code>, <code><b></code></td>
|
|
<td><code>**text**</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><em></code>, <code><i></code></td>
|
|
<td><code>*text*</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><code></code></td>
|
|
<td><code>`text`</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><pre><code></code></td>
|
|
<td>Fenced code block</td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><a href="url"></code></td>
|
|
<td><code>[text](url)</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><img src="url" alt=""></code></td>
|
|
<td><code></code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><ul><li></code></td>
|
|
<td><code>- item</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><ol><li></code></td>
|
|
<td><code>1. item</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><blockquote></code></td>
|
|
<td><code>> text</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><hr></code></td>
|
|
<td><code>---</code></td>
|
|
</tr>
|
|
<tr>
|
|
<td><code><del></code>, <code><s></code></td>
|
|
<td><code>~~text~~</code></td>
|
|
</tr>
|
|
</table>
|
|
|
|
<p>Container tags (<code><div></code>, <code><span></code>, <code><section></code>, etc.) are stripped but their content is preserved. Script and style tags are removed entirely.</p>
|
|
|
|
<h2>Examples</h2>
|
|
|
|
<h3>Basic Conversion</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
|
|
var md = "
|
|
# Welcome
|
|
|
|
This is a **Markdown** document with:
|
|
|
|
- Lists
|
|
- *Emphasis*
|
|
- `Code`
|
|
|
|
Visit [Wren](https://wren.io) for more.
|
|
"
|
|
|
|
var html = Markdown.toHtml(md)
|
|
System.print(html)</code></pre>
|
|
|
|
<h3>Safe Mode for User Content</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
|
|
var userInput = "# Title\n<script>alert('xss')</script>\nContent here."
|
|
|
|
var safeHtml = Markdown.toHtml(userInput, {"safeMode": true})
|
|
System.print(safeHtml)</code></pre>
|
|
|
|
<h3>Rendering a Blog Post</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
import "io" for File
|
|
|
|
var postContent = File.read("post.md")
|
|
var html = Markdown.toHtml(postContent)
|
|
|
|
var page = "<html>
|
|
<head><title>Blog</title></head>
|
|
<body>
|
|
<article>
|
|
%(html)
|
|
</article>
|
|
</body>
|
|
</html>"
|
|
|
|
File.write("post.html", page)</code></pre>
|
|
|
|
<h3>Code Blocks with Language Hints</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
|
|
var md = "
|
|
```wren
|
|
System.print(\"Hello, World!\")
|
|
```
|
|
"
|
|
|
|
var html = Markdown.toHtml(md)
|
|
System.print(html)
|
|
// <pre><code>System.print("Hello, World!")</code></pre></code></pre>
|
|
|
|
<h3>Combining with Templates</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
import "jinja" for Environment, DictLoader
|
|
|
|
var env = Environment.new(DictLoader.new({
|
|
"base": "<html><body>{{ content }}</body></html>"
|
|
}))
|
|
|
|
var md = "# Hello\n\nThis is **Markdown**."
|
|
var content = Markdown.toHtml(md)
|
|
|
|
var html = env.getTemplate("base").render({"content": content})
|
|
System.print(html)</code></pre>
|
|
|
|
<h3>Converting HTML to Markdown</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
|
|
var html = "
|
|
<html>
|
|
<body>
|
|
<h1>Article Title</h1>
|
|
<p>This is <strong>important</strong> content.</p>
|
|
<ul>
|
|
<li>First item</li>
|
|
<li>Second item</li>
|
|
</ul>
|
|
</body>
|
|
</html>
|
|
"
|
|
|
|
var md = Markdown.fromHtml(html)
|
|
System.print(md)
|
|
// # Article Title
|
|
//
|
|
// This is **important** content.
|
|
//
|
|
// - First item
|
|
// - Second item</code></pre>
|
|
|
|
<h3>Cleaning HTML for Plain Text</h3>
|
|
<pre><code>import "markdown" for Markdown
|
|
|
|
var webContent = "<div><script>alert('xss')</script><p>Safe <b>content</b></p></div>"
|
|
var clean = Markdown.fromHtml(webContent)
|
|
System.print(clean) // Safe **content**</code></pre>
|
|
|
|
<div class="admonition warning">
|
|
<div class="admonition-title">Warning</div>
|
|
<p>When rendering user-provided Markdown, always use <code>safeMode: true</code> to prevent cross-site scripting (XSS) attacks. Safe mode escapes HTML entities in the input text.</p>
|
|
</div>
|
|
|
|
<div class="admonition note">
|
|
<div class="admonition-title">Note</div>
|
|
<p>Language identifiers after code fences (e.g., <code>```wren</code>) are currently ignored. The code is rendered without syntax highlighting. Consider using a client-side syntax highlighter like Prism.js or highlight.js for the resulting HTML.</p>
|
|
</div>
|
|
</article>
|
|
|
|
<footer class="page-footer">
|
|
<a href="dataset.html" class="prev">dataset</a>
|
|
<a href="web.html" class="next">web</a>
|
|
</footer>
|
|
</main>
|
|
</div>
|
|
<script src="../js/main.js"></script>
|
|
</body>
|
|
</html>
|