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 does not apply solely to editing commands,
31 mainly because &dactyl.appName; doesn't have them.
39 <spec><oa>count</oa>@:</spec>
41 <p>Repeat the last Ex command <oa>count</oa> times.</p>
45 <h2 tag="macros complex-repeat">Macros</h2>
48 <tags><record-macro> q</tags>
50 <spec>q<a>0-9a-zA-Z</a></spec>
53 Record a key sequence as a macro. Available macros are
54 <a>0-9a-zA-Z</a>. If the macro is an uppercase letter, the
55 recorded keys are appended to the lowercase macro of the same
56 name. Typing <k>q</k> again stops the recording.
63 <spec>:mac<oa>ros</oa> <oa>pat</oa></spec>
66 List recorded macros matching the optional regular expression
67 <oa>pat</oa>. If no regexp is given, list all macros.
73 <tags>:delmac :delmacros</tags>
74 <spec>:delmac<oa>ros</oa> <a>pat</a></spec>
75 <spec>:delmac<oa>ros</oa>!</spec>
78 Delete recorded macros matching the regular expression
79 <a>pat</a>. If <em>!</em> is given, all macros are deleted.
85 <tags><play-macro> @</tags>
86 <spec><oa>count</oa>@<a>a-z0-9</a></spec>
89 Plays the contents of macro with name <a>a-z0-9</a> <oa>count</oa>
97 <spec><oa>count</oa>@@</spec>
98 <description short="true">
99 <p>Replay the last executed macro <oa>count</oa> times.</p>
103 <h2 tag="macro-utilities">Macro utilities</h2>
106 The following key bindings facilitate the recording of efficient
107 macros. They have no effect when typed normally, but are
108 recorded and take effect during macro playback.
112 <tags><![CDATA[<sleep> <A-m>s]]></tags>
113 <spec><a>count</a><![CDATA[<A-m>s]]></spec>
114 <description short="true">
116 Sleep for <a>count</a> milliseconds before resuming playback.
122 <tags><![CDATA[<wait-for-page-load> <A-m>l]]></tags>
124 <spec><oa>count</oa><![CDATA[<A-m>l]]></spec>
127 Wait for the current page to finish loading before resuming
128 playback. If <oa>count</oa> is given, wait no more than
129 <oa>count</oa> seconds. Otherwise wait no more than 25 seconds.
135 <h2 tag="group groups">Groups</h2>
138 In order to facilitate script writing, especially scripts which only
139 apply to certain web sites, many types of commands and mappings can
140 be assigned to a named group. In addition to helping identify the
141 source of such mappings in listings, and aiding in the cleanup of
142 scripts, these groups can be configured to apply only to certain web
147 <tags>:gr :group</tags>
148 <spec>:gr<oa>oup</oa></spec>
150 <p>List all active <t>groups</t>.</p>
155 <spec>:gr<oa>oup</oa><oa>!</oa> <a>group</a> …</spec>
158 Select, create, or modify a <t>group</t>. After invocation,
159 <a>group</a> becomes the default group for all further commands
160 issued in the current script. If <oa>!</oa> is given the group is
161 cleared of all mappings, commands, and any other entries bound to
162 it before making the specified additions (if any).
165 <p>The following <a>group</a> names have special meanings:</p>
168 <dt>builtin</dt> <dd>The default group for builtin items. Can not be modified in any way by scripts.</dd>
169 <dt>default</dt> <dd>The default group for this script.</dd>
170 <dt>user</dt> <dd>The default group for the command line and <t>&dactyl.name;rc</t>.</dd>
173 <p>The following arguments are available:</p>
176 <dt>-args=<a>javascript</a></dt> <dd>JavaScript Object which
177 augments the arguments passed to commands, mappings, and
178 autocommands, e.g., given <str delim="">{ foo: "bar" }</str>,
179 <tt>foo</tt> (<tt><foo></tt> if the Ex syntax is used) will
180 be replaced by <str delim="">bar</str> inside the definitions
181 (short name: <em>-a</em>)</dd>
182 <dt>-description</dt> <dd>A description of this group (short names: <em>-desc</em>, <em>-d</em>)</dd>
183 <dt>-locations=<a>filters</a></dt> <dd>The URLs for which this
184 group should be active. See <t>site-filters</t> (short names:
185 <em>-locs</em>, <em>-loc</em>, <em>-l</em>)</dd>
186 <dt>-nopersist</dt> <dd>Do not save this group to an auto-generated RC file (short name: <em>-n</em>)</dd>
192 <h2 tag="site-filter site-filters">Site Filters</h2>
195 Many &dactyl.appName; commands accept filters so that they may be applied
196 only to specific sites. Most of these commands accept filters in any of the
203 Any filter which is a valid domain name will match any site on that
204 domain or any sub-domain thereof. These filters may contain any letter
205 of the Roman alphabet, Arabic numerals, hyphens, and full stops.
206 Non-Latin domain names must be punycode encoded.
211 Any URL beginning with a valid protocol name and ending with a
212 <tt>*</tt> is treated as a URL prefix. It will match any URL which
213 begins with the given filter sans the trailing asterisk.
218 Any URL beginning with a valid protocol name and not ending with an
219 asterisk is treated as a full URL match. It will match any page which
220 has a URL identical to the filter.
223 <dt>Regular expression</dt>
225 Any filter which does not fall into one of the above categories is
226 treated as a case-sensitive regular expression.
231 In most cases, any of the above may be prefixed with a <tt>!</tt> character
232 to exclude matching sites.
235 <h2 tag="using-scripts">Using scripts</h2>
238 <tags>:so :source</tags>
239 <spec>:so<oa>urce</oa><oa>!</oa> <a>file</a></spec>
242 Read Ex commands, JavaScript, or CSS from <a>file</a>. Files are
243 interpreted based on their extensions. Files which end in
244 <em>.js</em> are executed as JavaScript, while those ending in
245 <em>.css</em> are loaded as Cascading Stylesheets, and anything
246 else is interpreted as Ex commands. In normal cases, any errors
247 generated by the execution or non-existence of <a>file</a> are
248 printed to the <t>command-line</t> area. When <oa>!</oa> is
249 provided, these are suppressed.
253 Environment variables in <a>file</a> are expanded to their current
254 value, and the prefix <em>~</em> is replaced with the value of
255 <em>$HOME</em>. See <t>expand-env</t> and <t>initialization</t>
256 for more information.
259 <h3 tag=":source-contexts">Script Contexts</h3>
262 Each script executes in its own JavaScript context. This means that
263 any global variable or function, including those defined by
264 <ex>:javascript</ex> and the <tt>-javascript</tt> flag of
265 <ex>:map</ex>, <ex>:command</ex>, and <ex>:autocmd</ex>,
266 is directly available only within the current script. Outside of the
267 current script, they can only be accessed as properties of the
268 script's global object, which is stored in the <tt>plugins</tt>
269 global under the script's full path.
272 <h3 tag=":source-groups">Script Groups</h3>
275 In addition to its own JavaScript context, each script is executed
276 with its own default <link topic="groups">group</link> into which
277 its styles, mappings, commands, and autocommands are placed. This
278 means that commands such as <ex>:delcommand!</ex> can be issued
279 without fear of trampling other user-defined mappings. The command
280 <ex>:group! default</ex> can be issued to clear all such items at
281 once, and should be placed at the head of most scripts to prevent
282 the accumulation of stale items when the script is re-sourced.
285 <h3 tag=":source-css">Cascading Stylesheets</h3>
288 When a CSS file is sourced, its contents are applied to every web
289 page and every chrome document, including all browser windows and
290 dialogs. If the same file is sourced more than once, its previous
291 rules are cleared before it is applied again. Rules can be
292 restricted to specific documents by enclosing them in
293 <link topic="https://developer.mozilla.org/en/CSS/@-moz-document">@-moz-document</link>
297 <h3 tag=":source-javascript">JavaScript</h3>
300 JavaScript files are executed with full chrome privileges in their
301 own global namespaces. These namespaces are stored as objects in
302 the <em>plugins</em> object, in the property named after the full
303 path of the sourced file. This means that any variables or
304 functions created by your script are stored as properties of that
305 object. Additionally, all properties of the global <em>window</em>
306 and <em>modules</em> objects are accessible to your script as
311 Files in <em>~/.&dactyl.name;/plugins</em> may additionally be
312 accessed in <em>plugins.<a>filename</a></em> where <a>filename</a>
313 is the last component of the file's path stripped of any
314 extensions, with all hyphens stripped and any letter following a
315 hyphen capitalized. So, the file
316 <em>~/.&dactyl.name;/plugins/foo-bar.js</em> may be accessed as
317 <em>plugins.fooBar</em>. See also <t>writing-plugins</t>.
320 <h3 tag=":source-ex">Ex commands</h3>
323 Ex command files are executed as if each line were entered into
324 the &tag.command-line; individually.
325 Additionally, certain commands support the same ‘here document’
326 syntax supported by most Unix shells and by the &tag.command-line;.
327 So, to execute a JavaScript statement which does not comfortably fit
328 on a single line, you can use:
331 <code><ex>:js</ex> <<<em>EOF</em>
332 <kwd><hl key="Object">var</hl></kwd> hello = <kwd>function</kwd> () {
333 alert(<str>Hello world</str>);
337 <p>See also <t>ex-scripts</t> below.</p>
343 <tags>:lpl :loadplugins</tags>
345 <spec>:loadplugins <oa>pattern</oa> …</spec>
348 Immediately load all plugins which have yet to be loaded. Because
349 plugins are not automatically loaded until after <tt><t>&dactyl.name;rc</t></tt>
350 is sourced, this command must be placed early in the
351 <tt>&dactyl.name;rc</tt> file if <tt>&dactyl.name;rc</tt> uses commands or options
352 which are defined by plugins. Additionally, this command allows
353 newly installed plugins to be easily loaded without restarting
354 &dactyl.appName;. See also <o>loadplugins</o>.
357 If <oa>pattern</oa>s are provided, the given regular expressions are
358 used as filters rather than those in <o>loadplugins</o>.
364 <tags>:ru :runtime</tags>
365 <spec>:runt<oa>ime</oa><oa>!</oa> <a>file</a> …</spec>
368 Source the specified file from the first directory in
369 <o>runtimepath</o> in which it exists. When <oa>!</oa> is given,
370 source the file from all directories in <o>runtimepath</o> in
373 <example><ex>:runtime plugins/foobar.js</ex></example>
378 <tags>:scrip :scriptnames</tags>
379 <spec>:scrip<oa>tnames</oa></spec>
381 <p>List all sourced script names, in the order they were first sourced.</p>
386 <tags>:fini :finish</tags>
388 <spec>:fini<oa>sh</oa></spec>
391 Stop sourcing a script file. This can only be called from within a
392 &dactyl.appName; script file.
397 <h3 tag="ex-scripts">Ex Command Scripts</h3>
400 Ex command scripts are similar to both entering commands on the
401 &tag.command-line; and to Vim
402 scripts, but with some notable differences.
405 <p tag="multiline-commands">
406 Commands in Ex command scripts can span multiple lines by
407 prefixing the second and further lines with a <em>\</em>
408 character. For instance, the following all define commands whose
409 definitions span multiple lines.
412 <code><ex>:command!</ex> <str delim="">foo</str>
413 \ <em>-description</em> <str>A command that frobs bars</str>
414 \ <ex>:javascript</ex> frob(content.bar)</code>
416 <code><ex>:style</ex> <em>-name</em> <str delim="'">foo</str>
417 \ <str delim="'">foobar.com</str>
418 \ p<str delim="">:first-line</str> { <em>font-variant</em>: <str delim="">small-caps</str>; }
419 \ div<em>#side-bar</em> > <str delim="">:first-child</str> { <em>display</em>: <str delim="">none</str>; }</code>
421 <code><ex>:command!</ex> <str delim="">do-some-stuff</str>
422 \ <em>-description</em> <str>A command which does some stuff in JavaScript</str>
423 \ <ex>:javascript</ex> <<<em>EOF</em>
424 \ window.do(<str>some</str>);
425 \ window.do(<str>stuff</str>);
428 <code><ex>:command!</ex> <str delim="">do-some-stuff</str>
429 \ <em>-description</em> <str>A command which does some stuff in JavaScript</str>
430 \ <ex>:javascript</ex>
431 \\ window.do(<str>some</str>);
432 \\ window.do(<str>stuff</str>);</code>
435 Lines may be commented out by prefixing them with a <em>"</em>
439 <code> <hl style="color: #444">" This is a comment</hl>
440 foo bar <hl style="color: #444">" This is a comment</hl>
441 <str> This is not a comment</str>
442 foo bar <str> This is not a comment</str>
445 <h2 tag="profile profiling">Profiling</h2>
449 <spec>:<oa>count</oa>time<oa>!</oa> <a>code|:command</a></spec>
452 Profile a piece of JavaScript code or an Ex command. Run
453 <a>code</a> <oa>count</oa> times and print the elapsed time.
454 If <a>code</a> begins with a <ex>:</ex>, it is executed as an Ex
455 command. Otherwise, it is executed as JavaScript, in which case it
456 is evaluated only once and stored as a function which is executed
457 <oa>count</oa> times.
461 When <oa>!</oa> is given, <a>code</a> is executed <oa>count</oa>
462 times, but no statistics are printed.
469 <!-- vim:se sts=4 sw=4 et: -->