size: 4 KiB


  

1<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
2   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
3<html>
4<head>
5    <meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
6    <title>Reference</title>
7    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
8</head>
9<body>
10
11<div id="container">
12
13<div id="product">
14	<div id="product_logo"></div>
15	<div id="product_name"><big><b></b></big></div>
16	<div id="product_description"></div>
17</div> <!-- id="product" -->
18
19<div id="main">
20
21
22<!-- Menu -->
23
24
25
26<div id="navigation">
27<h1>djot</h1>
28<ul>
29  <li><a href="../index.html">Index</a></li>
30</ul>
31
32<hr/>
33<ul>
34    <li><a href="#apply_filter">apply_filter&nbsp;(node, filter)</a></li>
35    <li><a href="#require_filter">require_filter&nbsp;(fp)</a></li>
36    <li><a href="#load_filter">load_filter&nbsp;(s)</a></li>
37</ul>
38
39</div>
40
41<div id="content">
42
43
44<h1>Module <code>djot.filter</code></h1>
45
46<p>
47
48</p>
49<p> Support filters that walk the AST and transform a
50 document between parsing and rendering, like pandoc Lua filters.</p>
51
52<p> This filter uppercases all str elements.</p>
53
54<pre><code> return {
55   str = function(e)
56     e.text = e.text:upper()
57    end
58 }
59</code></pre>
60
61<p> A filter may define functions for as many different tag types
62 as it likes.  traverse will walk the AST and apply matching
63 functions to each node.</p>
64
65<p> To load a filter:</p>
66
67<pre><code> local filter = require_filter(path)
68</code></pre>
69
70<p> or</p>
71
72<pre><code> local filter = load_filter(string)
73</code></pre>
74
75<p> By default filters do a bottom-up traversal; that is, the
76 filter for a node is run after its children have been processed.
77 It is possible to do a top-down travel, though, and even
78 to run separate actions on entering a node (before processing the
79 children) and on exiting (after processing the children). To do
80 this, associate the node's tag with a table containing <code>enter</code> and/or
81 <code>exit</code> functions.  The following filter will capitalize text
82 that is nested inside emphasis, but not other text:</p>
83
84<pre><code> local capitalize = 0
85 return {
86    emph = {
87      enter = function(e)
88        capitalize = capitalize + 1
89      end,
90      exit = function(e)
91        capitalize = capitalize - 1
92      end,
93    },
94    str = function(e)
95      if capitalize &gt; 0 then
96        e.text = e.text:upper()
97       end
98    end
99 }
100</code></pre>
101
102<p> For a top-down traversal, you'd just use the <code>enter</code> functions.
103 If the tag is associated directly with a function, as in the
104 first example above, it is treated as an <code>exit</code> function.</p>
105
106<p> It is possible to inhibit traversal into the children of a node,
107 by having the <code>enter</code> function return the value true (or any truish
108 value, say <code>&apos;stop&apos;</code>).  This can be used, for example, to prevent
109 the contents of a footnote from being processed:</p>
110
111<pre><code> return {
112   footnote = {
113     enter = function(e)
114       return true
115     end
116    }
117 }
118</code></pre>
119
120<p> A single filter may return a table with multiple tables, which will be
121 applied sequentially.</p>
122
123<br/>
124<br/>
125
126    <dl class="function">
127    <dt>
128    <a name = "apply_filter"></a>
129    <strong>apply_filter&nbsp;(node, filter)</strong>
130    </dt>
131    <dd>
132    Apply a filter to a document.
133
134
135
136
137
138</dd>
139    <dt>
140    <a name = "require_filter"></a>
141    <strong>require_filter&nbsp;(fp)</strong>
142    </dt>
143    <dd>
144    Returns a table containing the filter defined in <code>fp</code>.
145     <code>fp</code> will be sought using <a href="https://www.lua.org/manual/5.1/manual.html#pdf-require">require</a>, so it may occur anywhere
146 on the <code>LUA_PATH</code>, or in the working directory. On error,
147 returns nil and an error message.
148
149
150</dd>
151    <dt>
152    <a name = "load_filter"></a>
153    <strong>load_filter&nbsp;(s)</strong>
154    </dt>
155    <dd>
156    Load filter from a string, which should have the
157 form `return { ...
158     }`.  On error, return nil and an
159 error message.
160
161
162</dd>
163</dl>
164
165
166</div> <!-- id="content" -->
167</div> <!-- id="main" -->
168<div id="about">
169</div> <!-- id="about" -->
170</div> <!-- id="container" -->
171</body>
172</html>
173