lx-ls 0.8.0

//! Wrapper types for the values returned from `File`s.
//!
//! The methods of `File` that return information about the entry on the
//! filesystem -- size, modification date, block count, or Git status -- used
//! to just return these as formatted strings, but this became inflexible once
//! customisable output styles landed.
//!
//! Instead, they will return a wrapper type from this module, which tags the
//! type with what field it is while containing the actual raw value.
//!
//! The `output::details` module, among others, uses these types to render and
//! display the information as formatted strings.

// C-style `blkcnt_t` types don’t follow Rust’s rules!
#![allow(non_camel_case_types)]
#![allow(clippy::struct_excessive_bools)]


/// The type of a file’s block count.
pub type blkcnt_t = u64;

/// The type of a file’s group ID.
pub type gid_t = u32;

/// The type of a file’s inode.
pub type ino_t = u64;

/// The type of a file’s number of links.
pub type nlink_t = u64;


/// The type of a file’s user ID.
pub type uid_t = u32;


/// The file’s base type, which gets displayed in the very first column of the
/// details output.
///
/// This type is set entirely by the filesystem, rather than relying on a
/// file’s contents. So “link” is a type, but “image” is just a type of
/// regular file. (See the `filetype` module for those checks.)
///
/// Its ordering is used when sorting by type.
#[derive(PartialEq, Eq, PartialOrd, Ord, Copy, Clone)]
pub enum Type {
    Directory,
    File,
    Link,
    Pipe,
    Socket,
    CharDevice,
    BlockDevice,
    Special,
}

impl Type {
    pub fn is_regular_file(self) -> bool {
        matches!(self, Self::File)
    }
}


/// The file’s Unix permission bitfield, with one entry per bit.
#[derive(Copy, Clone)]
pub struct Permissions {
    pub user_read:      bool,
    pub user_write:     bool,
    pub user_execute:   bool,

    pub group_read:     bool,
    pub group_write:    bool,
    pub group_execute:  bool,

    pub other_read:     bool,
    pub other_write:    bool,
    pub other_execute:  bool,

    pub sticky:         bool,
    pub setgid:         bool,
    pub setuid:         bool,
}

/// The file's `FileAttributes` field, available only on Windows.
#[cfg(windows)]
#[derive(Copy, Clone)]
pub struct Attributes {
    pub archive:         bool,
    pub directory:       bool,
    pub readonly:        bool,
    pub hidden:          bool,
    pub system:          bool,
    pub reparse_point:   bool,
}

/// The three pieces of information that are displayed as a single column in
/// the details view. These values are fused together to make the output a
/// little more compressed.
#[derive(Copy, Clone)]
pub struct PermissionsPlus {
    pub file_type:   Type,
    #[cfg(unix)]
    pub permissions: Permissions,
    #[cfg(windows)]
    pub attributes:  Attributes,
    pub xattrs:      bool,
}


/// The permissions encoded as octal values
#[derive(Copy, Clone)]
pub struct OctalPermissions {
    pub permissions: Permissions,
}

/// A file’s number of hard links on the filesystem.
///
/// Under Unix, a file can exist on the filesystem only once but appear in
/// multiple directories. However, it’s rare (but occasionally useful!) for a
/// regular file to have a link count greater than 1, so we highlight the
/// block count specifically for this case.
#[derive(Copy, Clone)]
pub struct Links {

    /// The actual link count.
    pub count: nlink_t,

    /// Whether this file is a regular file with more than one hard link.
    pub multiple: bool,
}


/// A file’s inode. Every directory entry on a Unix filesystem has an inode,
/// including directories and links, so this is applicable to everything lx
/// can deal with.
#[derive(Copy, Clone)]
pub struct Inode(pub ino_t);


/// The number of blocks that a file takes up on the filesystem, if any.
#[derive(Copy, Clone)]
pub enum Blocks {

    /// This file has the given number of blocks.
    Some(blkcnt_t),

