1.1 Basic Data Types

There are a few core types that you should be aware of in CL-Remi-Slang. Most of these also have some functions associated with them.

Type: t/tty-init :none :low-level :full ¶

This describes how to initialize TTY handling facilities. It is used by the init-slang function.

Type: t/color-attribute :bold :blink :underline :reverse :italic :alt-chars ¶

This type defines the various text attributes that can be applied to text on the screen.

Function: t/color-attribute->int attr ¶

Converts a t/color-attribute to its integer value. Raises an slang-error if it’s not a valid t/color-attribute.

Function: t/color-attribute->int? attr ¶

Converts a t/color-attribute to its integer value. Returns nil if it’s not a valid t/color-attribute.

Function: int->t/color-attribute value ¶

Converts an integer to a t/color-attribute. Raises an slang-error if the value cannot be converted to a t/color-attribute.

Function: int->t/color-attribute? value ¶

Converts an integer to a t/color-attribute. Returns nil if the value cannot be converted to a t/color-attribute.

Function: t/color-attributes->val &rest attributes ¶

Given a list of t/color-attributes, return an integer with their values logical-ORed together.

Function: val->t/color-attributes value ¶

Given an integer value, return a list of t/color-attributes that are contained within its bits.

Type: t/drawable :hline :vline :ul-corner :ur-corner :ll-corner :lr-corner :checkerboard :right-tee :left-tee :up-tee :down-tee :plus ¶

This type defines the various kinds of “drawables” that you can write to the screen. These are extra glyphs, such as box characters, that S-Lang understands and that are commonly used in TUI applications.

Function: t/drawable->int attr ¶

Converts a t/drawable to its integer value. Raises an slang-error if it’s not a valid t/drawable.

Function: t/drawable->int? attr ¶

Converts a t/drawable to its integer value. Returns nil if it’s not a valid t/drawable.

Function: int->t/drawable value ¶

Converts an integer to a t/drawable. Raises an slang-error if the value cannot be converted to a t/drawable.

Function: int->t/drawable? value ¶

Converts an integer to a t/drawable. Returns nil if the value cannot be converted to a t/drawable.

Type: t/newline-behavior :ignored :moves :scrolls :printable ¶

This defines what happens when a newline is encountered.

Function: t/newline-behavior->int attr ¶

Converts a t/newline-behavior to its integer value. Raises an slang-error if it’s not a valid t/newline-behavior.

Function: t/newline-behavior->int? attr ¶

Converts a t/newline-behavior to its integer value. Returns nil if it’s not a valid t/newline-behavior.

Function: int->t/newline-behavior value ¶

Converts an integer to a t/newline-behavior. Raises an slang-error if the value cannot be converted to a t/newline-behavior.

Function: int->t/newline-behavior? value ¶

Converts an integer to a t/newline-behavior. Returns nil if the value cannot be converted to a t/newline-behavior.

---

1.2 Initializing and Deinitializing CL-Remi-Slang

With only a few exceptions, the CL-Remi-Slang library must first be initialized before using it.

Function: init-slang &key use-screen use-utf8 tty abort-char flow-control? echo-output? ¶

This is the most direct way to initialize the CL-Remi-Slang library. When the use-screen parameter is truthy, then screen managemetn is enabled, and the screen-* functions can be used. Its default is T.

When the use-utf8 parameter is truthy, then UTF-8 support is enabled. Its default is T.

The tty parameter describes how to initialize TTY handling facilities. This must be of type t/tty-init.

The abort-char parameter indicates a keyboard character to use for SIGINT. This is only useful when the TTY is enabled. It must be NIL or a character who’s code is between 0 and 255.

The flow-control? parameter indicates whether or not to enable flow control (XON/XOFF). Disabling flow control is necessary to pass certain characters to the program, such as C-s and C-q.

When the echo-output? parameter is truthy, then typed keys will be printed on the screen.

When finished with the library, you should always call deinit-slang to properly deinitialize S-Lang and return the terminal to its original condition.

Function: deinit-slang ¶

This deinitializes S-Lang and returns the terminal to its original condition.

Macro: with-slang &key use-screen use-utf8 tty abort-char flow-control? echo-output? &body forms ¶

This macro initializes the library with init-slang, then executes forms. This will ensure that deinit-slang is called before returning by wrapping everything in an unwind-protect.

---

1.3 Other Basic Functions

Function: slang-version ¶

This returns a string containing the version of the underling S-Lang library. The library does not need to be initialized to call this function.

Function: slang-version-number ¶

This returns an integer containing the version number of the underling S-Lang library. The library does not need to be initialized to call this function.

The format of this number is meant to be human readable. For example, a version of 2.3.2 would produce the number 20302.

Function: beep ¶

Rings the terminal bell.

---

3.1 Color Constants

Constant: +black+ ¶

The pre-defined screen color “black”.

Constant: +gray+ ¶

The pre-defined screen color “gray”.

Constant: +red+ ¶

The pre-defined screen color “red”.

Constant: +bright-red+ ¶

The pre-defined screen color “bright-red”.

