diff --git a/src/dir.rs b/src/dir.rs index 4126656..78e0ed6 100644 --- a/src/dir.rs +++ b/src/dir.rs @@ -14,8 +14,15 @@ use file::{File, fields}; /// check the existence of surrounding files, then highlight themselves /// accordingly. (See `File#get_source_files`) pub struct Dir { + + /// A vector of the files that have been read from this directory. contents: Vec, + + /// The path that was read. pub path: PathBuf, + + /// Holds a `Git` object if scanning for Git repositories is switched on, + /// and this directory happens to contain one. git: Option, } @@ -71,6 +78,7 @@ impl Dir { } +/// Iterator over reading the contents of a directory as `File` objects. pub struct Files<'dir> { inner: SliceIter<'dir, PathBuf>, dir: &'dir Dir, diff --git a/src/file.rs b/src/file.rs index 979ca27..4e2617d 100644 --- a/src/file.rs +++ b/src/file.rs @@ -56,6 +56,7 @@ pub struct File<'dir> { } impl<'dir> File<'dir> { + /// Create a new `File` object from the given `Path`, inside the given /// `Dir`, if appropriate. /// @@ -70,11 +71,11 @@ impl<'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(), + path: path.to_path_buf(), + dir: parent, + metadata: metadata, + ext: ext(&filename), + name: filename.to_string(), } } @@ -83,6 +84,12 @@ impl<'dir> File<'dir> { 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::read_dir(&*self.path, scan_for_git) } @@ -178,11 +185,11 @@ impl<'dir> File<'dir> { // 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(), + path: target_path.to_path_buf(), + dir: self.dir, + metadata: metadata, + ext: ext(&filename), + name: filename.to_string(), }) } else { @@ -282,6 +289,10 @@ impl<'dir> File<'dir> { } /// This file's permissions, with flags for each bit. + /// + /// The extended-attribute '@' character that you see in here is in fact + /// added in later, to avoid querying the extended attributes more than + /// once. (Yes, it's a little hacky.) pub fn permissions(&self) -> f::Permissions { let bits = self.metadata.permissions().mode(); let has_bit = |bit| { bits & bit == bit }; diff --git a/src/output/details.rs b/src/output/details.rs index 0757f81..f87d0ad 100644 --- a/src/output/details.rs +++ b/src/output/details.rs @@ -1,3 +1,116 @@ +//! The **Details** output view displays each file as a row in a table. +//! +//! It's used in the following situations: +//! +//! - Most commonly, when using the `--long` command-line argument to display the +//! details of each file, which requires using a table view to hold all the data; +//! - When using the `--tree` argument, which uses the same table view to display +//! each file on its own line, with the table providing the tree characters; +//! - When using both the `--long` and `--grid` arguments, which constructs a +//! series of tables to fit all the data on the screen. +//! +//! You will probably recognise it from the `ls --long` command. It looks like +//! this: +//! +//! .rw-r--r-- 9.6k ben 29 Jun 16:16 Cargo.lock +//! .rw-r--r-- 547 ben 23 Jun 10:54 Cargo.toml +//! .rw-r--r-- 1.1k ben 23 Nov 2014 LICENCE +//! .rw-r--r-- 2.5k ben 21 May 14:38 README.md +//! .rw-r--r-- 382k ben 8 Jun 21:00 screenshot.png +//! drwxr-xr-x - ben 29 Jun 14:50 src +//! drwxr-xr-x - ben 28 Jun 19:53 target +//! +//! The table is constructed by creating a `Table` value, which produces a `Row` +//! value for each file. These rows can contain a vector of `Cell`s, or they can +//! contain depth information for the tree view, or both. These are described +//! below. +//! +//! +//! ## Constructing Detail Views +//! +//! When using the `--long` command-line argument, the details of each file are +//! displayed next to its name. +//! +//! The table holds a vector of all the column types. For each file and column, a +//! `Cell` value containing the ANSI-coloured text and Unicode width of each cell +//! is generated, with the row and column determined by indexing into both arrays. +//! +//! The column types vector does not actually include the filename. This is +//! because the filename is always the rightmost field, and as such, it does not +//! need to have its width queried or be padded with spaces. +//! +//! To illustrate the above: +//! +//! ┌─────────────────────────────────────────────────────────────────────────┐ +//! │ columns: [ Permissions, Size, User, Date(Modified) ] │ +//! ├─────────────────────────────────────────────────────────────────────────┤ +//! │ rows: cells: filename: │ +//! │ row 1: [ ".rw-r--r--", "9.6k", "ben", "29 Jun 16:16" ] Cargo.lock │ +//! │ row 2: [ ".rw-r--r--", "547", "ben", "23 Jun 10:54" ] Cargo.toml │ +//! │ row 3: [ "drwxr-xr-x", "-", "ben", "29 Jun 14:50" ] src │ +//! │ row 4: [ "drwxr-xr-x", "-", "ben", "28 Jun 19:53" ] target │ +//! └─────────────────────────────────────────────────────────────────────────┘ +//! +//! Each column in the table needs to be resized to fit its widest argument. This +//! means that we must wait until every row has been added to the table before it +//! can be displayed, in order to make sure that every column is wide enough. +//! +//! +//! ## Constructing Tree Views +//! +//! When using the `--tree` argument, instead of a vector of cells, each row has a +//! `depth` field that indicates how far deep in the tree it is: the top level has +//! depth 0, its children have depth 1, and *their* children have depth 2, and so +//! on. +//! +//! On top of this, it also has a `last` field that specifies whether this is the +//! last row of this particular consecutive set of rows. This doesn't affect the +//! file's information; it's just used to display a different set of Unicode tree +//! characters! The resulting table looks like this: +//! +//! ┌───────┬───────┬───────────────────────┐ +//! │ Depth │ Last │ Output │ +//! ├───────┼───────┼───────────────────────┤ +//! │ 0 │ │ documents │ +//! │ 1 │ false │ ├── this_file.txt │ +//! │ 1 │ false │ ├── that_file.txt │ +//! │ 1 │ false │ ├── features │ +//! │ 2 │ false │ │ ├── feature_1.rs │ +//! │ 2 │ false │ │ ├── feature_2.rs │ +//! │ 2 │ true │ │ └── feature_3.rs │ +//! │ 1 │ true │ └── pictures │ +//! │ 2 │ false │ ├── garden.jpg │ +//! │ 2 │ false │ ├── flowers.jpg │ +//! │ 2 │ false │ ├── library.png │ +//! │ 2 │ true │ └── space.tiff │ +//! └───────┴───────┴───────────────────────┘ +//! +//! Creating the table like this means that each file has to be tested to see if +//! it's the last one in the group. This is usually done by putting all the files +//! in a vector beforehand, getting its length, then comparing the index of each +//! file to see if it's the last one. (As some files may not be successfully +//! `stat`ted, we don't know how many files are going to exist in each directory) +//! +//! These rows have a `None` value for their vector of cells, instead of a `Some` +//! vector containing any. It's possible to have *both* a vector of cells and +//! depth and last flags when the user specifies `--tree` *and* `--long`. +//! +//! +//! ## Extended Attributes and Errors +//! +//! Finally, files' extended attributes and any errors that occur while statting +//! them can also be displayed as their children. It looks like this: +//! +//! .rw-r--r-- 0 ben 3 Sep 13:26 forbidden +//! └── +//! .rw-r--r--@ 0 ben 3 Sep 13:26 file_with_xattrs +//! ├── another_greeting (len 2) +//! └── greeting (len 5) +//! +//! These lines also have `None` cells, and the error string or attribute details +//! are used in place of the filename. + + use std::error::Error; use std::io; use std::path::PathBuf; @@ -66,15 +179,19 @@ pub struct Details { } impl Details { + + /// Print the details of the given vector of files -- all of which will + /// have been read from the given directory, if present -- to stdout. pub fn view(&self, dir: Option<&Dir>, files: Vec) { + // First, transform the Columns object into a vector of columns for // the current directory. - let columns_for_dir = match self.columns { Some(cols) => cols.for_dir(dir), None => Vec::new(), }; + // Next, add a header if the user requests it. let mut table = Table::with_options(self.colours, columns_for_dir); if self.header { table.add_header() } @@ -85,9 +202,9 @@ impl Details { } } - /// Adds files to the table - recursively, if the `recurse` option - /// is present. - fn add_files_to_table<'dir, U: Users+Send+Sync>(&self, mut table: &mut Table, src: Vec>, depth: usize) { + /// Adds files to the table, possibly recursively. This is easily + /// parallelisable, and uses a pool of threads. + fn add_files_to_table<'dir, U: Users+Send>(&self, mut table: &mut Table, src: Vec>, depth: usize) { use num_cpus; use scoped_threadpool::Pool; use std::sync::{Arc, Mutex}; @@ -133,8 +250,11 @@ impl Details { }; let cells = table.lock().unwrap().cells_for_file(&file, !xattrs.is_empty()); - let links = true; - let name = Cell { text: filename(&file, &self.colours, links), length: file.file_name_width() }; + + let name = Cell { + text: filename(&file, &self.colours, true), + length: file.file_name_width() + }; let mut dir = None; @@ -218,10 +338,10 @@ struct Row { /// Vector of cells to display. /// - /// Most of the rows will be files that have had their metadata - /// successfully queried and displayed in these cells, so this will almost - /// always be `Some`. It will be `None` for a row that's only displaying - /// an attribute or an error. + /// Most of the rows will be used to display files' metadata, so this will + /// almost always be `Some`, containing a vector of cells. It will only be + /// `None` for a row displaying an attribute or error, neither of which + /// have cells. cells: Option>, // Did You Know? @@ -242,7 +362,8 @@ struct Row { impl Row { - /// Gets the 'width' of the indexed column, if present. If not, returns 0. + /// Gets the Unicode display width of the indexed column, if present. If + /// not, returns 0. fn column_width(&self, index: usize) -> usize { match self.cells { Some(ref cells) => cells[index].length,