registry module (Windows)

use registry reads and writes the Windows registry. The module is registered on every platform, so a playbook compiles and validates identically everywhere; on Linux and macOS every call returns a runtime error. Guard a call with a step condition on os.family or with sys::family() from the sys module. Every function returns Result[…, string]. A key is a hive-prefixed path such as HKLM\Software\Vendor\App; the hive names are also available as the constants registry::HKLM, HKCU, HKCR, HKU and HKCC. A key or value counts as absent only when Windows reports it as not found (ERROR_FILE_NOT_FOUND or ERROR_PATH_NOT_FOUND). Any other failure, such as access denied, is an Err naming the key and the Win32 error, so read never returns None and key_exists never returns false for a key the process cannot open.

read

registry::read(key: string, name: string) -> Result[Option[Value], string]

Reads a value. It returns None when the key or the value is absent. The Value is typed by the registry kind of the entry.

Any other registry type, such as REG_LINK, is an Err.

read_typed

registry::read_typed(key: string, name: string, opts: Value) -> Result[Option[Value], string]

Reads a value together with its kind. It returns None when the key or the value is absent, and otherwise a map {kind, data}. kind is the name write accepts: sz, expand_sz, dword, qword, multi_sz, binary or none. data has the shape read returns. A registry type outside that list, such as REG_LINK or REG_RESOURCE_LIST, is not an Err here: the map is {kind: "other", type, data}, where type is the REG_* number as an int and data is the raw bytes as a list of ints. write does not accept other. Use read_typed when a REG_SZ must be told apart from a REG_EXPAND_SZ, or a REG_DWORD from a REG_QWORD. opts is the view map described under Registry views below; pass Value::Null for the native view.

write

registry::write(key: string, name: string, value: Value, kind: string) -> Result[unit, string]

Writes a value. kind selects the registry type and must match the shape of value: sz and expand_sz take a string, dword and qword take an int, multi_sz takes a list of strings, and binary and none take a list of byte ints from 0 to 255.

delete_value

registry::delete_value(key: string, name: string) -> Result[unit, string]

Deletes one value from a key.

create_key and delete_key

registry::create_key(key: string) -> Result[unit, string]
registry::delete_key(key: string) -> Result[unit, string]

create_key creates a key and any missing parents. delete_key deletes a key and its whole subtree.

key_exists

registry::key_exists(key: string) -> Result[bool, string]

Whether a key exists. It returns false only when the key is not found; any other failure is an Err.

value_names

registry::value_names(key: string, opts: Value) -> Result[List[string], string]

Lists the names of a key's values. The list is sorted ignoring case, as the registry compares names, so it does not depend on the order Windows stores them in. The unnamed default value appears as "", the same name read and write use for it, and only when it is set; a key whose default value was never written does not list it. A key with no values returns an empty list. A missing key is an Err naming the key rather than an empty list, so a mistyped key cannot pass as a key with no values; check key_exists first when the key may legitimately be absent. Any other failure to open or enumerate the key is an Err naming the key and the Win32 error. opts is the view map described under Registry views below; pass Value::Null for the native view.

Registry views

registry::read_with(key: string, name: string, opts: Value) -> Result[Option[Value], string]
registry::write_with(key: string, name: string, value: Value, kind: string, opts: Value) -> Result[unit, string]
registry::delete_value_with(key: string, name: string, opts: Value) -> Result[unit, string]
registry::create_key_with(key: string, opts: Value) -> Result[unit, string]
registry::delete_key_with(key: string, opts: Value) -> Result[unit, string]
registry::key_exists_with(key: string, opts: Value) -> Result[bool, string]

Each _with function behaves like the function without the suffix and takes a trailing opts map. The only option is view. "native" (the default) uses the process's own view. "wow64_32" forces the 32-bit view (WOW6432Node), and "wow64_64" forces the 64-bit view. read_typed and value_names take the same map. Pass Value::Null for the defaults. An unknown option or view is an Err. The functions without the suffix always use the native view.

use registry
use value

fn check(props: Value) -> Result[CheckResult, string] {
    let key = "HKLM\\Software\\Vendor\\App"
    match registry::read(key, "Telemetry")? {
        Some(v) => if v.as_int() == Some(0) { Ok(CheckResult::AlreadyConfigured) } else { Ok(CheckResult::NotConfigured) },
        None => Ok(CheckResult::NotConfigured),
    }
}