fmt: format lua types

The fmt module is a small module which formats arbitrary lua types as well as enables users to define formatting for their own metatypes via the :__fmt(fmter) method.

It also provides several helper methods such as print, assertf and errorf, making it more convienent to print or format types. In addition, it sets io.fmt = io.fmt or Fmt{to=io.stderr}, providing a default hook for ds.html#ds.log and command line utilities to write formatted text to.

The #fmt.Fmt interface (which is passed to a metaty's __fmt method if present) accepts both :write(...) (like a file) and :styled("style", "styled text", ..."non-styled text"), enabling the asciicolor library (or your own library!) to provide user-configurable colors for specific styles which integrate with the vt100 library and the cxt libraries. This is used throughout civstack to provide user-configurable (and optional) color to the terminal, web-pages and the ele editor.

Mod fmt

format module: format any type into a readable string

Types: Fmt

Functions

• fn cmpDuck(a, b)
  Compares two values of any type.

  Note: nil < bool < number < string < table

• fn sortKeys(t) -> list
  Return a list of the table's keys sorted using cmpDuck
• fn tostring(v, fmt)
  Similar to lua's tostring() function except formats tables/types.
• fn format(fmt, ...)
  Similar to lua's string.format(...) function except %q formats tables/types.
• fn errorf(...)
  Shortcut for error(fmt.format(...))
• fn assertf(a, ...) -> a
  Asserts a else throws error(fmt.format(...)).
• fn fprint(fmter, ...)
  Writes the formatted arguments to f.
• fn print(io.fmt, ...)
  print(...) but using io.fmt.
• fn pprint(...)
  pretty print
• fn pretty(v) -> string
  pretty format the value
• fn table(tbl)
  Set to __fmt to format a type like a table.

Record Fmt

The formatter object.

This is the main API of this module. It enables formatting any type by simply calling it's instance, writing the result to to (if set) or just the fmter itself. For the latter, you can construct the string with fmter:tostring() or just table.concat(fmter).

Fields:

• style enable styling. If true, set to=Styler
• to if set calls write
• keyEnd =", "
• keySet ="="
• indexEnd =", "
• tableStart ="{"
• tableEnd ="}"
• listEnd ="" separator between list/map
• indent ="  "
• maxIndent =20
• numfmt ="%q"
• strfmt ="%q"
• table =Fmt.table
• string =Fmt.string

Methods

• fn:toPretty()
• fn pretty(T, self) -> T(self):toPretty()
  Create a new Formatter object with default "pretty" settings. Generally, this means line-separated and indented tables.
• fn:level(add) -> int: current level
  Add to the indent level and get the new value call with add=nil to just get the current level
• fn:write(...)
  Same as file:write.
• fn:flush()
• fn:close()
• fn:styled(style, text, ...)
  Call to:styled(...) if it is enabled, else simply self:write(text, ...). This allows for configurable styling of output, both for objects as well as command-line utilities/etc.
• fn:tableKey(k)
  Format like a table key. This can be overriden by type extensions to provide other behavior.
• fn nil(self)
  format a nil value.
• fn:boolean(b)
  format a boolean value.
• fn:number(n)
  format a number value.
• fn:string(s)
  format a string value.
• fn:thread(th)
  format a thread value.
• fn:userdata(ud)
  format a userdata value.
• fn function(self, fn)
  format a function value.
• fn:items(t, hasKeys, listEnd)
  format items in table "list"
• fn:keyvals(t, keys)
  format key/vals in table "map".
• fn:list(t)
  Format only the list-elements of a table.
• fn:rawtable(t)
• fn:table(t)
  Recursively format a table. Yes this is complicated. No, there is no way to really improve this while preserving the features.
• fn:format(fmt, ...) -> varargsUsed
  like string.format but use Fmt for %q. Doesn't return the string, instead writes to Fmt
• fn:concat(sep, ...) -> self
  fmt ... separated by sep
• fn:tabulated('\t', ...)
  fmt ... separated by tabs
• fn:lined('\n', ...)
  fmt ... separated by newlines
• fn:tostring()
  Returns the concattenated string written to the formatter.
  Error if to is set.

Command fmt.binary

Library to format binary text.

Cmd usage: seebin path/to/file.bin Arguments:

• width =16 column width in bytes
• fmt ="%.2x " format string for hex
• to file to output to
• i =0 starting index to use

Methods and Functions

• fn format(f, str, fmt)
• fn ascii(f, str)
• fn columns(f, str, width, si, fmt)
• fn bstring(...) -> string
  Simple API to get the concatenated arguments as binary.