mirror of
https://github.com/fish-shell/fish-shell.git
synced 2024-11-25 18:03:37 +08:00
414d9a1eb1
When writing scripts for other shells, it can be confusing and annoying that our `man` function shadows other manual pages, for example `exec(1p)` from [Linux man-pages]. I almost never want to see the fish variant for such contended cases (which obviuosly don't include fish-specific commands like `string`, only widely-known shell builtins). For the contented cases like `exec`, the POSIX documentation is more substantial and useful, since it describes a (sub)set of languages widely used for scripting. Because of this I think we should stop overriding the system's man pages. Nowadays we offer `exec -h` as intuitive way to show the documentation for the fish-specific command (note that `help` is not a good replacement because it uses a web browser). Looking through the contended commands, it seems like for most of them, the fish version is not substantially different from the system version. A notable exception is `read` but I don't think it's a very important one. So I think we should can sacrifice a bit of the native fish-scripting experience in exchange for playing nicer with other shells. I think the latter is more important because scripting is not our focus, the way I see it. So maybe put our manpath at the end. In lieu of that, let's at least have `exec.rst` reference the system variant. [Linux man-pages]: https://www.kernel.org/doc/man-pages/ Closes #10376
106 lines
4.0 KiB
ReStructuredText
106 lines
4.0 KiB
ReStructuredText
.. _cmd-printf:
|
|
|
|
printf - display text according to a format string
|
|
==================================================
|
|
|
|
Synopsis
|
|
--------
|
|
|
|
.. synopsis::
|
|
|
|
printf FORMAT [ARGUMENT ...]
|
|
|
|
Description
|
|
-----------
|
|
|
|
.. only:: builder_man
|
|
|
|
NOTE: This page documents the fish builtin ``printf``.
|
|
To see the documentation on any non-fish versions, use ``command man printf``.
|
|
|
|
``printf`` uses the format string *FORMAT* to print the *ARGUMENT* arguments. This means that it takes format specifiers in the format string and replaces each with an argument.
|
|
|
|
The *FORMAT* argument is re-used as many times as necessary to convert all of the given arguments. So ``printf %s\n flounder catfish clownfish shark`` will print four lines.
|
|
|
|
Unlike :doc:`echo <echo>`, ``printf`` does not append a new line unless it is specified as part of the string.
|
|
|
|
It doesn't support any options, so there is no need for a ``--`` separator, which makes it easier to use for arbitrary input than ``echo``. [#]_
|
|
|
|
Format Specifiers
|
|
-----------------
|
|
Valid format specifiers are taken from the C library function ``printf(3)``:
|
|
|
|
- ``%d`` or ``%i``: Argument will be used as decimal integer (signed or unsigned)
|
|
|
|
- ``%o``: An octal unsigned integer
|
|
|
|
- ``%u``: An unsigned decimal integer - this means negative numbers will wrap around
|
|
|
|
- ``%x`` or ``%X``: An unsigned hexadecimal integer
|
|
|
|
- ``%f``, ``%g`` or ``%G``: A floating-point number. ``%f`` defaults to 6 places after the decimal point (which is locale-dependent - e.g. in de_DE it will be a ``,``). ``%g`` and ``%G`` will trim trailing zeroes and switch to scientific notation (like ``%e``) if the numbers get small or large enough.
|
|
|
|
- ``%e`` or ``%E``: A floating-point number in scientific (XXXeYY) notation
|
|
|
|
- ``%s``: A string
|
|
|
|
- ``%b``: As a string, interpreting backslash escapes, except that octal escapes are of the form \0 or \0ooo.
|
|
|
|
``%%`` signifies a literal "%".
|
|
|
|
Conversion can fail, e.g. "102.234" can't losslessly convert to an integer, causing printf to print an error. If you are okay with losing information, silence errors with ``2>/dev/null``.
|
|
|
|
A number between the ``%`` and the format letter specifies the width. The result will be left-padded with spaces.
|
|
|
|
Backslash Escapes
|
|
-----------------
|
|
printf also knows a number of backslash escapes:
|
|
|
|
- ``\"`` double quote
|
|
- ``\\`` backslash
|
|
- ``\a`` alert (bell)
|
|
- ``\b`` backspace
|
|
- ``\c`` produce no further output
|
|
- ``\e`` escape
|
|
- ``\f`` form feed
|
|
- ``\n`` new line
|
|
- ``\r`` carriage return
|
|
- ``\t`` horizontal tab
|
|
- ``\v`` vertical tab
|
|
- ``\ooo`` octal number (ooo is 1 to 3 digits)
|
|
- ``\xhh`` hexadecimal number (hhh is 1 to 2 digits)
|
|
- ``\uhhhh`` 16-bit Unicode character (hhhh is 4 digits)
|
|
- ``\Uhhhhhhhh`` 32-bit Unicode character (hhhhhhhh is 8 digits)
|
|
|
|
Errors and Return Status
|
|
------------------------
|
|
If the given argument doesn't work for the given format (like when you try to convert a number like 3.141592 to an integer), printf prints an error, to stderr. printf will then also return non-zero, but will still try to print as much as it can.
|
|
|
|
It will also return non-zero if no argument at all was given, in which case it will print nothing.
|
|
|
|
This printf has been imported from the printf in GNU Coreutils version 6.9. If you would like to use a newer version of printf, for example the one shipped with your OS, try ``command printf``.
|
|
|
|
Example
|
|
-------
|
|
|
|
::
|
|
|
|
printf '%s\t%s\n' flounder fish
|
|
|
|
Will print "flounder fish" (separated with a tab character), followed by a newline character. This is useful for writing completions, as fish expects completion scripts to output the option followed by the description, separated with a tab character.
|
|
|
|
::
|
|
|
|
printf '%s: %d' "Number of bananas in my pocket" 42
|
|
|
|
Will print "Number of bananas in my pocket: 42", `without` a newline.
|
|
|
|
See Also
|
|
--------
|
|
|
|
- the :doc:`echo <echo>` command, for simpler output
|
|
|
|
Footnotes
|
|
---------
|
|
.. [#] In fact, while fish's ``echo`` supports ``--``, POSIX forbids it, so other implementations can't be used if the input contains anything starting with ``-``.
|