Luce packages
LuceLuce BaseLuciaOS

dymokomi/luce-std

Source of release 0.7.2

0.7.2 / src / paths.lucb

#==============================================================================================
#
#   paths - Lexical filesystem paths
#
#   DESCRIPTION:
#       Lexical filesystem paths. Both slash styles separate components on Windows; on POSIX a
#       backslash is an ordinary filename byte. No operation touches the disk.
#
#==============================================================================================

import strings
import platform
import core
import interop
import owned

## Whether `byte` separates path components on the target.
# mark: Paths =================================================================================

## Whether `byte` separates path components on this target.
pub func separator(byte: u8) -> bool:
    return byte == '/' or (platform.windows and byte == 92)

func last_separator(path: str) -> usize?:
    var index = path.length
    while index > 0:
        index -= 1
        if separator(path.bytes[index]):
            return index
    return none

func drive_prefix(path: str) -> bool:
    # Each platform is a branch of its own, so neither leaves code unreachable.
    if platform.windows:
        if path.length < 2 or path.bytes[1] != ':':
            return false
        let drive = path.bytes[0]
        return (drive >= 'A' and drive <= 'Z') or (drive >= 'a' and drive <= 'z')
    else:
        return false

## The volume and root prefix, preserved verbatim. A drive-relative `C:foo` has
## root `C:`; a UNC share is indivisible, including its optional trailing separator.
pub func root(path: str) -> str:
    if drive_prefix(path):
        let count: usize = 3 if path.length > 2 and separator(path.bytes[2]) else 2
        return (str)path.bytes[..<count]
    if path.length == 0 or not separator(path.bytes[0]):
        return ""
    if platform.windows:
        if path.length < 2 or not separator(path.bytes[1]):
            return (str)path.bytes[..<1]
        return share_root(path)
    else:
        return (str)path.bytes[..<1]

## A Windows root beginning with two separators: a device namespace (`\\?\`,
## `\\.\`) or a UNC share, which is indivisible.
func share_root(path: str) -> str:
    var start: usize = 2
    # Extended DOS and UNC namespaces retain the prefix at the OS boundary.
    if path.length >= 4 and (path.bytes[2] == '?' or path.bytes[2] == '.') and separator(path.bytes[3]):
        start = 4
        if path.length >= 8 and ((str)path.bytes[4..<7] == "UNC" or (str)path.bytes[4..<7] == "unc") and separator(path.bytes[7]):
            start = 8
        else:
            while start < path.length and not separator(path.bytes[start]):
                start += 1
            return (str)path.bytes[..<(start + 1 if start < path.length else start)]
    # The server and share name together identify a UNC volume.
    var components: usize = 0
    while start < path.length:
        if separator(path.bytes[start]):
            components += 1
            if components == 2:
                return (str)path.bytes[..<start + 1]
        start += 1
    return path

## Rooted paths may still depend on the current drive (`\foo`) or that drive's
## current directory (`C:foo`). Only `is_absolute` promises independence from cwd.
pub func is_rooted(path: str) -> bool:
    return root(path).length > 0

## Whether `path` begins at a filesystem root.
pub func is_absolute(path: str) -> bool:
    if drive_prefix(path):
        return path.length >= 3 and separator(path.bytes[2])
    if path.length == 0 or not separator(path.bytes[0]):
        return false
    if platform.windows:
        return share_absolute(path)
    else:
        return true

## Whether a Windows path from a separator names a whole share: two separators,
## then a nonempty server and share (or a device namespace component).
func share_absolute(path: str) -> bool:
    if path.length < 2 or not separator(path.bytes[1]):
        return false
    var index: usize = 2
    while index < path.length and not separator(path.bytes[index]):
        index += 1
    return index > 2 and index + 1 < path.length and not separator(path.bytes[index + 1])

## Everything up to the last separator, or `.` when there is none.
pub func directory(path: str) -> str:
    let prefix = root(path)
    let cut = last_separator(path) else return prefix if prefix.length > 0 else "."
    if cut < prefix.length:
        return prefix
    return (str)path.bytes[..<cut]

## The last component.
pub func base(path: str) -> str:
    let prefix = root(path)
    if prefix.length == path.length:
        return ""
    let cut = last_separator(path) else return (str)path.bytes[prefix.length..]
    return (str)path.bytes[cut + 1..]

## The extension with its dot, or the empty text.
pub func extension(path: str) -> str:
    let name = base(path)
    let dot = strings.last(name, '.') else return ""
    if dot == 0:
        return ""
    return (str)name.bytes[dot..]

