https://github.com/paintparty/bling
Rich text console printing for Clojure, ClojureScript, and Babashka.
https://github.com/paintparty/bling
accessibility babashka clojure clojurescript color console design rich-text styling terminal typography
Last synced: 30 days ago
JSON representation
Rich text console printing for Clojure, ClojureScript, and Babashka.
- Host: GitHub
- URL: https://github.com/paintparty/bling
- Owner: paintparty
- License: mit
- Created: 2024-08-20T17:10:22.000Z (9 months ago)
- Default Branch: main
- Last Pushed: 2025-03-11T04:43:01.000Z (2 months ago)
- Last Synced: 2025-04-04T20:02:48.901Z (about 1 month ago)
- Topics: accessibility, babashka, clojure, clojurescript, color, console, design, rich-text, styling, terminal, typography
- Language: Clojure
- Homepage:
- Size: 7.64 MB
- Stars: 122
- Watchers: 2
- Forks: 1
- Open Issues: 10
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- License: LICENSE
Awesome Lists containing this project
README
# bling
**Rich text in the console.**
**[Features]** • **[Setup]** • **[Basic Usage]** • **[Callout Blocks]** • **[Error Templates]**
[Features]: #features
[Setup]: #setup
[Basic Usage]: #basic-usage
[Callout Blocks]: #callout-blocks
[Error Templates]: #templates-for-errors-and-warnings
[Interop]: #printing-conventions
[Contributing]: #contributing
The same example as above, in a terminal emulator with a dark background.
## Features
- Works great for Clojure, ClojureScript, and Babashka.
- Supports both terminal emulators and browser consoles.
- Simple, accessibility-focused, 11-color pallette.
- All colors provide reasonable contrast on both light and dark backgrounds.
- Simple and intuitive hiccup-like markup syntax.
- Sensible templates for warning and error callouts.
## Setup
Add as a dependency to your project:
```Clojure
[io.github.paintparty/bling "0.5.0"]
```
Require:
```Clojure
(require '[bling.core :refer [bling callout point-of-interest]])
;; In ClojureScript, you may also want :refer bling.core/print-bling.
```
Or, import into your namespace:
```Clojure
(ns myns.core
(:require
[bling.core :refer [bling callout point-of-interest]]))
;; In ClojureScript, you may also want :refer bling.core/print-bling.
```
You can view an exhaustive sampling of Bling output by pasting this snippet into your terminal:
```clojure
clj -Sdeps '{:deps {io.github.paintparty/bling {:mvn/version "0.5.2"}}}' -e "(require '[bling.sample]) (println (bling.sample/sample))"
```
To view the above sample with Babashka, paste this snippet into your terminal:
```clojure
bb -Sdeps '{:deps {io.github.paintparty/bling {:mvn/version "0.5.2"}}}' -e "(require '[bling.sample]) (println (bling.sample/sample))"
```
## Basic Usage
> [!NOTE]
> If you are reading this on github in a light-mode theme, the dark-mode samples in the sections below will appear to have lower contrast than they actually do if you were viewing them in dark-mode.
**`bling.core/bling`** takes any number of arguments and returns a string
of text decorated with tags for colorization, italics, and boldness:
```Clojure
(println (bling [:bold "bold"]
", "
[:italic "italic"]
", or "
[:blue "colored"]))
```
In ClojureScript (browser context), **`bling`** returns a js object that needs to be printed like this:
`(.apply js/console.log js/console (goog.object/get o "consoleArray"))`.
To avoid typing all this out, you can use **`bling.core/print-bling`** to print the array returned from **`bling`**:
```Clojure
(print-bling (bling [:bold "bold"]
", "
[:italic "italic"]
", or "
[:blue "colored"]))
```
By default **`bling.core/print-bling`** prints with `js/console.log`.
If you would like to print with either `js.console/warn`, or `js/console.error`, you can pass either as a second argument.
```Clojure
(print-bling (bling [:bold "bold"]
", "
[:italic "italic"]
", or "
[:blue "colored"])
js/console.warn)
```
### Combo styles
You can add multiple decorations with hiccup-style tags (a keyword with dot separators). The order of the things separated by dots doesn't matter.
```Clojure
(println (bling [:bold.italic "bold & italic"]
", "
[:italic.blue "italic & colored"]
", "
[:bold.italic.white.blue-bg
"bold & italic & colored & colored-bg"]
", "
[:bold.italic.blue.underline
"bold & italic & colored & underline"]
", "
[:bold.italic.blue.strikethrough
"bold & italic & colored & strikethrough"]))
```
You can also pass a map (instead of a hiccup-style keyword tag) to style the text:
```Clojure
(bling [{:color :green
:background-color :black
:font-style :italic
:font-weight :bold}
"bold italic green text on black background"])
```
Using a map is preferrable if you are doing something like this:
```Clojure
(println (string/join (for [c ["red"
"orange"
"yellow"
"olive"
"green"
"blue"
"purple"
"magenta"]]
(bling [{:background-color c
:color :white
:font-weight :bold}
(str " " c " ")]))))
```
Note that all the arguments to **`bling.core/bling`** must satisfy this predicate:
```Clojure
(every? (fn [x]
(or (and (vector? x)
(= 2 (count x))
(-> x
(nth 0)
(maybe #(or (keyword? %)
(map? %)))))
(not (coll? x))))
args)
```
In other words, every one of the arguments to **`bling.core/bling`** must be either:
- A two-element vector, with the first element being a keyword or map.
- A value which is not a collection.
If, for example, you wanted to print `[1 2 3]` in red, you will need to stringify the vector:
```Clojure
(bling [:red (str [1 2 3])])
```
### The Bling pallette
Eleven carefully selected colors, from the [xterm range 16-255](https://en.m.wikipedia.org/wiki/Xterm#/media/File%3AXterm_256color_chart.svg), are available for use. All of these colors should display consistantly across most consoles on the end-user side. Don't expect all of the colors to pass the [strictest APCA contrast criterion](https://www.myndex.com/APCA/), but you can be sure of reasonable visibility on both light and dark backgrounds:
```Clojure
(println (bling [:bold.red "Red"]
", "
[:bold.orange "Orange"]
", "
[:bold.yellow "Yellow"]
", "
[:bold.green "Olive"]
", "
[:bold.green "Green"]
", "
[:bold.blue "Blue"]
", "
[:bold.blue "Purple"]
", "
[:bold.magenta "Magenta"]
", "
[:bold.gray "Gray"]
", "
[:bold.black "Black"]
", "
[:bold.white "White"] ))
```
### Color aliases
You can use the following semantic aliases for some colors:
```Clojure
(println (bling [:bold.negative "Negative"]
", "
[:bold.error "Error"]
", "
[:bold.warning "Warning"]
", "
[:bold.positive "Positive"]
", "
[:bold.info "Info"]
", "
[:bold.subtle "Subtle"]
", "
[:bold.neutral "Neutral"]))
```
### Using system colors
Bling also supports named color aliases for system colors (Xterm colors 0-16).
Most likely, you do **not** want to use these. They will not display consistently across user spaces, as the actual color is dictated by the theme the user has selected in their particular terminal emulator.
If, however, you are using Bling to provide errors, warnings, and messages for that only you will ever see (on your own computer), and your terminal emulator theme is totally dialed-in to your liking, then system colors might be an option worth exploring.
```Clojure
(println (bling [:system-black "black (SYSTEM)"]))
(println (bling [:system-maroon "maroon (SYSTEM)"]))
(println (bling [:system-green "green (SYSTEM)"]))
(println (bling [:system-olive "olive (SYSTEM)"]))
(println (bling [:system-navy "navy (SYSTEM)"]))
(println (bling [:system-purple "purple (SYSTEM)"]))
(println (bling [:system-teal "teal (SYSTEM)"]))
(println (bling [:system-silver "silver (SYSTEM)"]))
(println (bling [:system-grey "grey (SYSTEM)"]))
(println (bling [:system-red "red (SYSTEM)"]))
(println (bling [:system-lime "lime (SYSTEM)"]))
(println (bling [:system-yellow "yellow (SYSTEM)"]))
(println (bling [:system-blue "blue (SYSTEM)"]))
(println (bling [:system-fuchsia "fuchsia (SYSTEM)"]))
(println (bling [:system-aqua "aqua (SYSTEM)"]))
(println (bling [:system-white "white (SYSTEM)"]))
```
### Using arbitrary colors
Bling also supports arbitrary colors in the xTerm 0-256 range. If you are using
arbitrary colors to construct messages to stdout that other people might have to
read, you may want to test the appearance with both light and dark terminal
themes. They must be provided as integers, so you will need to use an options
map instead of a hiccup-style keyword:
```Clojure
(println (bling [{:color 180} "xTerm color 180, aka Tan"]))
```
## Callout blocks
**`bling.core/callout`** will print a message "block" to the console with a colored bounding border in the inline-start position.
**`callout`** takes one or two arguments. If two arguments are supplied, the first should be a map with 0 or more of following entries:
| Key | Pred | Description |
| :--------------- | ----------------- | ------------------------------------------------------------ |
| `:type` | #{`keyword?` `string?`} | Should be one of: `:error`, `:warning` , or `:info`.
Will set the label text (unless provided via `:label`). Will also set the `:colorway`, and override any provided `:colorway` value. |
| `:colorway` | #{`keyword?` `string?`} | The color of the sideline border, or gutter, depending on the value of `:theme`.
Should be one of: `:error`, `:warning` , `:info` , `:positive`, or `:subtle`.
Can also be any one of the pallete colors such as `:magenta`, `:green`, `:negative`, `:neutral`, etc. |
| `:theme` | #{`keyword?` `string?`} | Theme of callout. Can be one of `:sideline`, `:sideline-bold`, or `:gutter`. Defaults to `:sideline`. |
| `:label` | `any?` | Labels the callout. In a terminal emulator context, the value will be cast to a string. In a browser context, the label can be an instance of `bling.core/Enriched`, or any other value (which will be cast to a string).
In the case of a callout `:type` of `:warning`, `:error`, or `:info`, the value of the label will default to `WARNING`, `ERROR`, or `INFO`, respectively. |
| `:label-theme` | #{`keyword?` `string?`} | Theme of label. Can be one of `:marquee` or `:minimal`. Defaults to `:minimal`. |
| `:padding-top` | `int?` | Amount of padding (in newlines) at top, inside callout.
Defaults to `0`. |
| `:padding-bottom` | `int?` | Amount of padding (in newlines) at bottom, inside callout.
Defaults to `0`. In browser console, defaults to `1` in the case of callouts of type `:warning` or `:error`.|
| `:padding-left` | `int?` | Amount of padding (in blank character spaces) at left, inside callout.
In console emulator, defaults to `2`. In browser console, defaults to `0`.|
| `:margin-top` | `int?` | Amount of margin (in newlines) at top, outside callout.
Defaults to `1`. Only applies to terminal emulator printing. |
| `:margin-bottom` | `int?` | Amount of margin (in newlines) at bottom, outside callout.
Defaults to `0`. Only applies to terminal emulator printing. |
| `:margin-left` | `int?` | Amount of margin (in blank character spaces) at left, outside callout.
Defaults to `0`. Only applies to terminal emulator printing. |
| `:data?` | `boolean?` | Returns a data representation of result instead of printing it. |
Examples of `callout` with different `:type` / `:colorway` options:
```Clojure
(callout {:type :info}
"Example callout, with :type of :info")
(callout {:type :info
:label "My custom label"}
"Example callout, with :type of :info and custom :label")
(callout {:type :warning}
"Example callout, with :type of :warning")
(callout {:type :error}
"Example callout, with :type of :error")
(callout {:type :positive
:label "SUCCESS!"}
"Example callout, with :type of :positive, and custom :label")
(callout {:type :subtle}
"Example callout, with :type of :subtle (or :gray)")
(callout {:type :magenta}
"Example callout, with :type of :magenta")
(callout "Example callout, default")
```
The above calls would render the following in your terminal emulator:
With `{:theme :sideline-bold}`:
Callout accepts a `:label-theme` option. Supplying a value of `:marquee`, will render
the label inside a box:
With `{:theme :sideline-bold :label-theme :marquee}`:
## Templates for errors and warnings
**`bling.core/callout`**, paired with **`bling.core/point-of-interest`**
is perfect for creating your own custom error or warning messages.
Here is an example of creating a custom callout for an error message.
You must provide the relevant `:file`, `:line`, `:column`, and `:form` values.
```Clojure
(defn example-custom-callout
[{:keys [point-of-interest-opts callout-opts]}]
(let [poi-opts (merge {:header "Your header message goes here."
:body (str "The body of your message goes here."
"\n"
"Another line of copy."
"\n"
"Another line."
)}
point-of-interest-opts)
message (point-of-interest poi-opts)
callout-opts (merge callout-opts
{:padding-top 1})]
(callout callout-opts message)))
(example-custom-callout
{:point-of-interest-opts {:type :error
:file "example.ns.core"
:line 11
:column 1
:form '(+ foo baz)
:text-decoration-index 2}
:callout-opts {:type :error}})
```
The above callout would render like this your terminal emulator:
You can also render such warning and error callouts using a `:label-theme` value of `:marquee`.
The diagram inside the callout that shows the namespace, line, column, and form
with underlined is created by **`bling.core/point-of-interest`**, which takes a
single map with the following options:
| Key | Pred | Description |
| :-------- | ----------------- | ------------------------------------------------------------ |
| `:file` | `string?` | File or namespace |
| `:line` | `integer?` | Line number |
| `:column` | `integer?` | Column number |
| `:form` | `any?` | The form to draw attention to. Will be cast to string and truncated at 33 chars |
| `:header` | `any?` | Typically, a string. If multi-line, string should be composed with newlines as desired. In a browser context, can be an instance of `bling.core/Enriched` (produced by using `bling.core/enriched`)|
| `:body` | `any?` | Typically, a string. If multi-line, string should be composed with newlines as desired. In a browser context, can be an instance of `bling.core/Enriched` (produced by using `bling.core/enriched`)|
| `:margin-block` | `int?` | Controls the number of blank lines above and below the diagram.
Defaults to `1`.|
| `:type` | #{`:error` `:warning`} | Automatically sets the `:text-decoration-color`. |
| `:text-decoration-color` | #{`keyword?` `string?`} | Controls the color of the underline. Should be one of: `:error` `:warning`, or `:neutral`.
Can also be any one of the pallete colors such as `:magenta`, `:green`, `:negative`, `:neutral`, etc. Defaults to `:neutral` |
| `:text-decoration-style` | #{`:wavy` `:solid` `:dashed` `:dotted` `:double`} | Controls the color of the underline. |
| `:text-decoration-index` | `pos-int?` | If the value of `:form` is a collection, this is the index of the item to apply text-decoration (underline). |
## Go heavy
If you want to place more emphasis on your callouts you can pass
**`bling.core/callout`** a `:theme` option with a value of `:gutter`. With the
`:gutter` theme, the thickness of the colored border is controlled by the value of
`:margin-left`. Here is an example using the `example-custom-callout` function we
defined above:
```Clojure
(example-custom-callout
{:file "example.ns.core"
:line 11
:column 1
:form '(+ 1 true)
:type :error
:theme :gutter})
```
Example value of `2` for `:margin-left`, to increase the weight:
```Clojure
(example-custom-callout
{:file "example.ns.core"
:line 11
:column 1
:form '(+ 1 true)
:type :error
:margin-left 2
:theme :gutter})
```
More callout examples of the `:gutter` theme:
More example values of `2` for `:margin-left`, to increase the weight:
## Testing
There is a set of visual test suites in `bling.core-test`.
For visual testing of output in node / deno context first do:
`shadow-cljs compile node-script`
Then do
`node out/bling-in-node-demo-script.js`
## Status / Roadmap
Alpha, subject to change. Issues welcome, see [contributing](#contributing).
## Contributing
Issues for bugs, improvements, or features are very welcome. Please file an
issue for discussion before starting or issuing a PR.