Love Frames

To install utf8.lua, download the repository directly into your project folder. Note that there are currently no rockspecs available for package managers.

Because the default Lua 5.3 utf8 module takes precedence, you should use the full module path (e.g., .utf8) when requiring the library to ensure you are using this UTF-8 enabled version.

local utf8 = require('.utf8'):init()

You can integrate utf8.lua into your application in two ways:

1. Monkey-patching the global string library: This replaces the standard Lua string functions with UTF-8 aware versions globally.
2. Using the utf8 object directly: This keeps the standard library intact and allows you to call UTF-8 functions via the utf8 instance.

The library exports all vanilla string functions under the utf8.raw sub-object.

-- Option 1: Global monkey-patching
local utf8 = require('.utf8'):init()
for k,v in pairs(utf8) do
  string[k] = v
end

-- Option 2: Direct usage via the utf8 object
local utf8 = require('.utf8'):init()
local str = "пыщпыщ ололоо я водитель нло"
utf8.gsub(str, "ло+", "보라")

-- Accessing vanilla (non-UTF8) functions
utf8.raw.gsub(str, "ло+", "보라")

The library is highly modular and allows for customization of its back-ends and performance settings. Customization must be performed before calling :init().

Key configuration options include:

• utf8.config.cache: Provide a custom cache object (e.g., my_smart_cache) to precompile and store regexes.
• utf8.config.loadstring: Customize how strings are loaded/compiled.

If you change configuration after calling :init(), changes might apply to some parts of the library, but modules will require a reload to reflect the new settings.

local utf8 = require('.utf8')
utf8.config = {
  cache = my_smart_cache,
}
utf8:init()

While utf8.lua provides most functions from the Lua 5.3 UTF-8 module, it does not include utf8.len. To validate strings, use the following methods:

• utf8.validate(str, byte_pos): Validates the string starting from a specific byte position.
• utf8.validator: An iterator for validating strings.