Differences From
Artifact [fcb217abd6]:
222 222 <A> …oh, [!fuck].
223 223 (signal lost)
224 224 ~~~
225 225
226 226 # reference implementation
227 227 the cortav standard is implemented in [$cortav.lua], found in this repository. only the way [$cortav.lua] interprets the cortav language is defined as a reference implementation; other behaviors are simply how [$cortav.lua] implements the specification and may be copied, ignored, tweaked, violently assaulted, or used as inspiration by a compliant parser.
228 228
229 -## invocation
230 -[$cortav.lua] is operated from the command line, either with the command [$lua cortav.lua] or by first compiling it to bytecode; a makefile for producing a "bytecode binary" that can be executed like a normal executable is included in the repository. henceforth it will be assumed you are using the compiled form; if you are instead running [$cortav.lua] directly as an interpreted script, just replace [$$ cortav] with [$$ lua cortav.lua] in incantations.
229 +the reference implementation can be used both as a lua library and from the command line. [$cortav.lua] contains the parser and renderers, [$ext/*] contain various extensions, [$sirsem.lua] contains utility functions, and [$cli.lua] contains the CLI driver.
230 +
231 +## lua library
232 +there are various ways to use cortav from a lua script; the simplest however is probably to precompile your script with luac and link in the necessary components of the implementation. for instance, say we have the following program
233 +
234 +~~~ stdin2html.lua [lua] ~~~
235 +local ct = require 'cortav'
236 +local mode = {}
237 +local doc = ct.parse(io.stdin, {file = '(stdin)'}, mode)
238 +doc.stage = {
239 + kind = 'render';
240 + format = 'html';
241 + mode = mode;
242 +}
243 +output:write(ct.render.html(doc, {accent = '320'}))
244 +~~~
245 +
246 +and the only extension we need is the table-of-contents extension. our script can be translated into a self-contained lua bytecode blob with the following command
247 +
248 +~~~
249 +$ luac -s -o stdin2html.lc $cortav_repo/{sirsem,cortav,ext/toc}.lua stdin2html.lua
250 +~~~
251 +
252 +and can then be operated with the command [$lua stdin2html.lc], with no further need for the cortav repository files. note that the order of the [$luac] command is important! [$sirsem.lua] must come first, followed by [$cortav.lua], followed by any extensions. your driver script (i.e. the script with the entry point into the application) should always come last.
253 +
254 +## command line driver
255 +the [$cortav.lua] command line driver can be run from the repository directory with the command [$lua ./cli.lua], or by first compiling it into a bytecode form that links in all its dependencies. this is the preferred method for installation, as it produces a self-contained executable which loads more quickly, but running the driver in script form may be desirable for development or debugging.
256 +
257 +the repository contains a GNU makefile to automate compilation of the reference implementation on unix-like OSes. simply run [$$ make cortav] or [$$ gmake cortav] from the repository root to produce a self-contained bytecode executable that can be installed anywhere on your filesystem, with no dependencies other than the lua interpreter.
258 +
259 +! note that the makefile strips debugging symbols to save space, so running [$cli.lua] directly as a script may be helpful if you encounter errors and need stacktraces or other debugging information.
260 +
261 +henceforth it will be assumed that you have produced the [$cortav] executable and placed it somewhere in your [$$PATH]; if you are instead running [$cortav.lua] directly as an interpreted script, you'll need to replace [$$ cortav] with [$$ lua ./cli.lua] in incantations.
231 262
232 263 when run without commands, [$cortav.lua] will read input from standard input and write to standard output. alternately, a source file can be given as an argument. to write to a specific file instead of the standard output stream, use the [$-o [!file]] flag.
233 264
234 265 ~~~
235 266 $ cortav readme.ct -o readme.html
236 267 # reads from readme.ct, writes to readme.html
237 268 $ cortav -o readme.html