From a58b4dbf2958e2221ab5591789dd70d423d88ea8 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Thu, 31 Oct 2024 16:52:03 -0700 Subject: [PATCH 1/3] Document how to print complex strings --- README.md | 37 ++++++++++++++++++++++++++++++++++--- 1 file changed, 34 insertions(+), 3 deletions(-) diff --git a/README.md b/README.md index 994ec4881c..682f42f232 100644 --- a/README.md +++ b/README.md @@ -3583,9 +3583,9 @@ The following command will create two files, `some` and `argument.txt`: $ just foo "some argument.txt" ``` -The users shell will parse `"some argument.txt"` as a single argument, but when -`just` replaces `touch {{argument}}` with `touch some argument.txt`, the quotes -are not preserved, and `touch` will receive two arguments. +The user's shell will parse `"some argument.txt"` as a single argument, but +when `just` replaces `touch {{argument}}` with `touch some argument.txt`, the +quotes are not preserved, and `touch` will receive two arguments. There are a few ways to avoid this: quoting, positional arguments, and exported arguments. @@ -3910,6 +3910,37 @@ fetch: Given the above `justfile`, after running `just fetch`, the recipes in `foo.just` will be available. +### Printing Complex Strings + +`echo` can be used to print strings, but because it processes escape sequences, +like `\n`, and different implementations of `echo` recognize different escape +sequences, using `printf` is often a better choice. + +`printf` takes a C-style format string and any number of arguments, which are +interpolated into the format string. + +This can be combined with indented, triple quoted strings to emulate shell +heredocs. + +Substitution into recipe bodies with `{…}` can also lead to trouble, as, +depending on the presence of whitespace and quotes, it may be split by the +shell into multiple arguments, so exporting complex strings and referring to +them with `"$NAME"` can also help. + +Putting all this together, to print a string verbatim to standard output, with +all its various escape sequences and quotes undisturbed: + +```just +export FOO := ''' + a complicated string with + various dis\tur\bi\ng escape sequences + and "quotes" of 'different' kinds +''' + +bar: + printf %s "$FOO" +``` + ### Alternatives and Prior Art There is no shortage of command runners! Some more or less similar alternatives From e6b1c5ec1902e51fe266215132656011783fdda4 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Thu, 31 Oct 2024 16:52:43 -0700 Subject: [PATCH 2/3] Enhance --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 682f42f232..bdfd2608f6 100644 --- a/README.md +++ b/README.md @@ -3922,7 +3922,7 @@ interpolated into the format string. This can be combined with indented, triple quoted strings to emulate shell heredocs. -Substitution into recipe bodies with `{…}` can also lead to trouble, as, +Substitution into recipe bodies with `{…}` can also lead to trouble as, depending on the presence of whitespace and quotes, it may be split by the shell into multiple arguments, so exporting complex strings and referring to them with `"$NAME"` can also help. From 7bf5866eee5b4b4a7f0dcdbb9067b7009e4ee431 Mon Sep 17 00:00:00 2001 From: Casey Rodarmor Date: Thu, 31 Oct 2024 16:54:08 -0700 Subject: [PATCH 3/3] Adjust --- README.md | 11 ++++++----- 1 file changed, 6 insertions(+), 5 deletions(-) diff --git a/README.md b/README.md index bdfd2608f6..ca596854fc 100644 --- a/README.md +++ b/README.md @@ -3922,10 +3922,11 @@ interpolated into the format string. This can be combined with indented, triple quoted strings to emulate shell heredocs. -Substitution into recipe bodies with `{…}` can also lead to trouble as, -depending on the presence of whitespace and quotes, it may be split by the -shell into multiple arguments, so exporting complex strings and referring to -them with `"$NAME"` can also help. +Substitution complex strings into recipe bodies with `{…}` can also lead to +trouble as it may be split by the shell into multiple arguments depending on +the presence of whitespace and quotes. Exporting complex strings as environment +variables and referring to them with `"$NAME"`, note the double quotes, can +also help. Putting all this together, to print a string verbatim to standard output, with all its various escape sequences and quotes undisturbed: @@ -3933,7 +3934,7 @@ all its various escape sequences and quotes undisturbed: ```just export FOO := ''' a complicated string with - various dis\tur\bi\ng escape sequences + some dis\tur\bi\ng escape sequences and "quotes" of 'different' kinds '''