crystallabs / tput.cr Goto Github PK

Context

I'm experiencing an issue with the example provided in the tput.cr library's README.md (rather than the tput.cr library itself)... and as a result, I don't know what the good practices are for using tput.cr 😓

I've searched the source code and tried various things before the exit (soft_reset, clear, etc.), but I haven't (yet) found a function that solves the problem.

Environment

• Crystal Version: 1.10.1
• tput.cr Version: v1.0.7
• Operating System: Debian Bookworm (12)
• Terminal Emulator: Konsole 23.08.1 , xterm 386-1, qterminal 1.3.0-1,

Reproduction Steps

1. Create a project using the shards.yml below :

---
name: Test
version: 0.1.0

targets:
  test:
    main: src/test.cr

dependencies:
  tput:
    github: crystallabs/tput.cr
    version: ~> 1.0

license: MIT

2. Copy-paste the example from tput.cr's README.md in src/test.cr.
3. Compile with shards build and executed in Konsole.

Observed Behavior

• Post-execution, the terminal is left in an unusable state with no echo (invisible text), and the cursor is still colored.
• No specific error logs are generated by tput.cr or by the terminal.
• Typing "reset" in the terminal restores its functionality, indicating a probable issue in the cleanup sequence of the example code.

Insights/Fixes

The example code in tput.cr's documentation likely lacks an adequate cleanup or reset sequence for the terminal state, leading to this issue.

Crystal 1.0.0 [dd40a2442] (2021-03-22)

LLVM: 10.0.0
Default target: x86_64-unknown-linux-gnu
shard.yml

  tput:
    github: crystallabs/tput.cr
    branch: master

/usr/bin/crystal  build src/pager.cr -o bin/pager --warnings all --error-on-warnings
    152 | tput.set_title "Test 123"
Error: undefined method 'set_title' for Tput

Thanks for any help.

$ crystal version
Crystal 0.32.0 [6952aacb3] (2019-12-11)

LLVM: 8.0.0
Default target: x86_64-unknown-linux-gnu

$ crystal build

In lib/tput/src/methods.cr:521:22

 521 | _write("\x1b[" + param + "A")
                      ^
Error: no overload matches 'String#+' with type Int32

Overloads are:
 - String#+(other : self)
 - String#+(char : Char)

Tput.cr's support for terminal sequences is based on Blessed. Blessed keeps its terminal sequences in file https://github.com/chjj/blessed/blob/master/lib/program.js , starting roughly at line 1818 and spanning the next ~3k lines.

A good majority of those functions was reimplemented in tput.cr, and also more conveniently organized into multiple files, to separate groups of functionality:

ls src/tput/output

bell.cr
charset.cr
colors.cr
cursor.cr
emulator.cr
misc.cr
mouse.cr
rectangles.cr
screen.cr
scrolling.cr
terminal.cr
text.cr

All functions that were ported over to tput.cr have one thing in common -- they just output sequences to the terminal, and don't read anything back (that's why they are in the "output/" subdirectory). For example, they output sequences to trigger an audio or visual bell on the terminal (tput.bell), to move cursor one row down (tput.cursor_down), to move cursor to a specific (y,x) position, to erase some rectangular area on the screen, etc. Terminal does not send any "response" back to the app on these calls, it just does what it is told.

(On a side note: working with raw terminal sequences is not ideal -- e.g. if a particular terminal does not support e.g. cud(amount) (cursor down), then the user would need to check whether terminal maybe supports cud1 sequence (and if yes, repeat it amount times), and so on. This overhead should not befall on the programmer -- programmer should just request a "cursor down", and it should happen. That's why blessed's/tput's functions already have those fallbacks built-in, for example see https://github.com/crystallabs/tput.cr/blob/master/src/tput/output/cursor.cr#L272 . There we see that it first tries cud(amount), then cud1 * amount, and then finally falls back to generic sequence \e[*amount*B.)

Most console programs get away with using just those sequences.

But apart from those write-only sequences, there are some that actually do send a response back to the program. So after writing/outputting a sequence to the terminal, the program should expect to read a response. All such functions are currently not implemented in tput.cr.

In Blessed, it seems to me that there is just one function for this, in which Blessed's author has added support for reading all kinds of responses that it supports. That's function https://github.com/chjj/blessed/blob/master/lib/program.js#L1040 .

If support for something like that was added to tput.cr, then it would be possible for the app to read the position of cursor (instead of only set it), probably read colors used, and other stuff.

As mentioned, my impression is that most apps don't use this, but having it would be nice.