parkour.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @c %**start of header
   3 @setfilename parkour.info
   4 @settitle Parkour
   5 @c %**end of header
   6
   7 @contents
   8
   9 @documentdescription
  10 Structured editing of Lisp S-expressions
  11 @end documentdescription
  12
  13 @ifnottex
  14 @node Top
  15 @top Parkour
  16 @end ifnottex
  17
  18 Under construction.
  19 @include lastchange.txt
  20
  21 Parkour is a library and a few text editor plugins for structured editing of Lisp S-expressions.
  22
  23 @node Distribution
  24 @chapter Distribution
  25
  26 @table @asis
  27 @item Parkour base module
  28 @url{https://repo.or.cz/lisp-parkour.git}
  29 @item Vis plugin
  30 @url{https://repo.or.cz/vis-parkour.git}
  31 @item Textadept plugin
  32 @url{https://repo.or.cz/ta-parkour.git}
  33 @item Howl plugin
  34 @url{https://repo.or.cz/howl-parkour.git}
  35 @item This manual's source
  36 @url{https://repo.or.cz/parkour-doc.git}
  37 @end table
  38
  39 @node Concepts
  40 @chapter Concepts
  41
  42 This page describes behaviour common to all plugins based on Parkour.
  43
  44 @section Objects
  45
  46 Parkour maps the typical objects used in text editors to S-expressions (atoms and lists):
  47
  48 @itemize
  49 @item
  50 word --- atom, or, when the cursor is exactly on a delimiter, list or quasi-list@footnote{@dfn{Quasi-lists} are any double-quoted strings, block comments, and line comments. Like lists, you can perform wrap, splice, split, and join. Unlike lists, you cannot barf, slurp, or descend into them. Also, their content is not subjected to autoformatting.}
  51 @item
  52 block --- parenthesized list
  53 @item
  54 sentence --- the current list or quasi-list
  55 @item
  56 paragraph --- the current top-level expression
  57 @item
  58 section/page --- @code{form-feed}@footnote{@kbd{^L}, ASCII code 12}-separated group of top-level expressions
  59 @end itemize
  60
  61 @section Motions
  62
  63 Parkour provides the following motion types:
  64
  65 @itemize
  66 @item
  67 Structured motions --- move either horizontally (without leaving the current list or quasi-list), or diagonally (ascend or descend) through the tree of nested expressions.
  68
  69 When the cursor is in code, they skip over comments. (For other ways to descend into comments, see @ref{word-descent}, @ref{delete-descent}, @ref{semicolon-descent})
  70
  71 When the cursor is inside a quasi-list, horizontal motions land on individual words.@*
  72 Moreover, when in a group of line comments, horizontal motions will leave the current comment
  73 and enter the previous/next one, effectively treating the whole group as a single comment.
  74
  75 @item
  76 Flow motions --- land on the nearest expression start to the left, or end to the right.@*
  77 By using these motions alone (and some patience), you can land on any expression boundary in the text.
  78
  79 @item
  80 Word motions --- always land on atoms/words. They float up or sink down in the tree hierarchy, and @anchor{word-descent} enter or leave strings/comments, as needed.
  81 @end itemize
  82
  83 @section Electricity/DWIM
  84
  85 Besides the sexp-aware editing operators, which have dedicated key bindings,
  86 Parkour enhances the behaviour of common keys like @kbd{@key{BS}}, @kbd{@key{DEL}}, @kbd{@key{RET}}, @kbd{@key{SPC}}, and @kbd{;}.
  87
  88 @itemize
  89 @item
  90 @kbd{@key{RET}}
  91 @itemize
  92 @item
  93 at end of line --- opens an empty indented line after the current one
  94 @item
  95 at start of line --- opens an empty indented line before the current one
  96 @item
  97 before closing paren --- opens an empty indented line after the last list element
  98 @item
  99 on empty indented line --- does nothing (only one empty line is allowed in a list, and it will be collapsed on the next reindent)
 100 @item
 101 in line comment --- splits the comment
 102 @item
 103 elsewhere in code --- puts the text to the right of the cursor on a new indented line
 104 @end itemize
 105
 106 @item
 107 @kbd{@key{BS}}
 108 @itemize
 109 @item
 110 after a closing delimiter --- moves the cursor to the left of it
 111 @item
 112 after an opening delimiter --- does nothing
 113 @item
 114 at start of line --- joins it with the previous line (and cleans up any leftovers of indentation)
 115 @item
 116 same, but after a line comment --- does nothing (to prevent accidentally commenting out the current line)
 117 @item
 118 at start of line comment --- joins it with the previous one
 119 @item
 120 in empty line comment --- same, unless the empty comment is the last in a group.
 121 In that case, it splices the comment (which deletes it, effectively).
 122 @end itemize
 123
 124 @item
 125 @kbd{@key{DEL}}
 126 @itemize
 127 @item
 128 before an opening delimiter --- moves the cursor to the right of it
 129 @item
 130 before a closing delimiter --- does nothing
 131 @item
 132 at end of line --- joins it with the next line (and cleans up any leftovers of indentation)
 133 @item
 134 at start of line --- does nothing (indentation cannot be manually influenced)
 135 @item @anchor{delete-descent}
 136 before a line comment --- moves the cursor past the opening semicolons
 137 @item
 138 at end of line comment --- joins it with the next one
 139 @item
 140 in empty line comment --- same, unless the empty comment is the last in a group.
 141 In that case, it splices the comment (which deletes it, effectively).
 142 @end itemize
 143
 144 @item
 145 @kbd{@key{SPC}}
 146 @itemize
 147 @item
 148 on empty indented line --- deletes it and inserts the space on the previous line
 149 @item
 150 between a space and another character --- does nothing (only one space is allowed between same-line expressions)
 151 @end itemize
 152
 153 @item
 154 @kbd{;}
 155 @itemize
 156 @item
 157 at start of line --- inserts two or three semicolons (inside a list, or at top level, respectively), and a space.@*
 158 If the line was originally empty, the cursor ends up inside the new comment, so you can start typing.@*
 159 If there was code on the line, the cursor is kept before the semicolons, so you can move away from the commented out code without having to ascend out of it first.
 160 @item @anchor{semicolon-descent}
 161 before a line comment --- moves the cursor past the opening semicolons
 162 @item
 163 elsewhere in code --- shifts anything to the right of the cursor to column 40 and inserts a single semicolon
 164 @end itemize
 165 If in the code that would be commented out there was a delimiter whose match is on another line, the delimiter and anything
 166 to the right of it is moved to the next line in order to prevent any unbalancing.
 167 @end itemize
 168
 169 @section Paren autocorrect
 170
 171 In Clojure and Fennel square brackets are required at certain places.
 172 Parkour will insert a square bracket even if you pressed the wrong kind of delimiter (paren, brace, or even double-quote).
 173
 174 In some Scheme dialects (e.g., Racket) square brackets are recommended for readability reasons.
 175 If you are using such a dialect, you can get this behaviour by enabling the auto_square_brackets option.
 176
 177 @node Features
 178 @chapter Features
 179
 180 @itemize
 181 @item
 182 electric indent
 183 @item
 184 hungry deletion of whitespace
 185 @item
 186 line-comments autoextending/autoshrinking
 187 @item
 188 autopairs for @kbd{(}, @kbd{[}, @kbd{@{}, @kbd{|}, @kbd{"}, and @kbd{;}
 189 @item
 190 aggressive reformatting (almost as-you-type) --- all whitespace deviations in the current list are corrected
 191 as soon as you insert an electric character or delete anything at head position
 192 @item
 193 structured motions, objects, and selections
 194 @item
 195 flow motions
 196 @item
 197 word motions
 198 @item
 199 structured operators
 200 @end itemize
 201
 202 @section Editor-specific features
 203
 204 Some features could not be abstracted into the Parkour library and had to be implemented in the top-layer code
 205 of a particular editor plugin.
 206
 207 @subsection Vis
 208
 209 @itemize
 210 @item
 211 objectwise pasting
 212
 213 This is a generalization over linewise pasting --- pasting a previously deleted/yanked sexp object will put it before or after the current object and insert an appropriate whitespace separator (space or newline), regardless of where exactly the cursor is.@*
 214 This makes it easy to, say, transpose/barf/slurp, without using the dedicated operators, this way flattening the learning curve a bit.
 215 Of course, the dedicated operators have their advantages --- fewer keypresses, keeping cursor position, atomic undo, dot-repeatability.
 216 @item
 217 splicing delete
 218
 219 When inside a list or quasi-list, @kbd{d}-ing with a motion that lands on one of the delimiters will remove the opposite delimiter as well. This merges two paredit commands --- splice-killing-@{forward,backward@} and splicing, into the NORMAL-mode delete.
 220 You can use @kbd{dE}, @kbd{dB}, @kbd{x}, or @kbd{X}, but any motion that leads to the above situation will do (even something like @kbd{d5h}).
 221
 222 @item
 223 autoselect
 224
 225 This reverses the typical for vi verb-noun order, and makes vi motions work like those in @url{http://kakoune.org,Kakoune}.
 226 @end itemize
 227
 228 @bye
 229