lua-uuid

Overview

lua-uuid is a lightweight, native library for Lua (5.1 and newer) to deal with Universally Unique Id (UUID).

• On Unix-like distributions, it uses libuuid to generate UUIDs;
• On Windows, it uses the WINAPI rpcrt4 library;
• On macOS / iOS, it uses the CoreFoundation framework.

Table of Contents

• Installation
• Usage
  • Generate GUIDs / UUIDs
  • Parse GUIDs / UUIDs from string
  • Try to parse GUIDs / UUIDs from string
  • Compare GUIDs / UUIDs
  • Verify GUIDs / UUIDs nullity
  • Print the library version
• Constants
  • version
• Static Methods
  • new
  • parse
  • tryparse
• Instance Methods
  • isnil
• Metamethods
  • __eq
  • __tostring
• Change log

Installation

Important

On Windows or macOS, there is no need to install external dependencies.

On Unix-like distributions, lua-uuid depends on libuuid:

• On Debian-based (e.g: Ubuntu) distributions:

  sudo apt install -y uuid-dev

• On RedHat-based (e.g: Fedora) distributions:

  sudo dnf install libuuid-devel

• On BSD-based (e.g: FreeBSD) distributions:

  pkg install e2fsprogs-libuuid

Assuming that LuaRocks is properly installed and configured in the system, execute the following command:

luarocks install lua-uuid

In case LuaRocks is not an option, check the guides:

• Build on Windows or
• Build on Unix.

Usage

Generate GUIDs / UUIDs

• Generate GUIDs / UUIDs and print them

  -- load the library
  local uuid = require("lua-uuid")
  
  -- generate UUIDs
  local id1 = uuid.new()
  local id2 = uuid.new()
  
  -- print each UUID
  print(id1)
  print(id2)

• Generate GUIDs / UUIDs and get their string representations

  -- load the library
  local uuid = require("lua-uuid")
  
  -- generate UUIDs
  local id1 = uuid.new()
  local id2 = uuid.new()
  
  -- get their string representations
  local s1 = tostring(id1)
  local s2 = tostring(id2)
  
  assert(type(s1) == 'string')
  assert(type(s2) == 'string')
  
  -- print each string
  print(s1)
  print(s2)

Parse GUIDs / UUIDs from string

-- load the library
local uuid = require("lua-uuid")

-- parse UUIDs from string
local id1 = uuid.parse("33e4a9f2-8141-4734-a638-f2d08ee7d070")
local id2 = uuid.parse("653096e0-b09f-4626-b65e-07d4e21c70c6")

-- print each UUID
print(id1)
print(id2)

Try to parse GUIDs / UUIDs from string

-- load the library
local uuid = require("lua-uuid")

-- try to parse UUIDs from string
local id1, err1 = uuid.tryparse("some random string")
local id2, err2 = uuid.tryparse("653096e0-b09f-4626-b65e-07d4e21c70c6")

-- print each UUID
if (id1 == nil) then
    -- this branch is going
    -- to execute, because
    -- the string is not
    -- a valid GUID / UUID
    print(err1)
else
    print(id1)
end

if (id2 == nil) then
    print(err2)
else
    -- this branch is going
    -- to execute
    print(id2)
end

Compare GUIDs / UUIDs

-- load the library
local uuid = require("lua-uuid")

-- generate UUIDs
local id1 = uuid.new()
local id2 = uuid.new()

-- print each UUID
print(id1)
print(id2)

-- prints false
print(id1 == id2)

-- prints true
print(id1 == id1)

-- prints true
print(id2 == id2)

Verify GUIDs / UUIDs nullity

-- load the library
local uuid = require("lua-uuid")

-- generate UUIDs
local id1 = uuid.new()
local id2 = uuid.new()

-- prints false
print(id1:isnil())
print(id2:isnil())

-- parse UUID
local id3 = uuid.parse("00000000-0000-0000-0000-000000000000")

-- prints true
print(id3:isnil())

Print the library version

-- load the library
local uuid = require("lua-uuid")

-- print the library version
print("lua-uuid is version " .. uuid.version)

Constants

• Description: The library version
• Signature: version
• Return: (string)
• Usage: See here

Static Methods

new

• Description: Generates a new GUID / UUID
• Signature: new()
• Return: (userdata)
• Usage: See here
• Remark: If the underlying library fails to generate GUID / UUID, this function throws an exception. Guard the call with pcall to detect failures.

parse

• Description: Parses a GUID / UUID from a string value
• Signature: parse(value)
  • value (string): the string to be parsed
• Return: (userdata)
• Usage: See here
• Remark: If the underlying library fails to parse the GUID / UUID, this function throws an exception. Guard the call with pcall to detect failures.

tryparse

• Description: Tries to parse a GUID / UUID from a string value
• Signature: tryparse(value)
  • value (string): the string to be parsed
• Return:
  • obj: an userdata representing the GUID / UUID on success or nil on failure;
  • err: nil on success or string containing a description of the error.
• Usage: See here

Instance Methods

isnil

• Description: Verifies whether the GUID / UUID is considered null or not.

Note

a GUID / UUID is considered null when its string representation is equal to 00000000-0000-0000-0000-000000000000.

• Signature: instance:isnil()
  • instance (userdata): the GUID / UUID instance to check for nullity
• Return: (boolean)
• Usage: See here

Metamethods

__eq

• Description: Compares two GUIDs / UUIDs for equality
• Signature: left == right
  • left (any): the left-side element
  • right (any): the right-side element
• Return: (boolean)
• Usage: See here

__tostring

• Description: Converts the GUID / UUID to string
• Signature: tostring(value)
  • value (userdata): the GUID / UUID to perform the conversion
• Return: (string)
• Usage: See here

History

Browse the changelog