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 script source [-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 script call 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. Assigning new value to the number
158 changes the position of this window in the window list. If the
159 new window is occupied by some other window, they are changed by
165 description: The initial directory of the first
166 application (typically the shell) in that window.
171 description: the associated terminal device for that window.
176 description: the pid of of the slave end of the pty.
181 description: The window group we belongs to. (*This seems in-active?*)
186 description: The bell status of the window.
192 int get_monitor_status(bool activity);
193 Returns the status of the specified monitor type. Either activity or silence.
194 When the silence monitor is active, the threshold is returned.
196 void set_monitor_status(bool activity, int status);
197 Set the status of activity/silence monitor. The number of status for the
198 silence monitor is the seconds of threshold.
200 void stuff(string buf);
201 put the string into the input buffer.
203 int waitfor(string pattern);
204 Waiting for a specified output pattern. The pattern is limited to plain text.
205 NOTICE: This is an asynchronous method call and can only be called in
208 hook([obj], event, handler, [priv])
209 See the description in Screen object.
231 description: The login name.
236 description: The index in the ACL bit fields.
242 description: The escape character
247 description: The access for the window created by this user to other users.
248 The result will be in a form of 'rwx'.
260 This is a pseudo object standing for the whole screen object. All other
261 objects can be obtained starting from this one.
271 hook([obj], event, handler, [priv])
272 or obj:hook(event, handler,[priv])
274 listen to the event notification. The event is associated with the specified
275 obj. If the obj is omitted, the event is a global event. An optional privilege
276 can be specified through the priv parameter. The privilege determines the
277 position of this handler in the chain. A smaller value has higher privilege.
279 This method returns a ticket (or handle) of the registration. This is used to
280 unregister the notification, using the syntax: ticket:unhook().
282 input(prompt, callback, [prefill])
283 get input from user asynchronously with a callback.
284 This call returns immediately, with a input line poped up. The input prompt
285 is set to the first parameter and the buffer can be pre-filled with the third
286 parameter. Once the input is done with an enter, the callback function is
287 called with the inputed string to enable further process.
289 The input happens at the active canvas of the current display. If there is no
290 current display input line appears in all canvas that shows the current
297 detached (display, is_remote)
299 For detach-events, it's not enough to just listen to 'cmdexecuted'
300 command, since this command is not used for remote detaches. So
301 scripts looking to do something on a detach event need to hook to
302 this event, instead of hooking to 'cmdexecuted' event and looking
303 for 'detach' command.
309 Bindings are in fact script interpretors. We can have several different
310 language bindings at the same time, with each registered at the compiling time
311 and loaded (initialized) dynamically at runtime. It's an bridge between
312 scripts and screen itself.