add_tags

Adds the given tags to the entity if they are not present already. If the replace flag argument is set to true, and the tag already exists in the entity's tags it will be replaced with the new one.

Errors

• Return an error if the tag already exists and the replace flag is not set or set to false
• Return an error if the tag name is empty

Signature

---@params tags table[] @Array of tags to be add
---@params replace bool|nil @Replaces the tags on the entity if they already exists
---@return int|error @Number of added/replaced tags or an error
function Entity:add_tags(tags, replace)

Example of Usage

-- bind the exposed entity UserData to a local variable
local entityAPI = alacrity.Entity

-- create a new random unique user ID
local id = alacrity.uuid.new_v4()

-- create a new Entity instance
local e = entityAPI.new({
    id = id,
    name = "Ad-Hoc Test Entity",
    description = "Ad-Hoc entity for testing add_tags method",
    attributes = {},
    properties = {},    
})

local ok, err = pcall(function()
    local tags = {
        { name = "test_tag", value = "something" },
    }
    e:add_tags(tags)
end)

assert(ok)
assert(e:get_tag("test_tag").value:to_string() == "something")

-- this one will fail
local ok, err = pcall(function()
    local tags = {
        { name = "test_tag", value = "some other value" },
    }
    e:add_tags(tags)
end)

assert(not ok)
assert(e:get_tag("test_tag").value:to_string() == "something")

-- this one will go through
local ok, err = pcall(function()
    local tags = {
        { name = "test_tag", value = "nothing" }
    }
    e:add_tags(tags, true)
end)

assert(ok)
assert(e:get_tag("test_tag").value:to_string() == "nothing")