⚙️ ZUI
CGI+DHTML-like User Interface Library for Zsh / ZCurses
z-shell/ZUI
This is a RAD (Rapid Application Development) textual user interface library for Zsh. It in many aspects resembles a typical CGI+(D)HTML setup. There are:
- Generators ran on the "server" side (basic Zshell-code that is just generating text!),
- Event loop that turns the generated text into a document with active elements (buttons, anchors, toggle buttons, text fields, list boxes),
- Mechanism to regenerate document parts from the original generators.
So, a Zshell code generates text. It is then turned into a document with hyperlinks. DHTML-like calls are possible that will regenerate document parts on the fly. Page can be also reloaded with input data, just like an HTML page. A voiced video tutorial or file on google drive shows how to create an application – Nmap network scanner frontend.
Learning Zsh
ZUI will allow you to learn Zsh at the advanced level. The library uses Zshell e.g. Ruby. To write a functional program in Ruby, you need to know the language. To write a command or alias in Zsh, you can spend years not learning anything new. With ZUI you will learn how to use coproc
, patterns with (#b)
flag, Zstyles, arrays, hashes, and various substitutions. That said, examples are there to make the process easy, and problems have an easy and advanced way of issue solving.
API
The API consists of Standard Library, Utility Library and Callbacks. You normally want a few calls from Standard Library – to create buttons and regenerate document parts, and one or two callbacks. The fastest way to learn ZUI is to look at Hello World example and other example codes like the timeout example.
Screenshots
Text-fields demo, showing what color "default" can do:
List-boxes demo:
History demo – fully functional history tool with the incremental search:
Text Editor demo, written in 30 minutes:
Asciinema
Videos on the service Asciinema
, where you can resize the video like a normal web page, and select/copy text.
List boxes, text fields:
- Player
- Shortcuts
Key | Description |
---|---|
f | Toggle fullscreen mode |
space | Play / Pause |
← → | Rewind by 5sec. / Fast-forward by 5sec. |
Shift + ← / Shift + → | Rewind by 10% / fast-forward by 10% |
0, 1, 2, 3, 4, 5, 6, 7, 8, 9 | Jump to 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% |
Text editor written in 30 minutes:
- Player
- Shortcuts
Key | Description |
---|---|
f | Toggle fullscreen mode |
space | Play / Pause |
← → | Rewind by 5sec. / Fast-forward by 5sec. |
Shift + ← / Shift + → | Rewind by 10% / fast-forward by 10% |
0, 1, 2, 3, 4, 5, 6, 7, 8, 9 | Jump to 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% |
Configure/Make wrapper:
- Player
- Shortcuts
Key | Description |
---|---|
f | Toggle fullscreen mode |
space | Play / Pause |
← → | Rewind by 5sec. / Fast-forward by 5sec. |
Shift + ← / Shift + → | Rewind by 10% / fast-forward by 10% |
0, 1, 2, 3, 4, 5, 6, 7, 8, 9 | Jump to 0%, 10%, 20%, 30%, 40%, 50%, 60%, 70%, 80%, 90% |
Standard Library
Standard Library contains functions to:
- Initialize and clean up an application,
- Load and set the application's configuration,
- Create hyperlinks (buttons, anchors, text fields, list boxes),
- Handle hyperlinks (e.g. check if the given text is a hyperlink),
- Control document regeneration on-the-fly (the DHTML-like way),
- Handle modules (e.g. read module's position in the document).
Calls of Standard Library
Below are descriptions of Standard Library functions. Arguments in triangular brackets are mandatory, in square brackets – optional.
-zui_std_init
-zui_std_init [app:"application ID"] [app_name:"Application name"]
Initializes application. To be called before emulate. Optional argument app:...
will set ZUI[app]
– hash field needed by any application. Argument app_name:
does the same for ZUI[app_name]
(it is a human-readable application name, displayed in header).
-zui_std_init2
-zui_std_init2
Initialization to be called after emulate. emulate
is the command that makes a function an independent program and each ZUI application should use it.
-zui_std_stalog
-zui_std_stalog <Text 1> [Text 2] ...
Appends a message to the status window logs. Each text argument has a color assigned – see the log_colors
zstyle, it controls the colors.
-zui_std_special_text
-zui_std_special_text <text> [output array]
reply+=( "{output string}" )
Quote special characters in the text. This allows to use of strings like That's
in the document – special character '
will not disturb content. The default output array is reply
.
-zui_std_button_ext
-zui_std_button_ext <ID> <data1> <data2> <data3> <data4> <button text> [handler] [output array]
Creates string with the button. Every button has an ID assigned – it is the first argument. Then go four user-data arguments – if the handler will be invoked, the user-data will be passed to it along with the ID. <button text>
is the label of the button. [handler]
is the function name or inline code to be called at the press of the button. [output array]
name can be provided to have the result appended to that array (the default array is reply
). If the handler has a substring "internal" in it (in function name or inline code), then it will be invoked without a list restart. Otherwise, a list restart will be performed (this is like invoking JavaScript without web page reload, or doing the reload and calling code on the server side).
-zui_std_rc_button_ext
-zui_std_rc_button_ext <ID> <data1> <data2> <data3> <data4> <button text> [handler] [output array]
The function works identically to -zui_std_button
, but it wraps button text in square brackets – "rc" is for "rectangular". Also, both functions have no-_ext
versions that do not have <data1>
...<data4>
arguments.
-zui_std_anchor
-zui_std_anchor <ID> <index> <data1> <data2> <data3> <button text> [handler] [output array]
Creates an anchor – a hyperlink that moves the cursor to the specified line. Appends it to [output array]
(a parameter specified by name) – reply
by default. <index>
is the line number to jump to. It is relative to the current module. It in general cannot point to the absolute line number in the document. To point to the line outside the module, use A+B
syntax, e.g. 1-2
, to jump 2
lines before the first line of the module. Instead of the handler, you may use <data2>
and <data3>
to pass a module regeneration instruction. For example, pass ",mod2_ice1,"
"arg"
to regenerate some module numbered 2, instance 1, with passed user-data "arg". This regeneration is with list restart (i.e. it is like a web page reload with arg
passed to script on the server side). If the handler has substring "internal" in it (in function name or inline code), then the anchor will be internal – will not cause the document to reload. Anchor of which <data2>
matches ,*,
is set to be external. Example call:
-zui_std_anchor regen1 4 "" ",mod1_ice1," $RANDOM "[${ZUI[MAGENTA]}Regen${ZUI[FMT_END]}]"
This instructs to regenerate module 1
instance 1
, with no handler call, with $RANDOM
as the generator's third input - regeneration user-data. 4
is the line number on which the cursor will be placed after the regeneration. Note that any generator call has instance ID (mod and ice) in $1
and $2
by the design of the restart-regeneration loop.
-zui_std_text_field
-zui_std_text_field <ID> <width param> <index param> <text param> <data1> <data2> <data3> [handler] [output array]