bling.core — io.github.paintparty/bling 0.9.2

!?sgr clj/s

(!?sgr s)

Temporarily silences debugging of sgr code printing. Returns the value.

?sgr clj/s

(?sgr s)

For debugging of ANSI SGR tagged output.

Prints the value with escaped ANSI SGR codes so you can read them in terminal emulators (otherwise text would just get colored). Preserves coloring.

Returns the value.

bling clj/s

(bling & coll)

Giving any number of strings or hiccup-like vectors, returns a string tagged with ANSI SGR codes to style the text as desired.

bling-colors* clj/s

callout clj/s

(callout x & args)

Example:

(callout {:type                   :error
          ;; :colorway            :purple          ; <- any bling palette color, overrides :type
          ;; :label                  "My label"              ; overrides label assigned by :theme
          :side-label             "My side label"  ; must have a :label if you want a :side-label        
          :theme                  :sideline        ; :sideline :sideline-bold :minimal :gutter
          :label-theme            :minimal         ; :minimal :marquee
          ;; :padding-top            0                 
          ;; :padding-left           2                 
          ;; :padding-bottom         0                 
          ;; :padding-right          0                 
          ;; :margin-top             1                 
          ;; :margin-botom           0                 
          ;; :margin-left            0                 
          ;; :data?                  true             ; <- just returns string, no printing
          
          :border-block-length 80               ; <- Only applies to :minimal theme + no label
          
          ;; --- The options below exclusive to :theme of :boxed ---------------
          ;; :box-drawing-style      :thin-round      ; :thin :bold :double
          ;; :border-char            "*"
          ;; :vertical-border-char   "**"
          ;; :width                  40
          ;; :max-width              100
          ;; :min-width              40
          ;; :padding-block          1
          ;; :padding-inline         2
          }
        (bling [:bold (str "Line 1" "\n" "Line 2")])

Prints a message to the console with a block-based coloring motif. Returns nil.

If the :data? option is set to true, it does not print anything, and returns a data representation of the formatting and styling.

Callout prints a colored bounding border in the inline start position. The color of the border is determined by the value of the :type option, or the :colorway option. The characteristics of this border are controlled by the :theme option.

For callouts of the type :error, :warning, or :info, a label is printed in the block start postion. If a :type option is set, the label string will default to an uppercased version of that string, e.g. {:type :INFO} => "INFO". If a :label option is supplied, that value is used instead. When you want to omit label for callouts of the type :error, :warning, or :info, you must explicitly set the :label option to an empty string.

The amount of vertical padding (in number of lines) within the bounds of the message body can be controlled the padding-top and padding-bottom options. The amount of space (in number of lines) above and below the message block can be controlled the margin-top and margin-bottom options.

If two arguments are provided, the first should be a map of valid options.

All the options:

[:type
 {:optional true
  :desc     ["Will set the label text (unless provided via `:label`). Will also set the `:colorway`, and override any provided `:colorway` value."]}
 [:enum
  :error
  "error"
  :warning
  "warning"
  :info
  "info"]]

[:colorway
 {:optional true
  :desc     ["The color of the sideline border, or gutter, depending on the value of `:theme`."]}
 [:enum
  :error
  "error"
  :warning
  "warning"
  :info
  "info"
  :positive
  "positive"
  :subtle
  "subtle"
  :magenta
  "magenta"
  :green
  "green"
  :negative
  "negative"
  :neutral
  "neutral"]]

[:theme
 {:optional true
  :default  :sideline
  :desc     ["Theme of callout."]}
 [:enum
  :sideline
  "sideline"
  :sideline-bold
  "sideline-bold"
  :minimal
  "minimal"
  :gutter
  "gutter"
  :boxed
  "boxed"]]

[:label
 {:optional true
  :desc     ["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."]}
 :any]

[:side-label
 {:optional true
  :desc     ["Side label to the the callout label. 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."]}
 :any]

[:label-theme
 {:optional true
  :default  :minimal
  :desc     ["Theme of label."]}
 [:enum
  :marquee
  "marquee"
  :minimal
  "minimal"]]

[:padding-top
 {:optional true
  :default  0
  :desc     ["Amount of padding (in newlines) at top, inside callout."]}
 :int]

[:padding-bottom
 {:optional true
  :default  0
  :desc     ["Amount of padding (in newlines) at bottom, inside callout."]}
 :int]

[:padding-left
 {:optional true
  :default  2
  :desc     ["Amount of padding (in blank character spaces) at left, inside callout."]}
 :int]

[:margin-top
 {:optional true
  :default  1
  :desc     ["Amount of margin (in newlines) at top, outside callout."
             "Only applies to terminal emulator printing."]}
 :int]

[:margin-bottom
 {:optional true
  :default  0
  :desc     ["Amount of margin (in newlines) at bottom, outside callout."
             "Only applies to terminal emulator printing."]}
 :int]

[:margin-left
 {:optional true
  :default  0
  :desc     ["Amount of margin (in blank character spaces) at left, outside callout."]}
 :int]

[:border-block-length
 {:optional true
  :default  50
  :desc     ["The width of the top and bottom border, only applies to the `:minimal` callout theme."]}
 :int]

[:data?
 {:optional true
  :desc     ["Returns a data representation of result instead of printing it."]}
 :boolean]

point-of-interest clj/s

(point-of-interest {:keys [line file column form header body margin-block
                           text-decoration-color type]
                    :as opts})

Example:

(point-of-interest {:form                  '(+ 1 true) ; <- required
                    :line                  42
                    :column                11
                    :file                  "myfile.core"
                    :text-decoration-style :wavy  ; :underline :solid :dashed :dotted :double
                    :type                  :error ; :warning 
                    ;; :margin-block          0       ; <- default is one
                    ;; :text-decoration-index 2       ; <- If form is collection, this will focus underline
                    ;; :text-decoration-color :yellow ; <- and bling palette color
                    })

point-of-interest creates namespace info diagram which identifies a specific form. This provides the namespace, column, and line number, and a bolded, potentially truncated, representation of the specific form of interest. This form representation is accented with a squiggly underline.

The :line, :column, :form, and :file options must all be present in order for the namespece info diagram to be rendered. If the :form option is supplied, but any of the others are omitted, only the form will be rendered (with an underline and no line-info diagram).

By default, the diagram is created with a leading and trailing newlines. This can be set to zero, or increased, with the :margin-block option.

All the options:

[:form
 {:required true
  :desc     ["The form to draw attention to. Will be cast to string and"
             "truncated at 33 chars"]}
 :any]

[:file
 {:optional true
  :desc     ["File or namespace"]}
 :string]

[:line
 {:optional true
  :desc     ["Line number"]}
 :int]

[:column
 {:optional true
  :desc     ["Column number"]}
 :int]

[:margin-block
 {:optional true
  :default  1
  :desc     ["Controls the number of blank lines above and below the diagram."]}
 :int]

[:type
 {:optional true
  :desc     ["Automatically sets the `:text-decoration-color`."]}
 [:enum
  :error
  "error"
  :warning
  "warning"]]

[:text-decoration-color
 {:optional true
  :default  :neutral
  :desc     ["Controls the color of the underline."]}
 [:enum
  :error
  "error"
  :warning
  "warning"
  :neutral
  "neutral"
  :magenta
  "magenta"
  :green
  "green"
  :negative
  "negative"]]

[:text-decoration-style
 {:optional true
  :desc     ["Controls the color of the underline."]}
 [:enum
  :wavy
  "wavy"
  :solid
  "solid"
  :dashed
  "dashed"
  :dotted
  "dotted"
  :double
  "double"]]

[:text-decoration-index
 {:optional true
  :desc     ["If the value of `:form` is a collection, this is the index of"
             "the item to apply text-decoration (underline)."]}
 :pos-int]

print-bling clj/s

(print-bling & args)

In JVM Clojure, cljs(Node), and bb, print-bling is sugar for: (println (bling [:bold.blue "my blue text"]))

In cljs (browser dev consoles), print-bling is sugar for the the following: (print-to-browser-dev-console (bling [:bold.blue "my blue text"]))

Example: `(print-bling [:bold.blue "my blue text"])

print-to-browser-dev-console cljs

(print-to-browser-dev-console s)

system-colors-source clj/s