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:

  • 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
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:

  • 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
Common.extract_keys (tbl, ...)
Extracts certain keys from a table

Parameters:

  • tbl table table the which contains the keys
  • ... string the names of the keys you want extracted

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
generated by LDoc 1.4.3 Last updated 2019-05-29 22:30:49