vis

a vi-like editor based on Plan 9's structural regular expressions
README.md

(3372B)
      1 Lua LPeg lexers for vis
      2 =======================
      3 
      4 Vis reuses the [Lua](http://www.lua.org/) [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/)
      5 based lexers from the [Scintillua](https://orbitalquark.github.io/scintillua/index.html) project.
      6 
      7 # Vis integration
      8 
      9 Vis searches the lexers in the following locations (check the end of the
     10 `:help` output for the exact paths used by your binary):
     11 
     12  * `$VIS_PATH/lexers`
     13  * `./lua/lexers` relative to the binary location (using `/proc/self/exe`)
     14  * `$XDG_CONFIG_HOME/vis/lexers` where `$XDG_CONFIG_HOME` refers to
     15    `$HOME/.config` if unset.
     16  * `/etc/vis/lexers`
     17  * `/usr/local/share/vis/lexers` or `/usr/share/vis/lexers` depending on
     18     the build configuration
     19  * `package.path` the standard Lua search path is queried for `lexers/$name`
     20 
     21 At runtime a specific lexer can be loded by means of `:set syntax <name>`
     22 where `<name>` corresponds to the filename without the `.lua` extension.
     23 
     24 # Adding new lexers
     25 
     26 To add a new lexer, start with the template quoted below or a lexer of a
     27 similar language. Read the
     28 [lexer module documentation](https://orbitalquark.github.io/scintillua/api.html#lexer).
     29 The [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/) introduction might also
     30 be useful.
     31 
     32 For development purposes it is recommended to test the lexers from a lua
     33 script as described in the
     34 [Scintillua manual](https://orbitalquark.github.io/scintillua/manual.html#Using.Scintillua.as.a.Lua.Library).
     35 
     36 To enable auto syntax highlighting when opening a file you can associate your
     37 new lexer with a set of file extensions by adding a corresponding entry into
     38 the table found in [`plugins/filetype.lua`](../plugins/filetype.lua) file.
     39 
     40 Changes to existing lexers should also be sent upstream for consideration.
     41 
     42 A template for new lexers:
     43 
     44 ```lua
     45 -- Copyright 2006-2021 Mitchell. See LICENSE.
     46 -- ? LPeg lexer.
     47 
     48 local lexer = require('lexer')
     49 local token, word_match = lexer.token, lexer.word_match
     50 local P, S = lpeg.P, lpeg.S
     51 
     52 local lex = lexer.new('?')
     53 
     54 -- Whitespace.
     55 lex:add_rule('whitespace', token(lexer.WHITESPACE, lexer.space^1))
     56 
     57 -- Keywords.
     58 lex:add_rule('keyword', token(lexer.KEYWORD, word_match[[
     59   keyword1 keyword2 keyword3
     60 ]]))
     61 
     62 -- Identifiers.
     63 lex:add_rule('identifier', token(lexer.IDENTIFIER, lexer.word))
     64 
     65 -- Strings.
     66 local sq_str = lexer.range("'")
     67 local dq_str = lexer.range('"')
     68 lex:add_rule('string', token(lexer.STRING, sq_str + dq_str))
     69 
     70 -- Comments.
     71 lex:add_rule('comment', token(lexer.COMMENT, lexer.to_eol('#')))
     72 
     73 -- Numbers.
     74 lex:add_rule('number', token(lexer.NUMBER, lexer.number))
     75 
     76 -- Operators.
     77 lex:add_rule('operator', token(lexer.OPERATOR, S('+-*/%^=<>,.{}[]()')))
     78 
     79 -- Fold points.
     80 lex:add_fold_point(lexer.KEYWORD, 'start', 'end')
     81 lex:add_fold_point(lexer.OPERATOR, '{', '}')
     82 lex:add_fold_point(lexer.COMMENT, lexer.fold_consecutive_lines('#'))
     83 
     84 return lex
     85 ```
     86 
     87 # Color Themes
     88 
     89 The [`../themes directory`](../themes) contains the color
     90 schemes. Depending on the number of colors supported by your terminal,
     91 vis will start with either the [`default-16`](../themes/default-16.lua)
     92 or [`default-256`](../themes/default-256.lua) theme. Symlink it to
     93 your prefered style or add a command like the following one to your
     94 `visrc.lua`:
     95 
     96 ```
     97 vis:command("set theme solarized")
     98 ```
     99 
    100 # Dependencies
    101 
    102  * [Lua](http://www.lua.org/) 5.1 or greater
    103  * [LPeg](http://www.inf.puc-rio.br/~roberto/lpeg/) 1.0.0 or greater