src/drafts/scripting

   1 ===================
   2 The design
   3 ===================
   4
   5 I. Key Factors
   6 There are several aspects to deal with when adding scripting support to
   7 Screen:
   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.
  12
  13 A. Query & control interface
  14
  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.
  22
  23 B. Event hooking
  24
  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.
  30
  31 C. Asynchronous scripting
  32
  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.
  40
  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
  46 itself.
  47
  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
  50
  51 II. The Screen interface
  52
  53 Screen needs to provide a user interface to source and run scripts.
  54
  55 script source [-async|-a] [-binding|-b <binding>] script.
  56
  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?)
  66
  67 script call func arg1 arg2 ...
  68
  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.
  72
  73 Special invoke interface, such as those embedded in caption/hstatus format
  74 string.
  75
  76 III. The scripting interface
  77
  78 There are several kinds of objects that may be interested to scripts.
  79
  80 A. Display
  81
  82 Stands for a user interface.
  83
  84 ----------
  85 Properties:
  86 ----------
  87
  88 tty:
  89  mode: read only.
  90  type: String.
  91  description: The tty that this attach runs on.
  92
  93 term:
  94  mode: read only.
  95  type: String.
  96  description: The TERM env of that tty.
  97
  98 fore:
  99  mode: read only.
 100  type: Window.
 101  description: The fore window.
 102
 103 other:
 104  mode: read only.
 105  type: Window.
 106  description: List of windows other than the fore.
 107
 108 width:
 109  mode: read only.
 110  type: Int.
 111  description: As the name suggests
 112
 113 height:
 114  mode: read only.
 115  type: Int.
 116  description:  As the name suggests
 117
 118 user:
 119  mode: read only.
 120  type: User.
 121  description: The owner of this display.
 122
 123 layout:
 124  mode: read only.
 125  type: Layout.
 126  description: Active layout on this display.
 127
 128
 129 ----------
 130 Methods:
 131 ----------
 132
 133 get_canvases: Get a list of canvases on this display.
 134
 135 ----------
 136 Events:
 137 ----------
 138
 139 on_resize: Triggered after the geometry of the display is changed.
 140
 141 B. Window
 142
 143 Stands for the sub-terminal(PTY, telnet etc) that processes runs on.
 144
 145 ----------
 146 Properties:
 147 ----------
 148
 149 title:
 150  mode: read write
 151  type: String.
 152  description: The title of the window.
 153
 154 number:
 155  mode: read only
 156  type: int.
 157  description: The index in the window slots.
 158
 159 dir:
 160  mode: read only
 161  type: String.
 162  description: The initial directory of the first
 163               application (typically the shell) in that window.
 164
 165 tty:
 166  mode: read only
 167  type: String
 168  description: the associated terminal device for that window.
 169
 170 pid:
 171  mode: read only
 172  type: int
 173  description: the pid of of the slave end of the pty.
 174
 175 group:
 176  mode: read only
 177  type: Window
 178  description: The window group we belongs to. (*This seems in-active?*)
 179
 180 bell:
 181  mode: read only
 182  type: int
 183  description: The bell status of the window.
 184
 185 ----------
 186 Methods:
 187 ----------
 188
 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.
 192
 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.
 196
 197 void stuff(string buf);
 198  put the string into the input buffer.
 199
 200 int waitfor(string pattern);
 201  Waiting for a specified output pattern. The pattern is limited to plain text.
 202  NOTICE: This is an asynchronous method call and can only be called in
 203  asynchronous mode.
 204
 205 hook([obj], event, handler, [priv])
 206  See the description in Screen object.
 207
 208 ----------
 209 Events
 210 ----------
 211
 212 on_activity
 213 on_silence
 214 before_winchange
 215 on_winchange
 216 before_resize
 217 on_resize
 218
 219 C. User
 220
 221 --------
 222 Property:
 223 --------
 224
 225 name:
 226  mode: read only
 227  type: String.
 228  description: The login name.
 229
 230 uid:
 231  mode: read only
 232  type: int
 233  description: The index in the ACL bit fields.
 234
 235 esc:
 236 metaesc:
 237  mode: read only
 238  type: int
 239  description: The escape character
 240
 241 umask:
 242  mode: read only
 243  type: String.
 244  description: The access for the window created by this user to other users.
 245               The result will be in a form of 'rwx'.
 246
 247 D. Display
 248
 249
 250 ----------
 251 Methods:
 252 ----------
 253
 254 input
 255  get input from user.
 256
 257
 258 E. Screen
 259
 260  This is a pseudo object standing for the whole screen object. All other
 261  objects can be obtained starting from this one.
 262
 263 --------
 264 Methods:
 265 --------
 266 windows
 267 displays
 268 command
 269 windowbyname
 270
 271 hook([obj], event, handler, [priv])
 272 or obj:hook(event, handler,[priv])
 273
 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.
 278  This method returns a ticket (or handle) of the registration. This is used to
 279  unregister the notification.
 280
 281 unhook(ticket, handler)
 282 or obj:unhook(ticket, handler)
 283
 284  Unregister the hook. The ticket and handler must match, otherwise a false is
 285  returned.
 286
 287 --------
 288 Events:
 289 --------
 290 cmdexecuted
 291 detached (display, is_remote)
 292
 293 For detach-events, it's not enough to just listen to 'cmdexecuted'
 294 command, since this command is not used for remote detaches. So
 295 scripts looking to do something on a detach event need to hook to
 296 this event, instead of hooking to 'cmdexecuted' event and looking
 297 for 'detach' command.
 298
 299 ===================
 300 The Implementation
 301 ===================
 302
 303 Bindings are in fact script interpretors. We can have several different
 304 language bindings at the same time, with each registered at the compiling time
 305 and loaded (initialized) dynamically at runtime. It's an bridge between
 306 scripts and screen itself.
 307
 308 ---------------
 309 Binding related.
 310 ---------------
 311
 312 ---------------
 313 Binding independent
 314 ---------------