1 <?xml version="1.0" encoding="UTF-8"?>
2 <?xml-stylesheet type="text/xsl" href="dactyl://content/help.xsl"?>
4 <!DOCTYPE document SYSTEM "dactyl://content/dtd">
8 title="&dactyl.appName; Repeating Commands"
10 xmlns:html="&xmlns.html;">
12 <h1 tag="repeating">Repeating commands</h1>
16 &dactyl.appName; can repeat commands in a number of ways, from repeating
17 the last command, to recording and playing macros, to saving its state and
21 <h2 tag="single-repeat">Single repeats</h2>
24 <tags><repeat-key> .</tags>
26 <spec><oa>count</oa>.</spec>
29 Repeat the last keyboard mapping <oa>count</oa> times. Note that,
30 unlike in Vim, this also applies to other than editing commands.
38 <spec><oa>count</oa>@:</spec>
40 <p>Repeat the last Ex command <oa>count</oa> times.</p>
44 <h2 tag="macros complex-repeat">Macros</h2>
47 <tags><record-macro> q</tags>
49 <spec>q<a>0-9a-zA-Z</a></spec>
52 Record a key sequence as a macro. Available macros are
53 <a>0-9a-zA-Z</a>. If the macro is an uppercase letter, the
54 recorded keys are appended to the lowercase macro of the same
55 name. Typing <k>q</k> again stops the recording.
62 <spec>:mac<oa>ros</oa> <oa>pat</oa></spec>
65 List recorded macros matching the optional regular expression
66 <oa>pat</oa>. If no regexp is given, list all macros.
72 <tags>:delmac :delmacros</tags>
73 <spec>:delmac<oa>ros</oa> <a>pat</a></spec>
74 <spec>:delmac<oa>ros</oa>!</spec>
77 Delete recorded macros matching the regular expression
78 <a>pat</a>. If <em>!</em> is given, all macros are deleted.
84 <tags><play-macro> @</tags>
85 <spec><oa>count</oa>@<a>a-z0-9</a></spec>
88 Plays the contents of macro with name <a>a-z0-9</a> <oa>count</oa>
96 <spec><oa>count</oa>@@</spec>
97 <description short="true">
98 <p>Replay the last executed macro <oa>count</oa> times.</p>
102 <h2 tag="macro-utilities">Macro utilities</h2>
105 The following key bindings facilitate the recording of efficient
106 macros. They have no effect when typed normally, but are
107 recorded and take effect during macro playback.
111 <tags><![CDATA[<sleep> <A-m>s]]></tags>
112 <spec><a>count</a><![CDATA[<A-m>s]]></spec>
113 <description short="true">
115 Sleep for <a>count</a> milliseconds before resuming playback.
121 <tags><![CDATA[<wait-for-page-load> <A-m>l]]></tags>
123 <spec><oa>count</oa><![CDATA[<A-m>l]]></spec>
126 Wait for the current page to finish loading before resuming
127 playback. If <oa>count</oa> is given, wait no more than
128 <oa>count</oa> seconds. Otherwise wait no more than 25 seconds.
134 <h2 tag="group groups">Groups</h2>
137 In order to facilitate script writing, especially scripts which only
138 apply to certain web sites, many types of commands and mappings can
139 be assigned to a named group. In addition to helping identify the
140 source of such mappings in listings, and aiding in the cleanup of
141 scripts, these groups can be configured to apply only to certain web
146 <tags>:gr :group</tags>
147 <spec>:gr<oa>oup</oa></spec>
149 <p>List all active <t>groups</t>.</p>
154 <spec>:gr<oa>oup</oa><oa>!</oa> <a>group</a> …</spec>
157 Select, create, or modify a <t>group</t>. After invocation,
158 <a>group</a> becomes the default group for all further commands
159 issued in the current script. If <oa>!</oa> is given the group is
160 cleared of all mappings, commands, and any other entries bound to
161 it before making the specified additions (if any).
164 <p>The following <a>group</a> names have special meanings:</p>
167 <dt>builtin</dt> <dd>The default group for builtin items. Can not be modified in any way by scripts.</dd>
168 <dt>default</dt> <dd>The default group for the script containing this <tt>:group</tt> command.</dd>
169 <dt>user</dt> <dd>The default group for the command line and <t>&dactyl.name;rc</t>.</dd>
172 <p>The following arguments are available:</p>
175 <dt>-args=<a>javascript</a></dt> <dd>JavaScript Object which
176 augments the arguments passed to commands, mappings, and
177 autocommands, e.g., given <str delim="">{ foo: "bar" }</str>,
178 <tt>foo</tt> (<tt><foo></tt> if the Ex syntax is used) will
179 be replaced by <str delim="">bar</str> inside the definitions
180 (short name: <em>-a</em>)</dd>
181 <dt>-description</dt> <dd>A description of this group (short names: <em>-desc</em>, <em>-d</em>)</dd>
182 <dt>-locations=<a>filters</a></dt> <dd>The URLs for which this
183 group should be active. See <t>site-filters</t> (short names:
184 <em>-locs</em>, <em>-loc</em>, <em>-l</em>)</dd>
185 <dt>-nopersist</dt> <dd>Do not save this group to an auto-generated RC file (short name: <em>-n</em>)</dd>
191 <tags>:delgr :delgroup</tags>
192 <spec>:delgr<oa>oup</oa> <a>group</a></spec>
193 <spec>:delgr<oa>oup</oa>!</spec>
196 Delete the specified <a>group</a>. With <oa>!</oa> delete all
202 <h2 tag="site-filter site-filters">Site Filters</h2>
205 Many &dactyl.appName; commands accept filters so that they may be applied
206 only to specific sites. Most of these commands accept filters in any of the
213 Any filter which is a valid domain name will match any site on that
214 domain or any sub-domain thereof. These filters may contain any letter
215 of the Roman alphabet, Arabic numerals, hyphens, and full stops.
216 Non-Latin domain names must be punycode encoded.
221 Any URL beginning with a valid protocol name and ending with a
222 <tt>*</tt> is treated as a URL prefix. It will match any URL which
223 begins with the given filter sans the trailing asterisk.
228 Any URL beginning with a valid protocol name and not ending with an
229 asterisk is treated as a full URL match. It will match any page which
230 has a URL identical to the filter.
233 <dt>Regular expression</dt>
235 Any filter which does not fall into one of the above categories is
236 treated as a case-sensitive regular expression.
241 In most cases, any of the above may be prefixed with a <tt>!</tt> character
242 to exclude matching sites.
245 <h2 tag="using-scripts">Using scripts</h2>
248 <tags>:so :source</tags>
249 <spec>:so<oa>urce</oa><oa>!</oa> <a>file</a></spec>
252 Read Ex commands, JavaScript, or CSS from <a>file</a>. Files are
253 interpreted based on their extensions. Files which end in
254 <em>.js</em> are executed as JavaScript, while those ending in
255 <em>.css</em> are loaded as Cascading Stylesheets, and anything
256 else is interpreted as Ex commands. In normal cases, any errors
257 generated by the execution or non-existence of <a>file</a> are
258 printed to the <t>command-line</t> area. When <oa>!</oa> is
259 provided, these are suppressed.
263 Environment variables in <a>file</a> are expanded to their current
264 value, and the prefix <em>~</em> is replaced with the value of
265 <em>$HOME</em>. See <t>expand-env</t> and <t>initialization</t>
266 for more information.
269 <h3 tag=":source-contexts">Script Contexts</h3>
272 Each script executes in its own JavaScript context. This means that
273 any global variable or function, including those defined by
274 <ex>:javascript</ex> and the <tt>-javascript</tt> flag of
275 <ex>:map</ex>, <ex>:command</ex>, and <ex>:autocmd</ex>,
276 is directly available only within the current script. Outside of the
277 current script, they can only be accessed as properties of the
278 script's global object, which is stored in the <tt>plugins</tt>
279 global under the script's full path.
282 <h3 tag=":source-groups">Script Groups</h3>
285 In addition to its own JavaScript context, each script is executed
286 with its own default <link topic="groups">group</link> into which
287 its styles, mappings, commands, abbreviations and autocommands are
288 placed. This means that commands such as <ex>:delcommand!</ex> can
289 be issued without fear of trampling other user-defined mappings.
290 The command <ex>:group! default</ex> can be issued to clear all
291 such items at once, and should be placed at the head of most
292 scripts to prevent the accumulation of stale items when the script
296 <h3 tag=":source-css">Cascading Stylesheets</h3>
299 When a CSS file is sourced, its contents are applied to every web
300 page and every chrome document, including all browser windows and
301 dialogs. If the same file is sourced more than once, its previous
302 rules are cleared before it is applied again. Rules can be
303 restricted to specific documents by enclosing them in
304 <link topic="https://developer.mozilla.org/en/CSS/@-moz-document">@-moz-document</link>
308 <h3 tag=":source-javascript">JavaScript</h3>
311 JavaScript files are executed with full chrome privileges in their
312 own global namespaces. These namespaces are stored as objects in
313 the <em>plugins</em> object, in the property named after the full
314 path of the sourced file. This means that any variables or
315 functions created by your script are stored as properties of that
316 object. Additionally, all properties of the global <em>window</em>
317 and <em>modules</em> objects are accessible to your script as
322 Files in <em>~/.&dactyl.name;/plugins</em> may additionally be
323 accessed in <em>plugins.<a>filename</a></em> where <a>filename</a>
324 is the last component of the file's path stripped of any
325 extensions, with all hyphens stripped and any letter following a
326 hyphen capitalized. So, the file
327 <em>~/.&dactyl.name;/plugins/foo-bar.js</em> may be accessed as
328 <em>plugins.fooBar</em>. See also <t>writing-plugins</t>.
331 <h3 tag=":source-ex">Ex commands</h3>
334 Ex command files are executed as if each line were entered into
335 the &tag.command-line; individually.
336 Additionally, certain commands support the same ‘here document’
337 syntax supported by most Unix shells and by the &tag.command-line;.
338 So, to execute a JavaScript statement which does not comfortably fit
339 on a single line, you can use:
342 <code><ex>:js</ex> <<<em>EOF</em>
343 <kwd><hl key="Object">var</hl></kwd> hello = <kwd>function</kwd> () {
344 alert(<str>Hello world</str>);
348 <p>See also <t>ex-scripts</t> below.</p>
354 <tags>:lpl :loadplugins</tags>
356 <spec>:loadplugins[!] <oa>pattern</oa> …</spec>
359 Immediately load all plugins which have yet to be loaded. Because
360 plugins are not automatically loaded until after <tt><t>&dactyl.name;rc</t></tt>
361 is sourced, this command must be placed early in the
362 <tt>&dactyl.name;rc</tt> file if <tt>&dactyl.name;rc</tt> uses commands or options
363 which are defined by plugins. Additionally, this command allows
364 newly installed plugins to be easily loaded without restarting
365 &dactyl.appName;. See also <o>loadplugins</o>.
368 If <oa>pattern</oa>s are provided, the given regular expressions are
369 used as filters rather than those in <o>loadplugins</o>.
372 If <oa>!</oa> is given the plugins are forcibly loaded.
378 <tags>:runt :runtime</tags>
379 <spec>:runt<oa>ime</oa><oa>!</oa> <a>file</a> …</spec>
382 Source the specified file from the first directory in
383 <o>runtimepath</o> in which it exists. When <oa>!</oa> is given,
384 source the file from all directories in <o>runtimepath</o> in
387 <example><ex>:runtime plugins/foobar.js</ex></example>
392 <tags>:scrip :scriptnames</tags>
393 <spec>:scrip<oa>tnames</oa></spec>
395 <p>List all sourced script names, in the order they were first sourced.</p>
400 <tags>:fini :finish</tags>
402 <spec>:fini<oa>sh</oa></spec>
405 Stop sourcing a script file. This can only be called from within a
406 &dactyl.appName; script file.
411 <h3 tag="ex-scripts">Ex Command Scripts</h3>
414 Ex command scripts are similar to both entering commands on the
415 &tag.command-line; and to Vim
416 scripts, but with some notable differences.
419 <p tag="multiline-commands">
420 Commands in Ex command scripts can span multiple lines by
421 prefixing the second and further lines with a <em>\</em>
422 character. For instance, the following all define commands whose
423 definitions span multiple lines.
426 <code><ex>:command!</ex> <str delim="">foo</str>
427 \ <em>-description</em> <str>A command that frobs bars</str>
428 \ <ex>:javascript</ex> frob(content.bar)</code>
430 <code><ex>:style</ex> <em>-name</em> <str delim="'">foo</str>
431 \ <str delim="'">foobar.com</str>
432 \ p<str delim="">:first-line</str> { <em>font-variant</em>: <str delim="">small-caps</str>; }
433 \ div<em>#side-bar</em> > <str delim="">:first-child</str> { <em>display</em>: <str delim="">none</str>; }</code>
435 <code><ex>:command!</ex> <str delim="">do-some-stuff</str>
436 \ <em>-description</em> <str>A command which does some stuff in JavaScript</str>
437 \ <ex>:javascript</ex> <<<em>EOF</em>
438 \ window.do(<str>some</str>);
439 \ window.do(<str>stuff</str>);
442 <code><ex>:command!</ex> <str delim="">do-some-stuff</str>
443 \ <em>-description</em> <str>A command which does some stuff in JavaScript</str>
444 \ <ex>:javascript</ex>
445 \\ window.do(<str>some</str>);
446 \\ window.do(<str>stuff</str>);</code>
449 Lines may be commented out by prefixing them with a <em>"</em>
450 character. Comments and commands cannot both occur in a single command
454 <code> <hl style="color: #444">" This is a comment</hl>
455 foo bar " This is a syntax error
456 <str> This is not a comment</str>
457 foo bar <str> This is not a comment</str>
460 <h2 tag="profile profiling">Profiling</h2>
464 <spec>:<oa>count</oa>time<oa>!</oa> <a>code|:command</a></spec>
467 Profile a piece of JavaScript code or an Ex command. Run
468 <a>code</a> <oa>count</oa> times and print the elapsed time.
469 If <a>code</a> begins with a <ex>:</ex>, it is executed as an Ex
470 command. Otherwise, it is executed as JavaScript, in which case it
471 is evaluated only once and stored as a function which is executed
472 <oa>count</oa> times.
476 When <oa>!</oa> is given, <a>code</a> is executed <oa>count</oa>
477 times, but no statistics are printed.
484 <!-- vim:se sts=4 sw=4 et: -->