Path

fs.Path using Windows path syntax.

See fs.Path for the fields, methods, and operators every path shares; the members below are Windows-specific.

Alternate Data Streams

The final component may name an NTFS alternate data stream by appending :stream, optionally followed by :$TYPE:

let path = Path r"file.txt:zone:$DATA"
echo $path.name         # file.txt
echo $path.stream_name  # zone
echo $path.stream_type  # DATA

A stream suffix that names more than a stream and a type, or whose type is missing its leading $, raises a ValueError.

name, stem, and ext describe the file the stream belongs to, and the methods that rewrite them — add_ext, with_ext, without_ext, with_name, and with_stem — leave the stream attached to the renamed file:

let path = Path r"report.txt:zone:$DATA"
echo (path.add_ext "gz")       # report.txt.gz:zone:$DATA
echo (path.with_stem "sales")  # sales.txt:zone:$DATA

components yields the final component as it is spelled, suffix included. The / operator names a different file rather than a stream of this one, so the stream does not carry over:

let path = Path r"dir:zone:$DATA"
echo (path / "file.txt")  # dir\file.txt

Constructor

`Path path`

Converts a string or another path to a Windows path.

Converting a Unix path is allowed only when it is relative.

Parameters

Name	Type	Description
`path`	`(Str \| Path)`	Path value.

Fields

device @ (Str | nil)

Device namespace name for \\.\name paths, or nil otherwise.

let path = Path r"\\.\COM42"
echo $path.device  # COM42

disk @ (Str | nil)

Drive letter for C:-style and \\?\C:-style prefixes, or nil otherwise.

let path = Path "C:/work/file.txt"
echo $path.disk  # C

is_verbatim @ Bool

Whether the path uses a verbatim \\?\ prefix.

let path = Path r"\\?\C:\work\file.txt"
echo $path.is_verbatim  # true

server @ (Str | nil)

UNC server name, or nil if the path does not use a UNC prefix.

let path = Path "//server/share/file.txt"
echo $path.server  # server

share @ (Str | nil)

UNC share name, or nil if the path does not use a UNC prefix.

let path = Path "//server/share/file.txt"
echo $path.share  # share

stream_name @ (Str | nil)

Alternate data stream name, or nil if no stream is specified.

let path = Path "file.txt:zone"
echo $path.name         # file.txt
echo $path.stream_name  # zone

stream_type @ (Str | nil)

Alternate data stream type without the leading $.

This is nil when no alternate data stream was specified, or one was specified without an explicit type.

let path = Path "file.txt:zone:$DATA"
echo $path.stream_type  # DATA

Methods

`sec_desc … -> security.windows.SecDesc`

Gets selected parts of the Windows security descriptor.

SACL access requires SeSecurityPrivilege.

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`.
`:resolve?`	`fs.Resolve`	Resolution mode. Defaults to `:TARGET:`.

`streams … -> Iter[StreamEntry]`

Lists alternate data streams for this path.

Parameters

Name	Type	Description
`:resolve?`	`fs.Resolve`	Resolution mode. Defaults to `:TARGET:`.

Example

let path = Path "data.txt"
for stream = path.streams()
  echo "$(stream.name) $(stream.type)"
  echo (path / stream)

`update_sec_desc ...options …`

Applies the components selected by a SecDesc's mask.

Windows may normalize the descriptor when associating it with the filesystem object.

Parameters

Name	Type	Description
`desc?`	`security.windows.SecDescSpec`	Descriptor to apply.
`:resolve?`	`fs.Resolve`	Resolution mode. Defaults to `:TARGET:`.
`...options`		Components, as `sec_desc` takes them, instead of or alongside `desc`.

Example

path.update_sec_desc
  owner: :BUILTIN_ADMINISTRATORS:
  dacl_protected: true
  dacl:
    - allow: :LOCAL_SYSTEM:
      mask: :GENERIC_ALL:
    - allow: :BUILTIN_ADMINISTRATORS:
      mask: :GENERIC_ALL: