Repeating commands

&dactyl.appName; can repeat commands in a number of ways, from repeating the last command, to recording and playing macros, to saving its state and executing scripts.

Single repeats

<repeat-key> . count.

Repeat the last keyboard mapping count times. Note that, unlike in Vim, this also applies to other than editing commands.

@: count@:

Repeat the last Ex command count times.

Macros

<record-macro> q qa-zA-Z

Record a key sequence as a macro. Available macros are a-zA-Z. If the macro is an uppercase letter, the recorded keys are appended to the lowercase macro of the same name. Typing q again stops the recording.

:macros :macros pat

List recorded macros matching the optional regular expression pat. If no regexp is given, list all macros.

:delmac :delmacros :delmacros pat :delmacros!

Delete recorded macros matching the regular expression pat. If ! is given, all macros are deleted.

<play-macro> @ count@a-z

Plays the contents of macro with name a-z count times.

@@ count@@

Replay the last executed macro count times.

Macro utilities

The following key bindings facilitate the recording of efficient macros. They have no effect when typed normally, but are recorded and take effect during macro playback.

s]]>

counts]]>

Sleep for count milliseconds before resuming playback.

l]]>

countl]]>

Wait for the current page to finish loading before resuming playback. If count is given, wait no more than count seconds. Otherwise wait no more than 25 seconds.

Groups

In order to facilitate script writing, especially scripts which only apply to certain web sites, many types of commands and mappings can be assigned to a named group. In addition to helping identify the source of such mappings in listings, and aiding in the cleanup of scripts, these groups can be configured to apply only to certain web sites.

:gr :group :group

List all active groups.

:group! group …

Select, create, or modify a group. After invocation, group becomes the default group for all further commands issued in the current script. If ! is given the group is cleared of all mappings, commands, and any other entries bound to it before making the specified additions (if any).

The following group names have special meanings:

builtin: The default group for builtin items. Can not be modified in any way by scripts.
default: The default group for the script containing this :group command.
user: The default group for the command line and &dactyl.name;rc.

The following arguments are available:

-args=javascript: JavaScript Object which augments the arguments passed to commands, mappings, and autocommands, e.g., given { foo: "bar" }, foo (<foo> if the Ex syntax is used) will be replaced by bar inside the definitions (short name: -a)
-description: A description of this group (short names: -desc, -d)
-locations=filters: The URLs for which this group should be active. See site-filters (short names: -locs, -loc, -l)
-nopersist: Do not save this group to an auto-generated RC file (short name: -n)

:delgr :delgroup :delgroup group :delgroup!

Delete the specified group. With ! delete all user groups.

Site Filters

Many &dactyl.appName; commands accept filters so that they may be applied only to specific sites. Most of these commands accept filters in any of the following formats:

domain: Any filter which is a valid domain name will match any site on that domain or any sub-domain thereof. These filters may contain any letter of the Roman alphabet, Arabic numerals, hyphens, and full stops. Non-Latin domain names must be punycode encoded.
URL prefix: Any URL beginning with a valid protocol name and ending with a * is treated as a URL prefix. It will match any URL which begins with the given filter sans the trailing asterisk.
Full URL: Any URL beginning with a valid protocol name and not ending with an asterisk is treated as a full URL match. It will match any page which has a URL identical to the filter.
Regular expression: Any filter which does not fall into one of the above categories is treated as a case-sensitive regular expression.

In most cases, any of the above may be prefixed with a ! character to exclude matching sites.

Using scripts

:so :source :source! file

Read Ex commands, JavaScript, or CSS from file. Files are interpreted based on their extensions. Files which end in .js are executed as JavaScript, while those ending in .css are loaded as Cascading Stylesheets, and anything else is interpreted as Ex commands. In normal cases, any errors generated by the execution or non-existence of file are printed to the command-line area. When ! is provided, these are suppressed.

Environment variables in file are expanded to their current value, and the prefix ~ is replaced with the value of $HOME. See expand-env and initialization for more information.

Script Contexts

Each script executes in its own JavaScript context. This means that any global variable or function, including those defined by :javascript and the -javascript flag of :map, :command, and :autocmd, is directly available only within the current script. Outside of the current script, they can only be accessed as properties of the script's global object, which is stored in the plugins global under the script's full path.

Script Groups

In addition to its own JavaScript context, each script is executed with its own default group into which its styles, mappings, commands, abbreviations and autocommands are placed. This means that commands such as :delcommand! can be issued without fear of trampling other user-defined mappings. The command :group! default can be issued to clear all such items at once, and should be placed at the head of most scripts to prevent the accumulation of stale items when the script is re-sourced.

Cascading Stylesheets

When a CSS file is sourced, its contents are applied to every web page and every chrome document, including all browser windows and dialogs. If the same file is sourced more than once, its previous rules are cleared before it is applied again. Rules can be restricted to specific documents by enclosing them in @-moz-document blocks.

JavaScript

JavaScript files are executed with full chrome privileges in their own global namespaces. These namespaces are stored as objects in the plugins object, in the property named after the full path of the sourced file. This means that any variables or functions created by your script are stored as properties of that object. Additionally, all properties of the global window and modules objects are accessible to your script as global variables.

Files in ~/.&dactyl.name;/plugins may additionally be accessed in plugins.filename where filename is the last component of the file's path stripped of any extensions, with all hyphens stripped and any letter following a hyphen capitalized. So, the file ~/.&dactyl.name;/plugins/foo-bar.js may be accessed as plugins.fooBar. See also writing-plugins.

Ex commands

Ex command files are executed as if each line were entered into the &tag.command-line; individually. Additionally, certain commands support the same ‘here document’ syntax supported by most Unix shells and by the &tag.command-line;. So, to execute a JavaScript statement which does not comfortably fit on a single line, you can use:

:js <<EOF
var hello = function () {
    alert(Hello world);
}
EOF

Ex Command Scripts

Ex command scripts are similar to both entering commands on the &tag.command-line; and to Vim scripts, but with some notable differences.

Commands in Ex command scripts can span multiple lines by prefixing the second and further lines with a \ character. For instance, the following all define commands whose definitions span multiple lines.

:command! foo
        \ -description A command that frobs bars
        \ :javascript frob(content.bar)

:style -name foo
     \ foobar.com
     \ p:first-line { font-variant: small-caps; }
     \ div#side-bar > :first-child { display: none; }

:command! do-some-stuff
        \ -description A command which does some stuff in JavaScript
        \ :javascript <<EOF
        \     window.do(some);
        \     window.do(stuff);
        \EOF

:command! do-some-stuff
        \ -description A command which does some stuff in JavaScript
        \ :javascript
        \\    window.do(some);
        \\    window.do(stuff);

Lines may be commented out by prefixing them with a " character. Comments and commands cannot both occur in a single command line.

            " This is a comment
    foo bar " This is a syntax error
             This is not a comment
    foo bar  This is not a comment

Profiling

:time :counttime! code|:command

Profile a piece of JavaScript code or an Ex command. Run code count times and print the elapsed time. If code begins with a :, it is executed as an Ex command. Otherwise, it is executed as JavaScript, in which case it is evaluated only once and stored as a function which is executed count times.

When ! is given, code is executed count times, but no statistics are printed.