Constant: +green+ ¶

The pre-defined screen color “green”.

Constant: +bright-green+ ¶

The pre-defined screen color “bright-green”.

Constant: +brown+ ¶

The pre-defined screen color “brown”.

Constant: +yellow+ ¶

The pre-defined screen color “yellow”.

Constant: +blue+ ¶

The pre-defined screen color “blue”.

Constant: +bright-blue+ ¶

The pre-defined screen color “bright-blue”.

Constant: +magenta+ ¶

The pre-defined screen color “magenta”.

Constant: +bright-magenta+ ¶

The pre-defined screen color “bright-magenta”.

Constant: +cyan+ ¶

The pre-defined screen color “cyan”.

Constant: +bright-cyan+ ¶

The pre-defined screen color “bright-cyan”.

Constant: +light-gray+ ¶

The pre-defined screen color “light-gray”.

Constant: +white+ ¶

The pre-defined screen color “white”.

---

3.2 Basic Screen Functions

Function: screen-set-newline-behavior behavior ¶

Sets the behavior of newline characters. The behavior parameter must be a t/newline-behavior. Returns the new value.

Function: screen-suspend ¶

Suspends screen management.

Function: screen-resume ¶

Resumes screen management.

Function: screen-update-size ¶

Updates the internal screen size data used by S-Lang. You will want to call this before getting the screen dimensions in order to ensure the values are correct.

Function: screen-width ¶

Returns the last-known width of the screen. Use screen-update-size first if you think it may have changed and want to ensure the returned value is up to date.

Function: screen-height ¶

Returns the last-known height of the screen. Use screen-update-size first if you think it may have changed and want to ensure the returned value is up to date.

Function: screen-size ¶

Returns the last-known size of the screen as two values, where the width is the first value and the height is the second.

Function: screen-reinit ¶

Reinitializes screen management and checks the current size of the screen so that internal values are consistent. This should be called after a SIGWINCH.

---

3.3 Screen Reading Functions

Function: screen-get-char ¶

Gets the character at the current cursor position. Returns a character.

---

3.4 Screen Color Functions

Function: screen-has-ansi-colors-p ¶

Returns t if the screen supports ANSI colors, or nil otherwise.

Function: define-color id fg bg &rest attributes ¶

Defines a new color that can later be referenced by id, where id must be an integer between 0 and slang-core:sl-smg-max-colors, inclusive. This only has an effect if screen-has-ansi-colors-p returns t, otherwise this function does nothing.

The fg and bg parameters must be strings. One of three formats can be used for these parameters:

• A color name (e.g. “blue”)
• colorX, where X is an integer ANSI 256-color value.
• A string in the format “XXYYZZ”, where “XX”, “YY”, and “ZZ” are RGB values in hexadecimal between 00 and FF, inclusive.

The attributes parameter should be a set of t/color-attributes you want to apply to text that uses the color.

Function: screen-use-color id ¶

Changes the current color that is used when writing stuff to the screen. id must be a color ID that was previously defined with define-color.

Function: screen-default-color ¶

Goes back to using the default color. This is effectively the same as using the following:

(screen-use-color 0)

Function: screen-reverse-color ¶

Reverses the colors.

Function: screen-change-region-color id column row num-cols num-rows ¶

Changes the color in the rectangular region starting at the given column and row. The id parameter must be a color ID that was previously defined with define-color.

Macro: with-changed-color (id &optional old-id) &body forms ¶

Temporarily changes the color to id, then executes forms. Before returning, the color will be changed to the default if old-id is nil, or to the color ID in old-id.

The id parameter must be a color ID that was previously defined with define-color. Likewise, the old-id parameter must also be a color ID, or nil.

---

3.5 Cursor Movement and Info

Function: screen-hide-cursor ¶

Hides the cursor.

Function: screen-show-cursor ¶

Un-hides the cursor.

Function: screen-goto column row ¶

Moves the cursor to the given screen coordinates.

Function: screen-cursor-pos ¶

Returns two values, the first of which is the cursor’s current column and the second is the cursor’s current row.

Macro: with-restored-cursor (&key new-column new-row) &body forms ¶

Stores the current position of the cursor. Then, if both new-column and new-row are provided, the cursor is then moved to that position, the cursor is not moved. Finally, forms is executed.

Before returning, this will return the cursor to its previous position prior to calling this macro.

When provided, the new-column and new-row parameters must be integers. Both of these parameters must be provided, or neither of them.

Example 1:

;; Assume the cursor is at 4,5 at this point.
(with-restored-cursor ()
  ;; Writes "Hello, world!" starting at 4,5
  (screen-write-string "Hello, world!"))

;; The cursor is now back at 4,5

Example 2:

;; Assume the cursor is at 4,5 at this point.
(with-restored-cursor (:new-column 6 :new-row 9)
  ;; Writes "Hello, world!" starting at 6,9
  (screen-write-string "Hello, world!"))

;; The cursor is now back at 4,5

---

3.6 Screen Writing

Macro: screen-format str &rest fmt-args ¶

