diff options
| -rw-r--r-- | Makefile | 8 | ||||
| -rw-r--r-- | luadoc/README.md | 37 | ||||
| -rw-r--r-- | luadoc/config.ld | 14 | ||||
| -rw-r--r-- | vis-lua.c | 222 | ||||
| -rw-r--r-- | vis.lua | 33 |
5 files changed, 281 insertions, 33 deletions
@@ -86,8 +86,10 @@ man: done luadoc: - @ldoc -p "Vis Editor" -f markdown -M vis-lua.c -s '!pale' && \ - sed -e "s/RELEASE/${VERSION}/" -i doc/index.html + @cd luadoc && ldoc . && sed -e "s/RELEASE/${VERSION}/" -i index.html + +luadoc-all: + @cd luadoc && ldoc -a . && sed -e "s/RELEASE/${VERSION}/" -i index.html install: vis vis-menu @echo stripping executable @@ -127,4 +129,4 @@ uninstall: @echo removing support files from ${DESTDIR}${SHAREPREFIX}/vis @rm -rf ${DESTDIR}${SHAREPREFIX}/vis -.PHONY: all clean dist install uninstall debug profile coverage test test-update +.PHONY: all clean dist install uninstall debug profile coverage test test-update luadoc luadoc-all diff --git a/luadoc/README.md b/luadoc/README.md new file mode 100644 index 0000000..17531da --- /dev/null +++ b/luadoc/README.md @@ -0,0 +1,37 @@ +This is the destination directory for the LDoc documentation of Vis' Lua API +as generated by the `make luadoc`. + +Unfortunately `ldoc(1)` seems to have a bug which generates broken reference +links for custom types. The following patch seems to fix the issue: + +``` +From 96a1fbc8e972fedf665049a6351f46bc1aac1768 Mon Sep 17 00:00:00 2001 +From: =?UTF-8?q?Marc=20Andr=C3=A9=20Tanner?= <mat@brain-dump.org> +Date: Tue, 6 Dec 2016 15:59:17 +0100 +Subject: [PATCH] Fix references to class types. + +For classes the generated HTML anchors need to be prefixed 'Class_'. +--- + ldoc/doc.lua | 6 +++--- + 1 file changed, 3 insertions(+), 3 deletions(-) + +diff --git a/ldoc/doc.lua b/ldoc/doc.lua +index e19b2df..f368b90 100644 +--- a/ldoc/doc.lua ++++ b/ldoc/doc.lua +@@ -1073,9 +1073,9 @@ end + local function reference (s, mod_ref, item_ref) + local name = item_ref and item_ref.name or '' + -- this is deeply hacky; classes have 'Class ' prepended. +---~ if item_ref and doc.class_tag(item_ref.type) then +---~ name = 'Class_'..name +---~ end ++ if item_ref and doc.class_tag(item_ref.type) then ++ name = 'Class_'..name ++ end + return {mod = mod_ref, name = name, label=s} + end + +-- +1.9.1 +``` diff --git a/luadoc/config.ld b/luadoc/config.ld new file mode 100644 index 0000000..8567a89 --- /dev/null +++ b/luadoc/config.ld @@ -0,0 +1,14 @@ +-- Configuration file for Luadoc API generation +project="Vis Editor" +title="Vis Editor Lua API documentation" +format="markdown" +style="!fixed" +dir="." +sort=true +merge=true +no_space_before_args=true +file={ + "../vis-lua.c", + "../vis.lua", +} +
\ No newline at end of file @@ -1,5 +1,8 @@ /*** - * Lua API for [Vis Editor](https://github.com/martanne/vis). + * Lua Extension API for the [Vis Editor](https://github.com/martanne/vis). + * + * *WARNING:* there is no stability guarantee at this time, the API might + * change without notice! * * @module vis * @author Marc André Tanner @@ -499,7 +502,10 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) { * @tfield string VERSION * version information in `git describe` format, same as reported by `vis -v`. */ -// FIXME: resulting Lua documentation of these constants is suboptimal +/*** + * User interface. + * @tfield Ui ui the user interface being used + */ /*** * Normal mode. * @tfield int MODE_NORMAL @@ -526,14 +532,8 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) { */ /*** - * Current mode. - * @tfield int mode - */ - -/*** * LPeg lexer support module. * @field lexers - * @ref{TODO|LPeg lexer} support module. */ // TODO vis.events @@ -542,6 +542,11 @@ static const char *keymapping(Vis *vis, const char *keys, const Arg *arg) { * Create an iterator over all windows. * @function windows * @return the new iterator + * @see win + * @usage + * for win in vis:windows() do + * -- do something with win + * end */ static int windows_iter(lua_State *L); static int windows(lua_State *L) { @@ -571,6 +576,10 @@ static int windows_iter(lua_State *L) { * Create an iterator over all files. * @function files * @return the new iterator + * @usage + * for file in vis:files() do + * -- do something with file + * end */ static int files_iter(lua_State *L); static int files(lua_State *L) { @@ -597,10 +606,12 @@ static int files_iter(lua_State *L) { } /*** - * Execute an editor command. + * Execute a `:`-command. * @function command * @tparam string command the command to execute * @treturn bool whether the command succeeded + * @usage + * vis:command("set number") */ static int command(lua_State *L) { Vis *vis = obj_ref_check(L, 1, "vis"); @@ -656,7 +667,7 @@ static int message(lua_State *L) { * * Creates a new window and loads the given file. * - * @function message + * @function open * @tparam string filename the file name to load * @treturn File the file object representing the new file, or `nil` on failure */ @@ -747,6 +758,7 @@ static int map(lua_State *L) { * @function motion * @tparam int id the id of the motion to execute * @treturn bool whether the id was valid + * @local */ static int motion(lua_State *L) { Vis *vis = obj_ref_check(L, 1, "vis"); @@ -773,7 +785,8 @@ static size_t motion_lua(Vis *vis, Win *win, void *data, size_t pos) { * @function motion_register * @tparam function motion the Lua function implementing the motion * @treturn int the associated motion id, or `-1` on failure - * @see motion + * @see motion, motion_new + * @local * @usage * -- custom motion advancing to the next byte * local id = vis:motion_register(function(win, pos) @@ -798,6 +811,8 @@ err: * @function textobject * @tparam int id the id of the text object to execute * @treturn bool whether the id was valid + * @see textobject_register, textobject_new + * @local */ static int textobject(lua_State *L) { Vis *vis = obj_ref_check(L, 1, "vis"); @@ -822,7 +837,8 @@ static Filerange textobject_lua(Vis *vis, Win *win, void *data, size_t pos) { * @function textobject_register * @tparam function textobject the Lua function implementing the text object * @treturn int the associated text object id, or `-1` on failure - * @see textobject + * @see textobject, textobject_new + * @local * @usage * -- custom text object covering the next byte * local id = vis:textobject_register(function(win, pos) @@ -905,10 +921,17 @@ static int feedkeys(lua_State *L) { /*** * Currently active window. * @tfield Window win + * @see windows */ /*** * Currently active mode. * @tfield int mode + * @see MODE_NORMAL + * @see MODE_OPERATOR_PENDING + * @see MODE_INSERT + * @see MODE_REPLACE + * @see MODE_VISUAL + * @see MODE_VISUAL_LINE */ /*** * Whether a macro is being recorded. @@ -996,7 +1019,7 @@ static const struct luaL_Reg ui_funcs[] = { /*** * Viewport currently being displayed. - * @tfield range viewport + * @tfield Range viewport */ /*** * The window width. @@ -1139,6 +1162,17 @@ static int window_map(lua_State *L) { return keymap(L, win->vis, win); } +/*** + * Define a display style. + * @function style_define + * @tparam int id the style id to use + * @tparam string style the style definition + * @treturn bool whether the style definition has been successfully + * associated with the given id + * @see style + * @usage + * win:style_define(win.STYLE_DEFAULT, "fore:red") + */ static int window_style_define(lua_State *L) { Win *win = obj_ref_check(L, 1, "vis.window"); bool ret = false; @@ -1151,6 +1185,18 @@ static int window_style_define(lua_State *L) { return 1; } +/*** + * Style a window range. + * + * The style will be cleared after every window redraw. + * @function style + * @tparam int id the display style as registered with @{style_define} + * @tparam int start the absolute file position in bytes + * @tparam int len the length in bytes to style + * @see style_define + * @usage + * win:style(win.STYLE_DEFAULT, 0, 10) + */ static int window_style(lua_State *L) { Win *win = obj_ref_check(L, 1, "vis.window"); if (win) { @@ -1270,7 +1316,7 @@ static const struct luaL_Reg window_cursors_funcs[] = { */ /*** * The selection associated with this cursor. - * @tfield range selection the selection or `nil` if not in visual mode + * @tfield Range selection the selection or `nil` if not in visual mode */ static int window_cursor_index(lua_State *L) { Cursor *cur = obj_lightref_check(L, 1, "vis.window.cursor"); @@ -1372,7 +1418,16 @@ static const struct luaL_Reg window_cursor_funcs[] = { */ /*** * File content by logical lines. + * + * Assigning to array element `0` (`#lines+1`) will insert a new line at + * the beginning (end) of the file. * @tfield Array(string) lines the file content accessible as 1-based array + * @see content + * @usage + * local lines = vis.win.file.lines + * for i=1, #lines do + * lines[i] = i .. ": " .. lines[i] + * end */ /*** * Type of line endings. @@ -1496,8 +1551,15 @@ static int file_delete(lua_State *L) { /*** * Create an iterator over all lines of the file. + * + * For large files this is probably faster than @{lines}. * @function lines_iterator * @return the new iterator + * @see lines + * @usage + * for line in file:lines_iterator() do + * -- do something with line + * end */ static int file_lines_iterator_it(lua_State *L); static int file_lines_iterator(lua_State *L) { @@ -1535,6 +1597,10 @@ static int file_lines_iterator_it(lua_State *L) { * @tparam int pos the 0-based file position in bytes * @tparam int len the length in bytes to read * @treturn string the file content corresponding to the range + * @see lines + * @usage + * local file = vis.win.file + * local text = file:content(0, file.size) */ /*** * Get file content of range. @@ -1640,6 +1706,42 @@ static const struct luaL_Reg file_lines_funcs[] = { { NULL, NULL }, }; +/*** + * The user interface. + * + * @type Ui + */ +/*** + * Number of available colors. + * @tfield int colors + */ + +/*** + * A file range. + * + * For a valid range `start <= finish` holds. + * An invalid range is represented as `nil`. + * @type Range + */ +/*** + * The being of the range. + * @tfield int start + */ +/*** + * The end of the range. + * @tfield int finish + */ + +/*** + * Events. + * + * These events are invoked from the editor core. + * The following functions are looked up in the `vis.events` table. + * Keep in mind that the editor is blocked while the event handlers + * are being executed, avoid long running tasks. + * @section Events + */ + static void vis_lua_event_get(lua_State *L, const char *name) { lua_getglobal(L, "vis"); lua_getfield(L, -1, "events"); @@ -1871,16 +1973,33 @@ void vis_lua_init(Vis *vis) { } } +/*** + * Editor startup completed. + * This event is emitted immediately before the main loop starts. + * At this point all files are loaded and corresponding windows are created. + * We are about to process interactive keyboard input. + * Can be used to set *global* configuration options. + * @function start + */ void vis_lua_start(Vis *vis) { vis_lua_event_call(vis, "start"); } +/** + * Editor is about to terminate. + * @function quit + */ void vis_lua_quit(Vis *vis) { vis_lua_event_call(vis, "quit"); lua_close(vis->lua); vis->lua = NULL; } +/*** + * File open. + * @function file_open + * @tparam File file the file to be opened + */ void vis_lua_file_open(Vis *vis, File *file) { debug("event: file-open: %s %p %p\n", file->name ? file->name : "unnamed", (void*)file, (void*)file->text); lua_State *L = vis->lua; @@ -1892,6 +2011,14 @@ void vis_lua_file_open(Vis *vis, File *file) { lua_pop(L, 1); } +/*** + * File pre save. + * Triggered *before* the file is being written. + * @function file_save_pre + * @tparam File file the file being written + * @tparam string path the absolute path to which the file will be written, `nil` if standard output + * @treturn bool whether the write operation should be proceeded + */ bool vis_lua_file_save_pre(Vis *vis, File *file, const char *path) { lua_State *L = vis->lua; vis_lua_event_get(L, "file_save_pre"); @@ -1906,6 +2033,13 @@ bool vis_lua_file_save_pre(Vis *vis, File *file, const char *path) { return true; } +/*** + * File post save. + * Triggered *after* a successfull write operation. + * @function file_save_post + * @tparam File file the file which was written + * @tparam string path the absolute path to which it was written, `nil` if standard output + */ void vis_lua_file_save_post(Vis *vis, File *file, const char *path) { lua_State *L = vis->lua; vis_lua_event_get(L, "file_save_post"); @@ -1917,6 +2051,12 @@ void vis_lua_file_save_post(Vis *vis, File *file, const char *path) { lua_pop(L, 1); } +/*** + * File close. + * The last window displaying the file has been closed. + * @function file_close + * @tparam File file the file being closed + */ void vis_lua_file_close(Vis *vis, File *file) { debug("event: file-close: %s %p %p\n", file->name ? file->name : "unnamed", (void*)file, (void*)file->text); lua_State *L = vis->lua; @@ -1930,6 +2070,12 @@ void vis_lua_file_close(Vis *vis, File *file) { lua_pop(L, 1); } +/*** + * Window open. + * A new window has been created. + * @function win_open + * @tparam Window win the window being opened + */ void vis_lua_win_open(Vis *vis, Win *win) { debug("event: win-open: %s %p %p\n", win->file->name ? win->file->name : "unnamed", (void*)win, (void*)win->view); lua_State *L = vis->lua; @@ -1941,6 +2087,12 @@ void vis_lua_win_open(Vis *vis, Win *win) { lua_pop(L, 1); } +/*** + * Window close. + * An window is being closed. + * @function win_close + * @tparam Window win the window being closed + */ void vis_lua_win_close(Vis *vis, Win *win) { debug("event: win-close: %s %p %p\n", win->file->name ? win->file->name : "unnamed", (void*)win, (void*)win->view); lua_State *L = vis->lua; @@ -1954,6 +2106,14 @@ void vis_lua_win_close(Vis *vis, Win *win) { lua_pop(L, 1); } +/** + * Window highlight. + * The window has been redrawn and the syntax highlighting needs to be performed. + * @function win_highlight + * @tparam Window win the window being redrawn + * @tparam int horizon the maximal number of bytes the lexer should look behind to synchronize parsing state + * @see style + */ void vis_lua_win_highlight(Vis *vis, Win *win, size_t horizon) { lua_State *L = vis->lua; vis_lua_event_get(L, "win_highlight"); @@ -1965,6 +2125,13 @@ void vis_lua_win_highlight(Vis *vis, Win *win, size_t horizon) { lua_pop(L, 1); } +/*** + * Window syntax/filetype change. + * @function win_syntax + * @tparam Window win the affected window + * @tparam string syntax the lexer name or `nil` if syntax highlighting should be disabled for this window + * @treturn bool whether the syntax change was successful + */ bool vis_lua_win_syntax(Vis *vis, Win *win, const char *syntax) { lua_State *L = vis->lua; bool ret = false; @@ -1983,6 +2150,12 @@ bool vis_lua_win_syntax(Vis *vis, Win *win, const char *syntax) { return ret; } +/*** + * Window status bar redraw. + * @function win_status + * @tparam Window win the affected window + * @see status + */ void vis_lua_win_status(Vis *vis, Win *win) { lua_State *L = vis->lua; vis_lua_event_get(L, "win_status"); @@ -1995,6 +2168,11 @@ void vis_lua_win_status(Vis *vis, Win *win) { lua_pop(L, 1); } +/*** + * Theme change. + * @function theme_change + * @tparam string theme the name of the new theme to load + */ bool vis_theme_load(Vis *vis, const char *name) { lua_State *L = vis->lua; vis_lua_event_get(L, "theme_change"); @@ -2008,20 +2186,4 @@ bool vis_theme_load(Vis *vis, const char *name) { return true; } -/*** - * A file range. - * - * For a valid range `start <= finish` holds. - * An invalid range is represented as `nil`. - * @type Range - */ -/*** - * The being of the range. - * @tfield int start - */ -/*** - * The end of the range. - * @tfield int finish - */ - #endif @@ -1,4 +1,9 @@ +--- -- Vis Lua plugin API standard library +-- @module vis + +--- +-- @type Vis local ok, msg = pcall(function() vis.lexers = {} @@ -11,6 +16,20 @@ end vis.events = {} +--- Map a new motion. +-- +-- Sets up a mapping in normal, visual and operator pending mode. +-- The motion function will receive the @{Window} and an initial position +-- (in bytes from the start of the file) as argument and is expected to +-- return the resulting position. +-- @tparam string key the key to associate with the new mption +-- @tparam function motion the motion logic implemented as Lua function +-- @treturn bool whether the new motion could be installed +-- @usage +-- vis:motion_new("<C-l>", function(win, pos) +-- return pos+1 +-- end) +-- vis.motion_new = function(vis, key, motion) local id = vis:motion_register(motion) if id < 0 then @@ -25,6 +44,20 @@ vis.motion_new = function(vis, key, motion) return true end +--- Map a new text object. +-- +-- Sets up a mapping in visual and operator pending mode. +-- The text object function will receive the @{Window} and an initial +-- position(in bytes from the start of the file) as argument and is +-- expected to return the resulting range or `nil`. +-- @tparam string key the key associated with the new text object +-- @tparam function textobject the text object logic implemented as Lua function +-- @treturn bool whether the new text object could be installed +-- @usage +-- vis:textobject_new("<C-l>", function(win, pos) +-- return pos, pos+1 +-- end) +-- vis.textobject_new = function(vis, key, textobject) local id = vis:textobject_register(textobject) if id < 0 then |