docs/bin/hey.html

   1 <HTML>
   2 <HEAD>
   3
   4 <TITLE>hey Documentation</TITLE>
   5 </HEAD>
   6 <BODY BGCOLOR=#FFFFFF>
   7 <HR><CENTER><h1>hey version 1.2.8</h1>
   8 </CENTER>
   9 <HR>
  10 <BASEFONT size=4>
  11 <h2>What is hey?</h2>
  12 <CODE>hey</CODE> is a small public domain scripting utility which works with standard <FONT COLOR=#0000ff>B</FONT><FONT COLOR=#ff0000>e</FONT>OS scripting. It comes with source which you can modify as you wish. If you want your modification in the standard distribution, just drop me a line.
  13 Use it at your own risk.
  14 <p>
  15 <p>
  16 <br>
  17
  18 <h2>Installation</h2>
  19
  20 <UL>
  21 <LI>unzip the archive by doubleclicking on <CODE>hey-YYYYMMDD.zip</CODE> or by dropping it on Expander
  22 <LI>open the right project file depending on the hardware platform and select 'Make' from the 'Project' menu to compile it
  23 <LI>you may want to move the executable (<CODE>hey</CODE>) to <CODE>/boot/home/config/bin</CODE> </p>
  24 </ul>
  25 <p>
  26 <br>
  27
  28 <h2>Usage</h2>
  29 hey should be used from Terminal. When you start it without parameters it will display the command line syntax it accepts:
  30 <PRE><CODE>
  31 hey v1.2.8, written by Attila Mezei (attila.mezei@mail.datanet.hu)
  32 usage: hey [-s][-o] &lt;app|signature|teamid&gt; [let &lt;specifier&gt; do] &lt;verb&gt; &lt;specifier_1&gt; &lt;of
  33            &lt;specifier_n&gt;&gt;* [to &lt;value&gt;] [with name=&lt;value&gt; [and name=&lt;value&gt;]*]
  34 where  &lt;verb&gt; : DO|GET|SET|COUNT|CREATE|DELETE|GETSUITES|QUIT|SAVE|LOAD|'what'
  35   &lt;specifier&gt; : [the] &lt;property_name&gt; [ &lt;index&gt; | name | "name" | '"name"' ]
  36       &lt;index&gt; : int | -int | '['int']' | '['-int']' | '['startint to end']'
  37       &lt;value&gt; : "string" | &lt;integer&gt; | &lt;float&gt; | bool(value) | int8(value)
  38                 | int16(value) | int32(value) | float(value) | double(value)
  39                 | BPoint(x,y) | BRect(l,t,r,b) | rgb_color(r,g,b,a) | file(path)
  40 options: -s: silent
  41          -o: output result to stdout for easy parsing
  42
  43 </CODE></PRE>
  44 <br>
  45
  46 <h3>The verb</h3>
  47 The verbs send the following messages:
  48 <ul>
  49 <li>DO: B_EXECUTE_PROPERTY
  50 <li>GET: B_GET_PROPERTY
  51 <li>SET: B_SET_PROPERTY
  52 <li>COUNT: B_COUNT_PROPERTIES
  53 <li>CREATE: B_CREATE_PROPERTY
  54 <li>DELETE: B_DELETE_PROPERTY
  55 <li>GETSUITES: B_GET_SUPPORTED_SUITES
  56 <li>QUIT: B_QUIT_REQUESTED
  57 <li>SAVE: B_SAVE_REQUESTED
  58 <li>LOAD: B_REFS_RECEIVED
  59 </ul>
  60 You can use your own verbs if you specify the value names and constants in the 'value_info' structure. See <A HREF="http://www.haiku-os.org/legacy-docs/bebook/BPropertyInfo_Overview.html">BPropertyInfo</A> and <A HREF="file:///boot/develop/headers/be/app/PropertyInfo.h">PropertyInfo.h</A> for details.
  61 <p>
  62 Note that the verb is not case sensitive but the specifier names (e.g. "Frame", "Label"...) are. You can use 'what' constants
  63 directly, like
  64 <PRE><CODE>hey Application '_ABR'
  65 </CODE></PRE>
  66 will open the about window of the application.<p>
  67 LOAD and SAVE are actually not scripting commands, they are standard BeOS messages (B_REFS_RECEIVED and B_SAVE_REQUESTED). I included them for convenience. E.g. open a file in Application (the path can be relative or absolute):
  68 <PRE><CODE>hey Application load 'file(/boot/home/images/Be.jpg)'
  69 </CODE></PRE>
  70 or save it:
  71 <PRE><CODE>hey Application save Window "Be.jpg"
  72 </CODE></PRE>
  73
  74 <br>
  75
  76 <h3>The specifier</h3>
  77
  78 <p>The specifier can be direct, index, reverse index, range or named. Reverse range is
  79 not supported. If you enter an index which consists of only digits, you can omit the square
  80 brackets:
  81 <PRE><CODE>hey Application get Window 0
  82 </CODE></PRE>
  83
  84 <br>
  85 <h3>The value</h3>
  86
  87 It is easy to use the type names in front of the value but beware that the shell will throw a syntax error if you do this:
  88 <PRE><CODE>hey Application set .... to BPoint(100,100)
  89 </CODE></PRE>
  90 Instead use square brackets or quotes:
  91 <PRE><CODE>hey Application set .... to BPoint[100,100]
  92 hey Application set .... to 'BPoint(100,100)'
  93 </CODE></PRE>
  94
  95 If the value string contains only digits, it will be considered an int32. If it contains digits and a dot,
  96 a float type is assumed. "true" or "false" can also be used as bools.
  97
  98 <p>
  99 <br>
 100 <h2>DEBUG mode</h2>
 101 You can check the message to be sent to the application by setting the DEBUG_HEY preprocessor symbol to 1, and recompiling.<p>
 102 <br>
 103
 104 <h2>History</h2>
 105 v1.2.8
 106 <ul>
 107 <li>
 108                 (Sander Stoks): Added command-line option -o which will output the "result" value
 109                 in the reply message to stdout, so you can use it in shell scripting more easily:
 110                 "hey Becasso get AspectRatio of Canvas 0"
 111                 outputs
 112                 Reply BMessage(B_REPLY):
 113                    "result" (B_DOUBLE_TYPE) : 0.600
 114                 but "hey -o Becasso get AspectRatio of Canvas 0"
 115                 outputs 0.600000 directly.
 116 </ul>
 117 v1.2.7
 118 <ul>
 119 <li>
 120                 by Sander Stoks: Made a fork since I don't think Attila still supports "hey", and
 121                 because the latest version on BeBits seems to be 1.2.4.
 122                 Changes w.r.t. 1.2.6: When an application returns an error on a message, hey now
 123                 keeps iterating over applications with the same signature.  This is useful because,
 124                 for instance, Terminal starts as a new process for each instance, so it previously
 125                 wouldn't work to move a specific Terminal window using hey.  You can now say
 126                 "hey Terminal set Frame of Window foo to BRect[...]".
 127 </ul>
 128 v1.2.6
 129 <ul>
 130 <li>syntax extended by Sander Stoks <sander@adamation.com> to allow:
 131                 "hey Application let Specifier do ..."
 132                 allowing you to send messages directly to other handlers than the app itself.
 133                 In cooperation with the new Application defined commands (note that some
 134                 Be classes, e.g. BWindow, publish commands as well) this allows, for example:
 135                 "hey NetPositive let Window 0 do MoveBy BPoint[10,10]"
 136                 Note that this is partly redundant, since
 137                 "hey NetPositive let Window 0 do get Title"
 138                 duplicates "hey NetPositive get Title of Window 0"
 139                 But with the old system,
 140                 "hey NetPositive MoveBy of Window 0 with data=BPoint[10,10]"
 141                 couldn't work ("MoveBy" is not defined by the Application itself).
 142 </ul>
 143 v1.2.5
 144 <ul>
 145 <li>'value_info' is supported in BPropertyInfo. This means when you send GETSUITES (B_GET_SUPPORTED_SUITES) the value info is printed after the property infos (name, kind, value, usage).<br>
 146 You can also use application defined commands (as the verb) with hey:<br>
 147                 hey MyBackupApp Backup "Maui"<br>
 148 </ul>
 149 v1.2.4
 150 <ul>
 151 <li>The syntax is extended by <a href="mailto:pfolk@uni.uiuc.edu">Peter Folk</a>
 152     to contain:
 153       <br><code>do the x of y -3 of z '"1"'</code><br>
 154     I.e. "do" =&gt; B_EXECUTE_PROPERTY, optional "the" makes direct specifiers
 155     more like english, bare reverse-index-specifiers are now handled, and
 156     named specifiers can contain only digits by quoting it (but make sure the
 157     shell passes the quotes through).
 158
 159 <li>Hey(target,const char*,reply) was previously limited to 100 tokens.
 160     It now uses a vector<> so it's only limited by available memory.
 161
 162 <li>Also, the archive name is now Y2K compliant =)
 163 </ul>
 164 v1.2.3
 165 <ul>
 166 <li>new option: -s for silent processing (no reply or errors printed) AM
 167 </ul>
 168 v1.2.2
 169 <ul>
 170 <li>Fixes by Marco Nelissen (marcone@xs4all.nl):<br>
 171 <li>fixed parsing of negative numbers
 172 <li>fixed "with" syntax, which was broken (after a create, "with" would be taken as a specifier)
 173 </ul>
 174 v1.2.1
 175 <ul>
 176 <li>compiled for R4 with minor modifications of BPropertyInfo usage
 177 </ul>
 178 v1.2.0
 179 <ul>
 180 <li>the syntax is extended by Sander Stoks (sander@adamation.com) to contain<br>
 181                 with name=<value> [and name=<value> [...]]<br>
 182                 at the end of the command which will add additional data to the scripting message. E.g:<br>
 183                 hey Becasso create Canvas with name=MyCanvas and size=BRect(100,100,300,300)<br>
 184                 Also a small interpreter is included.
 185
 186 <li>            Detailed printout of B_PROPERTY_INFO in BMessages. Better than BPropertyInfo::PrintToStream().
 187                 Also prints usage info for a property if defined.
 188 </ul>
 189 v1.1.1
 190 <ul>
 191 <li>minor change from chrish@qnx.com to return -1 if an error is
 192                 sent back in the reply message; also added B_COUNT_PROPERTIES support
 193
 194 <li>            The range specifier sent to the target was 1 greater than it should've been. Fixed.
 195
 196 <li>            'hey' made the assumption that the first thread in a team will be the
 197                 application thread (and therefore have the application's name).
 198                 This was not always the case. Fix from Scott Lindsey (wombat@gobe.com).
 199 </ul>
 200 v1.1.0
 201 <ul>
 202 <li>flattened BPropertyInfo is printed if found in the reply of B_GET_SUPPORTED_SUITES
 203 <li>1,2,3 and 4 character message constant is supported (e.g. '1', '12', '123', '1234')
 204 <li>alpha is sent with rgb_color
 205 </ul>
 206 v1.0.0
 207 <ul>
 208 <li>First public release
 209 </ul>
 210
 211 <p>
 212 <br>
 213 <h2>Examples</h2>
 214
 215 For these examples you need to start the Network preferences application
 216 (the classic way to demo scripting ;-)
 217
 218
 219 <h3>Get the messenger of an application (not useful if you use 'hey'):</h3>
 220 <PRE><CODE>     hey Network get Messenger
 221 </CODE></PRE>
 222
 223 <h3>Get the suite of messages which the application can handle:</h3>
 224 <PRE><CODE>     hey Network getsuites
 225 </CODE></PRE>
 226 <ul>            (BApplication & BHandler suites printed)
 227 </ul>
 228 <h3>Get the name of the application</h3>
 229 <PRE><CODE>     hey Network get Name
 230 </CODE></PRE>
 231 <h3>Open the about window of the application</h3>
 232 <PRE><CODE>     hey Network '_ABR'
 233 </CODE></PRE>
 234 <h3>Get a window of the application (actually a messenger for the window)</h3>
 235 <PRE><CODE>     hey Network get Window [0]
 236 </CODE></PRE><ul>               or you can omit the square brackets when using an index:</ul>
 237 <PRE><CODE>     hey Network get Window 0
 238 </CODE></PRE><ul>               or you can specify a window name (with or without quotes):</ul>
 239 <PRE><CODE>     hey Network get Window "Network"
 240 </CODE></PRE>
 241 <h3>Get the suite of messages which the window can handle:</h3>
 242 <PRE><CODE>     hey Network getsuites of Window "Network"
 243 </CODE></PRE><ul>               (for the description of suite/vnd.Be-window see the BeBook)</ul>
 244
 245 <h3>Get the title, frame or other properties of the window:</h3>
 246 <PRE><CODE>     hey Network get Title of Window "Network"
 247         hey Network get Frame of Window "Network"
 248 </CODE></PRE>
 249 <h3>Set the title, frame or other properties of the window:</h3>
 250 <PRE><CODE>     hey Network set Title of Window "Network" to "hey is great"
 251         hey Network set Frame of Window "Network" to 'BRect(0,0,300,300)'
 252 </CODE></PRE><ul>               or you can use square brackets to avoid the 's:</ul>
 253 <PRE><CODE>     hey Network set Frame of Window "Network" to BRect[0,0,300,300]
 254 </CODE></PRE>
 255 <h3>Get a view from the window (actually a messenger for the view)</h3>
 256 <PRE><CODE>     hey Network get View 0 of Window "Network"
 257 </CODE></PRE>
 258 <h3>Get the suite of messages which the view can handle:</h3>
 259 <PRE><CODE>     hey Network getsuites of View 0 of Window "Network"
 260 </CODE></PRE><ul>               (for a description of suite/vnd.Be-view see the BeBook)</ul>
 261
 262 <h3>Get a view property:</h3>
 263 <PRE><CODE>     hey Network get Frame of View 0 of Window "Network"
 264         hey Network get Hidden of View 0 of View 0 of Window "Network"
 265         hey Network get Label of View 5 of View 0 of Window "Network"
 266         hey Network get Value of View 0 of View 2 of View 0 of Window "Network"
 267         hey Network get Text of View 2 of View 2 of View 0 of Window "Network"
 268 </CODE></PRE>
 269 <h3>Set a view property:</h3>
 270 <PRE><CODE>     hey Network set Frame of View 0 of Window "Network" to 'BRect(0,0,100,400)'
 271         hey Network set Hidden of View 0 of View 0 of Window "Network" to true
 272         hey Network set Label of View 5 of View 0 of Window "Network" to "Restart Something"
 273         hey Network set Value of View 0 of View 2 of View 0 of Window "Network" to 1
 274         hey Network set Text of View 2 of View 2 of View 0 of Window "Network" to "joe"
 275 </CODE></PRE>
 276 <h3>Close a window in an application</h3>
 277 <PRE><CODE>     hey Network quit Window "Network"
 278 </CODE></PRE>
 279 <h3>Quit an application</h3>
 280 <PRE><CODE>     hey Network quit
 281 </CODE></PRE>
 282 </BODY>
 283 </HTML>