From bd50401687c924ecacb979e419c447c5316bfeda Mon Sep 17 00:00:00 2001 From: jgmdev Date: Fri, 25 Jun 2021 02:25:05 -0400 Subject: [PATCH] Documented with EmmyLua the C API using .lua interface files. --- docs/api/globals.lua | 21 ++++ docs/api/process.lua | 163 +++++++++++++++++++++++++++++ docs/api/regex.lua | 57 ++++++++++ docs/api/renderer.lua | 177 ++++++++++++++++++++++++++++++++ docs/api/system.lua | 234 ++++++++++++++++++++++++++++++++++++++++++ 5 files changed, 652 insertions(+) create mode 100644 docs/api/globals.lua create mode 100644 docs/api/process.lua create mode 100644 docs/api/regex.lua create mode 100644 docs/api/renderer.lua create mode 100644 docs/api/system.lua diff --git a/docs/api/globals.lua b/docs/api/globals.lua new file mode 100644 index 00000000..98fe61b1 --- /dev/null +++ b/docs/api/globals.lua @@ -0,0 +1,21 @@ +---@meta + +---The command line arguments given to lite. +---@type table +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" diff --git a/docs/api/process.lua b/docs/api/process.lua new file mode 100644 index 00000000..0374c0c6 --- /dev/null +++ b/docs/api/process.lua @@ -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 diff --git a/docs/api/regex.lua b/docs/api/regex.lua new file mode 100644 index 00000000..d1d7346c --- /dev/null +++ b/docs/api/regex.lua @@ -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 list List of offsets where a match was found. +function regex:cmatch(subject, offset, options) end diff --git a/docs/api/renderer.lua b/docs/api/renderer.lua new file mode 100644 index 00000000..3a1c6036 --- /dev/null +++ b/docs/api/renderer.lua @@ -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 diff --git a/docs/api/system.lua b/docs/api/system.lua new file mode 100644 index 00000000..df0e711b --- /dev/null +++ b/docs/api/system.lua @@ -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