From a57739a26d15217f78a2ab0e7002d672fff9793e Mon Sep 17 00:00:00 2001 From: Matthias Zenger Date: Sun, 7 May 2023 00:05:43 +0200 Subject: [PATCH] Document justification directive ~<...~>. --- DIRECTIVES.md | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++- 1 file changed, 70 insertions(+), 1 deletion(-) diff --git a/DIRECTIVES.md b/DIRECTIVES.md index 0250a4d..818bb89 100644 --- a/DIRECTIVES.md +++ b/DIRECTIVES.md @@ -641,7 +641,76 @@ introduced in a way to not impact backward compatibility. it will not override an explicit prefix parameter of zero. If str is empty, then an argument is used as str. It must be a string and precede any arguments processed by the iteration.

-

+ + + + ~<…~> + +

JUSTIFICATION:   + ~mincol,colinc,minpad,padchar,maxcol,elchar<str~>

+

This directive justifies the text produced by processing control string str within + a field which is at least mincol columns wide (default: 0). str may be + divided up into segments via directive ~;, in which case the spacing is evenly + divided between the text segments.

+

With no modifiers, the leftmost text segment is left-justified in the field and the + rightmost text segment is right-justified. If there is only one text element, it is + right-justified. The : modifier causes spacing to be introduced before the + first text segment. The @ modifier causes spacing to be added after the last + text segment. The minpad parameter (default: 0) is the minimum number of padding + characters to be output between each segment. Whenever padding is needed, the padding + character padchar (default: ' ') is used. If the total width needed to satisfy the + constraints is greater than mincol, then the width used is + mincol + k × colinc for the smallest possible non-negative integer k + with colinc defaulting to 1.

+

  clformat("|~10,,,'.<foo~;bar~>|") + ⟹ |foo....bar|
+   clformat("|~10,,,'.:<foo~;bar~>|") + ⟹ |..foo..bar|
+   clformat("|~10,,,'.:@<foo~;bar~>|") + ⟹ |..foo.bar.|
+   clformat("|~10,,,'.<foobar~>|") + ⟹ |....foobar|
+   clformat("|~10,,,'.:<foobar~>|") + ⟹ |....foobar|
+   clformat("|~10,,,'.@<foobar~>|") + ⟹ |foobar....|
+   clformat("|~10,,,'.:@<foobar~>|") + ⟹ |..foobar..|

+

Note that str may include format directives. All the clauses in str are + processed in order. It is the resulting pieces of text that are justified. The ~^ + directive may be used to terminate processing of the clauses prematurely, in which case + only the completely processed clauses are justified.

+

If the first clause of a ~< directive is terminated with ~:; instead + of ~;, then it is used in a special way. All of the clauses are processed, but + the first one is not used in performing the spacing and padding. When the padded result + has been determined, then, if it fits on the current line of output, it is output, and + the text for the first clause is discarded. If, however, the padded text does not fit + on the current line, then the text segment for the first clause is output before the + padded text. The first clause ought to contain a newline (such as a ~% directive). + The first clause is always processed, and so any arguments it refers to will be used. + The decision is whether to use the resulting segment of text, not whether to process the + first clause. If the ~:; has a prefix parameter n, then the padded text + must fit on the current line with n character positions to spare to avoid + outputting the first clause’s text.

+

For example, the control string in the following example can be used to print a list + of items separated by comma without breaking items over line boundaries, beginning + each line with ;;. The prefix parameter 1 in ~1:; accounts for the width + of the comma that will follow the justified item if it is not the last element in the list, + or the period if it is. If ~:; has a second prefix parameter, like below, then it + is used as the width of the line, overriding the line width as specified by + clformat's linewidth: parameter (default: 80).

+

  clformat("~%;; ~{~<~%;; ~1,30:; ~S~>~^,~}.~%",
+            args: ["first line", "second", "a long third line",
+                   "fourth", "fifth"])
+     ⟹ 
+          ;; "first line", "second",
+          ;; "a long third line",
+          ;; "fourth", "fifth".
+          

+

If there is only one text segment str and parameter maxcol is provided and + the length of the output of str is exceeding maxcol, then the output is + truncated at width maxcol - 1 and the ellipsis character elchar + (default: '…') is inserted at the end.