Merge branch 'master' into Merged

This commit is contained in:
Adam 2021-08-01 14:58:36 -04:00 committed by GitHub
commit 47eaca18d8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
9 changed files with 767 additions and 7 deletions

View File

@ -300,6 +300,12 @@ end
function common.relative_path(ref_dir, dir) function common.relative_path(ref_dir, dir)
local drive_pattern = "^(%a):\\"
local drive, ref_drive = dir:match(drive_pattern), ref_dir:match(drive_pattern)
if drive and ref_drive and drive ~= ref_drive then
-- Windows, different drives, system.absolute_path fails for C:\..\D:\
return dir
end
local ref_ls = split_on_slash(ref_dir) local ref_ls = split_on_slash(ref_dir)
local dir_ls = split_on_slash(dir) local dir_ls = split_on_slash(dir)
local i = 1 local i = 1

View File

@ -112,7 +112,8 @@ end
function DocView:get_gutter_width() function DocView:get_gutter_width()
return self:get_font():get_width(#self.doc.lines) + style.padding.x * 2 local padding = style.padding.x * 2
return self:get_font():get_width(#self.doc.lines) + padding, padding
end end
@ -381,7 +382,7 @@ function DocView:draw_line_body(idx, x, y)
end end
function DocView:draw_line_gutter(idx, x, y) function DocView:draw_line_gutter(idx, x, y, width)
local color = style.line_number local color = style.line_number
for _, line1, _, line2 in self.doc:get_selections(true) do for _, line1, _, line2 in self.doc:get_selections(true) do
if idx >= line1 and idx <= line2 then if idx >= line1 and idx <= line2 then
@ -391,7 +392,7 @@ function DocView:draw_line_gutter(idx, x, y)
end end
local yoffset = self:get_line_text_y_offset() local yoffset = self:get_line_text_y_offset()
x = x + style.padding.x x = x + style.padding.x
renderer.draw_text(self:get_font(), idx, x, y + yoffset, color) common.draw_text(self:get_font(), color, idx, "right", x, y + yoffset, width, self:get_line_height())
end end
@ -420,12 +421,12 @@ function DocView:draw()
local lh = self:get_line_height() local lh = self:get_line_height()
local x, y = self:get_line_screen_position(minline) local x, y = self:get_line_screen_position(minline)
local gw, gpad = self:get_gutter_width()
for i = minline, maxline do for i = minline, maxline do
self:draw_line_gutter(i, self.position.x, y) self:draw_line_gutter(i, self.position.x, y, gpad and gw - gpad or gw)
y = y + lh y = y + lh
end end
local gw = self:get_gutter_width()
local pos = self.position local pos = self.position
x, y = self:get_line_screen_position(minline) x, y = self:get_line_screen_position(minline)
core.push_clip_rect(pos.x + gw, pos.y, self.size.x, self.size.y) core.push_clip_rect(pos.x + gw, pos.y, self.size.x, self.size.y)

View File

@ -646,8 +646,8 @@ local function check_plugin_version(filename)
if info ~= nil and info.type == "dir" then if info ~= nil and info.type == "dir" then
filename = filename .. "/init.lua" filename = filename .. "/init.lua"
info = system.get_file_info(filename) info = system.get_file_info(filename)
if not info then return true end
end end
if not info or not filename:match("%.lua$") then return false end
local f = io.open(filename, "r") local f = io.open(filename, "r")
if not f then return false end if not f then return false end
local version_match = false local version_match = false
@ -667,7 +667,7 @@ local function check_plugin_version(filename)
end end
end end
f:close() f:close()
return version_match return true, version_match
end end

28
docs/README.md Normal file
View File

@ -0,0 +1,28 @@
# Interface Files
This directory holds the documentation for the Lua C API that
is hidden in the C source files of Lite. The idea of these files
is to serve you as a quick reference about the functionality
that is not written in Lua it self. Please note that they
don't have any real code, just metadata or annotations.
Also, these interfaces are using
[EmmyLua annotation syntax](https://emmylua.github.io/annotation.html)
which is supported by LSP servers like the
[Sumneko Lua LSP](https://github.com/sumneko/lua-language-server).
This means that you can get nice code autocompletion and descriptions
of Lite core libraries and symbols when developing plugins or adding
any options to your **User Module File** (init.lua).
## The Base Core
Most of the code that is written in Lua for Lite is powered by the exposed
C API in the four namespaces that follow:
* [system](api/system.lua)
* [renderer](api/renderer.lua)
* [regex](api/regex.lua)
* [process](api/process.lua)
Finally, all global variables are documented in the file named
[globals.lua](api/globals.lua).

21
docs/api/globals.lua Normal file
View File

@ -0,0 +1,21 @@
---@meta
---The command line arguments given to lite.
---@type table<integer, string>
ARGS = {}
---The current operating system.
---@type string | "'Windows'" | "'Mac OS X'" | "'Linux'" | "'iOS'" | "'Android'"
PLATFORM = "Operating System"
---The current text or ui scale.
---@type number
SCALE = 1.0
---Full path of lite executable.
---@type string
EXEFILE = "/path/to/lite"
---Path to the users home directory.
---@type string
HOME = "/path/to/user/dir"

232
docs/api/process.lua Normal file
View File

@ -0,0 +1,232 @@
---@meta
---
---Functionality that allows you to launch subprocesses and read
---or write to them in a non-blocking fashion.
---@class process
process = {}
---Error triggered when the stdout, stderr or stdin fails while reading
---or writing, its value is platform dependent, so the value declared on this
---interface does not represents the real one.
---@type integer
process.ERROR_PIPE = -1
---Error triggered when a read or write action is blocking,
---its value is platform dependent, so the value declared on this
---interface does not represents the real one.
---@type integer
process.ERROR_WOULDBLOCK = -2
---Error triggered when a process takes more time than that specified
---by the deadline parameter given on process:start(),
---its value is platform dependent, so the value declared on this
---interface does not represents the real one.
---@type integer
process.ERROR_TIMEDOUT = -3
---Error triggered when trying to terminate or kill a non running process,
---its value is platform dependent, so the value declared on this
---interface does not represents the real one.
---@type integer
process.ERROR_INVAL = -4
---Error triggered when no memory is available to allocate the process,
---its value is platform dependent, so the value declared on this
---interface does not represents the real one.
---@type integer
process.ERROR_NOMEM = -5
---Used for the process:close_stream() method to close stdin.
---@type integer
process.STREAM_STDIN = 0
---Used for the process:close_stream() method to close stdout.
---@type integer
process.STREAM_STDOUT = 1
---Used for the process:close_stream() method to close stderr.
---@type integer
process.STREAM_STDERR = 2
---Instruct process:wait() to wait until the process ends.
---@type integer
process.WAIT_INFINITE = -1
---Instruct process:wait() to wait until the deadline given on process:start()
---@type integer
process.WAIT_DEADLINE = -2
---Used for the process.options stdin, stdout and stderr fields.
---@type integer
process.REDIRECT_DEFAULT = 0
---Used for the process.options stdin, stdout and stderr fields.
---@type integer
process.REDIRECT_PIPE = 1
---Used for the process.options stdin, stdout and stderr fields.
---@type integer
process.REDIRECT_PARENT = 2
---Used for the process.options stdin, stdout and stderr fields.
---@type integer
process.REDIRECT_DISCARD = 3
---Used for the process.options stdin, stdout and stderr fields.
---@type integer
process.REDIRECT_STDOUT = 4
---@alias process.errortype
---|>'process.ERROR_PIPE'
---| 'process.ERROR_WOULDBLOCK'
---| 'process.ERROR_TIMEDOUT'
---| 'process.ERROR_INVAL'
---| 'process.ERROR_NOMEM'
---@alias process.streamtype
---|>'process.STREAM_STDIN'
---| 'process.STREAM_STDOUT'
---| 'process.STREAM_STDERR'
---@alias process.waittype
---|>'process.WAIT_INFINITE'
---| 'process.WAIT_DEADLINE'
---@alias process.redirecttype
---|>'process.REDIRECT_DEFAULT'
---| 'process.REDIRECT_PIPE'
---| 'process.REDIRECT_PARENT'
---| 'process.REDIRECT_DISCARD'
---| 'process.REDIRECT_STDOUT'
---
--- Options that can be passed to process.start()
---@class process.options
---@field public timeout number
---@field public cwd string
---@field public stdin process.redirecttype
---@field public stdout process.redirecttype
---@field public stderr process.redirecttype
---@field public env table<string, string>
process.options = {}
---
---Create and start a new process
---
---@param command_and_params table First index is the command to execute
---and subsequente elements are parameters for the command.
---@param options process.options
---
---@return process | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:start(command_and_params, options) end
---
---Translates an error code into a useful text message
---
---@param code integer
---
---@return string | nil
function process.strerror(code) end
---
---Get the process id.
---
---@return integer id Process id or 0 if not running.
function process:pid() end
---
---Read from the given stream type, if the process fails with a ERROR_PIPE it is
---automatically destroyed returning nil along error message and code.
---
---@param stream process.streamtype
---@param len? integer Amount of bytes to read, defaults to 2048.
---
---@return string | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:read(stream, len) end
---
---Read from stdout, if the process fails with a ERROR_PIPE it is
---automatically destroyed returning nil along error message and code.
---
---@param len? integer Amount of bytes to read, defaults to 2048.
---
---@return string | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:read_stdout(len) end
---
---Read from stderr, if the process fails with a ERROR_PIPE it is
---automatically destroyed returning nil along error message and code.
---
---@param len? integer Amount of bytes to read, defaults to 2048.
---
---@return string | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:read_stderr(len) end
---
---Write to the stdin, if the process fails with a ERROR_PIPE it is
---automatically destroyed returning nil along error message and code.
---
---@param data string
---
---@return integer | nil bytes The amount of bytes written or nil if error
---@return string errmsg
---@return process.errortype | integer errcode
function process:write(data) end
---
---Allows you to close a stream pipe that you will not be using.
---
---@param stream process.streamtype
---
---@return integer | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:close_stream(stream) end
---
---Wait the specified amount of time for the process to exit.
---
---@param timeout integer | process.waittype Time to wait in milliseconds,
---if 0, the function will only check if process is running without waiting.
---
---@return integer | nil exit_status The process exit status or nil on error
---@return string errmsg
---@return process.errortype | integer errcode
function process:wait(timeout) end
---
---Sends SIGTERM to the process
---
---@return boolean | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:terminate() end
---
---Sends SIGKILL to the process
---
---@return boolean | nil
---@return string errmsg
---@return process.errortype | integer errcode
function process:kill() end
---
---Get the exit code of the process or nil if still running.
---
---@return number | nil
function process:returncode() end
---
---Check if the process is running
---
---@return boolean
function process:running() end

57
docs/api/regex.lua Normal file
View File

@ -0,0 +1,57 @@
---@meta
---
---Provides the base functionality for regular expressions matching.
---@class regex
regex = {}
---Instruct regex:cmatch() to match only at the first position.
---@type integer
regex.ANCHORED = 0x80000000
---Tell regex:cmatch() that the pattern can match only at end of subject.
---@type integer
regex.ENDANCHORED = 0x20000000
---Tell regex:cmatch() that subject string is not the beginning of a line.
---@type integer
regex.NOTBOL = 0x00000001
---Tell regex:cmatch() that subject string is not the end of a line.
---@type integer
regex.NOTEOL = 0x00000002
---Tell regex:cmatch() that an empty string is not a valid match.
---@type integer
regex.NOTEMPTY = 0x00000004
---Tell regex:cmatch() that an empty string at the start of the
---subject is not a valid match.
---@type integer
regex.NOTEMPTY_ATSTART = 0x00000008
---@alias regex.modifiers
---|>'"i"' # Case insesitive matching
---| '"m"' # Multiline matching
---| '"s"' # Match all characters with dot (.) metacharacter even new lines
---
---Compiles a regular expression pattern that can be used to search in strings.
---
---@param pattern string
---@param options? regex.modifiers A string of one or more pattern modifiers.
---
---@return regex|string regex Ready to use regular expression object or error
---message if compiling the pattern failed.
function regex.compile(pattern, options) end
---
---Search a string for valid matches and returns a list of matching offsets.
---
---@param subject string The string to search for valid matches.
---@param offset? integer The position on the subject to start searching.
---@param options? integer A bit field of matching options, eg:
---regex.NOTBOL | regex.NOTEMPTY
---
---@return table<integer, integer> list List of offsets where a match was found.
function regex:cmatch(subject, offset, options) end

181
docs/api/renderer.lua Normal file
View File

@ -0,0 +1,181 @@
---@meta
---
---Core functionality to render or draw elements into the screen.
---@class renderer
renderer = {}
---
---Represents a color used by the rendering functions.
---@class renderer.color
---@field public r number Red
---@field public g number Green
---@field public b number Blue
---@field public a number Alpha
renderer.color = {}
---
---Represent options that affect a font's rendering.
---@class renderer.fontoptions
---@field public antialiasing "'grayscale'" | "'subpixel'"
---@field public hinting "'slight'" | "'none'" | '"full"'
renderer.fontoptions = {}
---
---@class renderer.font
renderer.font = {}
---
---Create a new font object.
---
---@param path string
---@param size number
---@param options renderer.fontoptions
---
---@return renderer.font
function renderer.font.load(path, size, options) end
---
---Clones a font object into a new one.
---
---@param size? number Optional new size for cloned font.
---
---@return renderer.font
function renderer.font:copy(size) end
---
---Set the amount of characters that represent a tab.
---
---@param chars integer Also known as tab width.
function renderer.font:set_tab_size(chars) end
---
---Get the width in pixels of the given text when
---rendered with this font.
---
---@param text string
---
---@return number
function renderer.font:get_width(text) end
---
---Get the width in subpixels of the given text when
---rendered with this font.
---
---@param text string
---
---@return number
function renderer.font:get_width_subpixel(text) end
---
---Get the height in pixels that occupies a single character
---when rendered with this font.
---
---@return number
function renderer.font:get_height() end
---
---Gets the font subpixel scale.
---
---@return number
function renderer.font:subpixel_scale() end
---
---Get the current size of the font.
---
---@return number
function renderer.font:get_size() end
---
---Set a new size for the font.
---
---@param size number
function renderer.font:set_size(size) end
---
---Assistive functionality to replace characters in a
---rendered text with other characters.
---@class renderer.replacements
renderer.replacements = {}
---
---Create a new character replacements object.
---
---@return renderer.replacements
function renderer.replacements.new() end
---
---Add to internal map a character to character replacement.
---
---@param original_char string Should be a single character like '\t'
---@param replacement_char string Should be a single character like '»'
function renderer.replacements:add(original_char, replacement_char) end
---
---Toggles drawing debugging rectangles on the currently rendered sections
---of the window to help troubleshoot the renderer.
---
---@param enable boolean
function renderer.show_debug(enable) end
---
---Get the size of the screen area been rendered.
---
---@return number width
---@return number height
function renderer.get_size() end
---
---Tell the rendering system that we want to build a new frame to render.
function renderer.begin_frame() end
---
---Tell the rendering system that we finished building the frame.
function renderer.end_frame() end
---
---Set the region of the screen where draw operations will take effect.
---
---@param x number
---@param y number
---@param width number
---@param height number
function renderer.set_clip_rect(x, y, width, height) end
---
---Draw a rectangle.
---
---@param x number
---@param y number
---@param width number
---@param height number
---@param color renderer.color
function renderer.draw_rect(x, y, width, height, color) end
---
---Draw text.
---
---@param font renderer.font
---@param text string
---@param x number
---@param y number
---@param color renderer.color
---@param replace renderer.replacements
---@param color_replace renderer.color
---
---@return number x_subpixel
function renderer.draw_text(font, text, x, y, color, replace, color_replace) end
---
---Draw text at subpixel level.
---
---@param font renderer.font
---@param text string
---@param x number
---@param y number
---@param color renderer.color
---@param replace renderer.replacements
---@param color_replace renderer.color
---
---@return number x_subpixel
function renderer.draw_text_subpixel(font, text, x, y, color, replace, color_replace) end

234
docs/api/system.lua Normal file
View File

@ -0,0 +1,234 @@
---@meta
---
---Utilites for managing current window, files and more.
---@class system
system = {}
---@alias system.fileinfotype
---|>'"file"' # It is a file.
---| '"dir"' # It is a directory.
---
---@class system.fileinfo
---@field public modified number A timestamp in seconds.
---@field public size number Size in bytes.
---@field public type system.fileinfotype Type of file
system.fileinfo = {}
---
---Core function used to retrieve the current event been triggered by SDL.
---
---The following is a list of event types emitted by this function and
---the arguments for each of them if applicable.
---
---Window events:
--- * "quit"
--- * "resized" -> width, height
--- * "exposed"
--- * "minimized"
--- * "maximized"
--- * "restored"
--- * "focuslost"
---
---File events:
--- * "filedropped" -> filename, x, y
---
---Keyboard events:
--- * "keypressed" -> key_name
--- * "keyreleased" -> key_name
--- * "textinput" -> text
---
---Mouse events:
--- * "mousepressed" -> button_name, x, y, amount_of_clicks
--- * "mousereleased" -> button_name, x, y
--- * "mousemoved" -> x, y, relative_x, relative_y
--- * "mousewheel" -> y
---
---@return string type
---@return any? arg1
---@return any? arg2
---@return any? arg3
---@return any? arg4
function system.poll_event() end
---
---Wait until an event is triggered.
---
---@param timeout number Amount of seconds, also supports fractions
---of a second, eg: 0.01
---
---@return boolean status True on success or false if there was an error.
function system.wait_event(timeout) end
---
---Change the cursor type displayed on screen.
---
---@param type string | "'arrow'" | "'ibeam'" | "'sizeh'" | "'sizev'" | "'hand'"
function system.set_cursor(type) end
---
---Change the window title.
---
---@param title string
function system.set_window_title(title) end
---@alias system.windowmode
---|>'"normal"'
---| '"minimized"'
---| '"maximized"'
---| '"fullscreen"'
---
---Change the window mode.
---
---@param mode system.windowmode
function system.set_window_mode(mode) end
---
---Retrieve the current window mode.
---
---@return system.windowmode mode
function system.get_window_mode() end
---
---Toggle between bordered and borderless.
---
---@param bordered boolean
function system.set_window_bordered(bordered) end
---
---When then window is run borderless (without system decorations), this
---function allows to set the size of the different regions that allow
---for custom window management.
---
---@param title_height number
---@param controls_width number This is for minimize, maximize, close, etc...
---@param resize_border number The amount of pixels reserved for resizing
function system.set_window_hit_test(title_height, controls_width, resize_border) end
---
---Get the size and coordinates of the window.
---
---@return number width
---@return number height
---@return number x
---@return number y
function system.get_window_size() end
---
---Sets the size and coordinates of the window.
---
---@param width number
---@param height number
---@param x number
---@param y number
function system.set_window_size(width, height, x, y) end
---
---Check if the window currently has focus.
---
---@return boolean
function system.window_has_focus() end
---
---Opens a message box to display an error message.
---
---@param title string
---@param message string
function system.show_fatal_error(title, message) end
---
---Change the current directory path which affects relative file operations.
---This function raises an error if the path doesn't exists.
---
---@param path string
function system.chdir(path) end
---
---Create a new directory, note that this function doesn't recursively
---creates the directories on the given path.
---
---@param directory_path string
---
---@return boolean created True on success or false on failure.
function system.mkdir(directory_path) end
---
---Gets a list of files and directories for a given path.
---
---@param path string
---
---@return table|nil list List of directories or nil if empty or error.
---@return string? message Error message in case of error.
function system.list_dir(path) end
---
---Converts a relative path from current directory to the absolute one.
---
---@param path string
---
---@return string
function system.absolute_path(path) end
---
---Get details about a given file or path.
---
---@param path string Can be a file or a directory path
---
---@return system.fileinfo|nil info Path details or nil if empty or error.
---@return string? message Error message in case of error.
function system.get_file_info(path) end
---
---Retrieve the text currently stored on the clipboard.
---
---@return string
function system.get_clipboard() end
---
---Set the content of the clipboard.
---
---@param text string
function system.set_clipboard(text) end
---
---Get amount of iterations since the application was launched
---also known as SDL_GetPerformanceCounter() / SDL_GetPerformanceFrequency()
---
---@return number
function system.get_time() end
---
---Sleep for the given amount of seconds.
---
---@param seconds number Also supports fractions of a second, eg: 0.01
function system.sleep(seconds) end
---
---Similar to os.execute() but does not return the exit status of the
---executed command and executes the process in a non blocking way by
---forking it to the background.
---
---@param command string The command to execute.
function system.exec(command) end
---
---Generates a matching score depending on how well the value of the
---given needle compares to that of the value in the haystack.
---
---@param haystack string
---@param needle string
---@param file boolean Reverse the algorithm to prioritize the end
---of the haystack, eg: with a haystack "/my/path/to/file" and a needle
---"file", will get better score than with this option not set to true.
---
---@return integer score
function system.fuzzy_match(haystack, needle, file) end
---
---Change the opacity (also known as transparency) of the window.
---
---@param opacity number A value from 0.0 to 1.0, the lower the value
---the less visible the window will be.
function system.set_window_opacity(opacity) end