RGBCube/uutils-coreutils
1
Fork 0
mirror of https://github.com/RGBCube/uutils-coreutils synced 2025-07-28 03:27:44 +00:00
Code Issues Activity

Merge pull request #3024 from ndd7xv/printf-version-documentation

Browse source 
printf: add description and version
This commit is contained in:
Sylvestre Ledru 2022-02-04 10:45:28 +01:00 • committed by GitHub
commit 572a505119
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 178 additions and 169 deletions
Download patch file Download diff file Expand all files Collapse all files

149
src/uu/printf/src/printf.rs
View file

@ -9,15 +9,17 @@ use uucore::InvalidEncodingHandling;
const VERSION: &str = "version"; const VERSION: &str = "version";
const HELP: &str = "help"; const HELP: &str = "help";
const USAGE: &str = "printf FORMATSTRING [ARGUMENT]...";
const ABOUT: &str = "Print output based off of the format string and proceeding arguments.";
static LONGHELP_LEAD: &str = "printf static LONGHELP_LEAD: &str = "printf
USAGE: printf FORMATSTRING [ARGUMENT]... USAGE: printf FORMATSTRING [ARGUMENT]...
basic anonymous string templating: basic anonymous string templating:
prints format string at least once, repeating as long as there are remaining arguments prints format string at least once, repeating as long as there are remaining arguments
output prints escaped literals in the format string as character literals output prints escaped literals in the format string as character literals
output replaces anonymous fields with the next unused argument, formatted according to the field. output replaces anonymous fields with the next unused argument, formatted according to the field.
Options: Options:
--help display this help and exit --help display this help and exit
@ -25,144 +27,144 @@ Options:
"; ";
static LONGHELP_BODY: &str = " static LONGHELP_BODY: &str = "
Prints the , replacing escaped character sequences with character literals Prints the , replacing escaped character sequences with character literals
and substitution field sequences with passed arguments and substitution field sequences with passed arguments
literally, with the exception of the below literally, with the exception of the below
escaped character sequences, and the substitution sequences described further down. escaped character sequences, and the substitution sequences described further down.
ESCAPE SEQUENCES ESCAPE SEQUENCES
The following escape sequences, organized here in alphabetical order, The following escape sequences, organized here in alphabetical order,
will print the corresponding character literal: will print the corresponding character literal:
\" double quote \" double quote
\\\\ backslash \\\\ backslash
\\a alert (BEL) \\a alert (BEL)
\\b backspace \\b backspace
\\c End-of-Input \\c End-of-Input
\\e escape \\e escape
\\f form feed \\f form feed
\\n new line \\n new line
\\r carriage return \\r carriage return
\\t horizontal tab \\t horizontal tab
\\v vertical tab \\v vertical tab
\\NNN byte with value expressed in octal value NNN (1 to 3 digits) \\NNN byte with value expressed in octal value NNN (1 to 3 digits)
values greater than 256 will be treated values greater than 256 will be treated
\\xHH byte with value expressed in hexadecimal value NN (1 to 2 digits) \\xHH byte with value expressed in hexadecimal value NN (1 to 2 digits)
\\uHHHH Unicode (IEC 10646) character with value expressed in hexadecimal value HHHH (4 digits) \\uHHHH Unicode (IEC 10646) character with value expressed in hexadecimal value HHHH (4 digits)
\\uHHHH Unicode character with value expressed in hexadecimal value HHHH (8 digits) \\uHHHH Unicode character with value expressed in hexadecimal value HHHH (8 digits)
%% a single % %% a single %
SUBSTITUTIONS SUBSTITUTIONS
SUBSTITUTION QUICK REFERENCE SUBSTITUTION QUICK REFERENCE
Fields Fields
%s - string %s - string
%b - string parsed for literals %b - string parsed for literals
second parameter is max length second parameter is max length
%c - char %c - char
no second parameter no second parameter
%i or %d - 64-bit integer %i or %d - 64-bit integer
%u - 64 bit unsigned integer %u - 64 bit unsigned integer
%x or %X - 64-bit unsigned integer as hex %x or %X - 64-bit unsigned integer as hex
%o - 64-bit unsigned integer as octal %o - 64-bit unsigned integer as octal
second parameter is min-width, integer second parameter is min-width, integer
output below that width is padded with leading zeroes output below that width is padded with leading zeroes
%f or %F - decimal floating point value %f or %F - decimal floating point value
%e or %E - scientific notation floating point value %e or %E - scientific notation floating point value
%g or %G - shorter of specially interpreted decimal or SciNote floating point value. %g or %G - shorter of specially interpreted decimal or SciNote floating point value.
second parameter is second parameter is
-max places after decimal point for floating point output -max places after decimal point for floating point output
-max number of significant digits for scientific notation output -max number of significant digits for scientific notation output
parameterizing fields parameterizing fields
examples: examples:
printf '%4.3i' 7 printf '%4.3i' 7
has a first parameter of 4 has a first parameter of 4
and a second parameter of 3 and a second parameter of 3
will result in ' 007' will result in ' 007'
printf '%.1s' abcde printf '%.1s' abcde
has no first parameter has no first parameter
and a second parameter of 1 and a second parameter of 1
will result in 'a' will result in 'a'
printf '%4c' q printf '%4c' q
has a first parameter of 4 has a first parameter of 4
and no second parameter and no second parameter
will result in ' q' will result in ' q'
The first parameter of a field is the minimum width to pad the output to The first parameter of a field is the minimum width to pad the output to
if the output is less than this absolute value of this width, if the output is less than this absolute value of this width,
it will be padded with leading spaces, or, if the argument is negative, it will be padded with leading spaces, or, if the argument is negative,
with trailing spaces. the default is zero. with trailing spaces. the default is zero.
The second parameter of a field is particular to the output field type. The second parameter of a field is particular to the output field type.
defaults can be found in the full substitution help below defaults can be found in the full substitution help below
special prefixes to numeric arguments special prefixes to numeric arguments
0 (e.g. 010) - interpret argument as octal (integer output fields only) 0 (e.g. 010) - interpret argument as octal (integer output fields only)
0x (e.g. 0xABC) - interpret argument as hex (numeric output fields only) 0x (e.g. 0xABC) - interpret argument as hex (numeric output fields only)
\' (e.g. \'a) - interpret argument as a character constant \' (e.g. \'a) - interpret argument as a character constant
HOW TO USE SUBSTITUTIONS HOW TO USE SUBSTITUTIONS
Substitutions are used to pass additional argument(s) into the FORMAT string, to be formatted a Substitutions are used to pass additional argument(s) into the FORMAT string, to be formatted a
particular way. E.g. particular way. E.g.
printf 'the letter %X comes before the letter %X' 10 11 printf 'the letter %X comes before the letter %X' 10 11
will print will print
'the letter A comes before the letter B' 'the letter A comes before the letter B'
because the substitution field %X means because the substitution field %X means
'take an integer argument and write it as a hexadecimal number' 'take an integer argument and write it as a hexadecimal number'
Passing more arguments than are in the format string will cause the format string to be Passing more arguments than are in the format string will cause the format string to be
repeated for the remaining substitutions repeated for the remaining substitutions
printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York
will print will print
'it is 22 F in Portland 'it is 22 F in Portland
it is 25 F in Boston it is 25 F in Boston
it is 27 F in Boston it is 27 F in Boston
' '
If a format string is printed but there are less arguments remaining If a format string is printed but there are less arguments remaining
than there are substitution fields, substitution fields without than there are substitution fields, substitution fields without
an argument will default to empty strings, or for numeric fields an argument will default to empty strings, or for numeric fields
the value 0 the value 0
AVAILABLE SUBSTITUTIONS AVAILABLE SUBSTITUTIONS
This program, like GNU coreutils printf, This program, like GNU coreutils printf,
interprets a modified subset of the POSIX C printf spec, interprets a modified subset of the POSIX C printf spec,
a quick reference to substitutions is below. a quick reference to substitutions is below.
STRING SUBSTITUTIONS STRING SUBSTITUTIONS
All string fields have a 'max width' parameter All string fields have a 'max width' parameter
@ -233,7 +235,7 @@ static LONGHELP_BODY: &str = "
behavior in this utility is selected to reproduce in exact behavior in this utility is selected to reproduce in exact
the behavior of GNU coreutils' printf from an inputs and outputs standpoint. the behavior of GNU coreutils' printf from an inputs and outputs standpoint.
USING PARAMETERS USING PARAMETERS
Most substitution fields can be parameterized using up to 2 numbers that can Most substitution fields can be parameterized using up to 2 numbers that can
be passed to the field, between the % sign and the field letter. be passed to the field, between the % sign and the field letter.
@ -243,7 +245,7 @@ static LONGHELP_BODY: &str = "
The 2nd parameter is proceeded by a dot. The 2nd parameter is proceeded by a dot.
You do not have to use parameters You do not have to use parameters
SPECIAL FORMS OF INPUT SPECIAL FORMS OF INPUT
For numeric input, the following additional forms of input are accepted besides decimal: For numeric input, the following additional forms of input are accepted besides decimal:
Octal (only with integer): if the argument begins with a 0 the proceeding characters Octal (only with integer): if the argument begins with a 0 the proceeding characters
@ -295,7 +297,14 @@ pub fn uumain(args: impl uucore::Args) -> UResult<()> {
pub fn uu_app<'a>() -> App<'a> { pub fn uu_app<'a>() -> App<'a> {
App::new(uucore::util_name()) App::new(uucore::util_name())
.arg(Arg::new(VERSION).long(VERSION)) .version(crate_version!())
.arg(Arg::new(HELP).long(HELP)) .about(ABOUT)
.override_usage(USAGE)
.arg(Arg::new(HELP).long(HELP).help("Print help information"))
.arg(
Arg::new(VERSION)
.long(VERSION)
.help("Print version information"),
)
.setting(AppSettings::InferLongArgs) .setting(AppSettings::InferLongArgs)
} }