Key

An open registry key.

Returned by open and by Key's own open and create.

Methods

`close()`

Closes the key.

Closing an already-closed key does nothing. A key that is never closed explicitly is closed when it is collected.

`create subpath … -> Key`

Creates a subkey, or opens it when it already exists.

Parameters

Name	Type	Description
`subpath`	`Str`	Path to the subkey, relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.
`:access?`	`AccessMaskSpec`	Access rights. Defaults to `:READ:`.

Example

winreg.open :CURRENT_USER: access: :READ_WRITE: do |root|
  root.create "Software/MyApp" do |app|
    app.set "installed" true

`create[R] subpath func … -> R`

Creates or opens a subkey and calls func with it. The key is closed when func returns.

Parameters

Name	Type	Description
`subpath`	`Str`	Path to the subkey, relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.
`:access?`	`AccessMaskSpec`	Access rights. Defaults to `:READ:`.
`func`	`((Key) -> R)`	Called with the new `Key`.

`delete subpath …`

Deletes a subkey.

Recursive deletion removes a registry link itself rather than traversing or modifying its target.

Parameters

Name	Type	Description
`subpath`	`Str`	Path to the subkey, relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.
`:all?`	`Bool`	Delete the subkey's values and descendants too. Without it a subkey that has children is refused.
`:ignore?`	`Bool`	Treat a missing subkey as success.

Errors

Exception	Condition
`sys.NotFoundError`	The subkey does not exist
`sys.DirectoryNotEmptyError`	The subkey has children and `all: true` was not passed

Example

winreg.open :CURRENT_USER: access: :READ_WRITE: do |root|
  root.delete "Software/MyApp"
  root.delete "Software/MyAppTree" all: true
  root.delete "Software/Missing" ignore: true

`delete_value name`

Deletes a value.

Parameters

Name	Type	Description
`name`	`Str`	Value name; `""` is the key's default value.

Errors

sys.NotFoundError when no value of that name exists.

Example

key.delete_value "installed"

`get name -> Data`

Reads a value's data.

Parameters

Name	Type	Description
`name`	`Str`	Value name; `""` is the key's default value.

Returns

The value's natural Do representation -- see Value.value for the mapping.

Errors

sys.NotFoundError when no value of that name exists. Use get_value to test for one instead.

Example

let temp = env.get "TEMP"

`get_value name -> (Value | nil)`

Reads a value as a Value, or nil when it does not exist.

Unlike get this never raises for a missing value, and it keeps the value's kind rather than only its coerced data -- use it to test for existence or to inspect a raw REG_* kind.

Parameters

Name	Type	Description
`name`	`Str`	Value name; `""` is the key's default value.

Example

let entry = env.get_value "TEMP"
if entry
  echo "TEMP is a $entry.kind value: $entry.value"
else
  echo "TEMP is not set"

`link target_root target_subpath link_subpath …`

Creates a registry link.

The target need not exist. Arguments follow ln -s ordering: target first, link last.

Parameters

Name	Type	Description
`target_root`	`RegistryRoot`	Registry root the target lives under.
`target_subpath`	`Str`	Target path relative to `target_root`.
`link_subpath`	`Str`	New link path relative to this key.
`:view?`	`RegistryView`	Registry view used for both the target mapping and the destination. Defaults to `:NATIVE:`.

Errors

Exception	Condition
`sys.AlreadyExistsError`	The destination already exists and was not modified
`sys.InvalidInputError`	A path contains NUL

Example

root.link :CURRENT_USER: r"Software\MyApp" "MyAppLink"

`open subpath … -> Key`

Opens a subkey.

Parameters

Name	Type	Description
`subpath`	`Str`	Path to the subkey, relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.
`:access?`	`AccessMaskSpec`	Access rights. Defaults to `:READ:`.
`:resolve?`	`LinkResolution`	Link resolution. Defaults to `:TARGET:`.

Errors

