Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.1

0.7.1 / src / files / directory.lucb

#==============================================================================================
#
#   directory - Directory streams and listing
#
#   DESCRIPTION:
#       An owned directory stream that yields entry names, opens children, and reads their
#       metadata, plus the whole listing as an owned result.
#
#==============================================================================================

## One owned directory stream; the zero value is closed. Copying does not duplicate
## ownership. Borrow it for iteration and serialize access to the stream.
pub struct Directory:
    var handle: void*?

    ## Open a close-on-exec directory stream. With follow_symlinks=false, refuse
    ## a final symlink; intermediate path components still resolve normally.
    pub static func open(path: c.str, follow_symlinks: bool = true) -> Directory!:
        return try open_directory_at(current_directory_fd, path, follow_symlinks)

    ## Borrow the descriptor until close. Do not close it or change its position.
    pub func descriptor() -> i32!:
        let directory = self.handle else error(io.closed, "the directory is closed")
        if platform.windows:
            return ((WinDirectory*)directory).descriptor
        else:
            let descriptor = dirfd(directory)
            if descriptor < 0:
                error(classify_error(c.errno()), "the directory has no usable descriptor")
            return descriptor

    ## Metadata for the opened directory, independent of its current pathname.
    pub func metadata() -> Metadata!:
        return try metadata_descriptor(try self.descriptor())

    ## Resolve a relative path from this open directory, even after it is renamed.
    ## Absolute paths use normal OS resolution. With follow_symlinks=false, inspect
    ## the final link itself. Separators and parent components retain OS semantics.
    pub func entry_metadata(path: c.str, follow_symlinks: bool = true) -> Metadata!:
        return try metadata_at(try self.descriptor(), path, follow_symlinks)

    ## Open a directory relative to this handle. The new stream owns a separate
    ## descriptor and position; closing either stream does not close the other.
    ## With follow_symlinks=false, refuse a final symlink atomically during open.
    pub func open_directory(path: c.str, follow_symlinks: bool = true) -> Directory!:
        return try open_directory_at(try self.descriptor(), path, follow_symlinks)

    ## Open a file relative to this directory. Absolute paths and parent segments
    ## retain OS semantics; callers implementing containment must walk validated
    ## individual components. Refusing symlinks applies atomically to the final
    ## component. Nonblocking mode prevents FIFO opens from waiting for a peer;
    ## it does not make ordinary filesystem I/O asynchronous.
    pub func open_file(path: c.str, mode: OpenMode = OpenMode.read, permissions: u32 = 420, follow_symlinks: bool = true, nonblocking: bool = false) -> File!:
        let parent = try self.descriptor()
        var flags = try file_open_flags(mode, permissions)
        if platform.windows:
            let joined = try windows_relative(parent, path)
            defer joined.release()
            return File(handle = try windows_open((c.str)joined.value, flags, permissions, follow_symlinks, nonblocking))
        else:
            if not follow_symlinks:
                flags |= no_follow_flag
            if nonblocking:
                flags |= nonblocking_open_flag
            var descriptor = openat(parent, path, flags, permissions)
            while descriptor < 0 and c.errno() == c.interrupted:
                descriptor = openat(parent, path, flags, permissions)
            if descriptor < 0:
                error(classify_error(c.errno()), "the directory-relative file could not be opened")
            return File(handle = descriptor)

    ## The next name excluding dot and dot-dot, or none at end. Names are raw path
    ## bytes, NUL-terminated but not guaranteed UTF-8. The view expires on the next
    ## call or close.
    pub func next() -> str?!:
        let directory = self.handle else error(io.closed, "the directory is closed")
        while true:
            let name = try next_entry(directory) else return none
            if name != "." and name != "..":
                return name

    ## Consume ownership even on failure; repeated calls on this value are safe.
    pub func close() -> !:
        let directory = self.handle else return
        self.handle = none
        if platform.windows:
            try windows_directory_close((WinDirectory*)directory)
            return
        else:
            if closedir(directory) != 0:
                error(classify_error(c.errno()), "the directory could not be closed")

    ## Best-effort unwind cleanup; use close to observe an error on the success path.
    pub func destroy():
        self.close() catch failure:
            _ = failure

## Acquire a descriptor first so CLOEXEC and final-symlink policy are atomic.
## fdopendir takes ownership only on success; capture errno before closing on failure.
func open_directory_at(parent: i32, path: c.str, follow_symlinks: bool) -> Directory!:
    if platform.windows:
        return try windows_directory_open(parent, path, follow_symlinks)
    else:
        var flags = directory_flag | close_on_exec
        if not follow_symlinks:
            flags |= no_follow_flag
        var descriptor = openat(parent, path, flags)
        while descriptor < 0 and c.errno() == c.interrupted:
            descriptor = openat(parent, path, flags)
        if descriptor < 0:
            error(classify_error(c.errno()), "the directory could not be opened")
        if let stream = fdopendir(descriptor):
            return Directory(handle = stream)
        let number = c.errno()
        _ = close(descriptor)
        error(classify_error(number), "the directory stream could not be created")

# mark: Listing ===============================================================================

## The names in a directory, sorted by bytes, without `.` and `..`. The result owns the
## names: Luce copies them into a `list[str]`; a Base caller reads `.value` and calls
## `release()`. Each name is NUL-terminated, so it may be passed on as a `c.str`. On a
## failure nothing allocated is kept and the directory is closed.
pub func list(path: c.str) -> interop.Owned[const str[]]!:
    var directory = try Directory.open(path)
    defer directory.destroy()
    var names: owned.Gathered
    errdefer names.release()
    while let name = try directory.next():
        try names.add(name)
    try directory.close()
    # Heapsort-backed introsort: O(n log n) without a second allocation or a
    # recursion depth that depends on the filesystem's enumeration order.
    sort.sort(names.view())
    return try names.finish()