Class: TerminalSession

• Inheritance
• Description
• Class protocol
  • accessing
  • initialization
• Instance protocol
  • accessing
  • initialization & release
  • input / output
  • misc
  • queries
  • reader process
• Examples

Inheritance:

   Object
   |
   +--TerminalSession

Package:

stx:libbasic2

Category:

Views-TerminalViews

Version:

rev: 1.81 date: 2024/01/10 13:00:38

user: cg

file: TerminalSession.st directory: libbasic2

module: stx stc-classLibrary: libbasic2

Description:

This is basically a TerminalView without a view.

This keeps the state and API to interact with another program
via a terminal session. Under Unix, a pseudo-tty connection
is used; other operating systems might use other mechanisms.

This is (currently) used by the GDBApplication, to interact
with gdb, cscope and the program.
It can be used wherever more control is needed than a simple pipe
offers (such as terminal emulation, window size, CTRL-c support etc.)

A major feature is a mechanism to catch certain prompt strings of the output
and get a notification.
This is very useful, if a program's output is to be shown both in a terminalview,
and also to be analyzed for robot actions.
Applications for this are telnet like interaction, interactions with a debugger
or monitor (gdb, android-adb) etc.,

A lot of code has been extracted from TerminalView, 
which will be refactored, once this is stable. 
For now, there is some code duplication (as of Summer 2014).

outStream   - the controlled program's output (a pty-half)
inStream    - the controlled program's input (a pty-half)
errStream   - the controlled program's output (a pty-half)

copyright
COPYRIGHT (c) 2013 by eXept Software AG
             All Rights Reserved

This software is furnished under a license and may be used
only in accordance with the terms of that license and with the
inclusion of the above copyright notice. This software may not
be provided or otherwise made available to, or used by, any
other person. No title to or ownership of the software is
hereby transferred.

Class protocol:

 askToWaitLongerOnTimeoutQuery

by answering this with true, the ask-longer dialog is suppressed on timeout

 initialize

self initialize
Debug := true.

Instance protocol:

 errStream

the stdErrToStx stream.
Stuff written by the process' to its stderr will appear here

 inStream

the stxTostdIn stream.
Stuff written to this stream will appear at the process' stdin

 outStream

the process' stdOutToStx stream.
Stuff written by the process to its stdout will appear here

 pluggableCheckBeforeReadAction: aBlockOrNil

 pluggableProcessInputAction: aBlockOrNil

 pty

 ptyName

 shellCommand

 shellDirectory

 shellPid

 terminatedAction: aBlock

hook to be called when terminated

 closeDownShell

shut down my shell process

 closeDownShell: waitTimeInSeconds

shut down my shell process

 closeDownShellAndStopReaderProcess

shut down my shell process,
stop the background reader thread
and close the streams

 closeStreams

 createTerminalConnectionAndSetupWith: setupBlock

create a terminal connection (pseudo terminal or pipe)

 reinitialize

 startCommand: aCommand in: aDirectory environment: envIn setupTerminalWith: setupBlock terminatedAction: terminatedActionArg

start a command on a pseudo terminal.
If the command arg is nil, a shell is started.
If aDirectory is nil, the command is executed in the current directory.
Also fork a reader process, to read the shell's output
and tell me, whenever something arrives

 paste: someText

paste - redefined to send the chars to the shell instead
of pasting into the view

 send: aString

 sendCharacter: aCharacter

 sendLine: aString

 sendLineEnd

 collectedOutput

return any collected output, so far

 defineWindowSizeLines: numberOfLines columns: numberOfColumns

any idea, how to do this under windows ?

 forgetPrompt: aStringOrRegex

Transcript showCR: e' T: forget "{aStringOrRegex}'.

 onPrompt: aStringOrRegex do: aBlock

remember what to do, when a prompt arrives;
notice: will only start checking for prompt, when startCollectingOutput
has been called.

 onPrompt: stringOrRegex1 do: block1 onPrompt: stringOrRegex2 do: block2

remember what to do, when a prompt arrives;
notice: will only start checking for prompt, when startCollectingOutput
has been called.

 outputFromAction: aBlock prompt: prompt timeout: seconds

evaluate aBlock and wait for the prompt.
return gdb output as string collection

 outputFromAction: aBlock prompt: prompt timeout: seconds to: aStreamOrNil

evaluate aBlock and wait for the prompt.
return the output as string collection

 outputFromCommand: aCommand prompt: prompt timeout: seconds

return a command's output as string collection

 outputFromCommand: aCommand prompt: prompt timeout: seconds to: aStreamOrNil

return a command's output as string collection

 sendInterruptSignal

send an INT-signal to the shell (UNIX only)

 sendKillSignal

send a KILL-signal to the shell (UNIX only)

 startCollectingOutput

start collecting output in a collecting stream

 startCollectingOutputTo: aStream

start collecting output into a collecting (or other) stream

 stopCollectingOutput

start collecting output in a collecting stream

 isOpen

 collectOutputAndCheckForPrompt: buffer count: n

Logger debug:'string: "%1"' with:string.

 readAnyAvailableData

read data from the stream,
and sends me #processInput:n: events if something arrived.
Returns the amount of data read.

 readerProcessLoop

look for the session's output

 startReaderProcess

Start a reader process, which looks for the commands output,
and sends me #processInput:n: events whenever something arrives.

 stopReaderProcess

stop the background reader thread

Examples:

|session|

session := TerminalSession new.
session startReaderProcess.
session 
    pluggableProcessInputAction:[:buffer :n |
        Transcript show:(buffer copyTo:n).
        Transcript endEntry.
    ].
session 
    startCommand:'ls -l' in:'~' 
    environment:nil 
    setupTerminalWith:[] 
    terminatedAction:[ Transcript showCR:'finished' ].

session 
    startCommand:'(cd ~/work/cg/schemeNew ; make)' in:'~' 
    environment:nil 
    setupTerminalWith:[] 
    terminatedAction:[ Transcript showCR:'finished' ].

session 
    startCommand:'(ls ~/work/cg/schemeNew)' in:'~' 
    environment:nil 
    setupTerminalWith:[] 
    terminatedAction:[ Transcript showCR:'finished' ].