Edit

Styled Text

In this tutorial, we examine how to produce $styx styled text strings and output them to the terminal from an agent.

%shoe CLI Session Manager

%shoe is responsible to manage attached agent sessions. It adds a few arms to the standard Gall agent, namely:

  • +command-parser is the input parser, similar to the work we were carrying out just above. This parses every input and only permits valid keystrokes (think of Dojo real-time parsing).

  • +tab-list provides autocompletion options. We can ignore for now.

  • +on-command is called whenever a valid command is run. This produces the actual effects.

  • +can-connect supports |dojo/link connexion to the app.

  • +on-connect provides particular session support when a user connects. We can ignore for now.

  • +on-disconnect provides particular session support when a user disconnects. We can ignore for now.

To get started with text parsers and CLI agents, we need to focus on +command-parser and +on-command. But first, the agent's structure and state:

The agent will adopt a two-stage process, wherein a value is put on the stack then the stack is checked for any valid operations.

+command-parser

The input parser can simply accept whole words or single inputs, or parse complex expressions (as Dojo does with Hoon).

This results in a noun of $command-type based on the specific application. The example /app/shoe.hoon agent defines:

+$  command
  $?  %demo
      %row
      %table
  ==

and later uses this as:

where the unfamiliar parser components are:

  • +stag adds a label, here & pam TRUE/%.y to indicate that the command should be run immediately when it matches. (We won't want this below so we will +stag a | FALSE/%.n.)

  • +perk parses a fork in the type.

+on-command

This arm accepts a session ID and a command resulting from +command-parser. It produces a regular (quip card _this) so you can modify agent state and produce effects here.

%sole Effects

%sole is responsible for producing effects. If you want to yield effects to the command line from your CLI agent (which you often do), this is a great place to work.

%sole-effects are head-tagged by time and produce a variety of terminal effects, from text to bells, colors, and other screen effects.

$styx Styled Text String

A +klr effect uses a $styx, or styled text string. The relevant data structures are in /sys/lull.hoon:

  • $deco is a text decoration, here %bl blinking, %br bright (bold), and %un underlined.

  • $tint is a color, either explicitly the terminal red/green/blue/cyan etc. or a 24-bit true color value.

  • $stye composes these into a style which will be applied to a string.

  • $styl similarly composes styles together.

  • $styx pairs styles with cords.

This means that composing styled text correctly can require explicitly nesting statements in rather a complicated way.

For instance, to produce a bold string with hex color #123456, we could produce the sole-effect:

Agent Logic

Here is an agent that will accept a single character and produce a line with varying random colors of that character.

/app/track7.hoon

PreviousShip MonitoringNextWhat is Urbit ID?

Last updated