ela
Contents

ManualPackages

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-inDoes
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.number without places writes the number as ela writes it, grouped: 1234.5 is 1,234.5, and a number ela writes with an exponent, 1e+21, keeps it, ungrouped. places is a whole number from 0 to 20; null is the same as leaving it out.
  • places rounds 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.675 is stored a little under, so to 2 places it is 2.67; 0.125 is exact, so 0.12; to no places 0.5 is 0, 1.5 2 and 2.5 2. A port prints the digits its original printed.
  • text.pad takes text only and never looks inside it: a number goes in as "$size", as ela writes it, or through text.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 --lint names both fixes.
  • The width is the total width, as ljust(8) and printf's %8s take 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.
  • align is "left", "right" or "center"; any other word written in the call stops the script before line 1. Centred, an odd column goes where Python's str.center puts it: on the right, unless the width is odd too: text.pad("a", 4, align = "center") is " a ", and text.pad("ab", 5, align = "center") is " ab ".
  • fill is any text a terminal draws one column wide: ., ─, 0, é even as e and an accent mark. Any other stops the script with fill 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) is amber-lib.