The cl-spark Reference Manual

This is the cl-spark Reference Manual, version 0.1.13, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:28:25 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

The main system appears first, followed by any subsystem dependency.


2.1 cl-spark

CL-Spark generates sparkline string for a list of the numbers. CL-spark is a Common Lisp implementation of Zach Holman’s ‘spark’ and Gil Gonçalves’ ‘vspark’ with little extention.

* spark: https://github.com/holman/spark
* vspark: https://github.com/LuRsT/vspark
* cl-spark: https://github.com/tkych/cl-spark

Author

Takaya OCHIAI <>

License

MIT License

Version

0.1.13

Source

cl-spark.asd.

Child Component

spark.lisp (file).


3 Files

Files are sorted by type and then listed depth-first from the systems components trees.


3.1 Lisp


3.1.1 cl-spark/cl-spark.asd

Source

cl-spark.asd.

Parent Component

cl-spark (system).

ASDF Systems

cl-spark.


3.1.2 cl-spark/spark.lisp

Source

cl-spark.asd.

Parent Component

cl-spark (system).

Packages

cl-spark.

Public Interface
Internals

4 Packages

Packages are listed by definition order.


4.1 cl-spark

Source

spark.lisp.

Nickname

spark

Use List

common-lisp.

Public Interface
Internals

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.


5.1 Public Interface


5.1.1 Special variables

Special Variable: *ticks*

A simple-vector of characters for representation of sparklines. Default is #(#▁ #▂ #▃ #▄ #▅ #▆ #▇ #█).

Examples:

(defvar ternary ’(-1 0 1 -1 1 0 -1 1 -1))

(spark ternary) => "▁▄█▁█▄▁█▁"

