Merge pull request #138 from seapagan/feat/permission-display-modes

Add permission display modes

Author: seapagan

README.md

@@ -114,6 +114,8 @@ Currently, only a sub-set of the standard `ls` options are supported. These are:
 - `-F` / `--classify` - Append type indicators, including `*` for executables
 - `--no-indicators` - Disable file type indicators
 - `-l` / `--long` - Show long format listing
+- `--permissions <MODE>` - Select long-format permission display:
+  `symbolic`, `octal`, `both`, or `none`
 - `-h` / `--human-readable` - Human readable file sizes using powers of 1024
 - `--si` - Human readable file sizes using powers of 1000
 - `-D` / `--sort-dirs` - Sort directories first
@@ -154,6 +156,11 @@ piped, and redirected output is plain by default. You can also disable styled
 output explicitly with `--no-color`, `no_color = true` in the config file, or
 the `NO_COLOR` environment variable.
 
+Long-format output shows symbolic permissions by default. Use
+`--permissions octal` to replace them with octal permission bits,
+`--permissions both` to add octal bits after the symbolic field, or
+`--permissions none` to omit permission fields.
+
 Long-format output colors permission bits, timestamp freshness, and large file
 sizes by default. You can adjust those accents independently with
 `--no-permission-colors`, `--no-time-gradient`, `--no-size-colors`, or the

docs/src/config.md

@@ -187,6 +187,17 @@ This option controls long-format colors for the file type character and
 permission bits. Set it to `false`, or pass `--no-permission-colors`, to render
 those fields without accent colors.
 
+### permissions
+
+- Permitted values: `symbolic`, `octal`, `both`, or `none`
+- Default value: `symbolic`
+
+This option corresponds to `--permissions` and controls long-format permission
+fields. `symbolic` shows the default file type character and symbolic
+permissions, `octal` replaces that field with the file type character and
+four-digit octal permission bits, `both` adds an octal permission cell after
+the symbolic field, and `none` omits permission fields.
+
 ### time_gradient
 
 - Permitted values: `true` or `false`
@@ -245,6 +256,7 @@ human_readable = true
 # prune_dirs = ["target", "dist"]
 no_color = true
 permission_colors = false
+permissions = "symbolic"
 time_gradient = false
 size_colors = false
 fuzzy_time = true

docs/src/usage.md

@@ -18,6 +18,8 @@ Currently, only a sub-set of the standard `ls` options are supported. These are:
 - `-F` / `--classify` - Append type indicators, including `*` for executables
 - `--no-indicators` - Disable file type indicators
 - `-l` / `--long` - Show long format listing
+- `--permissions <MODE>` - Select long-format permission display:
+  `symbolic`, `octal`, `both`, or `none`
 - `-h` / `--human-readable` - Human readable file sizes using powers of 1024
 - `--si` - Human readable file sizes using powers of 1000
 - `-R` / `--recursive` - List subdirectories recursively
@@ -95,6 +97,11 @@ piped, and redirected output is plain by default. You can also disable styled
 output explicitly with `--no-color`, `no_color = true` in the config file, or
 the `NO_COLOR` environment variable.
 
+Long-format output shows symbolic permissions by default. Use
+`--permissions octal` to replace them with octal permission bits,
+`--permissions both` to add octal bits after the symbolic field, or
+`--permissions none` to omit permission fields.
+
 Long-format output colors permission bits, timestamp freshness, and large file
 sizes by default. You can adjust those accents independently with
 `--no-permission-colors`, `--no-time-gradient`, `--no-size-colors`, or the

src/cli.rs

@@ -9,7 +9,7 @@ use clap::{Arg, ArgAction, ArgMatches, Command};
 use std::env;
 use std::ffi::OsString;
 
-use crate::IndicatorStyle;
+use crate::{IndicatorStyle, structs::PermissionDisplay};
 
 const ARG_SHOW_ALL: &str = "show_all";
 const ARG_ALMOST_ALL: &str = "almost_all";