    /// This file isn’t of a type that can take up blocks.
    None,
}


/// The ID of the user that owns a file. This will only ever be a number;
/// looking up the username is done in the `display` module.
#[derive(Copy, Clone)]
pub struct User(pub uid_t);

/// The ID of the group that a file belongs to.
#[derive(Copy, Clone)]
pub struct Group(pub gid_t);


/// A file’s size, in bytes. This is usually formatted by the `unit_prefix`
/// crate into something human-readable.
#[derive(Copy, Clone)]
pub enum Size {

    /// This file has a defined size.
    Some(u64),

    /// This file has no size, or has a size but we aren’t interested in it.
    ///
    /// Under Unix, directory entries that aren’t regular files will still
    /// have a file size. For example, a directory will just contain a list of
    /// its files as its “contents” and will be specially flagged as being a
    /// directory, rather than a file. However, seeing the “file size” of this
    /// data is rarely useful — I can’t think of a time when I’ve seen it and
    /// learnt something. So we discard it and just output “-” instead.
    ///
    /// See this answer for more: <https://unix.stackexchange.com/a/68266>
    None,

    /// This file is a block or character device, so instead of a size, print
    /// out the file’s major and minor device IDs.
    ///
    /// This is what ls does as well. Without it, the devices will just have
    /// file sizes of zero.
    DeviceIDs(DeviceIDs),
}

/// The major and minor device IDs that gets displayed for device files.
///
/// You can see what these device numbers mean:
/// - <http://www.lanana.org/docs/device-list/>
/// - <http://www.lanana.org/docs/device-list/devices-2.6+.txt>
#[derive(Copy, Clone)]
pub struct DeviceIDs {
    pub major: u8,
    pub minor: u8,
}



/// A file’s status in a VCS repository.  Backend-agnostic: used for both
/// git and jj.
#[derive(PartialEq, Eq, Copy, Clone)]
pub enum VcsStatus {

    /// This file hasn’t changed since the last commit.
    NotModified,

    /// This file is new (added, not previously tracked).
    New,

    /// A file that’s been modified since the last commit.
    Modified,

    /// A deleted file. This can’t ever be shown, but it’s here anyway!
    Deleted,

    /// A file that the VCS has tracked a rename for.
    Renamed,

    /// A file that’s had its type (such as the file permissions) changed.
    TypeChange,

    /// A file that’s ignored (matches a VCS ignore pattern).
    Ignored,

    /// A file that’s updated but unmerged (conflicted).
    Conflicted,

    /// A file that’s been copied (jj tracks copies).
    Copied,

    /// A file that exists on disk but is not tracked by the VCS.
    Untracked,
}


/// A file’s complete VCS status.  For git this has separate staged and
/// unstaged status; for jj (which has no staging area) both fields hold
/// the same value.
#[derive(Copy, Clone)]
pub struct VcsFileStatus {
    pub staged:   VcsStatus,
    pub unstaged: VcsStatus,
}

impl Default for VcsFileStatus {
    fn default() -> Self {
        Self {
            staged: VcsStatus::NotModified,
            unstaged: VcsStatus::NotModified,
        }
    }
}

// Convenience aliases so existing `f::Git` / `f::GitStatus` references
// continue to compile during the migration.
pub type Git = VcsFileStatus;
pub type GitStatus = VcsStatus;


/// BSD/macOS file flags from `st_flags` (see `chflags(1)`).
///
/// On platforms without `st_flags`, the flags value is always 0.
#[derive(Debug, Copy, Clone)]
pub struct FileFlags(pub u32);