Formats str using fmt-args and writes the result to the screen at the current cursor position. The str parameter must be a string.

Internally, this macro will skip calling the Common Lisp function format if fmt-args is nil.

Function: screen-write-string string &key color column row ¶

Writes string to the screen. The string parameter must be a string.

If color is provided, then it must be a color ID (as defined with define-color), and the screen will first change its output color to that color before writing the string. It will remain that color after the call.

The row and column parameters must both be provided, or not at all. When provided, they must be integers, and the cursor will first seek to that screen position before writing the string.

Function: screen-write-char char &key color column row ¶

Writes char to the screen. The char parameter must be a character.

If color is provided, then it must be a color ID (as defined with define-color), and the screen will first change its output color to that color before writing the character. It will remain that color after the call.

The row and column parameters must both be provided, or not at all. When provided, they must be integers, and the cursor will first seek to that screen position before writing the character.

Function: screen-write thing &key color column row ¶

Writes thing to the screen.

If color is provided, then it must be a color ID (as defined with define-color), and the screen will first change its output color to that color before writing the character. It will remain that color after the call.

The row and column parameters must both be provided, or not at all. When provided, they must be integers, and the cursor will first seek to that screen position before writing the character.

If you are writing a string or character, then this function is slightly slower than calling screen-write-string or screen-write-char directly since it must look at the type of thing, possibly calling write-to-string on it.

Function: screen-write-wrapped str column row num-cols num-rows &optional fill ¶

Write a string to the display with wrapping, where it will be confined to the given rectangular region. If fill is truthy, then the last line that gets written will be padded with spaces.

---

3.7 Screen Clearing and Refreshing

Function: screen-clear &optional clear-type ¶

Clears content from the screen. The clear-type parameter defines what gets cleared and can be one of the following:

• :full - Clears the entire screen. This is the default.
• :end-of-line - Clears from the cursor to the end of the line.
• :end-of-screen - Clears from the cursor to the end of the screen.

Function: screen-refresh ¶

Updates the physical screen.

Function: screen-refresh-at row num-rows ¶

Marks num-rows lines starting from row for redisplay the next time screen-refresh is called.

---

3.8 Screen Drawing

Function: screen-draw-vline &key color length ¶

Draws a vertical line on the screen from the current cursor position. The cursor remains at the end of the line after drawing.

If color is provided, then the screen will first change its output color to that color. It will remain that color after the call. The color parameter must be an integer (a color ID) if it’s provided. The color is not changed back after drawing.

If length is provided, it must be an integer. When provided, the line will start at the cursor and be length rows long. When length is not provided or is nil, then the line starts at the cursor and continues to the bottom edge of the screen.

Function: screen-draw-vline* &key color column row length ¶

Draws a vertical line on the screen from the current cursor position. The cursor remains at the end of the line after drawing.

If color is provided, then the screen will first change its output color to that color. It will remain that color after the call. The color parameter must be an integer (a color ID) if it’s provided. The color is not changed back after drawing.

The row and column parameters must either both be provided, or not at all. If given, the cursor will first seek to that position before drawing the vertical line.

If length is provided, it must be an integer. When provided, the line will start at the cursor and be length rows long. When length is not provided or is nil, then the line starts at the cursor and continues to the bottom edge of the screen.

Function: screen-draw-hline &key color length ¶

Draws a horizontal line on the screen from the current cursor position. The cursor remains at the end of the line after drawing.

If color is provided, then the screen will first change its output color to that color. It will remain that color after the call. The color parameter must be an integer (a color ID) if it’s provided. The color is not changed back after drawing.

If length is provided, it must be an integer. When provided, the line will start at the cursor and be length columns long. When length is not provided or is nil, then the line starts at the cursor and continues to the right edge of the screen.

Function: screen-draw-hline* &key color column row length ¶

Draws a horizontal line on the screen from the current cursor position. The cursor remains at the end of the line after drawing.

If color is provided, then the screen will first change its output color to that color. It will remain that color after the call. The color parameter must be an integer (a color ID) if it’s provided. The color is not changed back after drawing.

The row and column parameters must either both be provided, or not at all. If given, the cursor will first seek to that position before drawing the horizontal line.

If length is provided, it must be an integer. When provided, the line will start at the cursor and be length columns long. When length is not provided or is nil, then the line starts at the cursor and continues to the right edge of the screen.

Function: screen-draw-box column row num-cols num-rows &optional color ¶

Draws a box starting at position given by column and row. The box will be num-cols wide and num-rows tall. The starting position is the upper-left corner.

If color is not nil, then the color will be switched before drawing. The color is not changed back after drawing.

Function: screen-draw column row obj &optional color ¶

Draws obj at the given coordinates, where obj must be a t/drawable.

If color is not nil, then the color will be switched before drawing. The color is not changed back after drawing.

Function: screen-fill start-column start-row num-cols num-rows ch ¶

Fills a rectangular region of the screen with ch.

The ch parameter must either be a character who’s char-code is between 0 and 255 inclusive, or an (unsigned-byte 8).

---