## expcore.common module

Adds some commonly used functions used in many modules

[[

- Author: cooldude2606

### Dependencies

resources.color_presets
utils.game
util

### 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 entities 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_values(table[, sorted][, as_string]) | Returns a copy of all of the values in the table.
Common.table_keys(table[, sorted][, as_string]) | Returns a copy of all of the keys in the 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 alternative 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

### Dependencies

# resources.color_presets
# utils.game
# util

### 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') --- @dep expcore.common

# 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 entities 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_values(table[, sorted][, as_string])

  Returns a copy of all of the values in the table.

  Parameters:
  - table : (table) tbl the to copy the keys from, or an empty table if tbl is nil
  - sorted : (boolean) whether to sort the keys (slower) or keep the random order from pairs() (optional)
  - as_string : (boolean) whether to try and parse the values as strings, or leave them as their existing type (optional)
  Returns:
  - (array) an array with a copy of all the values in the table
# Common.table_keys(table[, sorted][, as_string])

  Returns a copy of all of the keys in the table.

  Parameters:
  - table : (table) tbl the to copy the keys from, or an empty table if tbl is nil
  - sorted : (boolean) whether to sort the keys (slower) or keep the random order from pairs() (optional)
  - as_string : (boolean) whether to try and parse the keys as strings, or leave them as their existing type (optional)
  Returns:
  - (array) an array with a copy of all the keys in the table
# 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 alternative 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