impl FileFlags {
    /// Well-known BSD file flag bits.
    // User flags (UF_*)
    pub const UF_NODUMP:     u32 = 0x0000_0001;
    pub const UF_IMMUTABLE:  u32 = 0x0000_0002;
    pub const UF_APPEND:     u32 = 0x0000_0004;
    pub const UF_OPAQUE:     u32 = 0x0000_0008;
    pub const UF_NOUNLINK:   u32 = 0x0000_0010;  // FreeBSD
    pub const UF_COMPRESSED: u32 = 0x0000_0020;  // macOS/FreeBSD
    pub const UF_TRACKED:    u32 = 0x0000_0040;  // FreeBSD
    pub const UF_SYSTEM:     u32 = 0x0000_0080;  // FreeBSD: Windows system bit
    pub const UF_SPARSE:     u32 = 0x0000_0100;  // FreeBSD
    pub const UF_OFFLINE:    u32 = 0x0000_0200;  // FreeBSD
    pub const UF_REPARSE:    u32 = 0x0000_0400;  // FreeBSD: Windows reparse point
    pub const UF_ARCHIVE:    u32 = 0x0000_0800;  // FreeBSD: user archive
    pub const UF_READONLY:   u32 = 0x0000_1000;  // FreeBSD: Windows readonly
    pub const UF_HIDDEN:     u32 = 0x0000_8000;  // macOS/FreeBSD
    // System flags (SF_*)
    pub const SF_ARCHIVED:   u32 = 0x0001_0000;
    pub const SF_IMMUTABLE:  u32 = 0x0002_0000;
    pub const SF_APPEND:     u32 = 0x0004_0000;
    pub const SF_NOUNLINK:   u32 = 0x0010_0000;  // FreeBSD
    pub const SF_SNAPSHOT:   u32 = 0x0020_0000;  // FreeBSD

    // Linux file attributes (FS_IOC_GETFLAGS) — different bit layout.
    pub const FS_SECRM:       u32 = 0x0000_0001;
    pub const FS_UNRM:        u32 = 0x0000_0002;
    pub const FS_COMPR:       u32 = 0x0000_0004;
    pub const FS_SYNC:        u32 = 0x0000_0008;
    pub const FS_IMMUTABLE:   u32 = 0x0000_0010;
    pub const FS_APPEND:      u32 = 0x0000_0020;
    pub const FS_NODUMP:      u32 = 0x0000_0040;
    pub const FS_NOATIME:     u32 = 0x0000_0080;
    pub const FS_ENCRYPT:     u32 = 0x0000_0800;
    pub const FS_JOURNAL:     u32 = 0x0000_4000;
    pub const FS_NOTAIL:      u32 = 0x0000_8000;
    pub const FS_DIRSYNC:     u32 = 0x0001_0000;
    pub const FS_TOPDIR:      u32 = 0x0002_0000;
    pub const FS_EXTENT:      u32 = 0x0008_0000;
    pub const FS_VERITY:      u32 = 0x0010_0000;
    pub const FS_NOCOW:       u32 = 0x0080_0000;
    pub const FS_DAX:         u32 = 0x0200_0000;
    pub const FS_PROJINHERIT: u32 = 0x2000_0000;
    pub const FS_CASEFOLD:    u32 = 0x4000_0000;

