diff options
Diffstat (limited to 'man/man1/acmeevent.html')
| -rw-r--r-- | man/man1/acmeevent.html | 332 |
1 files changed, 332 insertions, 0 deletions
diff --git a/man/man1/acmeevent.html b/man/man1/acmeevent.html new file mode 100644 index 00000000..230145ce --- /dev/null +++ b/man/man1/acmeevent.html @@ -0,0 +1,332 @@ +<head> +<title>acmeevent(1) - Plan 9 from User Space</title> +<meta content="text/html; charset=utf-8" http-equiv=Content-Type> +</head> +<body bgcolor=#ffffff> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=10><td> +<tr><td width=20><td> +<tr><td width=20><td><b>ACMEEVENT(1)</b><td align=right><b>ACMEEVENT(1)</b> +<tr><td width=20><td colspan=2> + <br> +<p><font size=+1><b>NAME </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + acmeevent, acme.rc – shell script support for acme clients<br> + +</table> +<p><font size=+1><b>SYNOPSIS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>9p read acme/acme/$winid/event | acmeevent + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>. /usr/local/plan9/lib/acme.rc + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>newwindow + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + <tt><font size=+1>winread</font></tt> <i>file + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + <tt><font size=+1>winwrite</font></tt> <i>file + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + <tt><font size=+1>winctl</font></tt> <i>cmd + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + <tt><font size=+1>windump</font></tt> [ <i>dumpdir</i> | <tt><font size=+1>−</font></tt> ] [ <i>dumpcmd</i> | <tt><font size=+1>−</font></tt> ] + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>winname</font></tt> <i>name + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + <tt><font size=+1>windel</font></tt> [ <tt><font size=+1>sure</font></tt> ] + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>winwriteevent</font></tt> <i>c1 c2 q0 q1</i> [ <i>eq0 eq1 flag textlen text chordarg + chordaddr</i> ] + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <tt><font size=+1>wineventloop<br> + </font></tt> +</table> +<p><font size=+1><b>DESCRIPTION </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Acmeevent</i> and <i>acme.rc</i> make it easy to write simple <a href="../man1/acme.html"><i>acme</i>(1)</a> client + programs as shell scripts. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Acme</i> clients read the <tt><font size=+1>event</font></tt> files (see <a href="../man4/acme.html"><i>acme</i>(4)</a>) for the windows + they control, reacting to the events. The events are presented + in a format that is easy to read with C programs but hard to read + with shell scripts. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Acmeevent</i> reads an <a href="../man4/acme.html"><i>acme</i>(4)</a> event stream from standard input, printing + a shell-friendly version of the events, one per line, on standard + output. Each output line from <i>acmeevent</i> has the form:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>event</font></tt> <i>c1 c2 q0 q1 eq0 eq1 flag textlen text chordarg chordaddr + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </i> + + </table> + The fields are:<br> + <i>c1</i> A character indicating the origin or cause of the action. The + possible causes are: a write to the body or tag file (<tt><font size=+1>E</font></tt>), a write + to the window’s other files (<tt><font size=+1>F</font></tt>), input via the keyboard (<tt><font size=+1>K</font></tt>), and + input via the mouse (<tt><font size=+1>M</font></tt>).<br> + <i>c2</i> A character indicating the type of action. The possible types + are: text deleted from the body (<tt><font size=+1>D</font></tt>), text deleted from the tag + (<tt><font size=+1>d</font></tt>), text inserted in the body (<tt><font size=+1>I</font></tt>), text inserted in the tag (<tt><font size=+1>i</font></tt>), + a button 3 action in the body (<tt><font size=+1>L</font></tt>), a button 3 action in the tag + (<tt><font size=+1>l</font></tt>), a button 2 action in the body (<tt><font size=+1>X</font></tt>), and a button 2 action + in the + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + tag (<tt><font size=+1>x</font></tt>).<br> + + </table> + <i>q0</i>, <i>q1</i>The character addresses of the action.<br> + <i>eq0</i>, <i>q1<br> + </i> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The expanded character addresses of the action. If the text indicated + by <i>q0</i>, <i>q1</i> is a null string that has a non-null expansion, <i>eq0</i>, + <i>eq1</i> are the addresses of the expansion. Otherwise they are the + same as <i>q0</i>, <i>q1</i>.<br> + + </table> + <i>flag Flag</i> is a bitwise OR (reported decimally) of the following: + 1 if the text indicated is recognized as an <i>acme</i> built-in command; + 2 if the text indicated is a null string that has a non-null expansion + (see <i>eq0</i>, <i>eq1</i> above); 8 if the command has an extra (chorded) + argument (see <i>chordarg</i> below). <i>Flag</i> remains from the + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man4/acme.html"><i>acme</i>(4)</a> event format. Because <i>eq0</i>, <i>eq1</i>, and <i>chordarg</i> are explicit + in each event (unlike in <a href="../man4/acme.html"><i>acme</i>(4)</a> events), <i>flag</i> can usually be + ignored.<br> + + </table> + <i>textlen<br> + </i> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The length of the action text (or its expansion) for button 2 + and button 3 events in characters.<br> + + </table> + <i>text</i> If <i>textlen</i> is less than 256 chracters, <i>text</i> is the action + text itself. Otherwise it is an empty string and must be read + from the <tt><font size=+1>data</font></tt> file.<br> + <i>chordarg<br> + </i> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + The chorded argument for an action.<br> + + </table> + <i>chordorigin<br> + </i> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + If the chord argument is in the body of a named window, <i>chordorigin</i> + specifies the full address of the argument, as in <tt><font size=+1>/etc/group:#123,#234</font></tt>. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + + </table> + To experiment with <i>acmeevent</i>, create an empty window in <i>acme</i> (using + <i>New</i>),<i>type<br> + </i> + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>9p read acme/$winid/event | acmeevent<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + inside it, and execute it. Actions performed on the window will + be printed as events in the <tt><font size=+1>+Errors</font></tt> window. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Acme.rc</i> is a library of <a href="../man1/rc.html"><i>rc</i>(1)</a> shell functions useful for writing + acme clients. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Newwindow</i> creates a new acme window and sets <tt><font size=+1>$winid</font></tt> to the new + window’s id. The other commands all use <tt><font size=+1>$winid</font></tt> to determine which + window to operate on. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Winread</i> prints the current window’s <i>file</i> to standard output. It + is equivalent to <tt><font size=+1>cat /mnt/acme/acme/$winid/</font></tt><i>file</i> on Plan 9. Similarly, + <i>winwrite</i> writes standard input to the current window’s <i>file</i>. <i>Winread</i> + and <i>winwrite</i> are useful mainly in building more complex functions. + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Winctl</i> writes <i>cmd</i> to the window’s <tt><font size=+1>ctl</font></tt> file. The most commonly-used + command is <tt><font size=+1>clean</font></tt>, which marks the window as clean. See <a href="../man4/acme.html"><i>acme</i>(4)</a> + for a full list of commands. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Windump</i> sets the window’s dump directory and dump command (see + <a href="../man4/acme.html"><i>acme</i>(4)</a>). If either argument is omitted or is <tt><font size=+1>−</font></tt>, that argument + is not set. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Winname</i> sets the name displayed in the window’s tag. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Windel</i> simulates the <tt><font size=+1>Del</font></tt> command. If the argument <tt><font size=+1>sure</font></tt> is given, + it simulates the <tt><font size=+1>Delete</font></tt> command. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Winwriteevent</i> writes an event to the window’s event file. The + event is in the format produced by <i>acmeevent</i>. Only the first four + arguments are necessary: the rest are ignored. Event handlers + should call <i>winwriteevent</i> to pass unhandled button 2 or button + 3 events back to <i>acme</i> for processing. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + <i>Wineventloop</i> executes the current window’s event file, as output + by <i>acmeevent</i>. It returns when the window has been deleted. Before + running <i>wineventloop ,</i> clients must define a shell function named + <tt><font size=+1>event</font></tt>, which will be run for each incoming event, as <i>rc</i> executes + the output of <i>acmeevent</i>. A typical event function + need only worry about button 2 and button 3 events. Those events + not handled should be sent back to <i>acme</i> with <i>winwriteevent</i>.<br> + +</table> +<p><font size=+1><b>EXAMPLE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <i>Adict</i>, a dictionary browser, is implemented using <i>acmeevent</i> and + <i>acme.rc</i>. The <i>event</i> handler is:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>fn event {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + switch($1$2){<br> + case Mx MX # button 2 − pass back to acme<br> + winwriteevent $*<br> + case Ml ML # button 3 − open new window on dictionary or entry<br> + {<br> + if(~ $dict NONE)<br> + dictwin /adict/$7/ $7<br> + if not<br> + dictwin /adict/$dict/$7 $dict $7<br> + } &<br> + }<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Note that the button 3 handler starts a subshell in which to run + <i>dictwin</i>. That subshell will create a new window, set its name, + possibly fill the window with a dictionary list or dictionary + entry, mark the window as clean, and run the event loop:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>fn dictwin {<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + newwindow<br> + winname $1<br> + dict=$2<br> + if(~ $dict NONE)<br> + dict −d '?' >[2=1] | sed 1d | winwrite body<br> + if(~ $#* 3)<br> + dict −d $dict $3 >[2=1] | winwrite body<br> + winctl clean<br> + wineventloop<br> + + </table> + }<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + The script starts with an initial window:<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>dictwin /adict/ NONE<br> + + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + </font></tt> + + </table> + Button 3 clicking on a dictionary name in the initial window will + create a new empty window for that dictionary. Typing and button + 3 clicking on a word in that window will create a new window with + the dictionary’s entry for that word. + <table border=0 cellpadding=0 cellspacing=0><tr height=5><td></table> + + See <tt><font size=+1>/usr/local/plan9/bin/adict</font></tt> for the full implementation.<br> + +</table> +<p><font size=+1><b>SOURCE </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <tt><font size=+1>/usr/local/plan9/src/cmd/acmeevent.c<br> + /usr/local/plan9/lib/acme.rc<br> + </font></tt> +</table> +<p><font size=+1><b>SEE ALSO </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + <a href="../man1/acme.html"><i>acme</i>(1)</a>, <a href="../man4/acme.html"><i>acme</i>(4)</a>, <a href="../man1/rc.html"><i>rc</i>(1)</a><br> + +</table> +<p><font size=+1><b>BUGS </b></font><br> + +<table border=0 cellpadding=0 cellspacing=0><tr height=2><td><tr><td width=20><td> + + There is more that could be done to ease the writing of complicated + clients.<br> + +</table> + +<td width=20> +<tr height=20><td> +</table> +<!-- TRAILER --> +<table border=0 cellpadding=0 cellspacing=0 width=100%> +<tr height=15><td width=10><td><td width=10> +<tr><td><td> +<center> +<a href="../../"><img src="../../dist/spaceglenda100.png" alt="Space Glenda" border=1></a> +</center> +</table> +<!-- TRAILER --> +</body></html> |