Generalize UnicodeGraphics to generic filtering functions (#5)

* Fix Braille typos

* Fix `blockize` docstring

* Refactor to print to IOBuffer

* Update `braille_hex`

* Generalize to all boolean functions for filtering

* Type stability fixes for default cutoff filter

* Add higher level `bprint` interface

* Rename `brailize` to `brailleize`

* Update README

* Formatting fix to README

* Rename core functions to `to_braille`, `to_block`

* Use ReferenceTests.jl and test/Project.toml

Since saving runtests.jl runs some code formatters (i.e. in VSCode) and removes white space from strings, breaking the tests

* Remove `cutoff` defaults in `to_braille`, `to_block`

* Return newline instead of null char at the end of a string

* Refactor API to print to IO, add `bstring`

* Add more tests

* Format README example

* Fix and test deprecations

* Add CI workflow

* Document `bstring` in README

* Revert "Add CI workflow"

This reverts commit 422156c.

* Increase code coverage

* Add CI workflow

* Update README

* Drop support for Julia < 1.6

* Rename `bprint`/`bstring` to `uprint`/`ustring`

Using `u` since it is mnemonic with the package name

Author: adrhill

.github/workflows/CI.yml

@@ -0,0 +1,49 @@
+name: CI
+on:
+  push:
+    branches:
+      - master
+    tags: '*'
+  pull_request:
+    branches:
+      - master
+      
+jobs:
+  test:
+    name: Julia ${{ matrix.version }} - ${{ matrix.os }} - ${{ matrix.arch }} - ${{ github.event_name }}
+    runs-on: ${{ matrix.os }}
+    continue-on-error: ${{ matrix.version == 'nightly' }}
+    strategy:
+      fail-fast: false
+      matrix:
+        version:
+          - '1.6'
+          - '1'
+          - 'nightly'
+        os:
+          - ubuntu-latest
+        arch:
+          - x64
+    steps:
+      - uses: actions/checkout@v2
+      - uses: julia-actions/setup-julia@v1
+        with:
+          version: ${{ matrix.version }}
+          arch: ${{ matrix.arch }}
+      - uses: actions/cache@v1
+        env:
+          cache-name: cache-artifacts
+        with:
+          path: ~/.julia/artifacts
+          key: ${{ runner.os }}-test-${{ env.cache-name }}-${{ hashFiles('**/Project.toml') }}
+          restore-keys: |
+            ${{ runner.os }}-test-${{ env.cache-name }}-
+            ${{ runner.os }}-test-
+            ${{ runner.os }}-
+      - uses: julia-actions/julia-buildpkg@v1
+      - uses: julia-actions/julia-runtest@v1
+      - uses: julia-actions/julia-processcoverage@v1
+      - uses: codecov/codecov-action@v1
+        with:
+          file: lcov.info
+  

.github/workflows/CompatHelper.yml

@@ -9,7 +9,7 @@ jobs:
     runs-on: ${{ matrix.os }}
     strategy:
       matrix:
-        julia-version: [1.2.0]
+        julia-version: [1.6]
         julia-arch: [x86]
         os: [ubuntu-latest]
     steps:

.gitignore

@@ -1,3 +1,4 @@
 *.jl.cov
 *.jl.*.cov
 *.jl.mem
+Manifest.toml

Project.toml

@@ -4,11 +4,4 @@ authors = ["Rafael Schouten <[email protected]>"]
 version = "0.1.2"
 
 [compat]
-julia = "1"
-
-[extras]
-OffsetArrays = "6fe1bfb0-de20-5000-8ca7-80f57d26f881"
-Test = "8dfed614-e22c-5e08-85e1-65c5234f0b40"
-
-[targets]
-test = ["OffsetArrays", "Test"]
+julia = "1.6"

README.md

@@ -3,68 +3,90 @@
 [![Build Status](https://travis-ci.org/rafaqz/UnicodeGraphics.jl.svg?branch=master)](https://travis-ci.org/rafaqz/UnicodeGraphics.jl)
 [![codecov.io](http://codecov.io/github/rafaqz/UnicodeGraphics.jl/coverage.svg?branch=master)](http://codecov.io/github/rafaqz/UnicodeGraphics.jl?branch=master)
 
-Convert a matrix of Real into a braile or block Unicode string, real fast.
+Convert any matrix into a braille or block Unicode string, real fast and dependency free.
 
+## Installation 
+This package supports Julia ≥1.6. To install it, open the Julia REPL and run 
+```julia-repl
+julia> ]add UnicodeGraphics
 ```
-pac = [0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0;
-       0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0;
-       0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0;
-       0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0;
-       0 0 1 1 1 1 1 1 1 0 0 1 1 1 1 1 1 1 1 0;
-       0 1 1 1 1 1 1 1 1 0 0 1 1 1 1 1 1 1 1 0;
-       0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0;
-       1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0;
-       1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0;
-       1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0;
-       1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 1;
-       1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0;
-       1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0;
-       0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0;
-       0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0;
-       0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0;
-       0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0;
-       0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0;
-       0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0;
-       0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0]
 
-julia> print(blockize(pac))
-     ▄▄██████▄▄
-  ▄██████████████▄
- ▄███████  ████████
-▄██████████████▀▀
-███████████▀▀
+## Examples
+```julia
+julia> pac = [
+   0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0
+   0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0
+   0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0
+   0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0
+   0 0 1 1 1 1 1 1 1 0 0 1 1 1 1 1 1 1 1 0
+   0 1 1 1 1 1 1 1 1 0 0 1 1 1 1 1 1 1 1 0
+   0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0
+   1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0
+   1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0
+   1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 0
+   1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0 0 1
+   1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0 0 0
+   1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0
+   0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0
+   0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0
+   0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0
+   0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0
+   0 0 0 1 1 1 1 1 1 1 1 1 1 1 1 1 1 0 0 0
+   0 0 0 0 0 1 1 1 1 1 1 1 1 1 1 0 0 0 0 0
+   0 0 0 0 0 0 0 1 1 1 1 1 1 0 0 0 0 0 0 0
+];
+
+julia> uprint(pac)  # same as uprint(pac, :braille)
+⠀⣠⣴⣾⣿⣿⣷⣦⣄⠀
+⣰⣿⣿⣿⣧⣼⣿⡿⠟⠃
+⣿⣿⣿⣿⣿⣏⡁⠀⠀⠠
+⠹⣿⣿⣿⣿⣿⣿⣷⣦⡄
+⠀⠙⠻⢿⣿⣿⡿⠟⠋⠀
+
+julia> uprint(pac, :block)
+     ▄▄██████▄▄     
+  ▄██████████████▄  
+ ▄███████  ████████ 
+▄██████████████▀▀   
+███████████▀▀       
 ███████████▄▄      ▀
-▀██████████████▄▄
- ▀█████████████████
-  ▀██████████████▀
-     ▀▀██████▀▀
+▀██████████████▄▄   
+ ▀█████████████████ 
+  ▀██████████████▀  
+     ▀▀██████▀▀     
 ```
 
-Or braile:
-
+It is also possible to pass a filtering function, filling values for which the function returns `true`:
 ```julia
-ghost = [1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0;
-         0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0;
-         1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0;
-         0.0 0.0 0.0 0.0 0.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 0.0 0.0 0.0 0.0;
-         1.0 0.0 0.0 0.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 0.0 0.0 1.0;
-         0.0 0.0 0.0 0.0 1.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 0.0 0.0 0.0;
-         1.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 0.0 1.0 1.0 0.0 0.0 1.0;
-         0.0 0.0 0.0 0.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0;
-         1.0 0.0 0.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 0.0 1.0;
-         0.0 0.0 0.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 1.0 0.0 0.0;
-         1.0 0.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 1.0;
-         0.0 0.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 0.0;
-         1.0 0.0 0.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 1.0 0.0 1.0;
-         0.0 0.0 0.0 1.0 1.0 0.0 1.0 1.0 1.0 0.0 0.0 1.0 1.0 1.0 0.0 1.0 1.0 0.0 0.0;
-         1.0 0.0 0.0 1.0 0.0 0.0 0.0 1.0 1.0 0.0 0.0 1.0 1.0 0.0 0.0 0.0 1.0 0.0 1.0;
-         0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0 0.0;
-         1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0 0.0 1.0]
+julia> ghost = [
+   1 7 7 7 7 8 6 4 6 3 9 9 9 7
+   1 5 3 6 6 8 2 8 2 2 2 9 3 7
+   9 5 4 8 8 6 4 8 4 8 2 6 5 9
+   5 2 5 1 8 8 6 8 3 3 6 8 6 9
+   9 9 9 3 1 8 4 5 3 7 9 6 8 3
+   3 8 8 7 5 6 4 4 2 5 5 6 4 1
+   2 8 8 3 7 4 6 2 8 9 7 6 8 2
+   2 4 9 7 2 6 2 4 1 5 6 4 8 8
+   8 2 4 4 4 4 8 6 4 4 6 4 2 2
+   6 8 2 6 4 4 8 6 4 2 4 4 2 8
+   4 2 6 4 2 6 8 6 6 2 8 8 8 8
+   8 2 3 6 6 8 9 1 2 4 8 5 4 8
+   8 3 7 3 8 6 9 3 6 6 1 9 1 6
+];
+
+julia> uprint(iseven, ghost)
+⢀⠴⣾⣿⠷⣦⡀
+⣴⠆⣸⣷⠆⣸⣧
+⣿⢿⣿⠿⣿⡿⣿
+⠁⠀⠉⠀⠉⠀⠈
+```
+`uprint` can be used to write into any `IO` stream, defaulting to `stdout`.
 
+`ustring` can be used to return a string instead of printing to IO:
+```julia-repl
+julia> ustring(iseven, ghost)
+"⢀⠴⣾⣿⠷⣦⡀\n⣴⠆⣸⣷⠆⣸⣧\n⣿⢿⣿⠿⣿⡿⣿\n⠁⠀⠉⠀⠉⠀⠈\n"
 
-julia> print(brailize(view(ghost, 2:15, 4:17), 0.5))                                                                         
-⠀⣠⣴⣶⣦⣄⠀                                                                                                                
-⣨⡄⢹⣯⡄⢹⣇                                                                                                                
-⣿⣶⣿⣿⣶⣿⣿                                                                                                                
-⠋⠈⠛⠀⠛⠁⠙                                                                                                                
+julia> ustring(iseven, ghost, :block)
+"   ▄▄████▄▄   \n ▄▀▀████▀▀██▄ \n ▄▄  ██▄▄  ██ \n██▀ ▄███▀ ▄███\n██████████████\n██▀███▀▀███▀██\n▀   ▀▀  ▀▀   ▀\n"
 ```

src/UnicodeGraphics.jl

@@ -1,96 +1,13 @@
 """
-Block and braile rendering of julia arrays, for terminal graphics.
+Block and braille rendering of julia arrays, for terminal graphics.
 """
 module UnicodeGraphics
 
-export blockize, brailize, blockize!, brailize!
+const DEFAULT_METHOD = :braille
+include("api.jl")
+include("core.jl")
+include("deprecate.jl")
 
-"""
-    brailize(a, cutoff=0)
-
-Convert an array to a block unicode string, filling values above the cutoff point.
-"""
-blockize(a, cutoff=0) = blockize!(initblock(size(a)), a, cutoff) 
-
-# x and y are inverted: repl rows are columns.
-initblock((y, x)) = initblock(y, x) 
-initblock(y, x) = Array{Char,2}(undef, x + 1, (y - 1) ÷ 2 + 1)
-
-"""
-    blockize!(out, a, cutoff=0)
-
-Convert an array to a braile unicode string, filling the `out` array.
-Calculation of array dims is a little complicated:
-"""
-blockize!(out, a, cutoff=0) = join(block_array!(out, a, cutoff))
-
-function block_array!(out, a, cutoff)
-    yrange, xrange = axes(a)
-    for y in first(yrange):2:last(yrange)
-        for x in xrange
-            top = checkval(a, y, x, yrange, xrange, cutoff)
-            bottom = checkval(a, y + 1, x, yrange, xrange, cutoff)
-            if top
-                ch = bottom ? '█' : '▀'
-            else
-                ch = bottom ? '▄' : ' '
-            end
-            out[x-first(xrange) + 1, (y-first(yrange)) ÷ 2 + 1] = Char(ch)
-        end
-        # Return after every column
-        out[end, (y-first(yrange)) ÷ 2 + 1] = Char('\n')
-    end
-    # The last character is null
-    out[end, end] = 0x00
-    out
-end
-
-const braile_hex = ((0x01, 0x08), (0x02, 0x10), (0x04, 0x20), (0x40, 0x80))
-
-"""
-    brailize(a, cutoff=0)
-
-Convert an array to a braile unicode string, filling values above the cutoff point.
-"""
-brailize(a, cutoff=0) = brailize!(initbraile(size(a)), a, cutoff) 
-
-# x and y are inverted: repl rows are columns.
-initbraile((y, x)) = initbraile(y, x) 
-initbraile(y, x) = Array{Char,2}(undef, (x - 1) ÷ 2 + 2, (y - 1) ÷ 4 + 1)
-
-"""
-    brailize!(out, a, cutoff=0)
-
-Convert an array to a braile unicode string, filling the `out` array.
-"""
-brailize!(out, a, cutoff=0) = join(braile_array!(out, a, cutoff))
-
-function braile_array!(out, a, cutoff)
-    yrange, xrange = axes(a)
-    for y in first(yrange):4:last(yrange)
-        for x in first(xrange):2:last(xrange)
-            ch = 0x2800
-            for j = 0:3, i = 0:1
-                if checkval(a, y+j, x+i, yrange, xrange, cutoff)
-                    ch += braile_hex[j % 4 + 1][i % 2 + 1]
-                end
-            end
-            out[(x - first(xrange)) ÷ 2 + 1, (y-first(yrange)) ÷ 4 + 1] = ch
-        end
-        # Return after every column
-        out[end, (y-first(yrange)) ÷ 4 + 1] = Char('\n')
-    end
-    # The last character is null
-    out[end, end] = 0x00
-    out
-end
-
-checkval(a, y, x, yrange, xrange, cutoff) = begin
-    if x <= last(xrange) && y <= last(yrange)
-        a[y, x] > cutoff
-    else
-        false
-    end
-end
+export uprint, ustring
 
 end # module