path: root/src/file.rs

//! Files, and methods and fields to access their metadata.

use std::ascii::AsciiExt;
use std::env::current_dir;
use std::fs;
use std::io;
use std::os::unix::fs::{MetadataExt, PermissionsExt};
use std::path::{Component, Path, PathBuf};

use unicode_width::UnicodeWidthStr;

use dir::Dir;

use self::fields as f;


/// Constant table copied from https://doc.rust-lang.org/src/std/sys/unix/ext/fs.rs.html#11-259
/// which is currently unstable and lacks vision for stabilization,
/// see https://github.com/rust-lang/rust/issues/27712
#[allow(dead_code)]
mod modes {
    use std::os::unix::raw;

    pub const USER_READ: raw::mode_t = 0o400;
    pub const USER_WRITE: raw::mode_t = 0o200;
    pub const USER_EXECUTE: raw::mode_t = 0o100;
    pub const USER_RWX: raw::mode_t = 0o700;
    pub const GROUP_READ: raw::mode_t = 0o040;
    pub const GROUP_WRITE: raw::mode_t = 0o020;
    pub const GROUP_EXECUTE: raw::mode_t = 0o010;
    pub const GROUP_RWX: raw::mode_t = 0o070;
    pub const OTHER_READ: raw::mode_t = 0o004;
    pub const OTHER_WRITE: raw::mode_t = 0o002;
    pub const OTHER_EXECUTE: raw::mode_t = 0o001;
    pub const OTHER_RWX: raw::mode_t = 0o007;
    pub const ALL_READ: raw::mode_t = 0o444;
    pub const ALL_WRITE: raw::mode_t = 0o222;
    pub const ALL_EXECUTE: raw::mode_t = 0o111;
    pub const ALL_RWX: raw::mode_t = 0o777;
    pub const SETUID: raw::mode_t = 0o4000;
    pub const SETGID: raw::mode_t = 0o2000;
    pub const STICKY_BIT: raw::mode_t = 0o1000;
}


/// A **File** is a wrapper around one of Rust's Path objects, along with
/// associated data about the file.
///
/// Each file is definitely going to have its filename displayed at least
/// once, have its file extension extracted at least once, and have its metadata
/// information queried at least once, so it makes sense to do all this at the
/// start and hold on to all the information.
pub struct File<'dir> {

    /// This file's name, as a UTF-8 encoded String.
    pub name: String,

    /// The file's name's extension, if present, extracted from the name. This
    /// is queried a lot, so it's worth being cached.
    pub ext: Option<String>,

    /// The path that begat this file. Even though the file's name is
    /// extracted, the path needs to be kept around, as certain operations
    /// involve looking up the file's absolute location (such as the Git
    /// status, or searching for compiled files).
    pub path: PathBuf,

    /// A cached `metadata` call for this file. This is queried multiple
    /// times, and is *not* cached by the OS, as it could easily change
    /// between invocations - but exa is so short-lived it's better to just
    /// cache it.
    pub metadata: fs::Metadata,

    /// A reference to the directory that contains this file, if present.
    ///
    /// Filenames that get passed in on the command-line directly will have no
    /// parent directory reference - although they technically have one on the
    /// filesystem, we'll never need to look at it, so it'll be `None`.
    /// However, *directories* that get passed in will produce files that
    /// contain a reference to it, which is used in certain operations (such
    /// as looking up a file's Git status).
    pub dir: Option<&'dir Dir>,
}

impl<'dir> File<'dir> {

