README.md

   1 Parkour is a Lua library for structured editing of Lisp S-expressions, meant to be used in text editors.
   2
   3 Editors supported so far:
   4
   5 - [Vis](https://github.com/martanne/vis) - via [vis-parkour](https://repo.or.cz/vis-parkour.git)
   6 - [Textadept](https://github.com/orbitalquark/textadept) - via [ta-parkour](https://repo.or.cz/ta-parkour.git)
   7 - [Howl](https://github.com/howl-editor/howl) - via [howl-parkour](https://repo.or.cz/howl-parkour.git)
   8
   9 # Embedding
  10
  11 Parkour needs the following callback functions to be implemented in terms of editor-specific APIs:
  12
  13 - `read(pos, len)`
  14 - `write(pos, str)`
  15 - `delete(pos, len)`
  16 - `eol_at(pos)`
  17 - `bol_at(pos)`
  18
  19 They are supposed to work on the currently opened file.
  20 Its name is not explicitly used anywhere, you just need to ensure
  21 that it is in a language that Parkour understands.
  22
  23 `pos` and `len` are measured _in bytes_. Still, having multi-byte characters
  24 in identifiers and comment words is fine. As long as separators/delimiters are
  25 single-byte characters, Parkour will simply ignore what's in between.
  26 It can afford to because its commands only take and return positions at
  27 word or list boundaries.
  28
  29     local init, supported = table.unpack(require'parkour')
  30
  31     event.subscribe(FILE_OPENED, function(file)
  32         if not supported[file.type] then return end
  33         # Definitions of the callback functions go here.
  34         local pk = init(file.type, read, write, delete, eol_at, bol_at)
  35     end)
  36
  37 `supported` is a table with the names of all [supported Lisp dialects](init.lua#l1) as keys.
  38 `init()` returns a table with instances of
  39 [`walker`](walker.lua),
  40 [`edit`](edit.lua),
  41 [`input`](input.lua), and
  42 [`parser`](parser/init.lua)
  43 objects, initialized to work on a particular file.
  44
  45 Most of those objects' methods are almost ready for direct use.
  46 `walker` and `edit` methods will usually be bound via keymaps, while
  47 `input` is best handled by some sort of keypress/input event handler.
  48
  49 The methods usually take a `range` argument (a table) which is an abstraction over cursor/selection.
  50 If `range.start == range.finish`, it represents an "I-beam" cursor, like in GUI editors, or "the point" in Emacs.
  51 If `range.finish > range.start`, then it's either a block cursor, like in vim, or a selection.
  52 Some methods take an extra `pos` argument, when the "direction" of a selection is important.
  53 (`pos` should be equal to either `range.start` or `range.finish`)
  54 The return value of a method is the new position the cursor should be put at.