Crysterm

Crysterm is a console/terminal toolkit for Crystal. IT IS IN ACTIVE DEVELOPMENT.

The usage and API are DOM-like, and anyone can make awesome terminal applications with Crysterm quickly.

For a quick start, see directory examples/ and consult the User Manual below.

Crysterm is heavily inspired by the terminal library "blessed" for Node.js and, for convenience, shares much of its user-visible API.

Installation and Hello, World!

If you have an existing project and want to add Crysterm to it:

1. Add the dependency to shard.yml:

dependencies:
  crysterm:
    github: crystallabs/crysterm

1. Run shards

If you just want to try it out by running example programs:

1. Clone the Crysterm Git repository

2. Run 'crystal spec' to run all the specs

3. Run examples from the directory examples/ (for example, crystal examples/hello.cr)

User Manual

Event model

Event model is at the very core of the Crysterm library.

The basic class Event and system's built-in events come from the event_handler shard.

The necessary additional events used by built-in widgets are defined in src/events.cr.

The final event module (mixin) named EventHandler also comes from the event_handler shard. It provides all the macros and functions needed for a class to be event-enabled, that is, to accept event handlers and emit events. Every class that wants to emit its events needs to include EventHandler.

For more information about the event model, please see https://github.com/crystallabs/event_handler.

Class hierarchy

Class Event represents the parent class of all events.

Module EventHandler adds methods for adding and removing event handlers, and emitting events.

Basic crysterm class Node includes EventHandler.

Class Screen (of which there can be multiple in a running application) inherits from Node.

Class Element inherits from Node.

All other widgets, including layouts, inherit from Element or some of its subclasses such as Box or List.

Drawing

Crysterm does not use ncurses. It uses its own functionality to detect term characteristics, parse terminfo, and configure the program to output correct escape sequences for the current terminal. It is arguably as accurate as ncurses, and more optimized in some ways.

The renderer makes use of CSR (change-scroll-region) and BCE (back-color-erase). It draws the screen using the painter's algorithm, with smart cursor movements and screen damage buffer. Only the change (damage) is updated on the screen.

Text Attributes

Generally speaking, to define foreground and background colors and attributes for strings, one can embed appropriate escape sequences into the strings themselves or use Crystal's Colorize module.

Crysterm is interoperable with those two approaches, but also implements its own concept of "tags" in strings, such as "{lightblue-fg} text in light blue {/lightblue-fg}". Tags can be embedded in strings directly, applied from a Hash with generate_tags, and removed from a string with strip_tags or clean_tags. Any existing strings where "{}" should not be interpreted can be protected with escape_tags.

Roadmap

There are three parallel goals:

1. Add basic functions which do not have many dependencies and which can be implemented and tested standalone.

2. Implement event model and most basic widgets that will initialize an empty screen:

• Implement event model
• Implement Node
• Implement Screen, a subclass of Node (half-done)
• Implement Element, a subclass of Node
• Implement other widgets, subclasses of Element

3. Add lower-level elements like event loop, event stream parser, terminfo/termcap functions, etc.

Testing

Run crystal spec as usual.

Documentation

Run crystal docs as usual.

Thanks

• All the fine folks on FreeNode IRC channel #crystal-lang and on Crystal's Gitter channel https://gitter.im/crystal-lang/crystal

• Blacksmoke16 for a workable event implementation

• Asterite, Absolutejam, and Tenebrousedge for additional discussion

• Chjj for implementing library "blessed" for Node.js

Other projects

List of interesting or similar projects in no particular order:

Terminal-related:

• https://github.com/Papierkorb/fancyline - Readline-esque library with fancy features
• https://github.com/r00ster91/lime - Library for drawing graphics on the console screen
• https://github.com/andrewsuzuki/termbox-crystal - Bindings, wrapper, and utilities for termbox

Colors-related:

• https://crystal-lang.org/api/master/Colorize.html - Crystal's built-in module Colorize
• https://github.com/veelenga/rainbow-spec - Rainbow spec formatter for Crystal
• https://github.com/watzon/cor - Make working with colors in Crystal fun!
• https://github.com/icyleaf/terminal - Terminal output styling
• https://github.com/ndudnicz/selenite - Color representation convertion methods (rgb, hsv, hsl, ...) for Crystal
• https://github.com/jaydorsey/colorls-cr - Crystal toy app for colorizing LS output

Event-related:

• https://github.com/crystallabs/event_handler - Event model used by Crysterm
• https://github.com/Papierkorb/cute - Event-centric pub/sub model for objects inspired by the Qt framework
• https://github.com/hugoabonizio/event_emitter.cr - Idiomatic asynchronous event-driven architecture

Misc:

• https://github.com/Papierkorb/toka - Type-safe, object-oriented option parser
• https://github.com/eliobr/termspinner - Simple terminal spinner
• https://github.com/epoch/tallboy - Draw ascii character tables in the terminal
• https://github.com/teuffel/ascii_chart - Lightweight console ASCII line charts