terminfofont.lua

SYNOPSIS
DESCRIPTION

FUNCTIONS
CONSTANTS

DOWNLOAD
CHANGES

AUTHOR
SEE ALSO

NAME

terminfofont.lua - big fonts for use in a console or an xterm

SYNOPSIS

 local TIF = require 'terminfofont'
 TIF.clear()
 TIF.civis()
 local y = 0   -- start at the top
 local dx, dy
 TIF.setfontsize(4)
 dx,dy = TIF.show(1, y, 'AbcdEfghIjklMnoP', 1)
 TIF.setfontsize(7)
 y = y+dy - 1
 TIF.rectfill(TIF.cols*0.2, y+1, TIF.cols*0.6, 6, 'cyan')
 dx,dy = TIF.show(0, y, 'HijkLmnoP', 4)
 y = y+dy
 TIF.setfontsize(2)
 TIF.bold()
 dx,dy = TIF.centreshow(y, 'The Title', 'blue')
 y = y+dy - 1
 TIF.setfontsize(4)
 dx,dy = TIF.centreshow(y, 'The Title', 'violet')
 y = y+dy
 TIF.setfontsize(7)
 dx,dy = TIF.centreshow(y, 'The Title', 'red')
 TIF.moveto(0, TIF.lines-1)
 TIF.sgr0()
 TIF.cnorm()

 -- for example, I run this when shutting down to
 -- remind me to put out the garbage on Wednesday evenings:
 local date_t = os.date('*t')
 if date_t['wday'] == 4 and  date_t['hour'] > 17 then   -- Wed after 6pm
    local TIF = require 'terminfofont'
    TIF.clear() ; TIF.setfontsize(7)
    local dx,dy = TIF.show(0, 4, 'GARBAGE', 'red')
    TIF.moveto(0, 12) ; TIF.sgr0()
 end

This module implements in Lua two big fonts for use when terminfo is supported, such as in a console, or an xterm. It was inspired by the Bitfont5x7 font in the PostScript module fonts.ps, except that these are variable-width fonts because they're very big and space is at a premium.
The functions were inspired by PostScript procedures.

These are some screenshots on a 79x23 xterm . . .
The default big font is four lines high.
It uses some utf-8 characters, and therefore depends on your xterm using a utf-8 font:

The other font is seven lines high ( see setfontsize() ) :

FUNCTIONS

show(), stringwidth(), setfontsize(), moveto(), rectfill(), centreshow(),
clear(), civis(), cnorm(), fg_color(), bg_color(), bold(), sgr0(),

width, height = TIF.show (x,y, string, colour)

This displays the string, in the current font-size, starting at column x and line y, in the ANSI colour colour.
It returns the width and height (in columns and lines) of the string.
Since version 0.5 the position x and y specifies the top-left corner of the letters. The reason for this change is to make the height return-value useful.

The available colours are: black=0, red=1, green=2, yellow=3, blue=4, violet=5, cyan=6, and white=7, see man terminfo in the Colour Handling section, where it discusses the setaf and setbf capabilites. show also supports the colours being given as strings, for example 'red'

width, height = TIF.stringwidth (string)

This returns the width and height (in columns and lines) that the string would have if it were displayed. It's like the show function, except that nothing is displayed.

TIF.setfontsize (n)

The font size n must be either 1 or 2 or 4 or 7. The default is 4
4 depends on your tty using a utf-8 font, and so is not completely portable: for example, 10x20 and 12x24 are not utf-8 fonts.
2 is even less portable; it uses two old escape-sequences <esc>#3 and <esc>#4 which display the upper and lower halves of a double-height font. These are not present on the linux console or in screen. But they are present in xterm and its variants uxterm and lxterm.

TIF.moveto (x, y)

This moves the cursor to a given position, specified as column and line.
x and y are 0, 0 in the top left corner, and increasing y moves downwards.
So the bottom-left corner is TIF.moveto(0, TIF.lines-1)

TIF.rectfill (x,y, width,height, colour)

This creates and fills a rectangle with corner at x, y and the given width and height, in the ANSI colour colour. width and height should be positive,
As in show, the position x and y specifies the top-left corner of the rectangle.
Be aware that most terminal-fonts are about twice as high as they are wide (eg 10x20 or 12x24), so that to get something like a square you have to specify something like TIF.rectfill(10,10, 50,25, 'blue')

width = TIF.centreshow (y, string, colour)

This is a wrapper for show, which takes care of the x parameter so as to centralise the string in the middle of the screen.

TIF.clear ()

This clears the screen, just like os.execute('clear')

TIF.civis ()

This makes the cursor invisible

TIF.cnorm ()

This makes the cursor normal again

TIF.fg_color ('red')

This sets the xterm 's foreground colour, which may be given as a number, or as a string. The available colours are: black=0, red=1, green=2, yellow=3, blue=4, violet=5, cyan=6, and white=7

TIF.bg_color (7)

This sets the xterm 's background colour, which may be given as a number, or as a string. The available colours are: black=0, red=1, green=2, yellow=3, blue=4, violet=5, cyan=6, and white=7

TIF.bold ()

This turns on bold mode. See man terminfo

TIF.sgr0 ()

This turns off all attributes, restoring the xterm to its normal state. See man terminfo
It's useful for cleaning up before exit, and is also called automatically at the end of each show()

CONSTANTS

To save you from having to require 'terminfo', some integer constants: TIF.lines and TIF.cols

DOWNLOAD

This module exists as a LuaRock in luarocks.org/modules/peterbillam so you can install it with the command:
sudo luarocks install terminfofont
or:
sudo luarocks install http://www.pjb.com.au/comp/lua/terminfofont-0.8-0.rockspec

You will also need the terminfo module:
sudo luarocks install terminfo

The test script used during development is pjb.com.au/comp/lua/test_terminfofont.lua

CHANGES

 20191201 0.8 code refactored and neatened
 20191119 0.7 add fontsizes 1 and 2, and bold()
 20191118 0.6 introduce centreshow(), and refine the kerning
 20191116 0.5 x,y specify the top left corner, and introduce sgr0()
 20191116 0.4 introduce setfontsize() and the 4-line utf8-based font
 20191109 0.3 introduce clear() and $
 20191108 0.2 rename go_to as moveto, introduce rectfill
 20191106 0.1 first released version

AUTHOR

Peter J Billam, pjb.com.au/comp/contact.html