Parkour is a Lua library for structured editing of Lisp S-expressions, meant to be used in text editors.

Editors supported so far:

• Vis - via vis-parkour
• Textadept - via ta-parkour
• Howl - via howl-parkour

Embedding

Parkour needs the following callback functions to be implemented in terms of editor-specific APIs:

• read(pos, len)
• write(pos, str)
• delete(pos, len)
• eol_at(pos)
• bol_at(pos)

They are supposed to work on the currently opened file. Its name is not explicitly used anywhere, you just need to ensure that it is in a language that Parkour understands.

pos and len are measured in bytes. Still, having multi-byte characters in identifiers and comment words is fine. As long as separators/delimiters are single-byte characters, Parkour will simply ignore what's in between. It can afford to because its commands only take and return positions at word or list boundaries.

local init, supported = table.unpack(require'parkour')

event.subscribe(FILE_OPENED, function(file)
    if not supported[file.type] then return end
    # Definitions of the callback functions go here.
    local pk = init(file.type, read, write, delete, eol_at, bol_at)
end)

supported is a table with the names of all supported Lisp dialects as keys.
init() returns a table with instances of walker, edit, input, and parser objects, initialized to work on a particular file.

Most of those objects' methods are almost ready for direct use.
walker and edit methods will usually be bound via keymaps, while input is best handled by some sort of keypress/input event handler.

The methods usually take a range argument (a table) which is an abstraction over cursor/selection.
If range.start == range.finish, it represents an "I-beam" cursor, like in GUI editors, or "the point" in Emacs.
If range.finish > range.start, then it's either a block cursor, like in vim, or a selection.
Some methods take an extra pos argument, when the "direction" of a selection is important. (pos should be equal to either range.start or range.finish)
The return value of a method is the new position the cursor should be put at.