Merge pull request #8 from guicho271828/true-color-support

True color support

.travis.yml

@@ -1,13 +1,40 @@
-before_script:
-        - curl -O -L http://prdownloads.sourceforge.net/sbcl/sbcl-1.2.6-x86-64-linux-binary.tar.bz2
-        - tar xjf sbcl-1.2.6-x86-64-linux-binary.tar.bz2
-        - pushd sbcl-1.2.6-x86-64-linux/ && sudo bash install.sh && popd
-        - curl -O -L http://beta.quicklisp.org/quicklisp.lisp
-        - sbcl --load quicklisp.lisp --eval '(quicklisp-quickstart:install)' --eval '(quit)'
-        - curl -OL http://ccl.clozure.com/ftp/pub/release/1.10/ccl-1.10-linuxx86.tar.gz
-        - tar xzf ccl-1.10-linuxx86.tar.gz
-        - export PATH=`pwd`/ccl:$PATH
-#        - lx86cl64 -b --load quicklisp.lisp --eval '(progn (quicklisp-quickstart:install) (quit))'
+language: common-lisp
+sudo: false
+
+addons:
+  apt:
+    packages:
+      - libc6-i386
+      - clisp
+
+env:
+  global:
+    - PATH=~/.roswell/bin:$PATH
+    - ROSWELL_INSTALL_DIR=$HOME/.roswell
+  matrix:
+    - LISP=sbcl-bin
+    - LISP=ccl-bin
+    - LISP=abcl
+    - LISP=clisp
+    - LISP=ecl
+    - LISP=cmucl
+    - LISP=alisp
+
+matrix:
+  allow_failures:
+    - env: LISP=clisp
+    - env: LISP=abcl
+    - env: LISP=ecl
+    - env: LISP=cmucl
+    - env: LISP=alisp
+
+install:
+  - curl -L https://raw.githubusercontent.com/snmsts/roswell/release/scripts/install-for-ci.sh | sh
+
+cache:
+  directories:
+    - $HOME/.roswell
+    - $HOME/.config/common-lisp
 
 script:
-        - ./ci-test-run.sh
+  - ./testscr.ros

README.md

