djot.lua/objects/12e06a01d9: README.md

/repos/djot.lua/12e06a01d9: README.md

size: 3 KiB


  
1 # Djot.lua
2 
3 [![GitHub
4 CI](https://github.com/jgm/djot.lua/workflows/CI%20tests/badge.svg)](https://github.com/jgm/djot.lua/actions)
5 
6 This repository contains a Lua parser for
7 [djot](https://djot.net), a light markup syntax.
8 
9 Despite being written in an interpreted language, this
10 implementation is very fast (converting a 260K test document in
11 141 ms on an M1 mac using the standard `lua` interpreter). It
12 can produce an AST, rendered HTML, or a stream of match tokens
13 that identify elements by source position, which could be used
14 for syntax highlighting or a linting tool.
15 
16 We also provide a custom pandoc writer for djot (`djot-writer.lua`),
17 so that documents in other formats can be converted to djot
18 format, and a custom pandoc reader (`djot-reader.lua`), so that
19 djot documents can be converted to any format pandoc supports.
20 To use these, just put them in your working directory and use
21 `pandoc -f djot-reader.lua` to convert from djot, and `pandoc -t
22 djot-writer.lua` to convert to djot. You'll need pandoc version
23 2.18 or higher, and you'll need the djot library to be installed
24 in your `LUA_PATH`; see [Installing](#installing), below.  If
25 you're using the dev version of djot or don't want to worry
26 about the djot library being installed, you can create
27 self-contained versions of the custom reader and writer
28 using the `amalg` tool:
29 
30     luarocks install amalg
31     make djot-reader.amalg.lua
32     make djot-writer.amalg.lua
33 
34 These can be moved anywhere and do not require any Lua libraries
35 to be installed.
36 
37 ## Installing
38 
39 To install djot using [luarocks](https://luarocks.org), just
40 
41 ```
42 luarocks install djot
43 ```
44 
45 This will install both the library and the executable `djot`.
46 
47 ## Using the Lua library
48 
49 ### Quick start
50 
51 If you just want to parse some input and produce HTML:
52 
53 ``` lua
54 local djot = require("djot")
55 local input = "This is *djot*"
56 local doc = djot.parse(input)
57 local html = djot.render_html(doc)
58 ```
59 
60 The AST is available as a Lua table, `doc.ast`.
61 
62 To render the AST:
63 
64 ``` lua
65 local rendered = djot.render_ast_pretty(doc)
66 ```
67 
68 Or as JSON:
69 
70 ``` lua
71 local rendered = djot.render_ast_json(doc)
72 ```
73 
74 To alter the AST with a filter:
75 
76 ``` lua
77 local src = "return { str = function(e) e.text = e.text:upper() end }"
78 local filter = djot.filter.load_filter(src)
79 djot.filter.apply_filter(doc, filter)
80 ```
81 
82 For a streaming parser:
83 
84 ``` lua
85 for startpos, endpos, annotation in djot.parse_events("*hello there*") do
86   print(startpos, endpos, annotation)
87 end
88 ```
89 
90 (This will print start and end byte offsets into the input
91 for annotated tokens.)
92 
93 ## The code
94 
95 The code for djot (excluding the test suite) is standard Lua,
96 compatible with lua 5.1--5.4 and luajit. Djot has no external
97 dependencies. You can run it without installing it using
98 `./run.sh`.
99 
100 `make install` will build the rockspec and install the
101 library and executable using luarocks. Once installed,
102 the library can be used by Lua programs, and the executable can
103 be run using `djot`. `djot -h` will give help output.
104 
105 If you can't assume that lua or luajit will be installed on
106 the target machine, you can use `make djot` in the `clib`
107 directory to create a portable binary that bakes in a lua
108 interpreter and the necessary scripts.
109 
110 `make test` will run the tests, and `make testall` will also
111 run some tests of pathological cases.
112 
113 ## License
114 
115 The code and documentation are released under the MIT license.
116

1	# Djot.lua
2
3	[![GitHub
4	CI](https://github.com/jgm/djot.lua/workflows/CI%20tests/badge.svg)](https://github.com/jgm/djot.lua/actions)
5
6	This repository contains a Lua parser for
7	[djot](https://djot.net), a light markup syntax.
8
9	Despite being written in an interpreted language, this
10	implementation is very fast (converting a 260K test document in
11	141 ms on an M1 mac using the standard `lua` interpreter). It
12	can produce an AST, rendered HTML, or a stream of match tokens
13	that identify elements by source position, which could be used
14	for syntax highlighting or a linting tool.
15
16	We also provide a custom pandoc writer for djot (`djot-writer.lua`),
17	so that documents in other formats can be converted to djot
18	format, and a custom pandoc reader (`djot-reader.lua`), so that
19	djot documents can be converted to any format pandoc supports.
20	To use these, just put them in your working directory and use
21	`pandoc -f djot-reader.lua` to convert from djot, and `pandoc -t
22	djot-writer.lua` to convert to djot. You'll need pandoc version
23	2.18 or higher, and you'll need the djot library to be installed
24	in your `LUA_PATH`; see [Installing](#installing), below. If
25	you're using the dev version of djot or don't want to worry
26	about the djot library being installed, you can create
27	self-contained versions of the custom reader and writer
28	using the `amalg` tool:
29
30	luarocks install amalg
31	make djot-reader.amalg.lua
32	make djot-writer.amalg.lua
33
34	These can be moved anywhere and do not require any Lua libraries
35	to be installed.
36
37	## Installing
38
39	To install djot using [luarocks](https://luarocks.org), just
40
41	```
42	luarocks install djot
43	```
44
45	This will install both the library and the executable `djot`.
46
47	## Using the Lua library
48
49	### Quick start
50
51	If you just want to parse some input and produce HTML:
52
53	``` lua
54	local djot = require("djot")
55	local input = "This is djot"
56	local doc = djot.parse(input)
57	local html = djot.render_html(doc)
58	```
59
60	The AST is available as a Lua table, `doc.ast`.
61
62	To render the AST:
63
64	``` lua
65	local rendered = djot.render_ast_pretty(doc)
66	```
67
68	Or as JSON:
69
70	``` lua
71	local rendered = djot.render_ast_json(doc)
72	```
73
74	To alter the AST with a filter:
75
76	``` lua
77	local src = "return { str = function(e) e.text = e.text:upper() end }"
78	local filter = djot.filter.load_filter(src)
79	djot.filter.apply_filter(doc, filter)
80	```
81
82	For a streaming parser:
83
84	``` lua
85	for startpos, endpos, annotation in djot.parse_events("hello there") do
86	print(startpos, endpos, annotation)
87	end
88	```
89
90	(This will print start and end byte offsets into the input
91	for annotated tokens.)
92
93	## The code
94
95	The code for djot (excluding the test suite) is standard Lua,
96	compatible with lua 5.1--5.4 and luajit. Djot has no external
97	dependencies. You can run it without installing it using
98	`./run.sh`.
99
100	`make install` will build the rockspec and install the
101	library and executable using luarocks. Once installed,
102	the library can be used by Lua programs, and the executable can
103	be run using `djot`. `djot -h` will give help output.
104
105	If you can't assume that lua or luajit will be installed on
106	the target machine, you can use `make djot` in the `clib`
107	directory to create a portable binary that bakes in a lua
108	interpreter and the necessary scripts.
109
110	`make test` will run the tests, and `make testall` will also
111	run some tests of pathological cases.
112
113	## License
114
115	The code and documentation are released under the MIT license.
116