mirror of
https://github.com/fish-shell/fish-shell
synced 2024-12-28 13:53:10 +00:00
41c22d5e60
This is essentially the inverse of `string pad`.
Where that adds characters to get up to the specified width,
this adds an ellipsis to a string if it goes over a specific maximum width.
The char can be given, but defaults to our ellipsis string.
("…" if the locale can handle it and "..." otherwise)
If the ellipsis string is empty, it just truncates.
For arguments given via argv, it goes line-by-line,
because otherwise length makes no sense.
If "--no-newline" is given, it adds an ellipsis instead and removes all subsequent lines.
Like pad and `length --visible`, it goes by visible width,
skipping recognized escape sequences, as those have no influence on width.
The default target width is the shortest of the given widths that is non-zero.
If the ellipsis is already wider than the target width,
we truncate instead. This is safer overall, so we don't e.g. move into a new line.
This is especially important given our default ellipsis might be width 3.
89 lines
3.5 KiB
ReStructuredText
89 lines
3.5 KiB
ReStructuredText
string-shorten - shorten strings to a width, with an ellipsis
|
|
===============================================================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. BEGIN SYNOPSIS
|
|
|
|
.. synopsis::
|
|
|
|
string shorten [(-c | --char) CHARS] [(-m | --max) INTEGER] [(-N | --no-newline)] [(-l | --left)]
|
|
[STRING ...]
|
|
|
|
.. END SYNOPSIS
|
|
|
|
Description
|
|
-----------
|
|
|
|
.. BEGIN DESCRIPTION
|
|
|
|
``string shorten`` truncates each *STRING* to the given visible width and adds an ellipsis to indicate it. "Visible width" means the width of all visible characters added together, excluding escape sequences and accounting for :envvar:`fish_emoji_width` and :envvar:`fish_ambiguous_width`. It is the amount of columns in a terminal the *STRING* occupies.
|
|
|
|
The escape sequences reflect what fish knows about, and how it computes its output. Your terminal might support more escapes, or not support escape sequences that fish knows about.
|
|
|
|
If **-m** or **--max** is given, truncate at the given width. Otherwise, the lowest non-zero width of all input strings is used.
|
|
|
|
If **-N** or **--no-newline** is given, only the first line (or last line with **--left**) of each STRING is used, and an ellipsis is added if it was multiline. This only works for STRINGs being given as arguments, multiple lines given on stdin will be interpreted as separate STRINGs instead.
|
|
|
|
If **-c** or **--char** is given, add *CHAR* instead of an ellipsis. This can also be empty or more than one character.
|
|
|
|
If **-l** or **--left** is given, remove text from the left on instead, so this prints the longest *suffix* of the string that fits. With **--no-newline**, this will take from the last line instead of the first.
|
|
|
|
The default ellipsis is ``…``. If fish thinks your system is incapable because of your locale, it will use ``...`` instead.
|
|
|
|
.. END DESCRIPTION
|
|
|
|
Examples
|
|
--------
|
|
|
|
.. BEGIN EXAMPLES
|
|
|
|
::
|
|
|
|
>_ string shorten foo foobar
|
|
# No width was given, we infer, and "foo" is the shortest.
|
|
foo
|
|
fo…
|
|
|
|
>_ string shorten --char="..." foo foobar
|
|
# The target width is 3 because of "foo",
|
|
# and our ellipsis is 3 too, so we can't really show anything.
|
|
# This is the default ellipsis if your locale doesn't allow "…".
|
|
foo
|
|
...
|
|
|
|
>_ string shorten --char="" --max 4 abcdef 123456
|
|
# Leaving the char empty makes us not add an ellipsis
|
|
# So this truncates at 4 columns:
|
|
abcd
|
|
1234
|
|
|
|
>_ touch "a multiline"\n"file"
|
|
>_ for file in *; string shorten -N -- $file; end
|
|
# Shorten the multiline file so we only show one line per file:
|
|
a multiline…
|
|
|
|
>_ ss -p | string shorten -m$COLUMNS -c ""
|
|
# `ss` from Linux' iproute2 shows socket information, but prints extremely long lines.
|
|
# This shortens input so it fits on the screen without overflowing lines.
|
|
|
|
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20
|
|
# Take the current git branch and shorten it at 20 columns.
|
|
# Here the branch is "builtin-path-with-expand"
|
|
builtin-path-with-e…
|
|
|
|
>_ git branch | string match -rg '^\* (.*)' | string shorten -m20 --left
|
|
# Taking 20 columns from the right instead:
|
|
…in-path-with-expand
|
|
|
|
See Also
|
|
--------
|
|
|
|
- :ref:`string<cmd-string>`'s ``pad`` subcommand does the inverse of this command, adding padding to a specific width instead.
|
|
|
|
- The :ref:`printf <cmd-printf>` command can do simple padding, for example ``printf %10s\n`` works like ``string pad -w10``.
|
|
|
|
- :ref:`string length <cmd-string-length>` with the ``--visible`` option can be used to show what fish thinks the width is.
|
|
|
|
.. END EXAMPLES
|