terminal.q

Terminal (Console) Management

This library can track changes to the current terminal window that kdb+ is running in and adjust the kdb console size (system "c") to match it.

The adjustment can be done manually (via .terminal.setToCurrentSize) or automatically via the .z.pi event hander.

Automatic Update of Console Size

Automatic update of the kdb+ console size to the current terminal window is configured by .terminal.cfg.trackSizeChange.

If enabled, and the current terminal is interactive, the .z.pi event handler function will be set.

Notes

1. Any existing .z.pi function will be kept and wrapped by .terminal.i.trackHandler
   • If no existing .z.pi function exists, a default .terminal.cfg.defaultZPi function will be used instead
2. system "c xx yy" does not work with this mode
   • To specify a minimum terminal size, use the -c xx yy command line argument (see .terminal.setToCurrentSize)

.terminal.setToCurrentSize

This function changes the kdb+ console size to match the current terminal window size.

To protect against making the console size too small, there is an options .terminal.cfg.setMinWithCommandLineArg (defaults to true) that will look for the -c argument on the command line and use this value as the minimum console size.

When this function is called, the value specified by the -c will be used whenever the terminal window is smaller than this value.

Example

/ With TRACE logging enabled
q)\c
25 80i
q).terminal.setToCurrentSize[]
2020.05.16 20:00:24.128 DEBUG pid-1218 jas 0 Running system command: "stty size"
2020.05.16 20:00:24.140 TRACE pid-1218 jas 0 Console size change [ Old: 25 80i ] [ New: 84 157 ]
q)\c
84 157i

/ Minimum value via command line `-c 50 150`
...
2022.12.08 11:50:02.926 INFO  pid-1791 jas 0 Minimum console size specified via '-c' command line argument [ Minimum Size: 50, 150 ]
...
q)
2022.12.08 11:50:09.945 DEBUG pid-1791 jas 0 Running system command: "stty size"
2022.12.08 11:50:09.954 TRACE pid-1791 jas 0 Console size change [ Old: 50 150i ] [ New: 66 239 ]
q) / Resize smaller than 50 150
2022.12.08 11:50:16.760 DEBUG pid-1791 jas 0 Running system command: "stty size"
2022.12.08 11:50:16.772 TRACE pid-1791 jas 0 Console size change [ Old: 66 239i ] [ New: 50 150 ]

.terminal.isInteractive

This function returns true if the current kdb process is running interactively, false otherwise.

Example

/ Interactive session with "rlwrap $QHOME/l64/q src/require.q"

q).require.init[]; .require.lib`terminal
...

q).terminal.isInteractive[]
Running system command: "stty size"
Running system command: "tty --quiet; echo $?"
Current kdb process terminal state [ Interactive: yes ]
1b

# Non-interactive session

> echo '.require.init[]; .require.lib`terminal; -1 .Q.s .terminal.isInteractive[];' | $QHOME/l64/q src/require.q
...
Running system command: "tty --quiet; echo $?"
Current kdb process terminal state [ Interactive: no ]
0b