Text for people
In the terminalela --spec text-for-people
text makes values into text for people: a size, a time, a number grouped or to fixed places,
and text padded out to a column. str is the procs that work on text; text is the procs that
make it. Its procs are typed, as ela --builtins shows them, so --lint checks a call.
| Built-in | Does |
|---|---|
text.bytes(n) | Returns a byte count in binary units, as free -h has them: 512 B, 3 KiB, 1.4 GiB |
text.duration(seconds) | Returns a time, short: 250ms, 1.2s, 3m 12s |
text.number(n: number, places: number? = null, group: bool = true) | Returns the number with its thousands grouped by commas: 1,234,567, 1,234.5; places fixes the decimals, text.number(1234.5, places = 2) gives 1,234.50; group = false leaves out the commas, as printf's %.2f writes it: 1234.50 |
text.pad(text: string, width: number, align: string = "left", fill: string = " ") | Returns the text filled out with fill to width columns on screen: on the right (align = "left", the default), on the left ("right") or on both sides ("center"); text as wide or wider comes back whole |
files = [{"name": "ela", "size": 5_123_456}, {"name": "✅ 日本.txt", "size": 812}]echo "${text.pad("name", 12)}${text.pad("bytes", 12, align = "right")}"for f in $files size = text.number($f["size"]) echo "${text.pad($f["name"], 12)}${text.pad($size, 12, align = "right")}"end forecho ${text.pad("", 24, fill = "─")}total = text.number(5123.456, places = 2)echo ${text.pad($total, 24, align = "right", fill = ".")}
name bytesela 5,123,456✅ 日本.txt 812────────────────────────................5,123.46
text.numberwithoutplaceswrites the number as ela writes it, grouped:1234.5is1,234.5, and a number ela writes with an exponent,1e+21, keeps it, ungrouped.placesis a whole number from 0 to 20;nullis the same as leaving it out.placesrounds as printf does, in C, Python, Go and Rust: the number as it is stored, in binary, with an exact half to the even digit.2.675is stored a little under, so to 2 places it is2.67;0.125is exact, so0.12; to no places0.5is0,1.52and2.52. A port prints the digits its original printed.text.padtakes text only and never looks inside it: a number goes in as"$size", as ela writes it, or throughtext.number,text.pad(text.number($total), 12, align = "right"). A number given stops the script, before line 1 where the call writes it or a call that gives one, and--lintnames both fixes.- The width is the total width, as
ljust(8)and printf's%8stake it, a whole number from 0 to 10000. It counts columns as a terminal draws them: a wide character (日,✅) takes two, a combining mark none, so a table holding them still lines up. The count is wcwidth's, from Unicode's tables, code point by code point: a joined emoji (👩💻) or a flag counts each part. alignis"left","right"or"center"; any other word written in the call stops the script before line 1. Centred, an odd column goes where Python'sstr.centerputs it: on the right, unless the width is odd too:text.pad("a", 4, align = "center")is" a ", andtext.pad("ab", 5, align = "center")is" ab ".fillis any text a terminal draws one column wide:.,─,0,éeven aseand an accent mark. Any other stops the script withfill must be one column wide; "ab" is 2, before line 1 when the call writes it, and when the line runs when a variable holds it.- Text wider than the width comes back whole, never cut:
text.pad("amber-lib", 6)isamber-lib.