winreg

Reads and writes the Windows registry.

This API is VFS-aware: it operates through the VFS in scope for the current strand, so it works transparently under remote or elevated contexts such as admin.with. It is supported only on Windows targets; elsewhere every operation throws sys.UnsupportedError.

Types

Type	Description
AccessMask	Access rights for a registry key.
Key	An open registry key.
LinkTarget	A registry link's target, kept in both its native and canonical forms.
Value	One named value read from a key.
AccessMaskSpec	Rights, given as an AccessMask, one right, or an iterable of rights.
AccessRight	A right of an AccessMask: a registry-specific right or composite, or a generic Windows AccessRight.
Data	Registry value data in its natural Do representation. See Value.value for how each value kind maps to it.
LinkResolution	How opening a key treats a registry link.
RegistryRoot	A registry root.
RegistryView	A registry view.
ValueKind	The kind of a stored registry value.

AccessMaskSpec = (AccessMask | AccessRight | Iterable[AccessRight])

Rights, given as an AccessMask, one right, or an iterable of rights.

AccessRight = (:QUERY_VALUE: | :SET_VALUE: | :CREATE_SUB_KEY: | :ENUMERATE_SUB_KEYS: | :NOTIFY: | :CREATE_LINK: | :WOW64_64KEY: | :WOW64_32KEY: | :READ: | :WRITE: | :READ_WRITE: | security.windows.AccessRight)

A right of an AccessMask: a registry-specific right or composite, or a generic Windows AccessRight.

Symbol	Meaning
:QUERY_VALUE:	Queries key values
:SET_VALUE:	Sets key values
:CREATE_SUB_KEY:	Creates subkeys
:ENUMERATE_SUB_KEYS:	Enumerates subkeys
:NOTIFY:	Receives change notifications
:CREATE_LINK:	Creates symbolic-link keys
:WOW64_64KEY:	Uses the 64-bit registry view
:WOW64_32KEY:	Uses the 32-bit registry view

Registry composites, the ones worth reaching for by default:

Symbol	Equivalent to
:READ:	Query values, enumerate subkeys, receive change notifications, and read security information
:WRITE:	Set values, create subkeys, and read security information
:READ_WRITE:	:READ: and :WRITE: together

Data = (Str | Array[Str] | Int | Bin | nil)

Registry value data in its natural Do representation. See Value.value for how each value kind maps to it.

LinkResolution = (:TARGET: | :LINK:)

How opening a key treats a registry link.

Symbol	Meaning
:TARGET:	Follow the link
:LINK:	Open the link key itself

RegistryRoot = (:CLASSES_ROOT: | :CURRENT_USER: | :LOCAL_MACHINE: | :USERS: | :CURRENT_CONFIG:)

A registry root.

Symbol	Meaning
:CLASSES_ROOT:	File associations and class settings
:CURRENT_USER:	Current user's profile
:LOCAL_MACHINE:	Computer-wide configuration
:USERS:	All user profiles
:CURRENT_CONFIG:	Current hardware profile

RegistryView = (:NATIVE: | :WOW32: | :WOW64:)

A registry view.

Symbol	Meaning
:NATIVE:	The target process's native registry view
:WOW32:	The 32-bit registry view
:WOW64:	The 64-bit registry view

ValueKind = (:SZ: | :EXPAND_SZ: | :MULTI_SZ: | :DWORD: | :DWORD_BIG_ENDIAN: | :QWORD: | :BINARY: | :NONE:)

The kind of a stored registry value.

Symbol	Stored value type
:SZ:	UTF-16 string
:EXPAND_SZ:	Expandable UTF-16 string
:MULTI_SZ:	Sequence of UTF-16 strings
:DWORD:	Little-endian 32-bit integer
:DWORD_BIG_ENDIAN:	Big-endian 32-bit integer
:QWORD:	Little-endian 64-bit integer
:BINARY:	Raw bytes
:NONE:	No data

Functions

open root … -> Key

Opens a predefined registry root.

Parameters

Name	Type	Description
root	RegistryRoot	Registry root to open.
:view?	RegistryView	Registry view. Defaults to :NATIVE:.
:access?	AccessMaskSpec	Access rights. Defaults to :READ:.

Example

open :CURRENT_USER: do |root|
  echo (root.open("Environment").get "TEMP")

let root = open :LOCAL_MACHINE: access: :READ_WRITE:
root.close()

open[R] root func … -> R

Opens a registry root and calls func with it. The key is closed when func returns.

Parameters

Name	Type	Description
root	RegistryRoot	Registry root to open.
:view?	RegistryView	Registry view. Defaults to :NATIVE:.
:access?	AccessMaskSpec	Access rights. Defaults to :READ:.
func	((Key) -> R)	Called with the Key.