common/locale/en-US/eval.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
   3
   4 <!DOCTYPE document SYSTEM "dactyl://content/dtd">
   5
   6 <document
   7     name="eval"
   8     title="&dactyl.appName; Expression Evaluation"
   9     xmlns="&xmlns.dactyl;"
  10     xmlns:html="&xmlns.html;">
  11
  12 <h1 tag="expression expr eval javascript">Expression evaluation</h1>
  13 <toc start="2"/>
  14
  15 <p>
  16     Much of the power of &dactyl.appName; lies in its scriptable expression
  17     evaluation. &dactyl.appName; understands two kinds of expressions: Ex
  18     commands, and JavaScript. Ex commands are simple, easy to type, and
  19     readily accessible from the &tag.command-line;.
  20     They form a core part of the user interface. JavaScript, on the other hand,
  21     is much less straightforward, but allows for any number of complex actions
  22     to be executed, with full access to all of the internals of &dactyl.appName;
  23     and &dactyl.host;. Both expression evaluation methods support sophisticated
  24     expression completion, including option lists and descriptions thereof,
  25     along with parentheses matching and syntax error highlighting.
  26 </p>
  27
  28 <h2 tag="javascript-evaluation">JavaScript evaluation</h2>
  29
  30 <item>
  31     <tags>:ec :echo</tags>
  32     <spec>:ec<oa>ho</oa> <a>expr</a></spec>
  33     <description>
  34         <p>
  35             Echo a JavaScript expression. <a>expr</a> may be a simple quoted
  36             string, in which case it is shown in the &tag.status-line;, or any
  37             arbitrary JavaScript expression. If the expression results in
  38             anything other than a string, it is pretty-printed in a multi-line
  39             frame just above the command line. The output depends on the type
  40             of object. Functions display their source, DOM nodes display the
  41             pretty-printed XML of the top-level node, XML literals are
  42             rendered as page content, and all other objects display their
  43             string representation and all of their enumerable properties.
  44         </p>
  45
  46         <p>See also <ex>:javascript</ex>.</p>
  47     </description>
  48 </item>
  49
  50 <item>
  51     <tags>:echoe :echoerr</tags>
  52     <spec>:echoe<oa>rr</oa> <a>expr</a></spec>
  53     <description>
  54         <p>
  55             Echo the expression as an error message. Just like <ex>:ec<oa>ho</oa></ex> but echoes
  56             the result highlighted as with the ErrorMsg group and saves it to the message history.
  57         </p>
  58     </description>
  59 </item>
  60
  61 <item>
  62     <tags>:echom :echomsg</tags>
  63     <spec>:echom<oa>sg</oa> <a>expr</a></spec>
  64     <description>
  65         <p>
  66             Echo the expression as an informational message. Just like <ex>:ec<oa>ho</oa></ex> but
  67             also saves the message in the message history.
  68         </p>
  69     </description>
  70 </item>
  71
  72 <item>
  73     <tags>:exe :execute</tags>
  74     <spec>:exe<oa>cute</oa> <a>expr</a></spec>
  75     <description>
  76         <p>
  77             Execute the Ex command string that results from the evaluation of
  78             the JavaScript expression <a>expr</a>. For example,
  79         </p>
  80         <code><ex>:execute <str>open </str> + content.location.host</ex></code>
  81         <p>
  82             opens the homepage of the currently opened site.
  83         </p>
  84
  85         <note>Unlike Vim this only supports a single argument.</note>
  86     </description>
  87 </item>
  88
  89 <item>
  90     <tags>:js :javas :javascript</tags>
  91     <spec>:javas<oa>cript</oa> <a>cmd</a></spec>
  92     <spec style="white-space: pre; height: 1.6em; overflow: visible;">:javascript &lt;&lt;<a>endpattern</a>
  93   <a>cmd</a>
  94   …
  95 <a>endpattern</a></spec>
  96     <description>
  97         <p>
  98             Evaluates the given <a>cmd</a> as JavaScript. Behaves exactly as
  99             <ex>:echo</ex>, except that the result is not printed. Any
 100             exception raised by the evaluation will, however, be displayed as
 101             an error message and appended to <ex>:messages</ex>.
 102         </p>
 103
 104         <example>
 105             <ex>:javascript alert(<str>Hello world</str>)</ex> will open a
 106             dialog window with the message <str>Hello world</str>.
 107         </example>
 108
 109         <p>
 110             Moreover, multi-line scripts can be executed with shell-like here
 111             document syntax. For example, the following,
 112         </p>
 113
 114         <code><ex>:javascript</ex> &lt;&lt;<em>EOF</em>
 115 <kwd>for each</kwd> (<kwd>var</kwd> tab <kwd>in</kwd> tabs.visibleTabs)
 116     tab.linkedBrowser.reload();
 117 <em>EOF</em></code>
 118
 119         <p>
 120             will reload all visible tabs.
 121         </p>
 122
 123         <p>
 124             Moreover, sophisticated, context-sensitive <k name="Tab" mode="c"/>
 125             completion is available for JavaScript code, which extends to
 126             property names, object keys, and programmable completion for
 127             string function arguments. The completion code is designed to be
 128             both as safe and as powerful as possible. Expressions in a given
 129             command-line session will only be evaluated once, and, with
 130             auto-completion turned on, any completion which requires a function
 131             to be executed requires an explicit <k name="Tab" mode="c"/> press
 132             to commence.
 133         </p>
 134     </description>
 135 </item>
 136
 137 <item>
 138     <tags>REPL</tags>
 139     <spec>:js! <oa>context</oa></spec>
 140     <tags>:js! :javas! :javascript!</tags>
 141     <spec>:javas<oa>cript</oa>! <oa>context</oa></spec>
 142     <description>
 143         <p>
 144             Starts the JavaScript Read Eval Print Loop, where JavaScript
 145             statements are entered and evaluated, their results printed, and the
 146             input modified and entered again. Within the REPL, the results of a
 147             given evaluation are available as variables named for the given
 148             prompt.
 149         </p>
 150
 151         <p>
 152             If <oa>context</oa> is given, then statements are executed in that
 153             global context.
 154         </p>
 155
 156         <example><code><hl key="REPL"
 157 ><hl key="REPL-E"><hl key="REPL-R">js1></hl> ({ <hl key="Key">foo</hl>: <str>bar</str> })</hl
 158 ><hl key="REPL-P" style="display: block;"><hl key="Title Object">[object Object]</hl>::
 159 <hl key="Key">foo</hl>: <hl key="String">"bar"</hl></hl
 160 ><hl key="REPL-E"><hl key="REPL-R">js2></hl> js1.foo</hl
 161 ><hl key="REPL-P" style="display: block;"><str>bar</str></hl></hl></code></example>
 162     </description>
 163 </item>
 164
 165 <h2 tag="global-variables">Global Variables</h2>
 166
 167 <item>
 168     <tags>:let</tags>
 169     <spec>:let <a>var-name</a> [+-.]= <a>expr1</a></spec>
 170     <spec>:let <a>var-name</a></spec>
 171     <spec>:let</spec>
 172     <description>
 173         <deprecated>All scripts which make use of <ex>:let</ex> should be
 174             updated to use the simpler and more powerful options system
 175             instead.</deprecated>
 176         <p>
 177             Sets or lists a variable. Sets the variable <a>var-name</a> to the value of the
 178             expression <a>expr1</a>. If no expression is given, the value of the variable is
 179             displayed. Without arguments, displays a list of all variables.
 180             This functionality has few useful applications and so is deprecated.
 181         </p>
 182     </description>
 183 </item>
 184
 185 <item>
 186     <tags>:unl :unlet</tags>
 187     <spec>:unl<oa>et</oa><oa>!</oa> <a>name</a> …</spec>
 188     <description>
 189         <deprecated>All scripts which make use of <ex>:unlet</ex> should be
 190             updated to use the simpler and more powerful options system
 191             instead.</deprecated>
 192         <p>
 193             Deletes the named variables. When <oa>!</oa> is given, no error
 194             message is output for non-existing variables.
 195         </p>
 196     </description>
 197 </item>
 198
 199 <h2 tag="conditionals">Conditionals</h2>
 200
 201 <item>
 202     <tags>:if</tags>
 203     <strut/>
 204     <spec>:if <a>expr</a></spec>
 205     <description>
 206         <p>
 207             Execute commands until the next <ex>:elseif</ex>, <ex>:else</ex>,
 208             or <ex>:endif</ex> only if the JavaScript expression <a>expr</a>
 209             evaluates to a true value.
 210         </p>
 211     </description>
 212 </item>
 213
 214 <item>
 215     <tags>:endif :en :fi</tags>
 216     <spec>:en<oa>dif</oa></spec>
 217     <description short="true">
 218         <p>
 219             Ends a string of <ex>:if</ex>/<ex>:elseif</ex>/<ex>:else</ex>
 220             conditionals.
 221         </p>
 222     </description>
 223 </item>
 224
 225 <item>
 226     <tags>:elseif :elsei :elif</tags>
 227     <spec>:elsei<oa>f</oa> <a>expr</a></spec>
 228     <description>
 229         <p>
 230             Execute commands until the next <ex>:elseif</ex>, <ex>:else</ex>,
 231             or <ex>:endif</ex> only if the JavaScript expression <a>expr</a>
 232             evaluates to a true value.
 233         </p>
 234     </description>
 235 </item>
 236
 237 <item>
 238     <tags>:else :el</tags>
 239     <strut/>
 240     <spec>:el<oa>se</oa></spec>
 241     <description>
 242         <p>
 243             Execute commands until the next <ex>:endif</ex> only if the
 244             previous conditionals were not executed.
 245         </p>
 246     </description>
 247 </item>
 248
 249 </document>
 250
 251 <!-- vim:se sts=4 sw=4 et: -->