migration module

Mod migrations and version comparison functions.

See also

Usage

local migration = require("__flib__.migration")

Functions

format_version(version[, format="%02d"]) Normalize version strings for easy comparison.
is_newer_version(old_version, current_version[, format=%02d]) Check if current_version is newer than old_version.
run(old_version, migrations[, format="%02d"][, ...]) Run migrations against the given version.
on_config_changed(event_data, migrations[, mod_name]) Determine if migrations need to be run for this mod, then run them if needed.

Concepts

MigrationsTable A table of migrations to run for given versions.

Functions

# format_version(version[, format="%02d"])

Normalize version strings for easy comparison.

Parameters: Returns: Usage:
migration.format_version("1.10.1234", "%04d")
migration.format_version("3", "%02d")
# is_newer_version(old_version, current_version[, format=%02d])

Check if current_version is newer than old_version.

Parameters: Returns:
# run(old_version, migrations[, format="%02d"][, ...])

Run migrations against the given version.

Parameters:
  • old_version : (string)
  • migrations : (MigrationsTable)
  • format : (string) (default: "%02d")
  • ... : (any) Any additional arguments will be passed to each function within migrations. (optional)
# on_config_changed(event_data, migrations[, mod_name])

Determine if migrations need to be run for this mod, then run them if needed.

Parameters: Returns:
  • (boolean) If true, run generic migrations.
Usage:
-- In on_configuration_changed:
if migration.on_config_changed(e, migrations) then
  -- run generic (non-init) migrations
  rebuild_prototype_data()
end

Concepts

# MigrationsTable

A table of migrations to run for given versions.

Dictionary string –> function. Each string is a version number, and each function is logic to run for that version. When passed into migration.run or migration.on_config_changed, the module will check old_version against each version in this table, and for any that are newer, will run that version’s corresponding logic.

A version function can accept arguments that are passed in through migration.run.

Usage:
{
  ["1.0.1"] = function()
    global.foo = nil
    for _, player_table in pairs(global.players) do
      player_table.bar = "Lorem ipsum"
    end
  end,
  ["1.1.0"] = function(arg)
    global.foo = arg
  end
}