Liking cljdoc? Tell your friends :D

clj-commons.ansi

Help with generating textual output that includes ANSI escape codes for formatting. The compose function is the best starting point.

Reference: ANSI Escape Codes @ Wikipedia.

Help with generating textual output that includes ANSI escape codes for formatting.
The [[compose]] function is the best starting point.

Reference: [ANSI Escape Codes @ Wikipedia](https://en.wikipedia.org/wiki/ANSI_escape_code#SGR).
raw docstring

*color-enabled*clj

Determines if ANSI colors are enabled; color is a deliberate misnomer, as we lump other font characteristics (bold, underline, italic, etc.) along with colors.

This will be false if the environment variable NO_COLOR is non-blank.

Otherwise, the JVM system property clj-commons.ansi.enabled (if present) determines the value; "true" enables colors, any other value disables colors.

If the property is null, then the default is a best guess based on the environment: if either the nrepl.core namespace is present, or the JVM has a console (via (System/console)), then color will be enabled.

The nrepl.core check has been verified to work with Cursive, with lein repl, and with clojure (or clj).

Determines if ANSI colors are enabled; color is a deliberate misnomer, as we lump
other font characteristics (bold, underline, italic, etc.) along with colors.

This will be false if the environment variable NO_COLOR is non-blank.

Otherwise, the JVM system property `clj-commons.ansi.enabled` (if present) determines
the value; "true" enables colors, any other value disables colors.

If the property is null, then the default is a best guess based on the environment:
if either the `nrepl.core` namespace is present, or the JVM has a console  (via `(System/console)`),
then color will be enabled.

The nrepl.core check has been verified to work with Cursive, with `lein repl`, and with `clojure` (or `clj`).
sourceraw docstring

composeclj

(compose & inputs)

Given a Hiccup-inspired data structure, composes and returns a string that includes ANSI formatting codes for font color and other characteristics.

The data structure may consist of literal values (strings, numbers, etc.) that are formatted with str and concatenated.

Nested sequences are composed recursively; this (for example) allows the output from map or for to be mixed into the composed string seamlessly.

Nested vectors represent spans, a sequence of values with a specific visual representation. The first element in a span vector declares the visual properties of the span: the font color and other font characteristics, and the width and padding (described later). Spans may be nested.

The declaration is usually a keyword, to define just the font. The font def contains one or more terms, separated by periods.

The terms:

CharacteristicValues
foreground colorred or bright-red (for each color)
background colorsame as foreground color, with a -bg suffix (e.g., red-bg)
boldnessbold, faint, or plain
italicsitalic or roman
inverseinverse or normal
underlineunderlined or not-underlined

e.g.

(compose [:yellow "Warning: the " [:bold.bright-white.bright-red-bg "reactor"]
  " is about to "
  [:italic.bold.red "meltdown!"]])
=> ...

The order of the terms does not matter. Behavior for conflicting terms (e.g., :blue.green.black) is not defined.

Font defs apply on top of the font def of the enclosing span, and the outer span's font def is restored at the end of the inner span, e.g. [:red " RED " [:bold "RED/BOLD"] " RED "].

Alternately, a font def may be a vector of individual keywords, e.g., [[:bold :red] ...] rather than [:bold.red ...]. This works better when the exact font characteristics are determined dynamically.

A font def may also be nil, to indicate no change in font.

compose presumes that on entry the current font is plain (default foreground and background, not bold, or inverse, or italic, or underlined) and appends a reset sequence to the end of the returned string to ensure that later output is also plain.

The core colors are black, red, green, yellow, blue, magenta, cyan, and white.

When *color-enabled* is false, then any font defs are validated, but otherwise ignored (no ANSI codes will be included in the composed string).

The span's font declaration may also be a map with the following keys:

KeyTypeDescription
:fontkeyword or vector of keywordsThe font declaration
:widthnumberThe desired width of the span
:pad:left, :right, :bothWhere to pad the span if :width specified, default is :left

The map form of the font declaration is typically only used when a span width is specified. The span will be padded with spaces to ensure that it is the specified width. compose tracks the number of characters inside the span, excluding any ANSI code sequences injected by compose.

Padding adds spaces; thus aligning the text on the left means padding on the right, and vice-versa.

Setting the padding to :both will add spaces to both the left and the right; the content will be centered. If the necessary amount of padding is odd, the extra space will appear on the left.

compose doesn't consider the characters when calculating widths; if the strings contain tabs, newlines, or ANSI code sequences not generated by compose, the calculation of the span width will be incorrect.

Example:

[{:font :red
  :width 20} message]

This will output the value of message in red text, padded with spaces on the left to be 20 characters.

compose does not truncate a span to a width, it only pads if the span in too short.

Given a Hiccup-inspired data structure, composes and returns a string that includes ANSI formatting codes
for font color and other characteristics.

The data structure may consist of literal values (strings, numbers, etc.) that are formatted
with `str` and concatenated.

Nested sequences are composed recursively; this (for example) allows the output from
`map` or `for` to be mixed into the composed string seamlessly.

Nested vectors represent _spans_, a sequence of values with a specific visual representation.
The first element in a span vector declares the visual properties of the span: the font color
and other font characteristics, and the width and padding (described later).
Spans may be nested.

The declaration is usually a keyword, to define just the font.
The font def contains one or more terms, separated by periods.

The terms:

Characteristic   | Values
---              |---
foreground color | `red` or `bright-red` (for each color)
background color |  same as foreground color, with a `-bg` suffix (e.g., `red-bg`)
boldness         | `bold`, `faint`, or `plain`
italics          | `italic` or `roman`
inverse          | `inverse` or `normal`
underline        | `underlined` or `not-underlined`

e.g.

```
(compose [:yellow "Warning: the " [:bold.bright-white.bright-red-bg "reactor"]
  " is about to "
  [:italic.bold.red "meltdown!"]])
=> ...
```

The order of the terms does not matter. Behavior for conflicting terms (e.g., `:blue.green.black`)
is not defined.

Font defs apply on top of the font def of the enclosing span, and the outer span's font def
is restored at the end of the inner span, e.g. `[:red " RED " [:bold "RED/BOLD"] " RED "]`.

Alternately, a font def may be a vector of individual keywords, e.g., `[[:bold :red] ...]` rather than
`[:bold.red ...]`.  This works better when the exact font characteristics are determined
dynamically.

A font def may also be nil, to indicate no change in font.

`compose` presumes that on entry the current font is plain (default foreground and background, not bold,
or inverse, or italic, or underlined) and appends a reset sequence to the end of the returned string to
ensure that later output is also plain.

The core colors are `black`, `red`, `green`, `yellow`, `blue`, `magenta`, `cyan`, and `white`.

When [[*color-enabled*]] is false, then any font defs are validated, but otherwise ignored (no ANSI codes
will be included in the composed string).

The span's font declaration may also be a map with the following keys:

Key    | Type                          | Description
---    |---                            |---
:font  | keyword or vector of keywords | The font declaration
:width | number                        | The desired width of the span
:pad   | :left, :right, :both          | Where to pad the span if :width specified, default is :left

The map form of the font declaration is typically only used when a span width is specified.
The span will be padded with spaces to ensure that it is the specified width.  `compose` tracks the number
of characters inside the span, excluding any ANSI code sequences injected by `compose`.

Padding adds spaces; thus aligning the text on the left means padding on the right, and vice-versa.

Setting the padding to :both will add spaces to both the left and the right; the content will be centered.
If the necessary amount of padding is odd, the extra space will appear on the left.

`compose` doesn't consider the characters when calculating widths;
if the strings contain tabs, newlines, or ANSI code sequences not generated by `compose`,
the calculation of the span width will be incorrect.

Example:

    [{:font :red
      :width 20} message]

This will output the value of `message` in red text, padded with spaces on the left to be 20 characters.

`compose` does not truncate a span to a width, it only pads if the span in too short.
sourceraw docstring

pcomposecljdeprecated

(pcompose & inputs)

Composes its inputs as with compose and then prints the results, with a newline.

Deprecated: use pout instead.

Composes its inputs as with [[compose]] and then prints the results, with a newline.

Deprecated: use [[pout]] instead.
sourceraw docstring

perrclj

(perr & inputs)

Composes its inputs as with compose and then prints the result with a newline to *err*.

Composes its inputs as with [[compose]] and then prints the result with a newline to `*err*`.
sourceraw docstring

poutclj

(pout & inputs)

Composes its inputs as with compose and then prints the results, with a newline.

Composes its inputs as with [[compose]] and then prints the results, with a newline.
sourceraw docstring

when-color-enabledcljmacro

(when-color-enabled & body)

Evaluates its body only when *color-enabled* is true.

Evaluates its body only when [[*color-enabled*]] is true.
sourceraw docstring

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

× close