Liking cljdoc? Tell your friends :D

boot.from.io.aviso.columns


format-columnsclj

(format-columns & column-defs)

Converts a number of column definitions into a formatting function. Each column definition may be:

  • a string, to indicate a non-consuming column that outputs a fixed value. This is often just a space character or two, to seperate columns.
  • a number, to indicate a consuming column that outputs a left justified value of the given width.
  • a vector containing a keyword and a number; the number is the width, the keyword is the justification.
  • :none, to indicate a consuming column with no explicit width
  • nil, which is treated like an empty string

With explicit justification, the keyword may be :left, :right, or :none.

:left : Pads the column with spaces after the value. Truncates long values from the right, displaying initial character and discarding trailing characters.

:right : Pads the column with spaces before the value. Truncates long values from the left.

:none : Does not pad with spaces at all, and should only be used in the final column.

Generally speaking, truncation does not occur because columns are sized to fit their contents.

A column width is required for :left or :right. Column width is optional and ignored for :none.

Values are normally string, but any type is accepted and will be converted to a string. This code is aware of ANSI codes and ignores them to calculate the length of a value for formatting and identation purposes.

There will likely be problems if a long string with ANSI codes is truncated, however.

The returned function accepts a [[StringWriter]] and the column values and writes each column value, with appropriate padding, to the [[StringWriter]].

Example:

(let [formatter (format-columns [:right 20] ": " [:right 20] ": " :none)]
  (write-rows *out* formatter [:last-name :first-name :age] customers))
Converts a number of column definitions into a formatting function. Each column definition may be:

- a string, to indicate a non-consuming column that outputs a fixed value. This is often just a space
character or two, to seperate columns.
- a number, to indicate a consuming column that outputs a left justified value of the given width.
- a vector containing a keyword and a number; the number is the width, the keyword is the justification.
- :none, to indicate a consuming column with no explicit width
- nil, which is treated like an empty string

With explicit justification, the keyword may be :left, :right, or :none.

:left
: Pads the column with spaces after the value. Truncates long values from the right, displaying
  initial character and discarding trailing characters.

:right
: Pads the column with spaces before the value. Truncates long values from the left.

:none
: Does not pad with spaces at all, and should only be used in the final column.

Generally speaking, truncation does not occur because columns are sized to fit their contents.

A column width is required for `:left` or `:right`. Column width is optional and ignored for `:none`.

Values are normally string, but any type is accepted and will be converted to a string.
This code is aware of ANSI codes and ignores them to calculate the length of a value for formatting and
identation purposes.

There will likely be problems if a long string with ANSI codes is truncated, however.

The returned function accepts a [[StringWriter]] and the column values and writes each column value, with appropriate
padding, to the [[StringWriter]].

Example:

    (let [formatter (format-columns [:right 20] ": " [:right 20] ": " :none)]
      (write-rows *out* formatter [:last-name :first-name :age] customers))
sourceraw docstring

max-lengthclj

(max-length coll)

Find the maximum length of the strings in the collection, based on their visual length (that is, omitting ANSI escape codes).

Find the maximum length of the strings in the collection, based on their visual length (that is,
omitting ANSI escape codes).
sourceraw docstring

max-value-lengthclj

(max-value-length coll key)

A convinience for computing the maximum length of one string property from a collection of values.

coll : collection of values

key : key that is passed one value and returns the property, typically a keyword when the values are maps

A convinience for computing the maximum length of one string property from a collection of values.

coll
: collection of values

key
: key that is passed one value and returns the property, typically a keyword when the values are maps
sourceraw docstring

write-rowsclj

(write-rows writer extended-columns-defs row-data)
(write-rows writer column-formatter extractors row-data)

A convienience for writing rows of columns using a prepared column formatter.

In the 3-arity version of the function, the extended-column-defs is used to automatically compute the column-formatter and extractors.

Extended column definitions are like the column definitions used with format-columns except:

  • The first value in each vector is the extractor (a function or keyword)
  • If the column layout is :left or :right, then the width of the column is computed as the max-value-length of that column (using the extractor and the row-data).
  • An extended column definition may not be a vector, but instead:
    • A string, which is treated as literal text
    • nil, which is ignored
    • otherwise, assumed to be an extractor whose values will be right justified

writer : [[StringWriter]] target of output

extended-column-defs : used to compute column-formatter and extractors taking into account row-data

column-formatter : formatter function created by format-columns

extractors : seq of functions that extract a column value from a row; typically a keyword when the row is a map

row-data : a seq of row data

Example:

(write-rows *out*
            [:last-name ", " :first-name ": " [:age :none]]
            customers)

This will write three columns, seperated by literal text. The first column will be right justified, and as wide as longest last name. The second column will also be right justified, and as wide as the longest first name. The final column will not be justified at all, so it will be varying width.

A convienience for writing rows of columns using a prepared column formatter.


In the 3-arity version of the function, the extended-column-defs is used to
automatically compute the column-formatter and extractors.

Extended column definitions are like the column definitions used with
[[format-columns]] except:

- The first value in each vector is the extractor (a function or keyword)
- If the column layout is :left or :right, then the width of the column is computed
  as the [[max-value-length]] of that column (using the extractor and the row-data).
- An extended column definition may not be a vector, but instead:
    - A string, which is treated as literal text
    - nil, which is ignored
    - otherwise, assumed to be an extractor whose values will be right justified

writer
: [[StringWriter]] target of output

extended-column-defs
: used to compute column-formatter and extractors taking into account row-data

column-formatter
: formatter function created by format-columns

extractors
: seq of functions that extract a column value from a row; typically a keyword when the row is a map

row-data
: a seq of row data

Example:

    (write-rows *out*
                [:last-name ", " :first-name ": " [:age :none]]
                customers)

This will write three columns, seperated by literal text.
The first column will be right justified, and as wide as longest last name.
The second column will also be right justified, and as wide as the longest first name.
The final column will not be justified at all, so it will be varying width.
sourceraw docstring

cljdoc is a website building & hosting documentation for Clojure/Script libraries

× close