    /// Create a new `File` object from the given `Path`, inside the given
    /// `Dir`, if appropriate.
    ///
    /// This uses `symlink_metadata` instead of `metadata`, which doesn't
    /// follow symbolic links.
    pub fn from_path(path: &Path, parent: Option<&'dir Dir>) -> io::Result<File<'dir>> {
        fs::symlink_metadata(path).map(|metadata| File::with_metadata(metadata, path, parent))
    }

    /// Create a new File object from the given metadata result, and other data.
    pub fn with_metadata(metadata: fs::Metadata, path: &Path, parent: Option<&'dir Dir>) -> File<'dir> {
        let filename = path_filename(path);

        File {
            path:      path.to_path_buf(),
            dir:       parent,
            metadata:  metadata,
            ext:       ext(&filename),
            name:      filename.to_string(),
        }
    }

    /// Whether this file is a directory on the filesystem.
    pub fn is_directory(&self) -> bool {
        self.metadata.is_dir()
    }

    /// If this file is a directory on the filesystem, then clone its
    /// `PathBuf` for use in one of our own `Dir` objects, and read a list of
    /// its contents.
    ///
    /// Returns an IO error upon failure, but this shouldn't be used to check
    /// if a `File` is a directory or not! For that, just use `is_directory()`.
    pub fn to_dir(&self, scan_for_git: bool) -> io::Result<Dir> {
        Dir::read_dir(&*self.path, scan_for_git)
    }

    /// Whether this file is a regular file on the filesystem - that is, not a
    /// directory, a link, or anything else treated specially.
    pub fn is_file(&self) -> bool {
        self.metadata.is_file()
    }

    /// Whether this file is both a regular file *and* executable for the
    /// current user. Executable files have different semantics than
    /// executable directories, and so should be highlighted differently.
    pub fn is_executable_file(&self) -> bool {
        let bit = modes::USER_EXECUTE;
        self.is_file() && (self.metadata.permissions().mode() & bit) == bit
    }

    /// Whether this file is a symlink on the filesystem.
    pub fn is_link(&self) -> bool {
        self.metadata.file_type().is_symlink()
    }

    /// Whether this file is a named pipe on the filesystem.
    pub fn is_pipe(&self) -> bool {
        false  // TODO: Still waiting on this one...
    }

    /// Whether this file is a dotfile, based on its name. In Unix, file names
    /// beginning with a dot represent system or configuration files, and
    /// should be hidden by default.
    pub fn is_dotfile(&self) -> bool {
        self.name.starts_with(".")
    }

    /// Constructs the 'path prefix' of this file, which is the portion of the
    /// path up to, but not including, the file name.
    ///
    /// This gets used when displaying the path a symlink points to. In
    /// certain cases, it may return an empty-length string. Examples:
    ///
    /// - `code/exa/file.rs` has `code/exa/` as its prefix, including the
    ///   trailing slash.
    /// - `code/exa` has just `code/` as its prefix.
    /// - `code` has the empty string as its prefix.
    /// - `/` also has the empty string as its prefix. It does not have a
    ///   trailing slash, as the slash constitutes the 'name' of this file.
    pub fn path_prefix(&self) -> String {
        let components: Vec<Component> = self.path.components().collect();
        let mut path_prefix = String::new();

        // This slicing is safe as components always has the RootComponent
        // as the first element.
        for component in components[..(components.len() - 1)].iter() {
            path_prefix.push_str(&*component.as_os_str().to_string_lossy());

            if component != &Component::RootDir {
                path_prefix.push_str("/");
            }
        }
        path_prefix
    }

    /// The Unicode 'display width' of the filename.
    ///
    /// This is related to the number of graphemes in the string: most
    /// characters are 1 columns wide, but in some contexts, certain
    /// characters are actually 2 columns wide.
    pub fn file_name_width(&self) -> usize {
        UnicodeWidthStr::width(&self.name[..])
    }

    /// Assuming the current file is a symlink, follows the link and
    /// returns a File object from the path the link points to.
    ///
    /// If statting the file fails (usually because the file on the
    /// other end doesn't exist), returns the *filename* of the file
    /// that should be there.
    pub fn link_target(&self) -> Result<File, String> {
        let path = match fs::read_link(&self.path) {
            Ok(path)  => path,
            Err(_)    => return Err(self.name.clone()),
        };

        let target_path = match self.dir {
            Some(dir)  => dir.join(&*path),
            None       => path
        };

        let filename = path_filename(&target_path);

        // Use plain `metadata` instead of `symlink_metadata` - we *want* to follow links.
        if let Ok(metadata) = fs::metadata(&target_path) {
            Ok(File {
                path:      target_path.to_path_buf(),
                dir:       self.dir,
                metadata:  metadata,
                ext:       ext(&filename),
                name:      filename.to_string(),
            })
        }
        else {
            Err(filename.to_string())
        }
    }

    /// This file's number of hard links.
    ///
    /// It also reports whether this is both a regular file, and a file with
    /// multiple links. This is important, because a file with multiple links
    /// is uncommon, while you can come across directories and other types
    /// with multiple links much more often. Thus, it should get highlighted
    /// more attentively.
    pub fn links(&self) -> f::Links {
        let count = self.metadata.nlink();

        f::Links {
            count: count,
            multiple: self.is_file() &&