lua-uuid

Overview

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

• On Linux and BSD, 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
  • Compare GUIDs / UUIDs
  • Verify GUIDs / UUIDs nullity
• Static Methods
  • new
  • parse
• Instance Methods
  • isnil
• Metamethods
  • __eq
  • __tostring
• Change log
• Future works

Installation

Important

On Linux and BSD, 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 on your system, execute the following command:

luarocks install lua-uuid

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)

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())

Static Methods

new

• Description: Generates a new GUID / UUID
• Signature: new()
  • return: (userdata)
• Usage: See here

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

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

Change log

• v0.0.4:
  • Added support for BSD (e.g: FreeBSD, NetBSD, OpenBSD and DragonFly);
  • Moved #include <lua.h> and LUA_UUID_EXPORT macro definition to outside of __cplusplus declarations on lua-uuid.h.
• v0.0.3:
  • Changed to throw error when lua_newuserdata returns NULL;
  • Added macro LUA_UUID_BUILD_SHARED to CFLAGS_EXTRA on macos;
  • Changed luajit-master to luajit on CI when testing for LuaJIT;
  • Added print statements on tostring.lua sample;
  • Removed build / testing from CI for x86 packages on MSYS2;
  • Added documentation for static, instance and metamethods to the README.
• v0.0.2:
  • Fixed syntax issue in the rockspec lua-uuid-0.0.1-0.rockspec

Future works

• Add CMake as build system