@@ -3,138 +3,167 @@
 Because color in your terminal is nice.
 [![Build Status](https://travis-ci.org/pnathan/cl-ansi-text.svg?branch=master)](https://travis-ci.org/pnathan/cl-ansi-text)
 
+Installation: `(ql:quickload :cl-ansi-text)`
+
 ## Usage example -
-```lisp
-* (ql:quickload :cl-ansi-text)
-;To load "cl-ansi-text":
-;  Load 1 ASDF system:
-;    cl-ansi-text
-;; Loading "cl-ansi-text"
-; => (:CL-ANSI-TEXT)
-```
 
-The main macro is called `with-color`, which creates an enviroment where everything that is put on `stream` gets colored according to `color`. Color options are `:black`, `:red`, `:green`, `:yellow`, `:blue`, `:magenta`, `:cyan` and `:white`. You can also use a color structure from `CL-COLORS`, like `cl-colors:+red+`.
+The main macro is `with-color`, which creates an enviroment where everything that is put on `stream` gets colored according to `color`.
+
+Color options comes in several forms.
+
+### Keyword Symbol
+
+Basic 8 colors in the 3-bit color mode are supported, which are `:black`, `:red`, `:green`, `:yellow`, `:blue`, `:magenta`, `:cyan` and `:white`.
 
 ```lisp
-* (import 'cl-ansi-text:with-color)
-; => T
 * (with-color (:red)
     (princ "Gets printed red...")
     (princ "and this too!"))
 ; Gets printed red...and this too!
 ; => "and this too!"
 ```
+### `CL-COLORS:RGB` and `CL-COLORS:HSV` object
+
+These are color structures from `CL-COLORS2` (a maintained fork of `CL-COLORS`).
+`CL-COLORS2` has several constants e.g. `cl-colors:+red+` that holds the corresponding color values.
+`CL-COLORS2` also supports useful blending operations on colors.
+Note that `CL-COLORS2` library provides a package `CL-COLORS`, not `CL-COLORS2`.
+
+### Hex representation
+
+These are CSS-style color strings such as `"#FF0000"`.
+
+### Integer as a 24-bit color
+
+It treats an integer as a hex string.
+The bottom 8 bit is used for the blue, the 8th to 16th bits are used for green,
+the 16th to 24th bits are used for red.
+Remaining bits are ignored.
+
+### List of numbers as a 24-bit color
+
+It takes a list of three numbers (RGB) between 0 and 256.
+
+## Function interface for printing in specific colors
+
+We provide shorthand functions for generating a colored strings:
 
-There are also functions with the name of the colors, that return the string, colored:
 ```lisp
-* (import 'cl-ansi-text:yellow)
-; => T
 * (yellow "Yellow string")
 ; => "Yellow string"
 * (princ (yellow "String with yellow background" :style :background))
 ; "String with yellow background"
 ; => "String with yellow background"
-* (import 'cl-ansi-text:red)
-; => T
 * (princ
    (concatenate
     'string
     (yellow "Five") " test results went " (red "terribly wrong") "!"))
 ; Five test results went terribly wrong!
 ; => "Five test results went terribly wrong!"
 ```
-At any point, you can bind the `*enabled*` special variable to `nil`, and anything inside that binding will not be printed colorfully:
+
+You can bind the `*enabled*` special variable to `nil` to control the colorization:
+
 ```lisp
 * (let (cl-ansi-text:*enabled*)
     (princ (red "This string is printed normally")))
 ```
 
 # API
 
+## *Type* color-specifier
+
+``` lisp
+(or unsigned-byte
+    (cons (real 0 256)
+          (cons (real 0 256)
+                (cons (real 0 256)
+                      nil)))
+    cl-colors:rgb
+    cl-colors:hsv
+    term-colors
+    color-string)
+```
 
-## BLUE
-
-Returns a string with the `blue'string denotation preppended and the `reset' string denotation appended.
-
-*enabled* dynamically controls the function.
-
-## MAGENTA
-
-Returns a string with the `magenta'string denotation preppended and the `reset' string denotation appended.
-
-*enabled* dynamically controls the function.
-
-## CYAN
-
-Returns a string with the `cyan'string denotation preppended and the `reset' string denotation appended.
-
-*enabled* dynamically controls the function.
-
-## GREEN
-
-Returns a string with the `green'string denotation preppended and the `reset' string denotation appended.
-
-*enabled* dynamically controls the function.
+## *Type* term-colors
 
-## WITH-COLOR
+``` lisp
+(member :black :red :green :yellow :blue :magenta :cyan :white)
+```
 
-Writes out the string denoting a switch to `color`, executes body,
-then writes out the string denoting a `reset`.
+## *Type* color-string
 
-*enabled* dynamically controls expansion..
+A string of length 3, 4, 6, or 7, that optionally starts with a `#`, and
+the rest consists of 3 or 6 hexademical alphadigits (case-insensitive).
 
-## YELLOW
+## *Macro* with-color
 
-Returns a string with the `yellow'string denotation preppended and the `reset' string denotation appended.
+``` lisp
+with-color (color &key (stream t) (effect :unset) (style :foreground)) &body body
+```
 
-*enabled* dynamically controls the function.
+Writes out the ANSI escape code string 
+denoting `effect`, `style`, and a switch to `color`, then executes `body`,
+then writes out the string that resets the decoration.
 
-## BLACK
+## *Function* make-color-string
 
-Returns a string with the `black'string denotation preppended and the `reset' string denotation appended.
+``` lisp
+make-color-string color &key (effect :unset) (style :foreground) enabled
+```
 
-*enabled* dynamically controls the function.
+Takes an object of `color-specifier` and returns a string sufficient to change to the given color.
 
-## *ENABLED*
+Colorization is controlled by *enabled* unless manually specified otherwise by `:enabled` keyword.
 
-Turns on/off the colorization of functions
+## *Function* black, red, green, yellow, blue, magenta, cyan, white
 
-## MAKE-COLOR-STRING
+Shortcut functions that takes a single argument, `string`, and returns a string
+decorated by the corresponding color.
 
-Takes either a cl-color or a list denoting the ANSI colors and
-returns a string sufficient to change to the given color.
+## *Special variable* `*enabled*`
 
-Will be dynamically controlled by *enabled* unless manually specified
-otherwise
+Turns on/off the colorization.
 
-## RED
+## *Special variable* `*color-mode*`
 
-Returns a string with the `red'string denotation preppended and the `reset' string denotation appended.
+Controls the way `make-color-string` emits the color code.
 
-*enabled* dynamically controls the function.
+It should be one of the following keyword symbols: `:3bit`, `:8bit`, `:24bit`.
+The specified color is converted to the nearest color in the color space.
+The default value is `:8bit`.
 
-## WHITE
+Note that the actual appearance of the screen in the `:3bit` mode may be affected by
+the terminal setting -- For example, many terminals do not use `FF0000` for the red.
 
-Returns a string with the `white'string denotation preppended and the `reset' string denotation appended.
+## *Constant* `+reset-color-string+`
 
-*enabled* dynamically controls the function.
+A constant string that resets the color state of the terminal.
 
-## +RESET-COLOR-STRING+
 
-This string will reset ANSI colors
+# Running test
 
+Run `./testscr.ros` with Roswell. You can also manually run the test with
+`(ql:quickload :cl-ansi-text.test) (fiveam:run! :cl-ansi-text)`.
 
 # Note
 
 Note that your terminal MUST be ANSI-compliant to show these
-colors. My SLIME REPL (as of Feb 2013) does not display these
-colors. I have to use a typical Linux/OSX terminal to see them.
+colors. 
 
-This has been tested to work on a Linux system with SBCL, CLISP and
-CCL. CCL may not work quite perfectly, some level of conniptions were
-encountered in testing. The interested reader is advised to check the
-MAKE-LOAD-FORM defmethod in cl-ansi-text.lisp.
+SLIME REPL does not display these colors by default (2019.12.13).
+To make it understand the ANSI escape sequence,
+install `slime-repl-ansi-color` package available from [MELPA](https://melpa.org/)
+using `package-install` and add the following in `.emacs`:
+
+``` lisp
+(with-eval-after-load 'slime-repl
+  (require 'slime-repl-ansi-color))
+(add-hook 'slime-repl-mode-hook 'slime-repl-ansi-color-mode)
+```
 
-An earlier variant was tested on OSX 10.6 with SBCL.
+You can view the list of lisp implementation this library is tested
+on [Travis-CI](https://travis-ci.org/pnathan/cl-ansi-text).
+The testing environment is Linux, but we believe this should work also on OSX.
 
 License: LLGPL

cl-ansi-text.asd

@@ -1,8 +1,11 @@
 (asdf:defsystem #:cl-ansi-text
-  :depends-on ( #:cl-colors #:alexandria)
-  :components ((:file "cl-ansi-text"))
+  :depends-on ( #:cl-colors2 #:alexandria)
+  :serial t
+  :pathname "src/"
+  :components ((:file "cl-ansi-text")
+               (:file "define-colors"))
   :name "cl-ansi-text"
-  :version "1.0"
+  :version "1.1"
   :maintainer "Paul Nathan"
   :author "Paul Nathan"
   :licence "LLGPL"