-
Notifications
You must be signed in to change notification settings - Fork 1
/
Copy pathindex.html
396 lines (337 loc) · 12.7 KB
/
index.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
<!DOCTYPE html>
<html lang="en">
<head>
<!-- Standard Meta -->
<meta charset="utf-8" />
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="description" content="Main website for the λtext file templating utility" />
<!-- Site Properities -->
<title>λtext - General Purpose Templates</title>
<link rel="stylesheet" type="text/css" href="main.min.css" />
<link rel="apple-touch-icon" sizes="57x57" href="/apple-icon-57x57.png">
<link rel="apple-touch-icon" sizes="60x60" href="/apple-icon-60x60.png">
<link rel="apple-touch-icon" sizes="72x72" href="/apple-icon-72x72.png">
<link rel="apple-touch-icon" sizes="76x76" href="/apple-icon-76x76.png">
<link rel="apple-touch-icon" sizes="114x114" href="/apple-icon-114x114.png">
<link rel="apple-touch-icon" sizes="120x120" href="/apple-icon-120x120.png">
<link rel="apple-touch-icon" sizes="144x144" href="/apple-icon-144x144.png">
<link rel="apple-touch-icon" sizes="152x152" href="/apple-icon-152x152.png">
<link rel="apple-touch-icon" sizes="180x180" href="/apple-icon-180x180.png">
<link rel="icon" type="image/png" sizes="192x192" href="/android-icon-192x192.png">
<link rel="icon" type="image/png" sizes="32x32" href="/favicon-32x32.png">
<link rel="icon" type="image/png" sizes="96x96" href="/favicon-96x96.png">
<link rel="icon" type="image/png" sizes="16x16" href="/favicon-16x16.png">
<link rel="manifest" href="/manifest.json">
<meta name="msapplication-TileColor" content="#ffffff">
<meta name="msapplication-TileImage" content="/ms-icon-144x144.png">
<meta name="theme-color" content="#ffffff">
</head>
<body>
<main class="container">
<header>
<img src="logo/ltext.svg" onerror="this.onerror=null; this.src='logo/ltext.png'" alt="ltext logo">
<hgroup>
<h1>λtext</h1>
<h2>General-Purpose Text-File Templating Utility</h2>
</hgroup>
</header>
<section id="preview" class="grid">
<article>
<header>
<img src="img/copy.svg" alt="copy icon" class="icon" />
<h3>
Reduce Duplication
</h3>
</header>
<p>λtext is a generic templating tool for <strong>any</strong>
text file. For languages that don't support <code>import</code>-style
code-reuse, it's common to just copy/paste. However, after a change is
needed, that change must be replicated manually to
<strong>every file</strong> needing it.
With λtext, you <strong>parameterize the <em>files themselves</em></strong>, and let
λtext do the pasting.
</p>
</article>
<article>
<header>
<img src="img/lambda.svg" alt="lambda icon" class="icon" />
<h3>
Built for Precision
</h3>
</header>
<p>With <a href="http://en.wikipedia.org/wiki/Lambda_calculus" target="_blank">Lambda Calculus</a>
as the underlying engine, λtext features both <strong>generality</strong>
and <strong>precision</strong> - its
<a href="http://en.wikipedia.org/wiki/Hindley%E2%80%93Milner_type_system" target="_blank">Hindley-Milner</a>
type system gives us both <em>polymorphism</em> and <em>correctness</em>;
generic templates that seamlessly fit.
</p>
</article>
<article>
<header>
<a href="github.com/ltext/ltext" target="__blank">
<img src="img/mark-github.svg" alt="github icon" class="icon" />
<h3>
Open Source
</h3>
</a>
</header>
<p>λtext is <a href="http://opensource.org/licenses/BSD-2-Clause" target="_blank">BSD Licenced</a> - you are free
to do what you want with the project. It's written in the advanced
programming language <a href="http://haskell.org" target="_blank">Haskell</a>,
with its code available on
<a href="https://github.com/ltext/ltext" target="_blank">github</a>.
</p>
</article>
</section>
<section id="usage">
<header>
<h2>
How It Works
</h2>
</header>
<div class="grid">
<article>
<header>
<h3>1. Have a Text File</h3>
</header>
<p>You will first need a text file to parameterize. This
can be Html, JavaScript, Haskell, Bash, LaTeX, <em>anything</em>. In our
example, we'll use a plaintext file <code>foo</code>:
</p>
<pre>
Woo hoo! I'm a Text File!</pre>
</article>
<article>
<header>
<h3>2. Create a Parameter</h3>
</header>
<p>Just like lambda calculus, we create arity with <em>abstraction</em> -
the act of creating a parameter. In λtext, we need to declare our parameters
on the first line, inside <strong>delimiters</strong>.
Those parameters are later used within
the same delimiters. We are free to choose whatever syntax we
want - Jade-style delimiters a 'la <code>{{ ... }}</code>, Html-friendly
delimiters via comments <code><!-- --></code>, etc. Here's an example
<em>parametric</em> <code>foo</code>:
</p>
<pre>
$$ x %%
Woo hoo! I'm a Text File!
$$ x %%</pre>
</article>
<!-- </div>
<div class="grid"> -->
<article>
<header>
<h3>3. Use Another File as Input</h3>
</header>
<p>Now that we have our function/file <code>foo :: Text -> Text</code>,
we need some content to plug-in. Here's another file <code>bar</code>:
</p>
<pre>
Here's some content that I /really/
want inside `foo`!</pre>
<p>
Note the empty first line - we don't want <code>ltext</code> to think
some of our words are actually delimiters or parameters. Optionally, we
could designate this file as "raw" with the <code>--raw "bar"</code>
flag.
</p>
</article>
<article>
<header>
<h3>4. Apply the Files/Functions with λtext</h3>
</header>
<p>To use our function/files, we must <em>apply</em> them to one another -
application is the other counterpart to lambda calculus. To do this, invoke the
<code>ltext</code> executable from a terminal:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> <span style="color: #E07B53;">"foo bar"</span>
Woo hoo! I'm a Text File!
Here's some content that I /really/
want inside `foo`!</pre>
<p>The result expression / file text gets pumped out <code>stdout</code>.</p>
</article>
</div>
</section>
<section id="download">
<header>
<h2>
Get λtext
</h2>
</header>
<div class="grid">
<article>
<header>
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/linux/linux-plain.svg" alt="linux logo" class="logo" />
</header>
<!-- linux downloads -->
<a href="https://snapcraft.io/ltext">
<img alt="Get it from the Snap Store" src="https://snapcraft.io/static/images/badges/en/snap-store-white.svg" />
</a>
</article>
<article>
<header>
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/apple/apple-original.svg" alt="apple logo" class="logo" />
</header>
<!-- osx downloads -->
<em>None yet - <a href="#build-from-source">Build From Source</a></em>
</article>
<article>
<header>
<img src="https://cdn.jsdelivr.net/gh/devicons/devicon/icons/windows8/windows8-original.svg" alt="windows logo" class="logo" />
</header>
<!-- windows downloads -->
<em>None yet - <a href="#build-from-source">Build From Source</a></em>
</article>
</div>
<div class="grid divider">
<hr />
<div>
or
</div>
<hr />
</div>
<h3>Build From Source</h3>
<ol>
<li>
Get <a href="https://github.com/commercialhaskell/stack#how-to-install">Stack</a>
</li>
<li>
<code>stack install ltext</code>
</li>
</ol>
</section>
<section id="advanced">
<header>
<h2 id="advanced">
Advanced Usage
</h2>
<p>
There are a few other things to consider when working with λtext -
type checking, partial application, and... debugging! <strong>*gasp*</strong>
</p>
</header>
<article>
<header>
<h2 id="typechecking">Type Checking</h2>
</header>
<p>
To inspect the type of a file or an expression, just use the
<code>-t</code> option during invocation:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> --type <span style="color: #E07B53;">"foo"</span>
foo :: Text -> Text</pre>
<p>
You can read this as "foo takes in Text and returns Text", or "foo is a
<em>function</em> from Text to Text". This is useful if you are getting
type matching errors, or want to get a <em>description</em> of a file. We
can also check the type signature of expressions directly:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> --type <span style="color: #E07B53;">"\x -> x"</span>
a0 -> a0</pre>
<p>
This is a little technical, but we are creating a <strong>polymorphic</strong>
function <code>\x -> x</code>, which has a type from <strong>for all</strong>
<code>a0</code> to <code>a0</code> (you may see these cryptic type variables
instead of <code>Text</code>
from time to time). This would happen if, for instance, you made an "apply"-like
template:
</p>
<pre>
%% f x %%
asdf
%% f x %%</pre>
<p>
If you check the type of <code>apply</code>, you can see it's...
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> --type <span style="color: #E07B53;">"apply"</span>
(a1 -> Text) -> a1 -> Text</pre>
<p>
Meaning that <code>x</code> can be content of <em>any</em> type, so long
as it's the same input as <code>f</code>.
</p>
</article>
<article>
<header>
<h2 id="partial">Partial Application</h2>
</header>
<p>
Just like lambda calculus, we can partially apply templates to each other.
Take our <code>apply</code> template from before - that's a good example
to work though. If we apply our <code>foo</code> file from before to
<code>apply</code>, we should get a template from <code>Text -> Text</code> -
the parameter to <code>foo</code> being unified with the <code>x</code> parameter
in <code>apply</code>:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> --type <span style="color: #E07B53;">"apply foo"</span>
Text -> Text</pre>
<p>
It turns out, we can actually render this partially applied template, but only if
we <strong>explicitly</strong> supply new delimiters for the result:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> <span style="color: #E07B53;">"apply foo"</span> --left <span style="color: #E07B53;">"{{"</span> --right <span style="color: #E07B53;">"}}"</span>
{{ x }}
asdf
Woo hoo! I'm a Text File!
{{ x }}</pre>
</article>
<article>
<header>
<h2 id="debugging">Debugging</h2>
</header>
<p>
If you toyed around with the <code>apply</code> function from earlier, you
may have seen a daunting error:
</p>
<pre>
$ <span style="color: #00AD9C;">ltext</span> <span style="color: #E07B53;">"\f -> apply f bar"</span>
[Print Error] Can't print textual data while residually inside an expression:
Abs "f" (Concat (Lit ["###"]) (App (Var "f") (Abs "some" (Abs "content"
(Abs "that" (Abs "I" (Lit ["###"])))))))</pre>
<p>
This is intended! This makes sure that the templates we render are actually
<em>renderable</em>.
</p>
<p>
In laymen's terms, a template can only be rendered if <strong>all</strong>
<code>Text</code> data that is concatenated (<code><></code>) is at the
"top level" - if after reducing our expression, we wind up applying text to
an unknown function, or applying unknown input to a file, we can't fully
substitute the text, and are left with dangling references to files.
</p>
<p>
We can check the type of these expressions, but we can't render them. This
process will improve in the future, but for now just make sure `ltext` is used
to concatenate files completely, and not expect partial application to
"just work".
</p>
<p>
So, if you ever get this error, you know that there's something you still need
to apply before you can fully render your expression.
</p>
</article>
</section>
<footer>
Copyright © Athan Clark; 2014 - 2023 released under the
<a href="https://github.com/ltext/ltext/blob/master/LICENSE" target="_blank">BSD 3-Clause License</a>.
</footer>
</main>
<!-- Google tag (gtag.js) -->
<script async src="https://www.googletagmanager.com/gtag/js?id=G-CK4L3FLD6T"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){dataLayer.push(arguments);}
gtag('js', new Date());
gtag('config', 'G-CK4L3FLD6T');
</script>
</body>
</html>