diff options
author | Ben S <ogham@bsago.me> | 2015-02-26 08:27:29 +0000 |
---|---|---|
committer | Ben S <ogham@bsago.me> | 2015-02-26 08:27:29 +0000 |
commit | 8615f44076a27e8fceb74f673073894cf1b7301b (patch) | |
tree | f0c1eefce5e58566750709a17fa88cb5f7b8de5f /src/output | |
parent | 571be76454c32fc10d175c620bf59fbd75486277 (diff) |
Spew comments everywhere
Diffstat (limited to 'src/output')
-rw-r--r-- | src/output/details.rs | 141 |
1 files changed, 104 insertions, 37 deletions
diff --git a/src/output/details.rs b/src/output/details.rs index 3049c1c..dba0b0c 100644 --- a/src/output/details.rs +++ b/src/output/details.rs @@ -8,28 +8,45 @@ use users::OSUsers; use locale; use ansi_term::Style::Plain; +/// With the **Details** view, the output gets formatted into columns, with +/// each `Column` object showing some piece of information about the file, +/// such as its size, or its permissions. +/// +/// To do this, the results have to be written to a table, instead of +/// displaying each file immediately. Then, the width of each column can be +/// calculated based on the individual results, and the fields are padded +/// during output. +/// +/// Almost all the heavy lifting is done in a Table object, which handles the +/// columns for each row. #[derive(PartialEq, Debug, Copy)] pub struct Details { + + /// A Columns object that says which columns should be included in the + /// output in the general case. Directories themselves can pick which + /// columns are *added* to this list, such as the Git column. pub columns: Columns, - pub header: bool, + + /// Whether to recurse through directories with a tree view, and if so, + /// which options to use. This field is only relevant here if the `tree` + /// field of the RecurseOptions is `true`. pub recurse: Option<(RecurseOptions, FileFilter)>, + + /// Whether to show a header line or not. + pub header: bool, + + /// Whether to show each file's extended attributes. pub xattr: bool, } impl Details { pub fn view(&self, dir: Option<&Dir>, files: &[File]) { - // The output gets formatted into columns, which looks nicer. To - // do this, we have to write the results into a table, instead of - // displaying each file immediately, then calculating the maximum - // width of each column based on the length of the results and - // padding the fields during output. - - // Almost all the heavy lifting is done in a Table object, which - // automatically calculates the width of each column and the - // appropriate padding. + // First, transform the Columns object into a vector of columns for + // the current directory. let mut table = Table::with_columns(self.columns.for_dir(dir)); if self.header { table.add_header() } + // Then add files to the table and print it out. self.add_files_to_table(&mut table, files, 0); table.print_table(self.xattr, self.recurse.is_some()); } @@ -38,13 +55,20 @@ impl Details { /// is present. fn add_files_to_table(&self, table: &mut Table, src: &[File], depth: usize) { for (index, file) in src.iter().enumerate() { - table.add_row(file, depth, index == src.len() - 1); + table.add_file(file, depth, index == src.len() - 1); + // There are two types of recursion that exa supports: a tree + // view, which is dealt with here, and multiple listings, which is + // dealt with in the main module. So only actually recurse if we + // are in tree mode - the other case will be dealt with elsewhere. if let Some((r, filter)) = self.recurse { if r.tree == false || r.is_too_deep(depth) { continue; } + // Use the filter to remove unwanted files *before* expanding + // them, so we don't examine any directories that wouldn't + // have their contents listed anyway. if let Some(ref dir) = file.this { let mut files = dir.files(true); filter.transform_files(&mut files); @@ -56,24 +80,42 @@ impl Details { } struct Row { - depth: usize, - cells: Vec<Cell>, - name: String, - last: bool, - attrs: Vec<Attribute>, + + /// Vector of cells to display. + cells: Vec<Cell>, + + /// This file's name, in coloured output. The name is treated separately + /// from the other cells, as it never requires padding. + name: String, + + /// How many directories deep into the tree structure this is. Directories + /// on top have depth 0. + depth: usize, + + /// Vector of this file's extended attributes, if that feature is active. + attrs: Vec<Attribute>, + + /// Whether this is the last entry in the directory. This flag is used + /// when calculating the tree view. + last: bool, + + /// Whether this file is a directory and has any children. Also used when + /// calculating the tree view. children: bool, } -type ColumnInfo = (usize, Alignment); - +/// A **Table** object gets built up by the view as it lists files and +/// directories. struct Table { columns: Vec<Column>, - users: OSUsers, - locale: UserLocale, - rows: Vec<Row>, + users: OSUsers, + locale: UserLocale, + rows: Vec<Row>, } impl Table { + /// Create a new, empty Table object, setting the caching fields to their + /// empty states. fn with_columns(columns: Vec<Column>) -> Table { Table { columns: columns, @@ -83,51 +125,65 @@ impl Table { } } + /// Add a dummy "header" row to the table, which contains the names of all + /// the columns, underlined. This has dummy data for the cases that aren't + /// actually used, such as the depth or list of attributes. fn add_header(&mut self) { let row = Row { - depth: 0, - cells: self.columns.iter().map(|c| Cell::paint(Plain.underline(), c.header())).collect(), - name: Plain.underline().paint("Name").to_string(), - last: false, - attrs: Vec::new(), + depth: 0, + cells: self.columns.iter().map(|c| Cell::paint(Plain.underline(), c.header())).collect(), + name: Plain.underline().paint("Name").to_string(), + last: false, + attrs: Vec::new(), children: false, }; self.rows.push(row); } + /// Use the list of columns to find which cells should be produced for + /// this file, per-column. fn cells_for_file(&mut self, file: &File) -> Vec<Cell> { self.columns.clone().iter() .map(|c| file.display(c, &mut self.users, &self.locale)) .collect() } - fn add_row(&mut self, file: &File, depth: usize, last: bool) { + /// Get the cells for the given file, and add the result to the table. + fn add_file(&mut self, file: &File, depth: usize, last: bool) { let row = Row { - depth: depth, - cells: self.cells_for_file(file), - name: file.file_name_view(), - last: last, - attrs: file.xattrs.clone(), + depth: depth, + cells: self.cells_for_file(file), + name: file.file_name_view(), + last: last, + attrs: file.xattrs.clone(), children: file.this.is_some(), }; self.rows.push(row) } + /// Print the table to standard output, consuming it in the process. fn print_table(self, xattr: bool, show_children: bool) { let mut stack = Vec::new(); + // Work out the list of column widths by finding the longest cell for + // each column, then formatting each cell in that column to be the + // width of that one. let column_widths: Vec<usize> = range(0, self.columns.len()) .map(|n| self.rows.iter().map(|row| row.cells[n].length).max().unwrap_or(0)) .collect(); - for row in self.rows.iter() { + for row in self.rows.into_iter() { for (n, width) in column_widths.iter().enumerate() { let padding = width - row.cells[n].length; print!("{} ", self.columns[n].alignment().pad_string(&row.cells[n].text, padding)); } + // A stack tracks which tree characters should be printed. It's + // necessary to maintain information about the previously-printed + // lines, as the output will change based on whether the + // *previous* entry was the last in its directory. if show_children { stack.resize(row.depth + 1, TreePart::Edge); stack[row.depth] = if row.last { TreePart::Corner } else { TreePart::Edge }; @@ -140,11 +196,14 @@ impl Table { stack[row.depth] = if row.last { TreePart::Blank } else { TreePart::Line }; } + // If any tree characters have been printed, then add an extra + // space, which makes the output look much better. if row.depth != 0 { print!(" "); } } + // Print the name without worrying about padding. print!("{}\n", row.name); if xattr { @@ -163,10 +222,18 @@ impl Table { #[derive(PartialEq, Debug, Clone)] enum TreePart { + + /// Rightmost column, *not* the last in the directory. Edge, + + /// Not the rightmost column, and the directory has not finished yet. + Line, + + /// Rightmost column, and the last in the directory. Corner, + + /// Not the rightmost column, and the directory *has* finished. Blank, - Line, } impl TreePart { @@ -181,21 +248,21 @@ impl TreePart { } pub struct UserLocale { - pub time: locale::Time, + pub time: locale::Time, pub numeric: locale::Numeric, } impl UserLocale { pub fn new() -> UserLocale { UserLocale { - time: locale::Time::load_user_locale().unwrap_or_else(|_| locale::Time::english()), + time: locale::Time::load_user_locale().unwrap_or_else(|_| locale::Time::english()), numeric: locale::Numeric::load_user_locale().unwrap_or_else(|_| locale::Numeric::english()), } } pub fn default() -> UserLocale { UserLocale { - time: locale::Time::english(), + time: locale::Time::english(), numeric: locale::Numeric::english(), } } |