@@ -31,6 +31,7 @@ const ARG_DIRS_FIRST: &str = "dirs_first";
 const ARG_NO_ICONS: &str = "no_icons";
 const ARG_NO_COLOR: &str = "no_color";
 const ARG_NO_PERMISSION_COLORS: &str = "no_permission_colors";
+const ARG_PERMISSIONS: &str = "permissions";
 const ARG_NO_TIME_GRADIENT: &str = "no_time_gradient";
 const ARG_NO_SIZE_COLORS: &str = "no_size_colors";
 const ARG_GITIGNORE: &str = "gitignore";
@@ -100,6 +101,8 @@ pub struct Flags {
     pub no_color: bool,
     /// Disable permission and file-type colors in long-format output.
     pub no_permission_colors: bool,
+    /// Override long-format permission display mode.
+    pub permissions: Option<PermissionDisplay>,
     /// Use the fixed timestamp color instead of age-based colors.
     pub no_time_gradient: bool,
     /// Disable large-size colors in long-format output.
@@ -186,6 +189,7 @@ fn build_command(mode: CompatMode) -> Command {
         .arg(no_icons_arg())
         .arg(no_color_arg(mode))
         .arg(no_permission_colors_arg())
+        .arg(permissions_arg())
         .arg(no_time_gradient_arg())
         .arg(no_size_colors_arg())
         .arg(gitignore_arg(mode))
@@ -418,6 +422,15 @@ fn no_permission_colors_arg() -> Arg {
         )
 }
 
+fn permissions_arg() -> Arg {
+    Arg::new(ARG_PERMISSIONS)
+        .long("permissions")
+        .action(ArgAction::Set)
+        .value_name("MODE")
+        .value_parser(clap::value_parser!(PermissionDisplay))
+        .help("Select long-format permission display: symbolic, octal, both, or none")
+}
+
 fn no_time_gradient_arg() -> Arg {
     Arg::new(ARG_NO_TIME_GRADIENT)
         .long("no-time-gradient")
@@ -493,6 +506,9 @@ fn flags_from_matches(mode: CompatMode, matches: &ArgMatches) -> Flags {
         no_icons: matches.get_flag(ARG_NO_ICONS),
         no_color: matches.get_flag(ARG_NO_COLOR),
         no_permission_colors: matches.get_flag(ARG_NO_PERMISSION_COLORS),
+        permissions: matches
+            .get_one::<PermissionDisplay>(ARG_PERMISSIONS)
+            .copied(),
         no_time_gradient: matches.get_flag(ARG_NO_TIME_GRADIENT),
         no_size_colors: matches.get_flag(ARG_NO_SIZE_COLORS),
         gitignore: matches.get_flag(ARG_GITIGNORE),

src/structs.rs

@@ -1,4 +1,5 @@
 use super::utils::icons::Icon;
+use clap::ValueEnum;
 use config::Config;
 use serde::Deserialize;
 use std::convert::From;
@@ -29,6 +30,24 @@ pub enum IndicatorStyle {
     Classify,
 }
 
+/// Long-format permission column display modes.
+#[derive(
+    Debug, Clone, Copy, Deserialize, PartialEq, Eq, Default, ValueEnum,
+)]
+#[serde(rename_all = "kebab-case")]
+#[value(rename_all = "kebab-case")]
+pub enum PermissionDisplay {
+    /// Show the existing file-type character plus symbolic permissions.
+    #[default]
+    Symbolic,
+    /// Show the file-type character plus octal permission bits.
+    Octal,
+    /// Show symbolic permissions and a separate octal permission cell.
+    Both,
+    /// Hide permission cells entirely.
+    None,
+}
+
 /// Runtime options after CLI flags and config defaults have been merged.
 #[derive(Debug, PartialEq)]
 pub struct Params {
@@ -62,6 +81,8 @@ pub struct Params {
     pub no_color: bool,
     /// Color file type and permission bits in long-format output.
     pub permission_colors: bool,
+    /// Select which permission fields to show in long-format output.
+    pub permissions: PermissionDisplay,
     /// Color timestamps by age in long-format output.
     pub time_gradient: bool,
     /// Color large sizes in long-format output.
@@ -90,6 +111,7 @@ impl Default for Params {
             no_icons: false,
             no_color: false,
             permission_colors: true,
+            permissions: PermissionDisplay::Symbolic,
             time_gradient: true,
             size_colors: true,
             gitignore: false,
@@ -116,6 +138,7 @@ pub(crate) struct RawParams {
     no_icons: bool,
     no_color: bool,
     permission_colors: Option<bool>,
+    permissions: PermissionDisplay,
     time_gradient: Option<bool>,
     size_colors: Option<bool>,
     gitignore: bool,
@@ -182,6 +205,7 @@ impl From<RawParams> for Params {
             no_icons: raw.no_icons,
             no_color: raw.no_color,
             permission_colors: raw.permission_colors.unwrap_or(true),
+            permissions: raw.permissions,
             time_gradient: raw.time_gradient.unwrap_or(true),
             size_colors: raw.size_colors.unwrap_or(true),
             gitignore: raw.gitignore,
@@ -223,6 +247,7 @@ impl Params {
             no_color: flags.no_color || config.no_color,
             permission_colors: config.permission_colors
                 && !flags.no_permission_colors,
+            permissions: flags.permissions.unwrap_or(config.permissions),
             time_gradient: config.time_gradient && !flags.no_time_gradient,
             size_colors: config.size_colors && !flags.no_size_colors,
             gitignore: flags.gitignore || config.gitignore,
@@ -294,6 +319,9 @@ pub struct FileInfo {
     /// Unix-style permission string, possibly including `s`, `S`, `t`, or
     /// `T` special-bit overlays.
     pub mode: String,
+    /// Unix permission bits masked to the displayable permission and special
+    /// bit range.
+    pub mode_bits: u32,
     /// Link count from filesystem metadata.
     pub nlink: u64,
     /// Owner name, or numeric user ID when lookup fails.

src/utils/file.rs

@@ -28,6 +28,7 @@ use std::os::unix::ffi::OsStrExt;
 struct FileDetails {
     file_type: String,
     mode: String,
+    mode_bits: u32,
     nlink: u64,
     size: u64,
     mtime: SystemTime,
@@ -112,6 +113,7 @@ fn get_file_details(metadata: &fs::Metadata) -> FileDetails {
     FileDetails {
         file_type,
         mode: rwx_mode,
+        mode_bits: mode & 0o7777,
         nlink,
         size,
         mtime,
@@ -377,6 +379,7 @@ pub(crate) fn create_file_info_from_metadata_with_gitignore(
     FileInfo {
         file_type: details.file_type,
         mode: details.mode,
+        mode_bits: details.mode_bits,
         nlink: details.nlink,
         user: details.user,
         group: details.group,

src/utils/format.rs

@@ -19,6 +19,11 @@ pub fn mode_to_rwx(mode: u32) -> String {
     rwx
 }
 
+/// Format Unix permission and special bits as four octal digits.
+pub fn mode_to_octal(mode: u32) -> String {
+    format!("{:04o}", mode & 0o7777)
+}
+
 fn permission_char(mode: u32, bit: u32, value: char) -> char {
     if mode & bit != 0 { value } else { '-' }
 }

src/utils/render.rs

@@ -15,12 +15,12 @@ use strip_ansi_escapes::strip_str;
 use terminal_size::{Height, Width, terminal_size};
 use unicode_width::UnicodeWidthStr;
 
-use crate::Params;
 use crate::structs::{FileInfo, NameStyle};
 use crate::utils;
 use crate::utils::color::{LongFormatColorLevel, long_format_color_level};
 use crate::utils::file::check_display_name;
 use crate::utils::time::{DAY, MONTH, WEEK, YEAR};
+use crate::{Params, structs::PermissionDisplay};
 
 const SHORT_CELL_PADDING: usize = 2;
 const LARGE_SIZE_BYTES: u64 = 1024 * 1024;
@@ -79,12 +79,9 @@ fn build_long_format_table_with_name_prefixes<'a>(
         let (display_size, units) =
             utils::format::show_size(info.size, size_scale);
 
-        let mut row_cells = Vec::with_capacity(9);
+        let mut row_cells = Vec::with_capacity(10);
 
-        row_cells.push(Cell::new(&format!(
-            "{} ",
-            long_permission_text(info, params)
-        )));
+        append_permission_cells(&mut row_cells, info, params, color_level);
         row_cells.push(Cell::new(&info.nlink.to_string()));
         row_cells.push(Cell::new(&format!(" {}", info.user.cyan())));
         row_cells.push(Cell::new(&format!("{} ", info.group.green())));
@@ -127,16 +124,76 @@ fn build_long_format_table_with_name_prefixes<'a>(
     table
 }
 
-fn long_permission_text(info: &FileInfo, params: &Params) -> String {
+fn append_permission_cells(
+    row_cells: &mut Vec<Cell>,
+    info: &FileInfo,
+    params: &Params,
+    color_level: LongFormatColorLevel,
+) {
+    match params.permissions {
+        PermissionDisplay::Symbolic => {
+            row_cells.push(Cell::new(&format!(
+                "{} ",
+                long_permission_text(info, params)
+            )));
+        }
+        PermissionDisplay::Octal => {
+            row_cells.push(Cell::new(&format!(
+                "{} {} ",
+                long_file_type_text(info, params),
+                long_octal_permission_text(info, params, color_level)
+            )));
+        }
+        PermissionDisplay::Both => {
+            row_cells.push(Cell::new(&long_permission_text(info, params)));
+            row_cells.push(Cell::new(&format!(
+                "{} ",
+                long_octal_permission_text(info, params, color_level)
+            )));
+        }
+        PermissionDisplay::None => {}
+    }
+}
+
+fn long_file_type_text(info: &FileInfo, params: &Params) -> String {
     if !params.permission_colors {
-        return format!("{}{}", info.file_type, info.mode);
+        return info.file_type.clone();
     }
 
-    let mut output =
-        String::with_capacity(info.file_type.len() + info.mode.len());
+    let mut output = String::with_capacity(info.file_type.len());
     for value in info.file_type.chars() {
         write_file_type_char(&mut output, value);
     }
+    output
+}
+
+fn long_octal_permission_text(
+    info: &FileInfo,
+    params: &Params,
+    color_level: LongFormatColorLevel,
+) -> String {
+    let text = utils::format::mode_to_octal(info.mode_bits);
+    if !params.permission_colors {
+        return text;
+    }
+
+    match color_level {
+        LongFormatColorLevel::Truecolor => text.rgb(238, 204, 92).to_string(),
+        LongFormatColorLevel::Ansi256 => {
+            format!("\x1b[38;5;221m{text}\x1b[0m")
+        }
+        LongFormatColorLevel::Named => text.yellow().dim().to_string(),
+        LongFormatColorLevel::None => text,
+    }
+}
+
+fn long_permission_text(info: &FileInfo, params: &Params) -> String {
+    if !params.permission_colors {
+        return format!("{}{}", info.file_type, info.mode);
+    }
+
+    let mut output = long_file_type_text(info, params);
+    output.reserve(info.mode.len());
     for value in info.mode.chars() {
         write_permission_char(&mut output, value);
     }

tests/crate/app.rs

@@ -97,6 +97,7 @@ fn test_run_with_flags_lists_matching_entries() {
             no_icons: true,
             no_color: false,
             no_permission_colors: false,
+            permissions: None,
             no_time_gradient: false,
             no_size_colors: false,
             gitignore: false,