# 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.

```forth
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.

```forth
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.

```forth
( 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.

```forth
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.