Skip to main content

core.common

Utility functions.

local common = require "core.common"

common.serializeoptions

escape

(field) escape: boolean?

Uses normal escape characters ("\n") instead of decimal escape sequences ("\10").


indent_str

(field) indent_str: string?

The indentation character to use. Defaults to " ".


initial_indent

(field) initial_indent: number?

The initial indentation level. Defaults to 0.


limit

(field) limit: number?

Limits the depth when serializing nested tables. Defaults to math.huge.


pretty

(field) pretty: boolean?

Enables pretty printing.


sort

(field) sort: boolean?

Sorts the output if it is a sortable table.


basename

function core.common.basename(path: string)
-> string

Returns the last portion of a path.


bench

function core.common.bench(name: string, fn: fun(...any):any, ...any)
-> any

Prints the execution time of a function.

The execution time and percentage of frame time for the function is printed to standard output. The frame rate is always assumed to be 60 FPS, thus a value of 100% would mean that the benchmark took 1/60 of a second to execute.

@return — The result returned by the function


blend_colors

function core.common.blend_colors(dst: renderer.color, src: renderer.color)
-> blended_color: renderer.color

Combine two colors to create a new color based on their transparency.


clamp

function core.common.clamp(n: number, lo: number, hi: number)
-> number

Clamps the number n between lo and hi.


color

function core.common.color(str: string)
-> r: number
2. g: number
3. b: number
4. a: number

Parses a CSS color string.

Only these formats are supported:

  • rgb(r, g, b)
  • rgba(r, g, b, a)
  • #rrggbbaa
  • #rrggbb

darken_color

function core.common.darken_color(rgba: renderer.color, percent: integer)
-> renderer.color

Makes a color darker by the given percentage.


dir_list_suggest

function core.common.dir_list_suggest(text: string, dir_list: string[])
-> string[]

Filters a list of paths to find those that are related to the input path.

@param text — The input path.

@param dir_list — A list of paths to filter.


dir_path_suggest

function core.common.dir_path_suggest(text: string, root: string)
-> string[]

Returns a list of directories that are related to a path.

@param text — The input path.

@param root — The path to relate to.


dirname

function core.common.dirname(path: string)
-> string|nil

Returns the directory name of a path. If the path doesn't have a directory, this function may return nil.


distance

function core.common.distance(x1: number, y1: number, x2: number, y2: number)
-> number

Returns the euclidean distance between two points.


draw_text

function core.common.draw_text(font: renderer.font, color: renderer.color, text: string, align: string|"center"|"left"|"right", x: number, y: number, w: number, h: number)
-> x_advance: number
2. y_advance: number
3. x: number
4. y: number

Draws text onto the window. The function returns the X and Y coordinates of the bottom-right corner of the text.

align:
| "left" -- Align text to the left of the bounding box
| "right" -- Align text to the right of the bounding box
| "center" -- Center text in the bounding box

find_index

function core.common.find_index(tbl: table, prop: any)
-> number|nil

Returns the first index where a subtable in tbl has prop set. If none is found, nil is returned.


fuzzy_match

function core.common.fuzzy_match(haystack: string, needle: string, files: boolean)
-> number

Performs fuzzy matching.

If the haystack is a string, a score ranging from 0 to 1 is returned. If the haystack is a table, a table containing the haystack sorted in ascending order of similarity is returned.

@param files — If true, the matching process will be performed in reverse to better match paths.


fuzzy_match_with_recents

function core.common.fuzzy_match_with_recents(haystack: string[], recents: string[], needle: string)
-> string[]

Performs fuzzy matching and returns recently used strings if needed.

If the needle is empty, then a list of recently used strings are added to the result, followed by strings from the haystack.


home_encode

function core.common.home_encode(text: string)
-> string

Returns a path where the user's home directory is replaced by "~".


home_encode_list

function core.common.home_encode_list(paths: string[])
-> string[]

Returns a list of paths where the user's home directory is replaced by "~".

@param paths — A list of paths to encode


home_expand

function core.common.home_expand(text: string)
-> string

Expands the "~" prefix in a path into the user's home directory. This function is not guaranteed to return an absolute path.


hsv_to_rgb

function core.common.hsv_to_rgb(h: number, s: number, v: number, a: number)
-> rgba: renderer.color

Converts an HSV color value to RGB. Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space. Assumes h, s, and v are contained in the set [0, 1] and returns r, g, and b in the set [0, 255].

@param h — The hue

