uuidtools

The UUIDTools::UUID class provides several methods to generate different types of UUIDs conforming to RFC 4122. You can create UUIDs based on MD5 or SHA1 hashes using a namespace, generate timestamp-based UUIDs, or generate random UUIDs.

require "uuidtools"

# Create an MD5-based UUID using a namespace
UUIDTools::UUID.md5_create(UUIDTools::UUID_DNS_NAMESPACE, "www.widgets.com")

# Create a SHA1-based UUID using a namespace
UUIDTools::UUID.sha1_create(UUIDTools::UUID_DNS_NAMESPACE, "www.widgets.com")

# Create a timestamp-based UUID
UUIDTools::UUID.timestamp_create

# Create a random UUID
UUIDTools::UUID.random_create

You can install the uuidtools library using the standard Ruby gem command.

$ sudo gem install uuidtools

The core functionality of the library is contained within the UUIDTools::UUID class. It supports the following generation methods:

• md5_create(namespace, name): Generates a UUID using an MD5 hash of the name and namespace.
• sha1_create(namespace, name): Generates a UUID using a SHA1 hash of the name and namespace.
• timestamp_create: Generates a UUID based on the current timestamp.
• random_create: Generates a random UUID.

The UUID.timestamp_create method attempts to detect the machine's MAC address to generate Version 1 UUIDs. If detection fails or you are in a restricted environment, you can manually set the MAC address used for generation:

UUID.mac_address = "00:11:22:33:44:55"

Note: This affects subsequent calls to timestamp_create.

UUID.mac_address = "00:11:22:33:44:55"
uuid = UUID.timestamp_create

The UUIDTools::UUID class provides several methods to export the UUID data into different formats:

• to_s: Returns the standard string representation (e.g., "6ba7b810-9dad-11d1-80b4-00c04fd430c8").
• hexdigest: Returns the 32-character hexadecimal string.
• to_i: Returns the 128-bit integer representation.
• raw: Returns the 16-byte raw byte string.
• to_uri: Returns the URN representation (e.g., "urn:uuid:6ba7b810-9dad-11d1-80b4-00c04fd430c8").

uuid = UUID.random_create

puts uuid.to_s       # "..."
puts uuid.hexdigest  # "..."
puts uuid.to_i       # 12345...
puts uuid.raw        # "\x6b\xa7..."
puts uuid.to_uri     # "urn:uuid:..."

The UUIDTools::UUID class provides several factory methods to generate different types of UUIDs conforming to RFC 4122:

• Version 1 (Time-based): Use UUID.timestamp_create to generate a UUID based on the current time and the machine's MAC address.
• Version 3 (Name-based MD5): Use UUID.md5_create(namespace, name) to generate a UUID using an MD5 hash of a namespace and a name.
• Version 4 (Random): Use UUID.random_create to generate a completely random UUID.
• Version 5 (Name-based SHA-1): Use UUID.sha1_create(namespace, name) to generate a UUID using a SHA-1 hash of a namespace and a name.

# Version 1
UUID.timestamp_create

# Version 3
UUID.md5_create(UUID_DNS_NAMESPACE, "www.widgets.com")

# Version 4
UUID.random_create

# Version 5
UUID.sha1_create(UUID_DNS_NAMESPACE, "www.widgets.com")

The UUIDTools::UUID class provides several methods to instantiate a UUID object from various input formats:

• UUID.parse(uuid_string): Parses a standard UUID string (e.g., "6ba7b810-9dad-11d1-80b4-00c04fd430c8").
• UUID.parse_raw(raw_string): Parses a 16-byte raw string. If the string is shorter than 16 bytes, it is null-padded; if longer, the lower 128 bits are used.
• UUID.parse_int(uuid_int): Parses a 128-bit Integer.
• UUID.parse_hexdigest(uuid_hex): Parses a 32-character hexadecimal string.

# From string
uuid = UUID.parse("6ba7b810-9dad-11d1-80b4-00c04fd430c8")

# From hex string
uuid = UUID.parse_hexdigest("6ba7b8109dad11d180b400c04fd430c8")

# From integer
uuid = UUID.parse_int(0x6ba7b8109dad11d180b400c04fd430c8)

Once you have a UUIDTools::UUID object, you can access its components and metadata:

• Components: time_low, time_mid, time_hi_and_version, clock_seq_hi_and_reserved, clock_seq_low, and nodes.
• Metadata:
  • version: Returns the UUID version (1, 2, 3, 4, or 5).
  • variant: Returns the UUID variant.
  • valid?: Returns true if the UUID is valid (variant 0b100 and version between 1-8).
  • nil_uuid?: Returns true if the UUID is all zeros.
• Version 1 Specifics:
  • mac_address: Returns the IEEE 802 address used to generate the UUID (returns nil if the node ID was randomly generated or if it's not a version 1 UUID).
  • timestamp: Returns the Time object used to generate the UUID.

When creating name-based UUIDs (Version 3 or 5), use the provided constant namespaces:

• UUID_DNS_NAMESPACE: DNS namespace.
• UUID_URL_NAMESPACE: URL namespace.
• UUID_OID_NAMESPACE: OID namespace.
• UUID_X500_NAMESPACE: X500 namespace.

# Example using URL namespace for a specific URL
url = "https://example.com"
uuid = UUID.sha1_create(UUID_URL_NAMESPACE, url)