| <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> |
