extern/nushell
1
0
Fork 1
mirror of https://github.com/nushell/nushell.git synced 2025-04-16 01:08:21 +02:00
Code Issues Packages Projects Releases Wiki Activity
4bc28f1752
nushell/crates/nu-utils/src/default_files
History
Ian Manske 93e121782c
Improve and fix filesize formatting/display (#14397) 
# Description

This PR cleans up the code surrounding formatting and displaying file
sizes.
- The `byte_unit` crate we use for file size units displays kilobytes as
`KB`, which is not the SI or ISO/IEC standard. Rather it should be `kB`,
so this fixes #8872. On some systems, `KB` actually means `KiB`, so this
avoids any potential confusion.
- The `byte_unit` crate, when displaying file sizes, casts integers to
floats which will lose precision for large file sizes. This PR adds a
custom `Display` implementation for `Filesize` that can give an exact
string representation of a `Filesize` for metric/SI units.
- This PR also removes the dependency on the `byte_unit` crate which
brought in several other dependencies.

Additionally, this PR makes some changes to the config for filesize
formatting (`$env.config.filesize`).
- The previous filesize config had the `metric` and `format` options. If
a metric (SI) unit was set in `format`, but `metric` was set to false,
then the `metric` option would take precedence and convert `format` to
the corresponding binary unit (or vice versa). E.g., `{ format: kB,
metric: false }` => `KiB`. Instead, this PR adds the `unit` option to
replace the `format` and `metric` options. `unit` can be set to a fixed
file size unit like `kB` or `KiB`, or it can be set to one of the
special options: `binary` or `metric`. These options tells nushell to
format file sizes using an appropriately scaled metric or binary unit
(examples below).
  ```nushell
  # precision = null

  # unit = kB
  1kB  # 1 kB
  1KiB # 1.024 kB
  
  # unit = KiB
  1kB  # 0.9765625 KiB
  1KiB # 1 KiB
  
  # unit = metric
  1000B     # 1 kB
  1024B     # 1.024 kB
  10_000MB  # 10 GB
  10_240MiB # 10.73741824 GB

  # unit = binary
  1000B     # 1000 B
  1024B     # 1 KiB
  10_000MB  # 9.313225746154785 GiB
  10_240MiB # 10 GiB
  ```
- In addition, this PR also adds the `precision` option to the filesize
config. It determines how many digits to show after the decimal point.
If set to null, then everything after the decimal point is shown.
- The default filesize config is `{ unit: metric, precision: 1 }`.

# User-Facing Changes

- Commands that use the config to format file sizes will follow the
changes described above (e.g., `table`, `into string`, `to text`, etc.).
- The file size unit/format passed to `format filesize` is now case
sensitive. An error with the valid units is shown if the case does not
match.
- `$env.config.filesize.format` and `$env.config.filesize.metric` are
deprecated and replaced by `$env.config.filesize.unit`.
- A new `$env.config.filesize.precision` option was added.

# Tests + Formatting

Mostly updated test expected outputs.

# After Submitting

This PR does not change the way NUON serializes file sizes, because that
would require changing the nu parser to be able to losslessly decode the
new, exact string representation introduced in this PR.

Similarly, this PR also does not change the file size parsing in any
way. Although the file size units provided to `format filesize` or the
filesize config are now case-sensitive, the same is not yet true for
file size literals in nushell code.
2025-01-22 22:24:51 -08:00
..
default_config.nu Bump version to 0.101.1 (#14661) 2024-12-24 23:47:00 +01:00
default_env.nu Bump version to 0.101.1 (#14661) 2024-12-24 23:47:00 +01:00
doc_config.nu Improve and fix filesize formatting/display (#14397) 2025-01-22 22:24:51 -08:00
doc_env.nu Bump version to 0.101.1 (#14661) 2024-12-24 23:47:00 +01:00
README.md Remove unused sample_login.nu file (#14632) 2024-12-19 20:21:52 +01:00
scaffold_config.nu Bump version to 0.101.1 (#14661) 2024-12-24 23:47:00 +01:00
scaffold_env.nu Bump version to 0.101.1 (#14661) 2024-12-24 23:47:00 +01:00

README.md

Nushell configuration files

default_env.nu:

  • The internal default environment variables (other than $env.config) that will be set during Nushell startup.
  • Is loaded before the user's env.nu.
  • Will be loaded during any startup where the user's env.nu is also loaded. For example:
    • During normal startup with nu
    • During a startup where the user specifies an alternative env.nu via nu --env-config <path>
    • During a nu -c <commandstring> or nu <script> startup so that ENV_CONVERSIONS is properly handled for Windows.
  • Is not loaded when running with an explicit no --no-config-file (-n).
  • Is not commented - Comments are in doc_env.nu.
  • Should be optimized for fastest load times.
  • Can be introspected via config env --default | nu-highlight

default_config.nu:

Counterpart to default_env.nu.

  • Contains any $env.config values that are not set via Rust defaults.
  • Is loaded after the user's env.nu.
  • Is loaded before the user's config.nu.
  • Will be loaded during any startup where the user's config.nu is also loaded. For example:
    • During normal startup with nu
    • During a startup where the user specifies an alternative config.nu via nu --config <path>
  • Likewise, is never loaded during a startup where the user's config.nu would not be loaded. For example:
    • nu -n/--no-config
    • nu -c "ls"
    • nu <script.nu>
  • Is not commented - Comments are in doc_config.nu.
  • Should be optimized for fastest load times. Whenever possible, values should be set via nu-protocol::config
    • Exception: color_config values are currently set in this file so that user's can introspect the values
    • TODO: Implement defaults for color_config in nu-protocol::config and remove from default_config.nu
  • Can be introspected via config nu --default | nu-highlight
  • An ideal default_config.nu (when all values are set via nu-protocol::config) will simply be: 
    $env.config = {}

doc_env.nu

  • A commented file documenting the most common environment variables that a user might configure in env.nu
  • For convenient in-shell access - Can be pretty-printed via config env --doc | nu-highlight
  • Since this file is for documentation only, include actual Nushell code without comments so that it can be pretty-printed
  • No optimization necessary - Not intended for use other than documentation.
  • Consider replacing config env --doc with help env.nu at some point.
  • Uses a mix of default values (explained) as well as other examples that users might want in their own env.nu

doc_config.nu

Counterpart to doc_env.nu.

  • A commented file documenting the most common environment variables that a user might configure in config.nu
  • For convenient in-shell access - Can be pretty-printed via config nu --doc | nu-highlight
  • Since this file is for documentation only, include actual Nushell code without comments so that it can be pretty-printed
  • No optimization necessary - Not intended for use other than documentation.
  • Consider replacing config nu --doc with help config.nu at some point.
  • Uses a mix of default values (explained) as well as other examples that users might want in their own config.nu

scaffold_env.nu

  • This file is used one-time (typically) at first startup
  • If the $nu.default-config-path directory does not exist, the directory is created and then both scaffold_env.nu and scaffold_config.nu are written to it
  • Contains only commented lines explaining the purpose of the file to the user, along with information on the config env command.

scaffold_config.nu

Counterpart to scaffold_env.nu.

  • This file is used one-time (typically) at first startup
  • If the $nu.default-config-path directory does not exist, the directory is created and then both scaffold_env.nu and scaffold_config.nu are written to it
  • Contains only commented lines explaining the purpose of the file to the user, along with information on the config nu command.