ansi-terminal - An ANSI Terminal Library for Forth

This is a simple library for basic text formatting and the like in ANSI compliant terminals. It has support for:

• Setting text properties
  • Foreground/Background colors
    • Black
    • Red
    • Green
    • Yellow
    • Blue
    • Magenta
    • Cyan
    • White
    • Default
  • Typeface Variants
    • Bold
    • Dim
    • Italic
    • Underline
    • Blink
    • Inverse
    • Hidden
    • Strikethrough
  • Resetting text properties
• Clearing the screen/line
  • Full clear
  • After cursor clear
  • Before cursor clear
• Setting cursor visibility
• Setting cursor position

The library also defines the words at-xy and page using ANSI escape sequences.

Assumptions

There are three primary assumptions made:

1. Support for single quote syntax to get character-codes (e.g. 'a' leaves the ASCII for the letter a on the stack.)
2. Support for $ syntax to leave hex values on the stack without changing the base value.
3. There is no need to set the cursor position to greater than 99 in either dimension.

All of these assumptions could be corrected easily enough, but the code looks nicer, and is more minimal with these assumptions in place.

Definitions

Properties

Text

• fg-black
• fg-red
• fg-green
• fg-yellow
• fg-blue
• fg-magenta
• fg-cyan
• fg-white
• fg-default
• bg-black
• bg-red
• bg-green
• bg-yellow
• bg-blue
• bg-magenta
• bg-cyan
• bg-white
• bg-default
• property-bold
• property-dim
• property-italic
• property-underline
• property-blink
• property-inverse
• property-hidden
• property-strikethrough
• property-reset

Clear

• clear-full
• clear-before-cursor
• clear-after-cursor

Cursor

• cursor-visible
• cursor-invisible

Setters

• property-set
• screen-clear
• line-clear
• cursor-type-set
• cursor-position-set
• page
• at-xy

Helper Words

• escape
• start-sequence
• int-to-ascii

Examples

Setting Text Properties

To set the properties for the text being printed you need only put the property on the stack, and then let it be consumed by the property-set word.

fg-green      property-set
bg-black      property-set
property-bold property-set

To reset the properties of any text to be printed to the terminal's defaults, just use the property-reset property.

Setting the Cursor Visibility

To set the cursor visibility, just put the cursor property you are looking for on the stack, and have it consumed by the cursor-type-set word.

cursor-visible   cursor-type-set
cursor-invisible cursor-type-set

Clearing the Display

If you just wish to clear the whole display and reset the cursor position use page. If you are looking for a more specialized clear however, you need to put the clear type on the stack, and then let it be consumed by either the line-clear or screen-clear word.

( Clears screen and re-homes cursor )
page

( Clears the line starting at the cursor position )
clear-after-cursor  line-clear

( Clears the screen ending at the cursor position )
clear-before-cursor screen-clear

Setting the Cursor Position

To set the cursor position feed the x and y coordinates (as integers) into the at-xy word.

8 8 at-xy

Please note: My implementation of at-xy only supports up to the coordinates (99, 99). This is a hard limitation created by simplifications made in several underlying helper words.