Exception	Condition
`sys.NotFoundError`	The subkey does not exist
`sys.PermissionDeniedError`	Access was denied

Example

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

`open[R] subpath func … -> R`

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

Parameters

Name	Type	Description
`subpath`	`Str`	Path to the subkey, relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.
`:access?`	`AccessMaskSpec`	Access rights. Defaults to `:READ:`.
`:resolve?`	`LinkResolution`	Link resolution. Defaults to `:TARGET:`.
`func`	`((Key) -> R)`	Called with the `Key`.

`read_link subpath … -> LinkTarget`

Reads a registry link without following it.

An alias root such as :CLASSES_ROOT: or :CURRENT_CONFIG: may report the physical :LOCAL_MACHINE: or :USERS: path backing it.

Parameters

Name	Type	Description
`subpath`	`Str`	Link path relative to this key.
`:view?`	`RegistryView`	Registry view. Defaults to `:NATIVE:`.

Errors

Exception	Condition
`sys.InvalidInputError`	The key is not a link
`sys.InvalidDataError`	The link value is malformed

Example

let target = root.read_link "MyAppLink"
echo $target.native

`sec_desc … -> security.windows.SecDesc`

Reads parts of the key's Windows security descriptor through its open handle.

The key must already hold the rights the requested components need.

Parameters

Name	Type	Description
`:owner?`	`Bool`	Load the owner SID. Defaults to `true`.
`:group?`	`Bool`	Load the primary group SID. Defaults to `true`.
`:dacl?`	`Bool`	Load the discretionary ACL. Defaults to `true`.
`:sacl?`	`Bool`	Load the system ACL. Defaults to `false`.

Example

let desc = key.sec_desc dacl: true owner: false group: false

`set name value …`

Writes a value.

Parameters

Name	Type	Description
`name`	`Str`	Value name; `""` is the key's default value.
`value`		The Do value to write.
`:kind?`	`ValueKind`	Value kind to store under. Omit to let the kind be decided from what is already there, or from `value` itself.

`:kind`

Without kind, value is coerced into whatever kind is already stored under name. An unrecognized raw REG_* kind -- see Value.kind -- round-trips by writing value back under the same raw kind, so it must be a Bin.

When no value exists yet, the kind comes from value's own Do type:

Do type	Kind
`Str`	`:SZ:`
`Iterable` of `Str`	`:MULTI_SZ:`
`Bool`	`:DWORD:`, with data `0` or `1`
`Int`	`:DWORD:` if it fits in 32 bits, else `:QWORD:`
`Bin`	`:BINARY:`
`nil`	`:NONE:`

Coercing a Bool into a DWORD or QWORD kind, whether existing or given here, keeps that kind; reading it back returns an Int.

Example

key.set "installed" true
key.set "path" r"C:\Program Files\MyApp"
key.set "tags" ["a", "b"]
key.set "raw" b"\x01\x02" kind: :BINARY:

`subkeys() -> Iter[Str]`

Lists the names of this key's immediate subkeys.

The enumeration is live: entries are fetched as iteration advances.

Returns

An Iter yielding Str. Its len is the count captured when the enumeration was opened.

Example

for name = key.subkeys()
  echo $name

`update_sec_desc ...options …`

Applies the components a Windows security descriptor's mask selects, through the key's open handle.

The key must already hold the rights the selected components need.

Parameters

Name	Type	Description
`desc?`	`security.windows.SecDescSpec`	Descriptor to apply.
`...options`		Components, as `sec_desc` takes them, instead of or alongside `desc`.

Example

key.update_sec_desc $desc
key.update_sec_desc dacl: $acl

`values() -> Iter[Value]`

Lists this key's values.

The enumeration is live: entries are fetched as iteration advances.

Returns

An Iter yielding Values. Its len is the count captured when the enumeration was opened.

Example

for entry = key.values()
  echo "$(entry.name) ($(entry.kind)): $(entry.value)"