@param s — The saturation

@param v — The brightness

@param a — The alpha

@return rgba — The RGB representation


is_absolute_path

function core.common.is_absolute_path(path: string)
-> boolean

Checks whether a path is absolute or relative.


is_utf8_cont

function core.common.is_utf8_cont(s: string, offset?: integer)
-> boolean

Checks if the byte at offset is a UTF-8 continuation byte.

UTF-8 encodes code points in 1 to 4 bytes. For a multi-byte sequence, each byte following the start byte is a continuation byte.

@param offset — The offset of the string to start searching. Defaults to 1.


lerp

function core.common.lerp(a: number, b: number, t: number)
-> number

Returns a value between a and b on a linear scale, based on the interpolation point t.

If a and b are tables, a table containing the result for all the elements in a and b is returned.


lighten_color

function core.common.lighten_color(rgba: renderer.color, percent: integer)
-> renderer.color

Makes a color brighter by the given percentage.


match_ignore_rule

function core.common.match_ignore_rule(path: string, info: system.fileinfo, ignore_rules: core.ignore_file_rule[])
-> boolean

Checks if a path matches one of the given ignore rules.


match_pattern

function core.common.match_pattern(text: string, pattern: string|string[], ...any)
-> start_index: boolean|number
2. end_index: number|nil

Matches a string against a list of patterns.

If a match was found, its start and end index is returned. Otherwise, false is returned.

@param ... — Other options for string.find().


merge

function core.common.merge(a: table|nil, b?: table)
-> table

Returns a new table containing the contents of b merged into a.


mkdirp

function core.common.mkdirp(path: string)
-> success: boolean
2. error: string|nil
3. path: string|nil

Creates a directory recursively if necessary.

@return success

@return error

@return path — The path where an error occured.


normalize_path

function core.common.normalize_path(filename: string|nil)
-> string|nil

Normalizes a path into the same format across platforms.

On Windows, all drive letters are converted to uppercase. UNC paths with drive letters are converted back to ordinary Windows paths. All path separators ("/", "\\") are converted to platform-specific ones.


normalize_volume

function core.common.normalize_volume(filename: string|nil)
-> string|nil

Normalizes the drive letter in a Windows path to uppercase. This function expects an absolute path, e.g. a path from system.absolute_path.

This function is needed because the path returned by system.absolute_path may contain drive letters in upper or lowercase.

@param filename — The input path.


path_belongs_to

function core.common.path_belongs_to(filename: string, path: string)
-> boolean

Checks whether a path belongs to a parent directory.

@param filename — The path to check.

@param path — The parent path.


path_suggest

function core.common.path_suggest(text: string, root?: string)
-> string[]

Returns a list of paths that are relative to the input path.

If a root directory is specified, the function returns paths that are relative to the root directory.

@param text — The input path.

@param root — The root directory.


relative_path

function core.common.relative_path(ref_dir: string, dir: string)
-> string

Makes a path relative to the given reference directory when possible.

@param ref_dir — The path to check against.

@param dir — The input path.


rgb_to_hsv

function core.common.rgb_to_hsv(rgba: renderer.color)
-> hsva: table

Converts an RGB color value to HSV. Conversion formula adapted from http://en.wikipedia.org/wiki/HSV_color_space. Assumes r, g, and b are contained in the set [0, 255] and returns h, s, and v in the set [0, 1].

@return hsva — The HSV representation


rm

function core.common.rm(path: string, recursively: boolean)
-> success: boolean
2. error: string|nil
3. path: string|nil

Removes a path.

@param recursively — If true, the function will attempt to remove everything in the specified path.

@return success

@return error

@return path — The path where the error occured.


round

function core.common.round(n: number)
-> number

Returns the value of a number rounded to the nearest integer.


serialize

function core.common.serialize(val: any, opts?: common.serializeoptions)
-> string

Serializes a value into a Lua string that is loadable with load().

Only these basic types are supported:

  • nil
  • boolean
  • number (except very large numbers and special constants, e.g. math.huge, inf and nan)
  • integer
  • string
  • table

splice

function core.common.splice(t: any[], at: number, remove: number, insert?: any[])

Splices a numerically indexed table. This function mutates the original table.

@param at — Index at which to start splicing.

@param remove — Number of elements to remove.

@param insert — A table containing elements to insert after splicing.


utf8_chars

function core.common.utf8_chars(text: string)
-> fun():string

Returns an iterator that yields a UTF-8 character on each iteration.