walkero
/
lite-xl
1
0
Fork 0
Code Issues 7 Pull Requests Projects Releases 13 Wiki Activity

Documented with EmmyLua the C API using .lua interface files.

This commit is contained in:
jgmdev 2021-06-25 02:25:05 -04:00
parent 88704c6ecb
commit bd50401687
5 changed files with 652 additions and 0 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

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"

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

@ -0,0 +1,163 @@
---@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_INVALID = -4
---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
---
---Create a new process object
---
---@return process
function process.new() end
---
---Translates an error code into a useful text message
---
---@param code integer
---
---@return string
function process.strerror(code) end
---
---Start a process
---
---@param command_and_params table First index is the command to execute
---and subsequente elements are parameters for the command.
---@param working_directory? string Path where the command will be launched.
---@param deadline? integer Maximum time in milliseconds the
---process is allowed to run on a process:wait(process.WAIT_DEADLINE) call.
---
---@return integer|boolean status Negative integer error code if could
---not start or true on success
function process:start(command_and_params, working_directory, deadline) end
---
---Get the process id.
---
---@return integer id Process id or 0 if not running.
function process:pid() end
---
---Read from stdout, if the process fails with a ERROR_PIPE it is
---automatically destroyed, so checking process status with the
---process:running() method would be advised.
---
---@param len? integer Amount of bytes to read.
---@param tries? integer Retry reading the given amount of times
---if nothing was read.
---
---@return integer|nil bytes Amount of bytes read or nil if nothing was read.
function process:read(len, tries) end
---
---Read from stderr, if the process fails with a ERROR_PIPE it is
---automatically destroyed, so checking process status with the
---process:running() method would be advised.
---
---@param len? integer Amount of bytes to read.
---@param tries? integer Retry reading the given amount of times
---if nothing was read.
---
---@return integer|nil bytes Amount of bytes read or nil if nothing was read.
function process:read_errors(len, tries) end
---
---Write to the stdin, if the process fails with a ERROR_PIPE it is
---automatically destroyed, so checking process status with the
---process:running() method would be advised.
---
---@param data string
---
---@return integer bytes The amount of bytes written or negative integer
---error code: process.ERROR_PIPE, process.ERROR_WOULDBLOCK
function process:write(data) end
---
---Allows you to close a stream pipe that you will not be using.
---
---@param stream integer Could be one of the following:
---process.STREAM_STDIN, process.STREAM_STDOUT, process.STREAM_STDERR
---
---@return integer status Negative error code process.ERROR_INVALID if
---process is not running or stream is already closed.
function process:close_stream(stream) end
---
---Wait the specified amount of time for the process to exit.
---
---@param timeout integer Time to wait in milliseconds, if 0, the function
---will only check if process is running without waiting, also the timeout
---can be set to:
--- * process.WAIT_INFINITE - will wait until the process ends
--- * process.WAIT_DEADLINE - will wait until the deadline declared on start()
---
---@return integer exit_status The process exit status or negative integer
---error code like process.ERROR_TIMEDOUT
function process:wait(timeout) end
---
---Sends SIGTERM to the process
---
---@return boolean|integer status Returns true on success or a
---negative integer error code like process.ERROR_INVALID
function process:terminate() end
---
---Sends SIGKILL to the process
---
---@return boolean|integer status Returns true on success or a
---negative integer error code like process.ERROR_INVALID
function process:kill() 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 RegexModifiers
---|>'"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? RegexModifiers 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

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

@ -0,0 +1,177 @@
---@meta
---
---Core functionality to render or draw elements into the screen.
---@class renderer
renderer = {}
---
---Represents a color used by the rendering functions.
---@class RendererColor
---@field public r number Red
---@field public g number Green
---@field public b number Blue
---@field public a number Alpha
RendererColor = {}
---
---Represent options that affect a font's rendering.
---@class RendererFontOptions
---@field public antialiasing "'grayscale'" | "'subpixel'"
---@field public hinting "'slight'" | "'none'" | '"full"'
RendererFontOptions = {}
---
---@class renderer.font
renderer.font = {}
---
---Create a new font object.
---
---@param path string
---@param size number
---@param options RendererFontOptions
---
---@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 RendererColor
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 RendererColor
---@param replace renderer.replacements
---@param color_replace RendererColor
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 RendererColor
---@param replace renderer.replacements
---@param color_replace RendererColor
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 FileInfoType
---|>'"file"' # It is a file.
---| '"dir"' # It is a directory.
---
---@class FileInfo
---@field public modified number A timestamp in seconds.
---@field public size number Size in bytes.
---@field public type FileInfoType Type of file
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 SystemWindowMode
---|>'"normal"'
---| '"minimized"'
---| '"maximized"'
---| '"fullscreen"'
---
---Change the window mode.
---
---@param mode SystemWindowMode
function system.set_window_mode(mode) end
---
---Retrieve the current window mode.
---
---@return SystemWindowMode 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 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