From afe1b00e16c7efc5c93c958fa4f357325977a2a1 Mon Sep 17 00:00:00 2001 From: Peter Stephenson Date: Tue, 21 May 2002 11:10:13 +0000 Subject: 17141 plus mods: add `zle -F fd handler' feature. --- Doc/Zsh/zle.yo | 60 ++++++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 60 insertions(+) (limited to 'Doc/Zsh/zle.yo') diff --git a/Doc/Zsh/zle.yo b/Doc/Zsh/zle.yo index aee624eb7..67e66830d 100644 --- a/Doc/Zsh/zle.yo +++ b/Doc/Zsh/zle.yo @@ -314,6 +314,7 @@ xitem(tt(zle) tt(-R) [ tt(-c) ] [ var(display-string) ] [ var(string) ... ]) xitem(tt(zle) tt(-M) var(string)) xitem(tt(zle) tt(-U) var(string)) xitem(tt(zle) tt(-K) var(keymap)) +xitem(tt(zle) tt(-F) [ tt(-L) ] [ var(fd) [ var(handler) ] ]) xitem(tt(zle) tt(-I)) xitem(tt(zle) var(widget) tt([ -n) var(num) tt(]) tt([ -N ]) var(args) ...) item(tt(zle))( @@ -411,6 +412,65 @@ This keymap selection affects the interpretation of following keystrokes within this invocation of ZLE. Any following invocation (e.g., the next command line) will start as usual with the `tt(main)' keymap selected. ) +item(tt(-F) [ tt(-L) ] [ var(fd) [ var(handler) ] ])( +Only available if your system support the `select' system call; most +modern systems do. + +Installs var(handler) (the name of a shell function) to handle input from +file descriptor var(fd). When zle is attempting to read data, it will +examine both the terminal and the list of handled var(fd)'s. If data +becomes available on a handled var(fd), zle will call var(handler) with +the fd which is ready for reading as the only argument. If the handler +produces output to the terminal, it should call `tt(zle -I)' before doing +so (see below). The handler should not attempt to read from the terminal. +Note that zle makes no attempt to check whether this fd is actually +readable when installing the handler. The user must make their own +arrangments for handling the file descriptor when zle is not active. + +Any number of handlers for any number of readable file descriptors may be +installed. Installing a handler for an var(fd) which is already handled +causes the existing handler to be replaced. + +If no var(handler) is given, but an var(fd) is present, any handler for +that var(fd) is removed. If there is none, an error message is printed +and status 1 is returned. + +If no arguments are given, or the tt(-L) option is supplied, a list of +handlers is printed in a form which can be stored for later execution. + +An var(fd) (but not a var(handler)) may optionally be given with the tt(-L) +option; in this case, the function will list the handler if any, else +silently return status 1. + +Note that this feature should be used with care. Activity on one of the +var(fd)'s which is not properly handled can cause the terminal to become +unusable. + +Here is a simple example of using this feature. A connection to a remote +TCP port is created using the ztcp command; see +ifzman(the description of the tt(zsh/net/tcp) module in zmanref(zshmodules))\ +ifnzman(noderef(The zsh/net/tcp Module)). Then a handler is installed +which simply prints out any data which arrives on this connection. Note +that `select' will indicate that the file descriptor needs handling +if the remote side has closed the connection; we handle that by testing +for a failed read. +example(if ztcp pwspc 2811; then + tcpfd=$REPLY + handler() { + zle -I + local line + if ! read -r line <&$1; then + # select marks this fd if we reach EOF, + # so handle this specially. + print "[Read on fd $1 failed, removing.]" >&2 + zle -F $1 + return 1 + fi + print -r - $line + } + zle -F $tcpfd handler +fi) +) item(tt(-I))( Unusually, this option is only useful em(outside) ordinary widget functions. It invalidates the current zle display in preparation for output; usually -- cgit 1.4.1