README.org

crockery

Crockery

Print clojure maps as a human-readable table.

Usage

Add the latest version of library to your app.

For leiningen or boot:

[com.joshuadavey/crockery "<version>"]}

or, for deps.edn:

{com.joshuadavey/crockery {:mvn/version "<latest version>"}}

Require crockery.core, which contains the primary API:

(require '[crockery.core :as crockery])

The examples that follow use this data:

(def people
  [{:first-name "Alice", :last-name "Anderson", :age 32, :dues "98.00"}
   {:first-name "Bob", :last-name "Bobberson", :age 29, :dues "17"},
   {:first-name "Carol", :last-name "Carola", :age 26, :dues "105.50"},
   {:first-name "Doug", :last-name "Duggler", :age 41, :dues "0.125"}])

Print a table, inferring column names from the first map of the collection:

(crockery/print-table people)

Or, specify the columns you want included:

(crockery/print-table [:age :last-name] people)

You can mix and match colspec forms (maps and keywords):

(crockery/print-table [{:name :last-name, :align :right} :first-name] people)

Colspec options

In map form, most keys are optional, but a colspec must have at least :name or :key-fn and :title.

:name

Use a keyword for both the getter function and the title of the column (titleized):

(crockery/print-table [{:name :age} {:name :last-name}] people)

:key-fn

Specify a different accessor function. It should be a function that takes one arg, and will be called for each “row” in the collection.

(crockery/print-table
 [{:title "Age (months)" :key-fn (comp (partial * 12) :age)}
  :first-name]
 people)

:width

Widths are normally calculated by finding the longest string per column, but you can also specify one:

(crockery/print-table [{:name :age, :width 10} {:name :last-name, :width 5}] people)

Values that are too long will be truncated.

:align

One of #{:left :center :right}, defaults to :left. Affects the data rows. When no :title-align is specified, also affects the header.

One special alignment, :decimal, attempts to line up the column so that the decimal point is in the same place in each row:

(crockery/print-table [:first-name :last-name {:name :dues :align :decimal}] people)

Since numbers are printed as strings, in reality, the decimal alignment just looks for the first decimal point as an alignment anchor.

:title

Provide your own header title rather than titleizing the :name parameter.

(crockery/print-table [:last-name {:name :first-name, :title "Given name"}] people)

:title-align

Same properties as :align, but only affects the header.

Formats

The default output format is an :org, which outputs an org-mode compatible table. There are other built-in formats that can be used. You can specify the format with the :format key in the options map, either before other arguments, or globally by rebinding the crockery.core/*default-options* var.

For each of these formats, the following colspec will be used:

(def colspec [:last-name
              {:name :first-name
               :title "Given name"
               :align :right}
              :age])

:org

This is the default format. See any of the above examples.

:plain

A fixed-width, unadorned output format.

(crockery/print-table {:format :plain} colspec people)

:simple

(crockery/print-table {:format :simple} colspec people)

:grid

(crockery/print-table {:format :grid} colspec people)

:presto

Another fixed-width format, with no surrounding border.

(crockery/print-table {:format :presto} colspec people)

:rst

Based on the reStructured Text table format.

(crockery/print-table {:format :rst} colspec people)

:fancy

This format uses unicode pipe characters. :fancy-grid is also available if you’d like separators between data rows.

(crockery/print-table {:format :fancy} colspec people)

:heavy

Like :fancy, but with bolder lines. :heavy-grid is also available if you’d like separators between data rows.

(crockery/print-table {:format :heavy} colspec people)

:rounded

Like :fancy, but with rounded corners. :rounded-grid is also available if you’d like separators between data rows.

(crockery/print-table {:format :rounded} colspec people)

:double

Like :fancy, but with rounded corners. :double-grid is also available if you’d like separators between data rows.

(crockery/print-table {:format :double} colspec people)

:mixed-grid

Like :fancy-grid, but with bolder separators between the header and body rows.

(crockery/print-table {:format :mixed-grid} colspec people)

:tsv

This tab-delimited format doesn’t look great when printed directly, but is convenient for further processing with common unix utils. Alignment options are ignored.

(crockery/print-table {:format :tsv} colspec people)

:gfm

Github-flavored Markdown (GFM) extends standard Markdown with a table syntax, including alignment designators.

(crockery/print-table {:format :gfm} colspec people)

License

Copyright © 2021 Joshua Davey

Distributed under the Eclipse Public License version 1.0.