    /// Return a short string representation of the flags.
    /// Returns "-" if no flags are set.
    ///
    /// On BSD/macOS, names match `chflags(1)` / `ls -lO` output.
    /// On Linux, names match `chattr(1)` / `lsattr` conventions.
    pub fn to_short_string(self) -> String {
        if self.0 == 0 {
            return "-".to_string();
        }

        let mut parts = Vec::new();

        #[cfg(any(target_os = "macos", target_os = "freebsd"))]
        {
            // BSD user flags — names match chflags(1).
            if self.0 & Self::UF_NODUMP     != 0 { parts.push("nodump"); }
            if self.0 & Self::UF_IMMUTABLE  != 0 { parts.push("uchg"); }
            if self.0 & Self::UF_APPEND     != 0 { parts.push("uappnd"); }
            if self.0 & Self::UF_OPAQUE     != 0 { parts.push("opaque"); }
            if self.0 & Self::UF_NOUNLINK   != 0 { parts.push("uunlnk"); }
            if self.0 & Self::UF_COMPRESSED != 0 { parts.push("compressed"); }
            if self.0 & Self::UF_TRACKED    != 0 { parts.push("tracked"); }
            if self.0 & Self::UF_SYSTEM     != 0 { parts.push("system"); }
            if self.0 & Self::UF_SPARSE     != 0 { parts.push("sparse"); }
            if self.0 & Self::UF_OFFLINE    != 0 { parts.push("offline"); }
            if self.0 & Self::UF_REPARSE    != 0 { parts.push("reparse"); }
            if self.0 & Self::UF_ARCHIVE    != 0 { parts.push("uarch"); }
            if self.0 & Self::UF_READONLY   != 0 { parts.push("rdonly"); }
            if self.0 & Self::UF_HIDDEN     != 0 { parts.push("hidden"); }
            // BSD system flags
            if self.0 & Self::SF_ARCHIVED   != 0 { parts.push("arch"); }
            if self.0 & Self::SF_IMMUTABLE  != 0 { parts.push("schg"); }
            if self.0 & Self::SF_APPEND     != 0 { parts.push("sappnd"); }
            if self.0 & Self::SF_NOUNLINK   != 0 { parts.push("sunlnk"); }
            if self.0 & Self::SF_SNAPSHOT   != 0 { parts.push("snapshot"); }
        }

        #[cfg(target_os = "linux")]
        {
            // Linux attributes — names match chattr(1) conventions.
            if self.0 & Self::FS_SECRM       != 0 { parts.push("secrm"); }
            if self.0 & Self::FS_UNRM        != 0 { parts.push("unrm"); }
            if self.0 & Self::FS_COMPR       != 0 { parts.push("compr"); }
            if self.0 & Self::FS_SYNC        != 0 { parts.push("sync"); }
            if self.0 & Self::FS_IMMUTABLE   != 0 { parts.push("immutable"); }
            if self.0 & Self::FS_APPEND      != 0 { parts.push("append"); }
            if self.0 & Self::FS_NODUMP      != 0 { parts.push("nodump"); }
            if self.0 & Self::FS_NOATIME     != 0 { parts.push("noatime"); }
            if self.0 & Self::FS_ENCRYPT     != 0 { parts.push("encrypt"); }
            if self.0 & Self::FS_JOURNAL     != 0 { parts.push("journal"); }
            if self.0 & Self::FS_NOTAIL      != 0 { parts.push("notail"); }
            if self.0 & Self::FS_DIRSYNC     != 0 { parts.push("dirsync"); }
            if self.0 & Self::FS_TOPDIR      != 0 { parts.push("topdir"); }
            if self.0 & Self::FS_EXTENT      != 0 { parts.push("extent"); }
            if self.0 & Self::FS_VERITY      != 0 { parts.push("verity"); }
            if self.0 & Self::FS_NOCOW       != 0 { parts.push("nocow"); }
            if self.0 & Self::FS_DAX         != 0 { parts.push("dax"); }
            if self.0 & Self::FS_PROJINHERIT != 0 { parts.push("projinherit"); }
            if self.0 & Self::FS_CASEFOLD    != 0 { parts.push("casefold"); }
        }

        if parts.is_empty() {
            // Unknown flags — show hex.
            format!("0x{:x}", self.0)
        } else {
            parts.join(",")
        }
    }
}


/// Per-directory VCS repository status, for the `--vcs-repos` column.
#[derive(Debug, Clone)]
pub enum VcsRepoStatus {
    /// This directory is not a VCS repository root.
    None,
    /// This directory is a VCS repository root.
    Repo {
        /// Which backend: "git" or "jj".
        backend: &'static str,
        /// Whether the working copy is clean (no uncommitted changes).
        clean: bool,
        /// The current branch or bookmark name (if detectable).
        branch: Option<String>,
    },
}