Module expcore.common
Adds some commonly used functions used in many modules
[[
Info:
- Author: cooldude2606
Functions
Common.type_check (value[, test_type=nil]) | Compare types faster for faster validation of params |
Common.type_check_error (value, test_type, error_message, level) | Raises an error if the value is of the wrong type |
Common.param_check (value, test_type, param_name, param_number) | Raises an error when the value is the incorrect type, uses a consistent error message format |
Common.player_return (value[, colour=defines.colour.white[, player=game.player]]) | Will return a value of any type to the player/server console, allows colour for in-game players |
Common.write_json (path, tbl) | Writes a table object to a file in json format |
Common.opt_require (path) | Calls a require that will not error if the file is not found |
Common.ext_require (path, ...) | Calls a require and returns only the keys given, file must return a table |
Common.format_time (ticks, options) | Formats tick into a clean format, denominations from highest to lowest long will use words rather than letters time will use : separates string will return a string not a locale string when a denomination is false it will overflow into the next one |
Common.move_items (items[, surface=navies[, position={0[, radius=32[, chest_type=iron-chest]]]]) | Moves items to the position and stores them in the closest entity of the type given |
Common.print_grid_value (value, surface, position, scale, offset, immutable) | https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4a2/map_gen/maps/diggy/debug.lua#L31 Prints a colored value on a location. |
Common.print_colored_grid_value (value, surface, position, offset, immutable, color_value, base_color, delta_color, under_bound, over_bound) | Prints a colored value on a location. |
Common.clear_flying_text (surface) | Clears all flying text entites on a surface |
Common.string_contains (s, contains) | Tests if a string contains a given substring. |
Common.extract_keys (tbl, ...) | Extracts certain keys from a table |
Common.enum (tbl) | Converts a table to an enum |
Common.auto_complete (options, input[, use_key=false[, rtn_key=false]]) | Returns the closest match to the input |
Common.table_keys (tbl) | Returns all the keys of a table |
Common.table_values (tbl) | Returns all the values of a table |
Common.table_alphanumsort (tbl) | Returns the list is a sorted way that would be expected by people (this is by key) |
Common.table_keysort (tbl) | Returns the list is a sorted way that would be expected by people (this is by key) (faster alterative than above) |
Common.format_chat_colour (message, color) | Returns a message with valid chat tags to change its colour |
Common.format_chat_colour_localized (message, color) | Returns a message with valid chat tags to change its colour, using localization |
Common.format_chat_player_name (player[, raw_string=false]) | Returns the players name in the players color |
Functions
- Common.type_check (value[, test_type=nil])
-
Compare types faster for faster validation of params
Parameters:
- value any the value to be tested
- test_type string the type to test for if not given then it tests for nil (default nil)
Returns:
-
boolean
is v of type test_type
Usage:
type_check('foo','string') -- return true
type_check('foo') -- return false
- Common.type_check_error (value, test_type, error_message, level)
-
Raises an error if the value is of the wrong type
Parameters:
- value any the value that you want to test the type of
- test_type string the type that the value should be
- error_message string the error message that is returned
- level number the level to call the error on (level = 1 means the caller)
Returns:
-
boolean
true if no error was called
Usage:
type_check_error('foo','number','Value must be a number') -- will raise error "Value must be a number"
- Common.param_check (value, test_type, param_name, param_number)
-
Raises an error when the value is the incorrect type, uses a consistent error message format
Parameters:
- value any the value that you want to test the type of
- test_type string the type that the value should be
- param_name string the name of the param
- param_number number the number param it is
Returns:
-
boolean
true if no error was raised
Usage:
param_check('foo','number','repeat_count',2) -- will raise error "Invalid param #02 given to <anon>; repeat_count is not of type number"
- Common.player_return (value[, colour=defines.colour.white[, player=game.player]])
-
Will return a value of any type to the player/server console, allows colour for in-game players
Parameters:
- value any value of any type that will be returned to the player or console
- colour defines.color or string the colour of the text for the player, ignored when printing to console (default defines.colour.white)
- player LuaPlayer the player that return will go to, if no game.player then returns to server (default game.player)
Usage:
player_return('Hello, World!') -- returns 'Hello, World!' to game.player or server console
player_return('Hello, World!','green') -- returns 'Hello, World!' to game.player with colour green or server console
player_return('Hello, World!',nil,player) -- returns 'Hello, World!' to the given player
- Common.write_json (path, tbl)
-
Writes a table object to a file in json format
Parameters:
- Common.opt_require (path)
-
Calls a require that will not error if the file is not found
Parameters:
- path string the path that you want to require
Returns:
-
the returns from that file or nil, error if not loaded
Usage:
local file = opt_require('file.not.present') -- will not cause any error
- Common.ext_require (path, ...)
-
Calls a require and returns only the keys given, file must return a table
Parameters:
- path string the path that you want to require
- ... string the name of the keys that you want returned
Returns:
-
the keys in the order given
Usage:
local extract, param_check = ext_require('expcore.common','extract','param_check')
- Common.format_time (ticks, options)
-
Formats tick into a clean format, denominations from highest to lowest
long will use words rather than letters
time will use : separates
string will return a string not a locale string
when a denomination is false it will overflow into the next one
Parameters:
- ticks number the number of ticks that represents a time
- options table table a of options to use for the format
Returns:
-
string
a locale string that can be used
- Common.move_items (items[, surface=navies[, position={0[, radius=32[, chest_type=iron-chest]]]])
-
Moves items to the position and stores them in the closest entity of the type given
Parameters:
- items table items which are to be added to the chests, ['name']=count
- surface LuaSurface the surface that the items will be moved to (default navies)
- position table the position that the items will be moved to {x=100,y=100} (default {0)
- radius number the radius in which the items are allowed to be placed (default 32)
- chest_type string the chest type that the items should be moved into (default iron-chest)
- Common.print_grid_value (value, surface, position, scale, offset, immutable)
-
https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4a2/map_gen/maps/diggy/debug.lua#L31
Prints a colored value on a location.
Parameters:
- value between -1 and 1
- surface LuaSurface
- position Position {x, y}
- scale float
- offset float
- immutable bool if immutable, only set, never do a surface lookup, values never change
- Common.print_colored_grid_value (value, surface, position, offset, immutable, color_value, base_color, delta_color, under_bound, over_bound)
-
Prints a colored value on a location. When given a color_value and a delta_color,
will change the color of the text from the base to base + value * delta. This will
make the color of the text range from 'base_color' to 'base_color + delta_color'
as the color_value ranges from 0 to 1
Parameters:
- value of number to be displayed
- surface LuaSurface
- position Position {x, y}
- offset float position offset
- immutable bool if immutable, only set, never do a surface lookup, values never change
- color_value float How far along the range of values of colors the value is to be displayed
- base_color {r,g,b} The color for the text to be if color_value is 0
- delta_color {r,g,b} The amount to correct the base_color if color_value is 1
- under_bound {r,g,b} The color to be used if color_value < 0
- over_bound {r,g,b} The color to be used if color_value > 1
- Common.clear_flying_text (surface)
-
Clears all flying text entites on a surface
Parameters:
- surface LuaSurface the surface to clear
- Common.string_contains (s, contains)
-
Tests if a string contains a given substring.
Parameters:
Returns:
-
boolean
true if the substring was found in the string
- Common.extract_keys (tbl, ...)
-
Extracts certain keys from a table
Parameters:
Returns:
-
the keys in the order given
Usage:
local key_three, key_one = extract({key_one='foo',key_two='bar',key_three=true},'key_three','key_one')
- Common.enum (tbl)
-
Converts a table to an enum
Parameters:
- tbl table table the that will be converted
Returns:
-
table
the new table that acts like an enum
- Common.auto_complete (options, input[, use_key=false[, rtn_key=false]])
-
Returns the closest match to the input
Parameters:
- options table table a of options for the auto complete
- input string string the input that will be completed
- use_key boolean when true the keys of options will be used as the options (default false)
- rtn_key boolean when true the the key will be returned rather than the value (default false)
Returns:
-
the list item found that matches the input
- Common.table_keys (tbl)
-
Returns all the keys of a table
Parameters:
- tbl table table the to get the keys of
Returns:
-
table
an array of the table keys
- Common.table_values (tbl)
-
Returns all the values of a table
Parameters:
- tbl table table the to get the values of
Returns:
-
table
an array of the table values
- Common.table_alphanumsort (tbl)
-
Returns the list is a sorted way that would be expected by people (this is by key)
Parameters:
- tbl table the table to be sorted
Returns:
-
table
the sorted table
- Common.table_keysort (tbl)
-
Returns the list is a sorted way that would be expected by people (this is by key) (faster alterative than above)
Parameters:
- tbl table the table to be sorted
Returns:
-
table
the sorted table
- Common.format_chat_colour (message, color)
-
Returns a message with valid chat tags to change its colour
Parameters:
- message string the message that will be in the output
- color table a color which contains r,g,b as its keys
Returns:
-
string
the message with the color tags included
- Common.format_chat_colour_localized (message, color)
-
Returns a message with valid chat tags to change its colour, using localization
Parameters:
- message string or table the message that will be in the output
- color table a color which contains r,g,b as its keys
Returns:
-
table
the message with the color tags included
- Common.format_chat_player_name (player[, raw_string=false])
-
Returns the players name in the players color
Parameters:
- player LuaPlayer the player to use the name and color of
- raw_string boolean when true a is returned rather than a localized string (default false)
Returns:
-
table
the players name with tags for the players color