Common-Library core

Core Module - Common Library - Adds some commonly used functions used in many modules

Dependencies

utils.color_presets
utils.game
util

Type Checking

type_check(value[, test_type=nil]) Asserts the argument is of type test_type
type_error(value, test_type, error_message, level) Raises an error if the value is of the wrong type
multi_type_check(value, test_types) Asserts the argument is one of type test_types
multi_type_error(value, test_types, error_message, level) Raises an error if the value is of the wrong type
validate_argument_type(value, test_type, param_name, param_number) Raises an error when the value is the incorrect type, uses a consistent error message format
validate_argument_multi_type(value, test_types, param_name, param_number) Raises an error when the value is the incorrect type, uses a consistent error message format
error_if_runtime() Will raise an error if called during runtime
error_if_runetime_closure(func) Will raise an error if the function is a closure

Value Returns

string_contains(s, contains) Tests if a string contains a given substring.
resolve_value(value) Used to resolve a value that could also be a function returning that value
get_actor() Returns a valid string with the name of the actor of a command.
cast_bool(var) Converts a varible into its boolean value, nil and false return false
ternary(c, t, f) Returns either the second or third argument based on the first argument
comma_value(n) Returns a string for a number with comma seperators
set_and_return(tbl, key, value) Sets a table element to value while also returning value.
write_json(path, tbl) Writes a table object to a file in json format
opt_require(path) Calls a require that will not error if the file is not found
get_file_path([offset=0]) Returns a desync safe file path for the current file
enum(tbl) Converts a table to an enum
auto_complete(options, input[, use_key=false][, rtn_key=false]) Returns the closest match to the input

Formating

format_chat_colour(message, color) Returns a message with valid chat tags to change its colour
format_chat_colour_localized(message, color) Returns a message with valid chat tags to change its colour, using localization
format_chat_player_name(player[, raw_string=false]) Returns the players name in the players color
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
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

Factorio

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
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.
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.
clear_flying_text(surface) Clears all flying text entities on a surface

Dependencies

# utils.color_presets
# utils.game
# util

Type Checking

# type_check(value[, test_type=nil])

Asserts the argument is of type test_type

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: Usage:
type_check('foo','string') -- return true
type_check('foo') -- return false
# type_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_error('foo','number','Value must be a number') -- will raise error "Value must be a number"
# multi_type_check(value, test_types)

Asserts the argument is one of type test_types

Parameters:
  • value : the variable to check
  • test_types : the type as a table of strings
Returns:
  • (boolean) true if value is one of test_types
# multi_type_error(value, test_types, 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_types : (table) the type as a table of strings
  • 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:
multi_type_error('foo',{'string','table'},'Value must be a string or table') -- will raise error "Value must be a string or table"
# validate_argument_type(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:
validate_argument_type('foo','number','repeat_count',2) -- will raise error "Bad argument #02 to "<anon>"; "repeat_count" is of type string expected number"
# validate_argument_multi_type(value, test_types, 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_types : (string) the types 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:
validate_argument_type('foo',{'string','table'},'repeat_count',2) -- will raise error "Bad argument #02 to "<anon>"; "repeat_count" is of type string expected string or table"
# error_if_runtime()

Will raise an error if called during runtime

Usage:
error_if_runtime()
# error_if_runetime_closure(func)

Will raise an error if the function is a closure

Parameters:
  • func
Usage:
error_if_runetime_closure(func)

Value Returns

# string_contains(s, contains)

Tests if a string contains a given substring.

Parameters:
  • s : (string) the string to check for the substring
  • contains : (string) the substring to test for
Returns:
  • (boolean) true if the substring was found in the string
# resolve_value(value)

Used to resolve a value that could also be a function returning that value

Parameters:
  • value : (any) the value which you want to test is not nil and if it is a function then call the function
Returns:
  • (any) the value given or returned by value if it is a function
Usage:
-- Default value handling
-- if default value is not a function then it is returned
-- if it is a function then it is called with the first argument being self
local value = Common.resolve_value(self.defaut_value,self)
# get_actor()

Returns a valid string with the name of the actor of a command.

Returns:
  • (string) the name of the current actor
# cast_bool(var)

Converts a varible into its boolean value, nil and false return false

Parameters:
  • var
Returns:
  • (boolean) the boolean form of the varible
# ternary(c, t, f)

Returns either the second or third argument based on the first argument

Parameters:
  • c
  • t
  • f
# comma_value(n)

Returns a string for a number with comma seperators

Parameters:
  • n : (credit http) //richard.warburton.it
# set_and_return(tbl, key, value)

Sets a table element to value while also returning value.

Parameters:
  • tbl : table to change the element of
  • key : string
  • value : nil|boolean|number|string|table to set the element to
Returns:
  • value
# write_json(path, tbl)

Writes a table object to a file in json format

Parameters:
  • path : (string) the path of the file to write include / to use dir
  • tbl : (table) the table that will be converted to a json string and wrote to file
# 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
# get_file_path([offset=0])

Returns a desync safe file path for the current file

Parameters:
  • offset : (number) the offset in the stack to get, 0 is current file (default: 0)
Returns:
# 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
# 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

Formating

# 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
# 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
# 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
# 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
# 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

Factorio

# 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)
# 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
# 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
# clear_flying_text(surface)

Clears all flying text entities on a surface

Parameters: