Fill in design document.

[screen-lua.git] / src / drafts / scripting

===================
The design
===================

I. Key Factors
There are several aspects to deal with when adding scripting support to
Screen:
1. The set of information to expose.
2. The command interface to provide.
3. The hook on interesting events in Screen.
4. The ability to do run asynchronously to Screen itself.

[Note: asynchronous scripting support is not supported yet, due to the fact
that screen is highly thread-unsafe. One possible solution is to implement an
implicit locking through the asynchronous IO mechanism (similar to the one
used by attacher <=> back end) that is currently in use.]

A. Query & control interface

Currently, screen provides a way to control a running session through the -X
command switch, which sends the specified command through the sever socket.
It's quite useful and can already do automation to some degree, (e.g. [1]).
However, the problem is that, there is no way to get enough feedback to make
decision in your script in such a scheme. The first job is to provide an
interface for scripts to query internal status of Screen. The second job is to
provide an interface to control Screen, with reasonable feedback.

B. Event hooking

When the internal status of Screen changed, we say that an event happened.
Events are also interesting to scripts, but are not covered by the query
interface. A hook / callback system is needed to notify scripts about
interested events. With the callback that triggers before an event, the script
should be able to stop the event from happening.

C. Asynchronous scripting

So far, with the described scripting support, we can write small functions
that provide enhanced functionality to a screen command, or write event
handler that handles interested events. But we are restricted to finish our
work quickly. The problem is that, Screen itself is a single threaded
application, utilizing asynchronous I/O to provide services to all windows
running inside. So you simply can not do time-consuming work in any of the
processing path, including the scripts.

Sometimes we may need to wait for something in a script, such as emulating
Expect in a Screen script [2]. The core of this use case is to wait for an
output pattern and react upon it. One possible way is to provide an event
callback for it. But it's not a pleasant way to do a series of interaction.
A natural solution is to make the script able to run asynchronously to Screen
itself.

[1] http://github.com/rblackwe/yapc--na-2007--making-an-ajax-gui-for-gnu-screen
[2] http://lists.gnu.org/archive/html/screen-users/2009-05/msg00006.html

II. The Screen interface

Screen needs to provide a user interface to source and run scripts.

script source [-async|-a] [-binding|-b <binding>] script.

  This command sources the specified script. This command can be used several
  times to source multiple scripts. Use the -async switch if the
  script is supposed to run asynchronously , e.g. it needs to wait for
  external events. Asynchronous scripts running mode needs to acquire a
  lock before playing on Screen itself. As a result, it pays more overhead
  than synch ones. Moreover, asynchronous scripts may be isolated from other
  scripts and may not share any information with them. In other words, normal
  scripts may share the same context. (Note: the isolation between scripts may
  be implementation dependent. Which is more desirable?)

script call func arg1 arg2 ...

  Call functions defined by scripts. If the same function are defined in 
  multiple scripting context, the last one applies. Call to normal script
  returns synchronously. And call to asynchronous one will return immediately.

Special invoke interface, such as those embedded in caption/hstatus format
string.

III. The scripting interface

There are several kinds of objects that may be interested to scripts.

==========
A. Display

Stands for a user view that presented by an attacher.

----------
Properties:
----------

tty:
 mode: read only.
 type: String.
 description: The tty that this attach runs on.

term:
 mode: read only. 
 type: String. 
 description: The TERM env of that tty.

fore:
 mode: read only. 
 type: Window. 
 description: The fore window.

other:
 mode: read only. 
 type: Window. 
 description: List of windows other than the fore.

width:
 mode: read only. 
 type: Int. 
 description: As the name suggests

height:
 mode: read only. 
 type: Int. 
 description:  As the name suggests

user:
 mode: read only. 
 type: User. 
 description: The owner of this display.

layout:
 mode: read only. 
 type: Layout. 
 description: Active layout on this display.

idle_timeout:
 mode: write only.
 type: Int.
 description: Set the idle timeout of the next activation for this display,
              and actives the idle event. It differs from the idle command, 
              which uses a global value for all attached displays.

----------
Methods:
----------

table get_canvases();
 Returns a list/table of canvases on this display.

Canvas top_canvas();
 Returns the top (or top-left) canvas on the display.

Canvas bottom_canvas();
 Returns the bottom canvas on the display.

----------
Events:
----------

onidle: (Display)
        Triggered whenever the idle timeout is reached. The handler will be
        called with a reference to the idling display. If the handler returns
        non-zero, the internal idle processing will be overridden. Please note
        that the The idle timeout is not reseted on such a situation, remember to
        setup idle timeout in the handler if multiple activation is needed.. 


=========
B. Window

Stands for the sub-terminal(PTY, telnet etc) that processes runs on.

----------
Properties:
----------

title:
 mode: read write
 type: String.
 description: The title of the window.

number:
 mode: read write
 type: int.
 description: The index in the window slots. Assigning new value to the number
              changes the position of this window in the window list. If the
              new window is occupied by some other window, they are changed by
              position.

dir:
 mode: read only
 type: String.
 description: The initial directory of the first 
              application (typically the shell) in that window.

tty:
 mode: read only
 type: String
 description: the associated terminal device for that window.

pid:
 mode: read only
 type: int
 description: the pid of of the slave end of the pty.

group:
 mode: read only
 type: Window
 description: The window group we belongs to. (*This seems in-active?*)

bell:
 mode: read only
 type: int
 description: The bell status of the window.

----------
Methods:
----------

int get_monitor_status(bool activity);
 Returns the status of the specified monitor type. Either activity or silence.
 When the silence monitor is active, the threshold is returned.
 
void set_monitor_status(bool activity, int status);
 Set the status of activity/silence monitor. The number of status for the
 silence monitor is the seconds of threshold.
 
char ** get_lines();
 Return the content on the window as an array of string. Each string represent
 a single line.

char ** get_history();
 Return the history buffer of the window as an array of string. Each string 
 represent a single line.

void stuff(string buf);
 put the string into the input buffer. This can be used to interactive with
 the application within the window

void activate();
 Show the window in current focused canvas.

int waitfor(string pattern);
 NOT IMPLEMENTED YET
 Waiting for a specified output pattern. The pattern is limited to plain text. 
 NOTICE: This is an asynchronous method call and can only be called in
 asynchronous mode.

hook([obj], event, handler, [priv])
 See the description in Screen object.

----------
Events
----------

onactivity (display, window)
  triggered when the activity monitor got fired. This will be triggered for
  each display on which the window is hidden. Return non-zero in the handler
  will override the default activity message.
  
onsilent (display, window)
  triggered when the silence monitor got fired. This will be triggered for
  each display on which the window is hidden. Return non-zero in the handler
  will override the default silent message.

onfocus (display, window)
 Triggered when the window gets input focus on a display.
 Differs from the global event forechange, it's associated with a specific
 window.

onleave (display, window)
 Triggered after the window lost input focus on a display.
 Differs from the global event forechange, it's associated with a specific
 window.

onshow (display, window)
 Triggered after the first view of this window show up on a display.
 Differs from on_focus when there are many regions on a display.

onhide (display, window)
 Triggered after the last view of this window disappeared from a display.
 Differs from on_leave when there are many regions on a display.

onclose (window)
 Triggered before the window close. Can be used to free any references to
 the window.

onresize (window)
 Triggered after the window is resized.

onoutput (window, string)
 Triggered when the window has new output. This output is not cooked to on
 line basis. Please be careful when using this hook. The system speed can be
 significantly slowed down due to ill use of this.

=======
C. User

--------
Property:
--------

name:
 mode: read only
 type: String.
 description: The login name.

uid:
 mode: read only
 type: int
 description: The index in the ACL bit fields.

esc:
metaesc:
 mode: read only
 type: int
 description: The escape character

umask:
 mode: read only
 type: String.
 description: The access for the window created by this user to other users.
              The result will be in a form of 'rwx'.
              NOTE: NOT IMPLEMENTED YET.

=========
D. Canvas

--------
Property:
--------

next:
 mode: read only
 type: Canvas
 description: The next canvas on display.

xoff:
yoff:
 mode: read only
 type: int
 description: The x/y offset of canvas on the display.

xe/ye:
 mode: read only
 description: The bottom right coordinate of the canvas.

window:
 mode: read write
 description: The window currently showing on the canvas.
              Can be used to select a new window to show.
              The new window can also be NULL, so that the
              canvas shows nothing.

display:
 mode: read only
 description: The display that this canvas belongs to.

caption:
 mode: write only
 description: The caption string for this canvas. The string set to caption
              can contain screen escapes and will be expended before show 
              up on the display.


----------
Methods:
----------

select()
  Get input focus for this canvas.

split(horizontal)
  Split the canvas into two part. If the horizontal flag is not set, the split
  is done in vertical.

=========
E. Layout

 The layout of canvases on a display. Can be used to emulate the tab feature
 of VIM.

----------
Properties:
----------

title
 mode: read write
 type: string
 description: The title of a layout.


number 
 mode: read write
 type: int
 description: The number of the layout in the layout list.

autosave
 mode: read write
 type: int
 description: Specify whether the layout will be automatically updated on
              switch.

--------
Methods:
--------

select();
 Use this layout on current display. Does nothing whenever the current display
 is NULL.

=========
F. Screen

 This is a pseudo object standing for the whole screen object. All other
 objects can be obtained starting from this one. Since this is not a real
 object, there's no property for it.

--------
Methods:
--------
Table windows();
 Returns a list/table of windows in screen. The table/list is not necessary
 indexed by the window number. But the order of the windows should keep the
 same.

Table displays();
 Returns a list/table of attached displays in screen.

Table layouts();
 Returns a list/table of defined layouts.

command(string);
 Invoke a screen command specified as a string.

Display display();
 The display that currently has internal events happening. Can be null.

append_msg(string msg);
 Show a message on the status/caption line.

schedule(int timeout, handler);
 Schedule an handler to be triggered in 'timeout' seconds later.

hook([obj], event, handler, [priv]);
or obj:hook(event, handler,[priv])

 listen to the event notification. The event is associated with the specified
 obj. If the obj is omitted, the event is a global event. An optional privilege
 can be specified through the priv parameter. The privilege determines the
 position of this handler in the chain. A smaller value has higher privilege.

 This method returns a ticket (or handle) of the registration. This is used to
 unregister the notification, using the syntax: ticket:unhook().

input(prompt, callback, [prefill]);
 get input from user asynchronously with a callback.
 This call returns immediately, with a input line poped up. The input prompt
 is set to the first parameter and the buffer can be pre-filled with the third
 parameter. Once the input is done with an enter, the callback function is
 called with the inputed string to enable further process.

 The input happens at the active canvas of the current display. If there is no
 current display input line appears in all canvas that shows the current
 layer.

--------
Events:
--------
cmdexecuted(command, args)
 An SCREEN command is executed with a list of arguments (args). This has
 nothing to do with the shell command in user window.

detached (display, is_remote)

 For detach-events, it's not enough to just listen to 'cmdexecuted'
 command, since this command is not used for remote detaches. So
 scripts looking to do something on a detach event need to hook to
 this event, instead of hooking to 'cmdexecuted' event and looking
 for 'detach' command.

forechanged(display, window)
 Triggered when a new window has been set on the display.

onattach(display)
 Triggered after a new display is attached.

oncreatewindow(window)
 Triggered after a new window is created. Can be used to hook other events on
 that window.

processcaption(canvas)
 Triggered whenever the caption for the canvas needs to be updated.

===================
The Implementation
===================

Bindings are in fact script interpretors. We can have several different
language bindings at the same time, with each registered at the compiling time
and loaded (initialized) dynamically at runtime. It's an bridge between
scripts and screen itself.