From f5f96d9bcee78d517869f64d6f3b9bed5af3b3aa Mon Sep 17 00:00:00 2001 From: m11o Date: Tue, 4 Apr 2023 00:44:41 +0900 Subject: [PATCH 01/20] printf: move help strings to markdown file --- src/uu/printf/printf.md | 259 ++++++++++++++++++++++++++++++++++++ src/uu/printf/src/printf.rs | 259 +----------------------------------- 2 files changed, 263 insertions(+), 255 deletions(-) create mode 100644 src/uu/printf/printf.md diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md new file mode 100644 index 000000000..703a25fdb --- /dev/null +++ b/src/uu/printf/printf.md @@ -0,0 +1,259 @@ +# printf + +``` +printf FORMATSTRING [ARGUMENT]... +``` + +Print output based off of the format string and proceeding arguments. + +## After Help + +basic anonymous string templating: + +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 replaces anonymous fields with the next unused argument, formatted according to the field. + +Prints the , replacing escaped character sequences with character literals +and substitution field sequences with passed arguments + +literally, with the exception of the below +escaped character sequences, and the substitution sequences described further down. + +ESCAPE SEQUENCES + +The following escape sequences, organized here in alphabetical order, +will print the corresponding character literal: + +\" double quote + +\\\\ backslash + +\\a alert (BEL) + +\\b backspace + +\\c End-of-Input + +\\e escape + +\\f form feed + +\\n new line + +\\r carriage return + +\\t horizontal tab + +\\v vertical tab + +\\NNN byte with value expressed in octal value NNN (1 to 3 digits) +values greater than 256 will be treated + +\\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 character with value expressed in hexadecimal value HHHH (8 digits) + +%% a single % + +SUBSTITUTIONS + +SUBSTITUTION QUICK REFERENCE + +Fields + +%s - string +%b - string parsed for literals +second parameter is max length + +%c - char +no second parameter + +%i or %d - 64-bit integer +%u - 64 bit unsigned integer +%x or %X - 64-bit unsigned integer as hex +%o - 64-bit unsigned integer as octal +second parameter is min-width, integer +output below that width is padded with leading zeroes + +%f or %F - decimal floating point value +%e or %E - scientific notation floating point value +%g or %G - shorter of specially interpreted decimal or SciNote floating point value. +second parameter is +-max places after decimal point for floating point output +-max number of significant digits for scientific notation output + +parameterizing fields + +examples: + +printf '%4.3i' 7 +has a first parameter of 4 +and a second parameter of 3 +will result in ' 007' + +printf '%.1s' abcde +has no first parameter +and a second parameter of 1 +will result in 'a' + +printf '%4c' q +has a first parameter of 4 +and no second parameter +will result in ' q' + +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, +it will be padded with leading spaces, or, if the argument is negative, +with trailing spaces. the default is zero. + +The second parameter of a field is particular to the output field type. +defaults can be found in the full substitution help below + +special prefixes to numeric arguments +0 (e.g. 010) - interpret argument as octal (integer output fields only) +0x (e.g. 0xABC) - interpret argument as hex (numeric output fields only) +\' (e.g. \'a) - interpret argument as a character constant + +HOW TO USE SUBSTITUTIONS + +Substitutions are used to pass additional argument(s) into the FORMAT string, to be formatted a +particular way. E.g. + + printf 'the letter %X comes before the letter %X' 10 11 + +will print + +'the letter A comes before the letter B' + +because the substitution field %X means +'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 +repeated for the remaining substitutions + +printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York + +will print + +'it is 22 F in Portland +it is 25 F in Boston +it is 27 F in Boston +' +If a format string is printed but there are less arguments remaining +than there are substitution fields, substitution fields without +an argument will default to empty strings, or for numeric fields +the value 0 + +AVAILABLE SUBSTITUTIONS + +This program, like GNU coreutils printf, +interprets a modified subset of the POSIX C printf spec, +a quick reference to substitutions is below. + +STRING SUBSTITUTIONS +All string fields have a 'max width' parameter +%.3s means 'print no more than three characters of the original input' + +%s - string + +%b - escaped string - the string will be checked for any escaped literals from +the escaped literal list above, and translate them to literal characters. +e.g. \\n will be transformed into a newline character. + + One special rule about %b mode is that octal literals are interpreted differently + In arguments passed by %b, pass octal-interpreted literals must be in the form of \\0NNN + instead of \\NNN. (Although, for legacy reasons, octal literals in the form of \\NNN will + still be interpreted and not throw a warning, you will have problems if you use this for a + literal whose code begins with zero, as it will be viewed as in \\0NNN form.) + +CHAR SUBSTITUTIONS +The character field does not have a secondary parameter. + +%c - a single character + +INTEGER SUBSTITUTIONS +All integer fields have a 'pad with zero' parameter +%.4i means an integer which if it is less than 4 digits in length, +is padded with leading zeros until it is 4 digits in length. + +%d or %i - 64-bit integer + +%u - 64 bit unsigned integer + +%x or %X - 64 bit unsigned integer printed in Hexadecimal (base 16) +%X instead of %x means to use uppercase letters for 'a' through 'f' + +%o - 64 bit unsigned integer printed in octal (base 8) + +FLOATING POINT SUBSTITUTIONS + +All floating point fields have a 'max decimal places / max significant digits' parameter +%.10f means a decimal floating point with 7 decimal places past 0 +%.10e means a scientific notation number with 10 significant digits +%.10g means the same behavior for decimal and Sci. Note, respectively, and provides the shorter +of each's output. + +Like with GNU coreutils, the value after the decimal point is these outputs is parsed as a +double first before being rendered to text. For both implementations do not expect meaningful +precision past the 18th decimal place. When using a number of decimal places that is 18 or +higher, you can expect variation in output between GNU coreutils printf and this printf at the +18th decimal place of +/- 1 + +%f - floating point value presented in decimal, truncated and displayed to 6 decimal places by +default. There is not past-double behavior parity with Coreutils printf, values are not +estimated or adjusted beyond input values. + +%e or %E - floating point value presented in scientific notation +7 significant digits by default +%E means use to use uppercase E for the mantissa. + +%g or %G - floating point value presented in the shorter of decimal and scientific notation +behaves differently from %f and %E, please see posix printf spec for full details, +some examples of different behavior: + + Sci Note has 6 significant digits by default + Trailing zeroes are removed + Instead of being truncated, digit after last is rounded + +Like other behavior in this utility, the design choices of floating point +behavior in this utility is selected to reproduce in exact +the behavior of GNU coreutils' printf from an inputs and outputs standpoint. + +USING PARAMETERS +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. + +The 1st parameter always indicates the minimum width of output, it is useful for creating +columnar output. Any output that would be less than this minimum width is padded with +leading spaces +The 2nd parameter is proceeded by a dot. +You do not have to use parameters + +SPECIAL FORMS OF INPUT +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 +will be interpreted as octal (base 8) for integer fields + +Hexadecimal: if the argument begins with 0x the proceeding characters will be interpreted +will be interpreted as hex (base 16) for any numeric fields +for float fields, hexadecimal input results in a precision +limit (in converting input past the decimal point) of 10^-15 + +Character Constant: if the argument begins with a single quote character, the first byte +of the next character will be interpreted as an 8-bit unsigned integer. If there are +additional bytes, they will throw an error (unless the environment variable POSIXLY_CORRECT +is set) + +WRITTEN BY : +Nathan E. Ross, et al. for the uutils project + +MORE INFO : +https://github.com/uutils/coreutils + +COPYRIGHT : +Copyright 2015 uutils project. +Licensed under the MIT License, please see LICENSE file for details diff --git a/src/uu/printf/src/printf.rs b/src/uu/printf/src/printf.rs index 2592f212d..487f06ac1 100644 --- a/src/uu/printf/src/printf.rs +++ b/src/uu/printf/src/printf.rs @@ -4,265 +4,14 @@ use clap::{crate_version, Arg, ArgAction, Command}; use uucore::error::{UResult, UUsageError}; -use uucore::format_usage; +use uucore::{format_usage, help_about, help_usage, help_section}; use uucore::memo::printf; const VERSION: &str = "version"; const HELP: &str = "help"; -const USAGE: &str = "{} FORMATSTRING [ARGUMENT]..."; -const ABOUT: &str = "Print output based off of the format string and proceeding arguments."; -const AFTER_HELP: &str = " -basic anonymous string templating: - -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 replaces anonymous fields with the next unused argument, formatted according to the field. - -Prints the , replacing escaped character sequences with character literals - and substitution field sequences with passed arguments - -literally, with the exception of the below - escaped character sequences, and the substitution sequences described further down. - -ESCAPE SEQUENCES - -The following escape sequences, organized here in alphabetical order, -will print the corresponding character literal: - -\" double quote - -\\\\ backslash - -\\a alert (BEL) - -\\b backspace - -\\c End-of-Input - -\\e escape - -\\f form feed - -\\n new line - -\\r carriage return - -\\t horizontal tab - -\\v vertical tab - -\\NNN byte with value expressed in octal value NNN (1 to 3 digits) - values greater than 256 will be treated - -\\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 character with value expressed in hexadecimal value HHHH (8 digits) - -%% a single % - -SUBSTITUTIONS - -SUBSTITUTION QUICK REFERENCE - -Fields - -%s - string -%b - string parsed for literals - second parameter is max length - -%c - char - no second parameter - -%i or %d - 64-bit integer -%u - 64 bit unsigned integer -%x or %X - 64-bit unsigned integer as hex -%o - 64-bit unsigned integer as octal - second parameter is min-width, integer - output below that width is padded with leading zeroes - -%f or %F - decimal floating point value -%e or %E - scientific notation floating point value -%g or %G - shorter of specially interpreted decimal or SciNote floating point value. - second parameter is - -max places after decimal point for floating point output - -max number of significant digits for scientific notation output - -parameterizing fields - -examples: - -printf '%4.3i' 7 -has a first parameter of 4 - and a second parameter of 3 -will result in ' 007' - -printf '%.1s' abcde -has no first parameter - and a second parameter of 1 -will result in 'a' - -printf '%4c' q -has a first parameter of 4 - and no second parameter -will result in ' q' - -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, - it will be padded with leading spaces, or, if the argument is negative, - with trailing spaces. the default is zero. - -The second parameter of a field is particular to the output field type. - defaults can be found in the full substitution help below - -special prefixes to numeric arguments - 0 (e.g. 010) - interpret argument as octal (integer output fields only) - 0x (e.g. 0xABC) - interpret argument as hex (numeric output fields only) - \' (e.g. \'a) - interpret argument as a character constant - -HOW TO USE SUBSTITUTIONS - -Substitutions are used to pass additional argument(s) into the FORMAT string, to be formatted a -particular way. E.g. - - printf 'the letter %X comes before the letter %X' 10 11 - -will print - - 'the letter A comes before the letter B' - -because the substitution field %X means -'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 - repeated for the remaining substitutions - - printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York - -will print - - 'it is 22 F in Portland - it is 25 F in Boston - it is 27 F in Boston - ' -If a format string is printed but there are less arguments remaining - than there are substitution fields, substitution fields without - an argument will default to empty strings, or for numeric fields - the value 0 - -AVAILABLE SUBSTITUTIONS - -This program, like GNU coreutils printf, -interprets a modified subset of the POSIX C printf spec, -a quick reference to substitutions is below. - - STRING SUBSTITUTIONS - All string fields have a 'max width' parameter - %.3s means 'print no more than three characters of the original input' - - %s - string - - %b - escaped string - the string will be checked for any escaped literals from - the escaped literal list above, and translate them to literal characters. - e.g. \\n will be transformed into a newline character. - - One special rule about %b mode is that octal literals are interpreted differently - In arguments passed by %b, pass octal-interpreted literals must be in the form of \\0NNN - instead of \\NNN. (Although, for legacy reasons, octal literals in the form of \\NNN will - still be interpreted and not throw a warning, you will have problems if you use this for a - literal whose code begins with zero, as it will be viewed as in \\0NNN form.) - - CHAR SUBSTITUTIONS - The character field does not have a secondary parameter. - - %c - a single character - - INTEGER SUBSTITUTIONS - All integer fields have a 'pad with zero' parameter - %.4i means an integer which if it is less than 4 digits in length, - is padded with leading zeros until it is 4 digits in length. - - %d or %i - 64-bit integer - - %u - 64 bit unsigned integer - - %x or %X - 64 bit unsigned integer printed in Hexadecimal (base 16) - %X instead of %x means to use uppercase letters for 'a' through 'f' - - %o - 64 bit unsigned integer printed in octal (base 8) - - FLOATING POINT SUBSTITUTIONS - - All floating point fields have a 'max decimal places / max significant digits' parameter - %.10f means a decimal floating point with 7 decimal places past 0 - %.10e means a scientific notation number with 10 significant digits - %.10g means the same behavior for decimal and Sci. Note, respectively, and provides the shorter - of each's output. - - Like with GNU coreutils, the value after the decimal point is these outputs is parsed as a - double first before being rendered to text. For both implementations do not expect meaningful - precision past the 18th decimal place. When using a number of decimal places that is 18 or - higher, you can expect variation in output between GNU coreutils printf and this printf at the - 18th decimal place of +/- 1 - - %f - floating point value presented in decimal, truncated and displayed to 6 decimal places by - default. There is not past-double behavior parity with Coreutils printf, values are not - estimated or adjusted beyond input values. - - %e or %E - floating point value presented in scientific notation - 7 significant digits by default - %E means use to use uppercase E for the mantissa. - - %g or %G - floating point value presented in the shorter of decimal and scientific notation - behaves differently from %f and %E, please see posix printf spec for full details, - some examples of different behavior: - - Sci Note has 6 significant digits by default - Trailing zeroes are removed - Instead of being truncated, digit after last is rounded - - Like other behavior in this utility, the design choices of floating point - behavior in this utility is selected to reproduce in exact - the behavior of GNU coreutils' printf from an inputs and outputs standpoint. - -USING PARAMETERS - 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. - - The 1st parameter always indicates the minimum width of output, it is useful for creating - columnar output. Any output that would be less than this minimum width is padded with - leading spaces - The 2nd parameter is proceeded by a dot. - You do not have to use parameters - -SPECIAL FORMS OF INPUT - 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 - will be interpreted as octal (base 8) for integer fields - - Hexadecimal: if the argument begins with 0x the proceeding characters will be interpreted - will be interpreted as hex (base 16) for any numeric fields - for float fields, hexadecimal input results in a precision - limit (in converting input past the decimal point) of 10^-15 - - Character Constant: if the argument begins with a single quote character, the first byte - of the next character will be interpreted as an 8-bit unsigned integer. If there are - additional bytes, they will throw an error (unless the environment variable POSIXLY_CORRECT - is set) - -WRITTEN BY : - Nathan E. Ross, et al. for the uutils project - -MORE INFO : - https://github.com/uutils/coreutils - -COPYRIGHT : - Copyright 2015 uutils project. - Licensed under the MIT License, please see LICENSE file for details - -"; +const USAGE: &str = help_usage!("printf.md"); +const ABOUT: &str = help_about!("printf.md"); +const AFTER_HELP: &str = help_section!("after help", "printf.md"); mod options { pub const FORMATSTRING: &str = "FORMATSTRING"; From 57a70eb2000d91ec401e6d124243428c431d1c6e Mon Sep 17 00:00:00 2001 From: m11o Date: Tue, 4 Apr 2023 00:51:24 +0900 Subject: [PATCH 02/20] fix to align indents --- src/uu/printf/printf.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 703a25fdb..ceb1f0124 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -163,11 +163,11 @@ All string fields have a 'max width' parameter the escaped literal list above, and translate them to literal characters. e.g. \\n will be transformed into a newline character. - One special rule about %b mode is that octal literals are interpreted differently - In arguments passed by %b, pass octal-interpreted literals must be in the form of \\0NNN - instead of \\NNN. (Although, for legacy reasons, octal literals in the form of \\NNN will - still be interpreted and not throw a warning, you will have problems if you use this for a - literal whose code begins with zero, as it will be viewed as in \\0NNN form.) + One special rule about %b mode is that octal literals are interpreted differently + In arguments passed by %b, pass octal-interpreted literals must be in the form of \\0NNN + instead of \\NNN. (Although, for legacy reasons, octal literals in the form of \\NNN will + still be interpreted and not throw a warning, you will have problems if you use this for a + literal whose code begins with zero, as it will be viewed as in \\0NNN form.) CHAR SUBSTITUTIONS The character field does not have a secondary parameter. @@ -214,9 +214,9 @@ estimated or adjusted beyond input values. behaves differently from %f and %E, please see posix printf spec for full details, some examples of different behavior: - Sci Note has 6 significant digits by default - Trailing zeroes are removed - Instead of being truncated, digit after last is rounded + Sci Note has 6 significant digits by default + Trailing zeroes are removed + Instead of being truncated, digit after last is rounded Like other behavior in this utility, the design choices of floating point behavior in this utility is selected to reproduce in exact From e5d88082c4777d311d1091d231876b082fdabfca Mon Sep 17 00:00:00 2001 From: m11o Date: Tue, 4 Apr 2023 21:50:30 +0900 Subject: [PATCH 03/20] Fix style violation in src/uu/printf/src/printf.rs --- src/uu/printf/src/printf.rs | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/src/printf.rs b/src/uu/printf/src/printf.rs index 487f06ac1..bf79369cc 100644 --- a/src/uu/printf/src/printf.rs +++ b/src/uu/printf/src/printf.rs @@ -4,8 +4,8 @@ use clap::{crate_version, Arg, ArgAction, Command}; use uucore::error::{UResult, UUsageError}; -use uucore::{format_usage, help_about, help_usage, help_section}; use uucore::memo::printf; +use uucore::{format_usage, help_about, help_section, help_usage}; const VERSION: &str = "version"; const HELP: &str = "help"; From 23f7434530138f6b3672e3d12f7145a0aade5bb6 Mon Sep 17 00:00:00 2001 From: m11o Date: Tue, 4 Apr 2023 22:09:06 +0900 Subject: [PATCH 04/20] Ignore spells for spell-checker --- src/uu/printf/printf.md | 2 ++ 1 file changed, 2 insertions(+) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index ceb1f0124..b81c9f0f1 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -1,3 +1,5 @@ + + # printf ``` From feef6f4e24aa38346b7c611ffbd3a8a0eaf58d74 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Tue, 4 Apr 2023 22:32:07 +0900 Subject: [PATCH 05/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index ceb1f0124..65593b442 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -14,7 +14,7 @@ prints format string at least once, repeating as long as there are remaining arg 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. -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 literally, with the exception of the below From 76e15d049bf346ad75dc925a1576c0f0c484e3c4 Mon Sep 17 00:00:00 2001 From: m11o Date: Wed, 5 Apr 2023 01:36:30 +0900 Subject: [PATCH 06/20] Fix markdown --- src/uu/printf/printf.md | 205 ++++++++++++++++++++-------------------- 1 file changed, 101 insertions(+), 104 deletions(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index b75971544..ad6ad0d50 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -1,4 +1,4 @@ - + # printf @@ -22,89 +22,90 @@ and substitution field sequences with passed arguments literally, with the exception of the below escaped character sequences, and the substitution sequences described further down. -ESCAPE SEQUENCES +### ESCAPE SEQUENCES The following escape sequences, organized here in alphabetical order, 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) -values greater than 256 will be treated +* `\\NNN` byte with value expressed in octal value NNN (1 to 3 digits) + 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 -%s - string -%b - string parsed for literals -second parameter is max length +* `%s`: string +* `%b`: string parsed for literals second parameter is max length -%c - char -no second parameter +* `%c`: char no second parameter -%i or %d - 64-bit integer -%u - 64 bit unsigned integer -%x or %X - 64-bit unsigned integer as hex -%o - 64-bit unsigned integer as octal -second parameter is min-width, integer -output below that width is padded with leading zeroes +* `%i or %d`: 64-bit integer +* `%u`: 64 bit unsigned integer +* `%x or %X`: 64-bit unsigned integer as hex +* `%o`: 64-bit unsigned integer as octal + second parameter is min-width, integer + output below that width is padded with leading zeroes -%f or %F - decimal floating point value -%e or %E - scientific notation floating point value -%g or %G - shorter of specially interpreted decimal or SciNote floating point value. -second parameter is --max places after decimal point for floating point output --max number of significant digits for scientific notation output +* `%f or %F`: decimal floating point value +* `%e or %E`: scientific notation floating point value +* `%g or %G`: shorter of specially interpreted decimal or SciNote floating point value. + second parameter is + -max places after decimal point for floating point output + -max number of significant digits for scientific notation output parameterizing fields examples: +``` printf '%4.3i' 7 -has a first parameter of 4 -and a second parameter of 3 -will result in ' 007' +``` +It has a first parameter of 4 and a second parameter of 3 and will result in ' 007' + +``` printf '%.1s' abcde -has no first parameter -and a second parameter of 1 -will result in 'a' +``` +It has no first parameter and a second parameter of 1 and will result in 'a' + +``` printf '%4c' q -has a first parameter of 4 -and no second parameter -will result in ' q' +``` + +It has a first parameter of 4 and no second parameter and will result in ' q' 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, @@ -115,19 +116,21 @@ The second parameter of a field is particular to the output field type. defaults can be found in the full substitution help below special prefixes to numeric arguments -0 (e.g. 010) - interpret argument as octal (integer output fields only) -0x (e.g. 0xABC) - interpret argument as hex (numeric output fields only) -\' (e.g. \'a) - interpret argument as a character constant -HOW TO USE SUBSTITUTIONS +* `0 (e.g. 010)`: interpret argument as octal (integer output fields only) +* `0x (e.g. 0xABC)`: interpret argument as hex (numeric output fields only) +* `\' (e.g. \'a)`: interpret argument as a character constant + +#### HOW TO USE SUBSTITUTIONS Substitutions are used to pass additional argument(s) into the FORMAT string, to be formatted a 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 - 'the letter A comes before the letter B' because the substitution field %X means @@ -136,10 +139,11 @@ because the substitution field %X means Passing more arguments than are in the format string will cause the format string to be repeated for the remaining substitutions +``` printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York +``` will print - 'it is 22 F in Portland it is 25 F in Boston it is 27 F in Boston @@ -149,53 +153,55 @@ than there are substitution fields, substitution fields without an argument will default to empty strings, or for numeric fields the value 0 -AVAILABLE SUBSTITUTIONS +#### AVAILABLE SUBSTITUTIONS This program, like GNU coreutils printf, interprets a modified subset of the POSIX C printf spec, a quick reference to substitutions is below. -STRING SUBSTITUTIONS +#### STRING SUBSTITUTIONS + All string fields have a 'max width' parameter -%.3s means 'print no more than three characters of the original input' +`%.3s` means 'print no more than three characters of the original input' -%s - string +* `%s`: string -%b - escaped string - the string will be checked for any escaped literals from -the escaped literal list above, and translate them to literal characters. -e.g. \\n will be transformed into a newline character. +* `%b`: escaped string - the string will be checked for any escaped literals from + the escaped literal list above, and translate them to literal characters. + e.g. `\\n` will be transformed into a newline character. + One special rule about `%b` mode is that octal literals are interpreted differently + In arguments passed by `%b`, pass octal-interpreted literals must be in the form of `\\0NNN` + instead of `\\NNN`. (Although, for legacy reasons, octal literals in the form of `\\NNN` will + still be interpreted and not throw a warning, you will have problems if you use this for a + literal whose code begins with zero, as it will be viewed as in `\\0NNN` form.) - One special rule about %b mode is that octal literals are interpreted differently - In arguments passed by %b, pass octal-interpreted literals must be in the form of \\0NNN - instead of \\NNN. (Although, for legacy reasons, octal literals in the form of \\NNN will - still be interpreted and not throw a warning, you will have problems if you use this for a - literal whose code begins with zero, as it will be viewed as in \\0NNN form.) +#### CHAR SUBSTITUTIONS -CHAR SUBSTITUTIONS The character field does not have a secondary parameter. -%c - a single character +* `%c`: a single character + +#### INTEGER SUBSTITUTIONS -INTEGER SUBSTITUTIONS All integer fields have a 'pad with zero' parameter -%.4i means an integer which if it is less than 4 digits in length, +`%.4i` means an integer which if it is less than 4 digits in length, is padded with leading zeros until it is 4 digits in length. -%d or %i - 64-bit integer +* `%d or %i`: 64-bit integer -%u - 64 bit unsigned integer +* `%u`: 64-bit unsigned integer -%x or %X - 64 bit unsigned integer printed in Hexadecimal (base 16) -%X instead of %x means to use uppercase letters for 'a' through 'f' +* `%x or %X`: 64-bit unsigned integer printed in Hexadecimal (base 16) + `%X` instead of `%x` means to use uppercase letters for 'a' through 'f' -%o - 64 bit unsigned integer printed in octal (base 8) +* `%o`: 64-bit unsigned integer printed in octal (base 8) -FLOATING POINT SUBSTITUTIONS +#### FLOATING POINT SUBSTITUTIONS All floating point fields have a 'max decimal places / max significant digits' parameter -%.10f means a decimal floating point with 7 decimal places past 0 -%.10e means a scientific notation number with 10 significant digits -%.10g means the same behavior for decimal and Sci. Note, respectively, and provides the shorter +`%.10f` means a decimal floating point with 7 decimal places past 0 +`%.10e` means a scientific notation number with 10 significant digits +`%.10g` means the same behavior for decimal and Sci. Note, respectively, and provides the shortest of each's output. Like with GNU coreutils, the value after the decimal point is these outputs is parsed as a @@ -204,27 +210,27 @@ precision past the 18th decimal place. When using a number of decimal places tha higher, you can expect variation in output between GNU coreutils printf and this printf at the 18th decimal place of +/- 1 -%f - floating point value presented in decimal, truncated and displayed to 6 decimal places by -default. There is not past-double behavior parity with Coreutils printf, values are not -estimated or adjusted beyond input values. +* `%f`: floating point value presented in decimal, truncated and displayed to 6 decimal places by + default. There is not past-double behavior parity with Coreutils printf, values are not + estimated or adjusted beyond input values. -%e or %E - floating point value presented in scientific notation -7 significant digits by default -%E means use to use uppercase E for the mantissa. +* `%e or %E`: floating point value presented in scientific notation + 7 significant digits by default + `%E` means use to use uppercase E for the mantissa. -%g or %G - floating point value presented in the shorter of decimal and scientific notation -behaves differently from %f and %E, please see posix printf spec for full details, -some examples of different behavior: - - Sci Note has 6 significant digits by default - Trailing zeroes are removed - Instead of being truncated, digit after last is rounded +* `%g or %G`: floating point value presented in the shortest of decimal and scientific notation + behaves differently from `%f` and `%E`, please see posix printf spec for full details, + some examples of different behavior: + Sci Note has 6 significant digits by default + Trailing zeroes are removed + Instead of being truncated, digit after last is rounded Like other behavior in this utility, the design choices of floating point behavior in this utility is selected to reproduce in exact 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 be passed to the field, between the % sign and the field letter. @@ -234,7 +240,8 @@ leading spaces The 2nd parameter is proceeded by a dot. 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: Octal (only with integer): if the argument begins with a 0 the proceeding characters @@ -249,13 +256,3 @@ Character Constant: if the argument begins with a single quote character, the fi of the next character will be interpreted as an 8-bit unsigned integer. If there are additional bytes, they will throw an error (unless the environment variable POSIXLY_CORRECT is set) - -WRITTEN BY : -Nathan E. Ross, et al. for the uutils project - -MORE INFO : -https://github.com/uutils/coreutils - -COPYRIGHT : -Copyright 2015 uutils project. -Licensed under the MIT License, please see LICENSE file for details From b8a3f14fb3f1a35e54029b520925fdeca11f2a3a Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:19:57 +0900 Subject: [PATCH 07/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index ad6ad0d50..9dadba433 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -71,7 +71,7 @@ Fields * `%c`: char no second parameter -* `%i or %d`: 64-bit integer +* `%i` or `%d`: 64-bit integer * `%u`: 64 bit unsigned integer * `%x or %X`: 64-bit unsigned integer as hex * `%o`: 64-bit unsigned integer as octal From 75bb1661687998a58672d0734708efb8be7028f3 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:20:37 +0900 Subject: [PATCH 08/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 9dadba433..d5c7d4f14 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -73,7 +73,7 @@ Fields * `%i` or `%d`: 64-bit 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 second parameter is min-width, integer output below that width is padded with leading zeroes From 46f11737e1defa5e67850023eb6b024ae9daf5e2 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:20:46 +0900 Subject: [PATCH 09/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index d5c7d4f14..d8f57b26c 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -78,7 +78,7 @@ Fields second parameter is min-width, integer 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 * `%g or %G`: shorter of specially interpreted decimal or SciNote floating point value. second parameter is From 13bb755e6035992365a9976f88f1fb56b0f0b27d Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:21:33 +0900 Subject: [PATCH 10/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index d8f57b26c..6387b856b 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -79,7 +79,7 @@ Fields output below that width is padded with leading zeroes * `%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. second parameter is -max places after decimal point for floating point output From f688a7ec8d45a800d842407a5f9946fb4b90beff Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:21:44 +0900 Subject: [PATCH 11/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 6387b856b..ae6f36280 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -80,7 +80,7 @@ Fields * `%f` or `%F`: decimal 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 -max places after decimal point for floating point output -max number of significant digits for scientific notation output From 097002bdaf7ce23772b9513a472bda5d8d3a4689 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:21:57 +0900 Subject: [PATCH 12/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index ae6f36280..0151e14c0 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -82,7 +82,7 @@ Fields * `%e` or `%E`: scientific notation floating point value * `%g` or `%G`: shorter of specially interpreted decimal or SciNote floating point value. 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 parameterizing fields From ade823c16301d39459adbf121ab18032a272855d Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:22:08 +0900 Subject: [PATCH 13/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 0151e14c0..8bff53edc 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -83,7 +83,7 @@ Fields * `%g` or `%G`: shorter of specially interpreted decimal or SciNote floating point value. second parameter is `-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 From a838c31978331012149b52d186d15e8bf1c1f159 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:22:26 +0900 Subject: [PATCH 14/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 8bff53edc..097eeb8ef 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -214,7 +214,7 @@ higher, you can expect variation in output between GNU coreutils printf and this default. There is not past-double behavior parity with Coreutils printf, values are not estimated or adjusted beyond input values. -* `%e or %E`: floating point value presented in scientific notation +* `%e` or `%E`: floating point value presented in scientific notation 7 significant digits by default `%E` means use to use uppercase E for the mantissa. From 109aa925c43f71336ffa20584f1e43484f264b3e Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:23:27 +0900 Subject: [PATCH 15/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 097eeb8ef..5acc99bf3 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -187,7 +187,7 @@ All integer fields have a 'pad with zero' parameter `%.4i` means an integer which if it is less than 4 digits in length, is padded with leading zeros until it is 4 digits in length. -* `%d or %i`: 64-bit integer +* `%d` or `%i`: 64-bit integer * `%u`: 64-bit unsigned integer From 11f3976e352fb3e2d5f4ed33524b3c9136b3239d Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:24:06 +0900 Subject: [PATCH 16/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 5acc99bf3..e596c0831 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -191,7 +191,7 @@ is padded with leading zeros until it is 4 digits in length. * `%u`: 64-bit unsigned integer -* `%x or %X`: 64-bit unsigned integer printed in Hexadecimal (base 16) +* `%x` or `%X`: 64-bit unsigned integer printed in Hexadecimal (base 16) `%X` instead of `%x` means to use uppercase letters for 'a' through 'f' * `%o`: 64-bit unsigned integer printed in octal (base 8) From cbc0ff67718d606ed1e73957fad3c3ef047a75e3 Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:24:19 +0900 Subject: [PATCH 17/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index e596c0831..4aeeae3f7 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -218,7 +218,7 @@ higher, you can expect variation in output between GNU coreutils printf and this 7 significant digits by default `%E` means use to use uppercase E for the mantissa. -* `%g or %G`: floating point value presented in the shortest of decimal and scientific notation +* `%g` or `%G`: floating point value presented in the shortest of decimal and scientific notation behaves differently from `%f` and `%E`, please see posix printf spec for full details, some examples of different behavior: Sci Note has 6 significant digits by default From 5633eb9cd7e411f03707bd01fa4998fe5a5921cd Mon Sep 17 00:00:00 2001 From: Masahito Osako <43847020+m11o@users.noreply.github.com> Date: Thu, 6 Apr 2023 00:25:28 +0900 Subject: [PATCH 18/20] Update src/uu/printf/printf.md Co-authored-by: Sylvestre Ledru --- src/uu/printf/printf.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 4aeeae3f7..1d25a0e59 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -133,7 +133,7 @@ printf 'the letter %X comes before the letter %X' 10 11 will print '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' Passing more arguments than are in the format string will cause the format string to be From 45ce14c85bec0b6a8625d7833382c3dfcb8cc9d5 Mon Sep 17 00:00:00 2001 From: m11o Date: Thu, 6 Apr 2023 00:44:26 +0900 Subject: [PATCH 19/20] fix review to use code block --- src/uu/printf/printf.md | 12 +++++++++--- 1 file changed, 9 insertions(+), 3 deletions(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index 1d25a0e59..e64321ede 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -131,7 +131,10 @@ printf 'the letter %X comes before the letter %X' 10 11 ``` will print -'the letter A comes before the letter B' + +``` +the letter A comes before the letter B +``` because the substitution field `%X` means 'take an integer argument and write it as a hexadecimal number' @@ -144,10 +147,13 @@ printf 'it is %i F in %s \n' 22 Portland 25 Boston 27 New York ``` will print -'it is 22 F in Portland + +``` +it is 22 F in Portland it is 25 F in Boston it is 27 F in Boston -' +``` + If a format string is printed but there are less arguments remaining than there are substitution fields, substitution fields without an argument will default to empty strings, or for numeric fields From 1c5f068886b1a0fbaee563b31593b970961b2e9a Mon Sep 17 00:00:00 2001 From: m11o Date: Thu, 6 Apr 2023 00:50:02 +0900 Subject: [PATCH 20/20] use ` for keyword --- src/uu/printf/printf.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/uu/printf/printf.md b/src/uu/printf/printf.md index e64321ede..60b50354c 100644 --- a/src/uu/printf/printf.md +++ b/src/uu/printf/printf.md @@ -117,9 +117,9 @@ defaults can be found in the full substitution help below special prefixes to numeric arguments -* `0 (e.g. 010)`: interpret argument as octal (integer output fields only) -* `0x (e.g. 0xABC)`: interpret argument as hex (numeric output fields only) -* `\' (e.g. \'a)`: interpret argument as a character constant +* `0`: (e.g. 010) interpret argument as octal (integer output fields only) +* `0x`: (e.g. 0xABC) interpret argument as hex (numeric output fields only) +* `\'`: (e.g. \'a) interpret argument as a character constant #### HOW TO USE SUBSTITUTIONS