## The last component without its extension.
pub func stem(path: str) -> str:
    let name = base(path)
    let ext = extension(name)
    return (str)name.bytes[..<name.length - ext.length]

## Join with a separator only when needed; an absolute right path wins. This is
## lexical joining, without normalization or filesystem access. The result owns its
## NUL-terminated text: a Base caller passes `.value` on (as a `c.str` too) and calls
## `release()`; `join_into` joins into the caller's own storage instead.
pub func join(left: str, right: str) -> interop.Owned[str]!:
    return try owned.adopt_text(try join_text(left, right))

func join_text(left: str, right: str) -> str!:
    if is_absolute(right) or drive_prefix(right) or left.length == 0:
        return try strings.copy(right)
    if platform.windows and is_rooted(right):
        let prefix = root(left)
        var end = prefix.length
        while end > 0 and separator(prefix.bytes[end - 1]):
            end -= 1
        let rooted_pieces: str[2] = [(str)prefix.bytes[..<end], right]
        return try strings.join(rooted_pieces, "")
    let drive_only = drive_prefix(left) and left.length == 2
    let delimiter = "" if separator(left.bytes[left.length - 1]) or drive_only else "/"
    let pieces: str[2] = [left, right]
    return try strings.join(pieces, delimiter)

## The join rule, appended to a caller's buffer. Shared by `join_into`.
func join_write(b: core.FormatBuffer*, left: str, right: str):
    if is_absolute(right) or drive_prefix(right) or left.length == 0:
        _ = core.format_put(b, right.bytes.data, right.length)
        return
    if platform.windows and is_rooted(right):
        let prefix = root(left)
        var end = prefix.length
        while end > 0 and separator(prefix.bytes[end - 1]):
            end -= 1
        _ = core.format_put(b, prefix.bytes.data, end)
        _ = core.format_put(b, right.bytes.data, right.length)
        return
    let drive_only = drive_prefix(left) and left.length == 2
    _ = core.format_put(b, left.bytes.data, left.length)
    if not (separator(left.bytes[left.length - 1]) or drive_only):
        _ = core.format_put(b, "/".bytes.data, 1)
    _ = core.format_put(b, right.bytes.data, right.length)

## Join into `buffer` without allocating, returning a view of it, or "" when it does
## not fit. Same rule as `join`, but the caller owns the storage — a stack array or an
## arena — so there is nothing to release and the result lives as long as `buffer`. It is
## NUL-terminated when there is room, so it may be used as a `c.str`.
pub func join_into(buffer: u8[], left: str, right: str) -> str:
    var b = core.FormatBuffer(data = buffer.data, capacity = buffer.length, used = 0)
    join_write(&b, left, right)
    # A path cut short names another file: one that does not fit (with its NUL) is "".
    if b.used >= b.capacity:
        if buffer.length > 0:
            buffer[0] = 0
        return ""
    return core.format_finish(&b)

## Lexically remove dot components, redundant separators and cancellable parent
## components. This does not resolve symbolic links; use filesystem resolution
## when identity matters. Roots cannot be crossed. Relative leading parents and
## Windows drive-relative prefixes are retained. The result owns its NUL-terminated
## text, as `join`'s does.
pub func normalize(path: str) -> interop.Owned[str]!:
    let prefix = root(path)
    let buffer = try new u8[path.length + 2] ---
    defer free(buffer)
    let starts = try new usize[path.length + 1] ---
    defer free(starts)
    var used = prefix.length
    for index in 0..<used: buffer[index] = prefix.bytes[index]
    var count: usize = 0
    var at = prefix.length
    let bounded = prefix.length > 0 and not (drive_prefix(path) and prefix.length == 2)
    while at < path.length:
        while at < path.length and separator(path.bytes[at]): at += 1
        let begin = at
        while at < path.length and not separator(path.bytes[at]): at += 1
        let component = (str)path.bytes[begin..<at]
        if component.length == 0 or component == ".": continue
        if component == "..":
            if count > 0:
                var previous = starts[count - 1]
                if previous < used and separator(buffer[previous]): previous += 1
                if (str)buffer[previous..<used] != "..":
                    used = starts[count - 1]
                    count -= 1
                    continue
            elif bounded:
                continue
        starts[count] = used
        count += 1
        if used > 0 and not separator(buffer[used - 1]) and not (used == 2 and drive_prefix(path)):
            buffer[used] = 47
            used += 1
        for byte in component.bytes:
            buffer[used] = byte
            used += 1
    return try owned.copy_text("." if used == 0 else (str)buffer[..<used])