(let ((*ticks* #(#_ #- #¯)))
(spark ternary)) => "_-¯_¯-_¯_"

(let ((*ticks* #(#▄ #⎯ #▀)))
(spark ternary)) => "▄⎯▀▄▀⎯▄▀▄"

Package

cl-spark.

Source

spark.lisp.

Special Variable: *vticks*

A simple-vector of characters for representation of vartical sparklines. Default is #(#▏ #▎ #▍ #▌ #▋ #▊ #▉ #█).

Examples:

;; Japan GDP growth rate, annal
;; see. http://data.worldbank.org/indicator/NY.GDP.MKTP.KD.ZG (defparameter growth-rate
’((2007 . 2.192186) (2008 . -1.041636) (2009 . -5.5269766) (2010 . 4.652112) (2011 . -0.57031655) (2012 . 1.945)))

(vspark growth-rate :key #’cdr :labels (mapcar #’car growth-rate)) =>
"
-5.5269766 -0.4374323 4.652112 ˫———————+———————˧
2007 ██████████████████████████████████▏
2008 ███████████████████▊
2009 ▏
2010 ████████████████████████████████████████████
2011 █████████████████████▉
2012 █████████████████████████████████▏
"

(let ((*vticks* #(#- #0 #+)))
(vspark growth-rate :key (lambda (y-r) (float-sign (cdr y-r))) :labels (mapcar #’car growth-rate)
:size 1))
=>
"
2007 +
2008 -
2009 -
2010 +
2011 -
2012 +
"

Package

cl-spark.

Source

spark.lisp.


5.1.2 Ordinary functions

Function: spark (numbers &key min max key)

Generates a sparkline string for a list of real numbers.

Usage: SPARK <numbers> &key <min> <max> <key>

* <numbers> ::= <list> of <real-number>
* <min> ::= { <null> | <real-number> }, default is NIL
* <max> ::= { <null> | <real-number> }, default is NIL
* <key> ::= <function>

* <numbers> ~ data.
* <min> ~ lower bound of output.
NIL means the minimum value of the data.
* <max> ~ upper bound of output.
NIL means the maximum value of the data.
* <key> ~ function for preparing data.

Examples:

(spark ’(1 0 1 0)) => "█▁█▁"
(spark ’(1 0 1 0 0.5)) => "█▁█▁▄"
(spark ’(1 0 1 0 -1)) => "█▄█▄▁"

(spark ’(0 30 55 80 33 150)) => "▁▂▃▅▂█" (spark ’(0 30 55 80 33 150) :min -100) => "▃▄▅▆▄█" (spark ’(0 30 55 80 33 150) :max 50) => "▁▅██▅█" (spark ’(0 30 55 80 33 150) :min 30 :max 80) => "▁▁▄█▁█"

(spark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4)))) => "▄▆█▆▄▂▁▂▄"
(spark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (cos (* x pi 1/4)))) => "█▆▄▂▁▂▄▆█"

For more examples, see cl-spark/spark-test.lisp

Package

cl-spark.

Source

spark.lisp.

Function: vspark (numbers &key min max key size labels title scale? newline?)

Generates a vartical sparkline string for a list of real numbers.

Usage: VSPARK <numbers> &key <min> <max> <key> <size>
<labels> <title> <scale?> <newline?>

* <numbers> ::= <list> of <real-number>
* <min> ::= { <null> | <real-number> }, default is NIL
* <max> ::= { <null> | <real-number> }, default is NIL
* <key> ::= <function>
* <size> ::= <integer 1 *>, default is 50
* <labels> ::= <list>
* <title> ::= <object>, default is NIL
* <scale?> ::= <generalized-boolean>, default is T
* <newline?> ::= <generalized-boolean>, default is T

* <numbers> ~ data.
* <min> ~ lower bound of output.
NIL means the minimum value of the data.
* <max> ~ upper bound of output.
NIL means the maximum value of the data.
* <key> ~ function for preparing data.
* <size> ~ maximum number of output columns (contains label). * <labels> ~ labels for data.
* <title> ~ If title is too big for size, it is not printed. * <scale?> ~ If T, output graph with scale for easy to see.
If string length of min and max is too big for size, the scale is not printed.
* <newline?> ~ If T, output graph with newlines for easy to see.

Examples:

;; Life expectancy by WHO region, 2011, bothsexes
;; see. http://apps.who.int/gho/data/view.main.690
(defvar life-expectancies ’(("Africa" 56)
("Americans" 76)
("South-East Asia" 67)
("Europe" 76)
("Eastern Mediterranean" 68) ("Western Pacific" 76)
("Global" 70)))

(vspark life-expectancies :key #’second :scale? nil :newline? nil) =>
"▏
██████████████████████████████████████████████████ ███████████████████████████▌ ██████████████████████████████████████████████████ ██████████████████████████████▏ ██████████████████████████████████████████████████ ███████████████████████████████████▏"

(vspark life-expectancies :min 50 :max 80
:key #’second
:labels (mapcar #’first life-expectancies) :title "Life Expectancy")
=>
"
Life Expectancy
50 65 80 ˫————+————-˧
Africa █████▋
Americans ████████████████████████▎
South-East Asia ███████████████▉
Europe ████████████████████████▎
Eastern Mediterranean ████████████████▊
Western Pacific ████████████████████████▎
Global ██████████████████▋
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 20)
"
-1.0 0.0 1.0
˫——–+———˧
██████████▏
█████████████████▏
████████████████████
█████████████████▏
██████████▏
██▉

██▉
█████████▉
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 10)
=>
"
-1.0 1.0
˫——–˧
█████▏
████████▏
██████████
████████▏
█████▏
█▏

█▏
████▏
"

(vspark ’(0 1 2 3 4 5 6 7 8) :key (lambda (x) (sin (* x pi 1/4))) :size 1)
=>
"









"

For more examples, see cl-spark/spark-test.lisp

Package

cl-spark.

Source

spark.lisp.


5.2 Internals


5.2.1 Macros

Macro: aif (test true-clause &optional false-clause)
Package

cl-spark.

Source

spark.lisp.

Macro: awhen (test &body body)
Package

cl-spark.

Source

spark.lisp.


5.2.2 Ordinary functions

Function: at-least-two-chars-p (x)
Package

cl-spark.

Source

spark.lisp.

Function: ensure-non-double-float (x)
Package

cl-spark.

Source

spark.lisp.

Function: generate-bar (number unit min max num-content-ticks)
Package

cl-spark.

Source

spark.lisp.

Function: generate-scale (min max size max-lengeth-label)
Package

cl-spark.

Source

spark.lisp.

Function: generate-title (title size max-lengeth-label)
Package

cl-spark.

Source

spark.lisp.

Function: string-concat (&rest strings)
Package

cl-spark.

Source

spark.lisp.

Function: to-string (n)
Package

cl-spark.

Source

spark.lisp.


5.2.3 Types

Type: <ticks> ()
Package

cl-spark.

Source

spark.lisp.


Appendix A Indexes


A.1 Concepts