6 There are several aspects to deal with when adding scripting support to
8 1. The set of information to expose.
9 2. The command interface to provide.
10 3. The hook on interesting events in Screen.
11 4. The ability to do run asynchronously to Screen itself.
13 A. Query & control interface
15 Currently, screen provides a way to control a running session through the -X
16 command switch, which sends the specified command through the sever socket.
17 It's quite useful and can already do automation to some degree, (e.g. [1]).
18 However, the problem is that, there is no way to get enough feedback to make
19 decision in your script in such a scheme. The first job is to provide an
20 interface for scripts to query internal status of Screen. The second job is to
21 provide an interface to control Screen, with reasonable feedback.
25 When the internal status of Screen changed, we say that an event happened.
26 Events are also interesting to scripts, but are not covered by the query
27 interface. A hook / callback system is needed to notify scripts about
28 interested events. With the callback that triggers before an event, the script
29 should be able to stop the event from happening.
31 C. Asynchronous scripting
33 So far, with the described scripting support, we can write small functions
34 that provide enhanced functionality to a screen command, or write event
35 handler that handles interested events. But we are restricted to finish our
36 work quickly. The problem is that, Screen itself is a single threaded
37 application, utilizing asynchronous I/O to provide services to all windows
38 running inside. So you simply can not do time-consuming work in any of the
39 processing path, including the scripts.
41 Sometimes we may need to wait for something in a script, such as emulating
42 Expect in a Screen script [2]. The core of this use case is to wait for an
43 output pattern and react upon it. One possible way is to provide an event
44 callback for it. But it's not a pleasant way to do a series of interaction.
45 A natural solution is to make the script able to run asynchronously to Screen
48 [1] http://github.com/rblackwe/yapc--na-2007--making-an-ajax-gui-for-gnu-screen
49 [2] http://lists.gnu.org/archive/html/screen-users/2009-05/msg00006.html
51 II. The Screen interface
53 Screen needs to provide a user interface to source and run scripts.
55 sourcescript [-async|-a] [-binding|-b <binding>] script.
57 This command sources the specified script. This command can be used several
58 times to source multiple scripts. Use the -async switch if the
59 script is supposed to run asynchronously , e.g. it needs to wait for
60 external events. Asynchronous scripts running mode needs to acquire a
61 lock before playing on Screen itself. As a result, it pays more overhead
62 than synch ones. Moreover, asynchronous scripts may be isolated from other
63 scripts and may not share any information with them. In other words, normal
64 scripts may share the same context. (Note: the isolation between scripts may
65 be implementation dependent. Which is more desirable?)
67 scriptcall func arg1 arg2 ...
69 Call functions defined by scripts. If the same function are defined in
70 multiple scripting context, the last one applies. Call to normal script
71 returns synchronously. And call to asynchronous one will return immediately.
73 Special invoke interface, such as those embedded in caption/hstatus format
76 III. The scripting interface
78 There are several kinds of objects that may be interested to scripts.
82 Stands for a user interface.
91 description: The tty that this attach runs on.
96 description: The TERM env of that tty.
101 description: The fore window.
106 description: List of windows other than the fore.
111 description: As the name suggests
116 description: As the name suggests
121 description: The owner of this display.
126 description: Active layout on this display.
133 get_canvases: Get a list of canvases on this display.
139 on_resize: Triggered after the geometry of the display is changed.
143 Stands for the sub-terminal(PTY, telnet etc) that processes runs on.
152 description: The title of the window.
157 description: The index in the window slots.
162 description: The initial directory of the first
163 application (typically the shell) in that window.
168 description: the associated terminal device for that window.
173 description: the pid of of the slave end of the pty.
178 description: The window group we belongs to. (*This seems in-active?*)
183 description: The bell status of the window.
189 int get_monitor_status(bool activity);
190 Returns the status of the specified monitor type. Either activity or silence.
191 When the silence monitor is active, the threshold is returned.
193 void set_monitor_status(bool activity, int status);
194 Set the status of activity/silence monitor. The number of status for the
195 silence monitor is the seconds of threshold.
197 void stuff(string buf);
198 put the string into the input buffer.
200 int waitfor(string pattern);
201 Waiting for a specified output pattern.
202 NOTICE: This is an asynchronous method call and can only be called in