## Common core

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

### Dependencies

utils.color_presets
utils.game

### 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_number[, param_name]) | Raises an error when the value is the incorrect type, uses a consistent error message format
validate_argument_multi_type(value, test_types, param_number[, param_name]) | 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
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

### Formatting

get_actor(player_name) | Returns a valid string with the name of the actor of a command.
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 -- time will use : separates -- when a denomination is false it will overflow into the next one

### Factorio

copy_items_stack(items[, surface=navies][, position={0][, radius=32][, chest_type=iron-chest]) | Copies items to the position and stores them in the closest entity of the type given -- Copies the items by prototype name, but keeps them in the original inventory
move_items_stack(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 -- Differs from move_items by accepting a table of LuaItemStack and transferring them into the inventory - not copying
print_grid_value(value, surface, position[, scale=1][, offset=0][, immutable=false]) | Prints a colored value on a location, color is based on the value.
clear_flying_text(surface) | Clears all flying text entities on a surface

### Dependencies

# utils.color_presets
# utils.game

### 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:
  - (boolean) is v of type test_type
  Usage:

      -- Check for a string value
      local is_string = type_check(value, 'string')

      -- Check for a nil value
      local is_nil = type_check(value)

# 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 is the caller)
  Returns:
  - (boolean) true if no error was called
  Usage:

      -- Raise error if value is not a number
      type_error(value, 'number', '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
  Usage:

      -- Check for a string or table
      local is_string_or_table = multi_type_check(value, {'string', 'table'})

# 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 is the caller)
  Returns:
  - (boolean) true if no error was called
  Usage:

      -- Raise error if value is not a string or table
      multi_type_error('foo', {'string', 'table'}, 'Value must be a string or table')

# validate_argument_type(value, test_type, param_number[, param_name])

  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_number : (number) the number param it is
  - param_name : (string) the name of the param (optional)
  Returns:
  - (boolean) true if no error was raised
  Usage:

      -- Output: "Bad argument #2 to "<anon>"; argument is of type string expected number"
      validate_argument_type(value, 'number', 2)

      -- Output: "Bad argument #2 to "<anon>"; "repeat_count" is of type string expected number"
      validate_argument_type(value, 'number', 2, 'repeat_count')

# validate_argument_multi_type(value, test_types, param_number[, param_name])

  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_number : (number) the number param it is
  - param_name : (string) the name of the param (optional)
  Returns:
  - (boolean) true if no error was raised
  Usage:

      -- Output: "Bad argument #2 to "<anon>"; argument is of type number expected string or table"
      validate_argument_type(value, {'string', 'table'}, 2)

      -- Output: "Bad argument #2 to "<anon>"; "player" is of type number expected string or table"
      validate_argument_type(value, {'string', 'table'}, 2, 'player')

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

      -- Test if a string contains a sub string
      local found = string_contains(str, 'foo')

# 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 default value is a function then it is called with the first argument being self
      local value = Common.resolve_value(self.defaut_value, self)

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

      local bool = cast_bool(var)

# ternary(c, t, f)

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

  Parameters:
  - c
  - t
  - f
  Usage:

      ternary(input_string == 'test', 'Input is test', 'Input is not test')

# comma_value(n)

  Returns a string for a number with comma seperators

  Parameters:
  - n : (credit http) //richard.warburton.it
  Usage:

      comma_value(input_number)

# 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) the key to set the value of
  - value : (any) the value to set the key as
  Returns:
  - (any) the value that was set
  Usage:

      -- Set and return value
      local value = set_and_return(players, player.name, player.online_time)

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

      -- Write a lua table as a json to script-outpt/dump
      write_json('dump', tbl)

# 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

      -- Require a file without causing errors, for when a file might not exist
      local Module = opt_require 'expcore.common'

# 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:
  - (string) the file path
  Usage:

      -- Get the current file path
      local file_path = get_file_path()

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

      -- Make an enum
      local colors = enum{
          'red',
          'green',
          'blue'
      }

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

      -- Get the element that includes "foo"
      local value = auto_complete(tbl, "foo")

      -- Get the element with a key that includes "foo"
      local value = auto_complete(tbl, "foo", true)

      -- Get the key with that includes "foo"
      local key = auto_complete(tbl, "foo", true, true)

### Formatting

# get_actor(player_name)

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

  Parameters:
  - player_name : (string) the name of the player to use rather than server, used only if game.player is nil
  Returns:
  - (string) the name of the current actor
  Usage:

      -- Get the current actor
      local player_name = get_actor()

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

      -- Use factorio tags to color a chat message
      local message = format_chat_colour('Hello, World!', { r=355, g=100, b=100 })

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

      -- Use factorio tags and locale strings to color a chat message
      local message = format_chat_colour_localized('Hello, World!', { r=355, g=100, b=100 })

# 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 string is returned rather than a localized string (default: false)
  Returns:
  - (table) the players name with tags for the players color
  Usage:

      -- Format a players name using the players color as a string
      local message = format_chat_player_name(game.player, true)

# 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) a 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:

      -- Return a value to the current actor, rcon included
      player_return('Hello, World!')

      -- Return a value to the current actor, with color
      player_return('Hello, World!', 'green')

      -- Return to a player other than the current
      player_return('Hello, World!', nil, player)

# format_time(ticks, options)

  Formats tick into a clean format, denominations from highest to lowest -- time will use : separates -- 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
  Usage:

      -- Output: "0h 5m"
      local time = format_time(18000, { hours=true, minutes=true, string=true })

      -- Output: "0 hours and 5 minutes"
      local time = format_time(18000, { hours=true, minutes=true, string=true, long=true })

      -- Output: "00:05:00"
      local time = format_time(18000, { hours=true, minutes=true, seconds=true, string=true })

      -- Output: "--:--:--"
      local time = format_time(18000, { hours=true, minutes=true, seconds=true, string=true, null=true })

### Factorio

# copy_items_stack(items[, surface=navies][, position={0][, radius=32][, chest_type=iron-chest])

  Copies items to the position and stores them in the closest entity of the type given -- Copies the items by prototype name, but keeps them in the original inventory

  Parameters:
  - items : (table) items which are to be added to the chests, an array of LuaItemStack
  - surface : (LuaSurface) the surface that the items will be copied to (default: navies)
  - position : (table) the position that the items will be copied 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 copied into (default: iron-chest)
  Returns:
  - (LuaEntity) the last chest that had items inserted into it
  Usage:

      -- Copy all the items in a players inventory and place them in chests at {0, 0}
      copy_items_stack(game.player.get_main_inventory().get_contents())

# move_items_stack(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 -- Differs from move_items by accepting a table of LuaItemStack and transferring them into the inventory - not copying

  Parameters:
  - items : (table) items which are to be added to the chests, an array of LuaItemStack
  - 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)
  Returns:
  - (LuaEntity) the last chest that had items inserted into it
  Usage:

      -- Copy all the items in a players inventory and place them in chests at {0, 0}
      move_items_stack(game.player.get_main_inventory())

# print_grid_value(value, surface, position[, scale=1][, offset=0][, immutable=false])

  Prints a colored value on a location, color is based on the value.

  nb: src is below but the gradent has been edited https://github.com/Refactorio/RedMew/blob/9184b2940f311d8c9c891e83429fc57ec7e0c4a2/map_gen/maps/diggy/debug.lua#L31

  Parameters:
  - value : (number) the value to show must be between -1 and 1, scale can be used to achive this
  - surface : (LuaSurface) the surface to palce the value on
  - position : (table) {x, y} the possition to palce the value at
  - scale : (number) how much to scale the colours by (default: 1)
  - offset : (number) the offset in the +x +y direction (default: 0)
  - immutable : (boolean) if immutable, only set, never do a surface lookup, values never change (default: false)
  Usage:

      -- Place a 0 at {0, 0}
      print_grid_value(0, game.player.surface, { x=0, y=0 })

# clear_flying_text(surface)

  Clears all flying text entities on a surface

  Parameters:
  - surface : (LuaSurface) the surface to clear
  Usage:

      -- Remove all flying text on the surface
      clear_flying_text(game.player.surface)