path: root/common/locale/en-US/repeat.xml

<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet type="text/xsl" href="chrome://dactyl/content/help.xsl"?>

<!DOCTYPE document SYSTEM "chrome://dactyl/content/dactyl.dtd">

<document
    name="repeat"
    title="&dactyl.appname; Repeating Commands"
    xmlns="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">
<h1 tag="repeating">Repeating commands</h1>
<toc start="2"/>

<p>
    &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.
</p>

<h2 tag="single-repeat">Single repeats</h2>

<item>
    <tags>.</tags>
    <strut/>
    <spec><oa>count</oa>.</spec>
    <description>
        <p>
            Repeat the last keyboard mapping <oa>count</oa> times. Note that,
            unlike in Vim, this does not apply solely to editing commands,
            mainly because &dactyl.appname; doesn't have them.
        </p>
    </description>
</item>


<item>
    <tags>@:</tags>
    <strut/>
    <spec><oa>count</oa>@:</spec>
    <description>
        <p>Repeat the last Ex command <oa>count</oa> times.</p>
    </description>
</item>



<h2 tag="macros complex-repeat">Macros</h2>

<item>
    <tags>q</tags>
    <strut/>
    <spec>q<a>0-9a-zA-Z</a></spec>
    <description>
        <p>
            Record a key sequence as a macro. Available macros are
            <a>0-9a-zA-Z</a>. If the macro is an uppercase letter, the
            recorded keys are appended to the lowercase macro of the same
            name. Typing <k>q</k> again stops the recording.
        </p>
    </description>
</item>


<item>
    <tags>:macros</tags>
    <spec>:mac<oa>ros</oa> <oa>pat</oa></spec>
    <description>
        <p>
            List recorded macros matching the optional regular expression
            <oa>pat</oa>. If no regex is given, list all macros.
        </p>
    </description>
</item>


<item>
    <tags>:delmac :delmacros</tags>
    <spec>:delmac<oa>ros</oa> <a>pat</a></spec>
    <spec>:delmac<oa>ros</oa>!</spec>
    <description>
        <p>
            Delete recorded macros matching the regular expression
            <a>pat</a>. If <em>!</em> is given, all macros are deleted.
        </p>
    </description>
</item>


<item>
    <tags>@ :play</tags>
    <spec>:pl<oa>ay</oa> <a>a-z0-9</a></spec>
    <spec><oa>count</oa>@<a>a-z0-9</a></spec>
    <description>
        <p>
            Plays the contents of macro with name <a>a-z0-9</a> <oa>count</oa>
            times.
        </p>
    </description>
</item>


<item>
    <tags>@@</tags>
    <spec><oa>count</oa>@@</spec>
    <description short="true">
        <p>Replay the last executed macro <oa>count</oa> times.</p>
    </description>
</item>



<h2 tag="using-scripts">Using scripts</h2>

<item>
    <tags>:so :source</tags>
    <spec>:so<oa>urce</oa><oa>!</oa> <a>file</a></spec>
    <description>
        <p>
            Read Ex commands, JavaScript, or CSS from <a>file</a>. Files are
            interpreted based on their extensions. Files when end in
            <em>.js</em> are executed as JavaScript, while those ending in
            <em>.css</em> 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 <a>file</a> are
            printed to the <t>command-line</t> area.  When <oa>!</oa> is
            provided, these are suppressed. 
        </p>

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

        <h3 tag=":source-css">Cascading Stylesheets</h3>

        <p>
            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 
            <link topic="https://developer.mozilla.org/en/CSS/@-moz-document">@-moz-document</link>
            blocks.
        </p>

        <h3 tag=":source-javascript">JavaScript</h3>

        <p>
            JavaScript files are executed with full chrome privileges in their
            own global namespaces. These namespaces are stored as objects in
            the <em>plugins</em> object, in the property named for 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 <em>window</em>
            and <em>modules</em> objects are accessible to your script as
            global variables.
        </p>
            
        <p>
            Files in <em>~/.&dactyl.name;/plugins</em> may additionally be
            accessed in <em>plugins.<a>filename</a></em> where <a>filename</a>
            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
            <em>~/.&dactyl.name;/plugins/foo-bar.js</em> may be accessed as 
            <em>plugins.fooBar</em>. See also <t>writing-plugins</t>
        </p>

        <h3 tag=":source-ex">Ex commands</h3>

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

        <code><ex>js</ex> &lt;&lt;<em>EOF</em>
<hl key="Object">var</hl> hello = <hl key="Key">function</hl> () {
    alert(<str>Hello world</str>);
}
<em>EOF</em></code>
    </description>
</item>


<item>
    <tags>:lpl :loadplugins</tags>
    <strut/>
    <spec>:loadplugins</spec>
    <description>
        <p>
            Immediately load all plugins which have yet to be loaded. Because
            plugins are not automatically loaded until after &dactyl.name;rc
            is sourced, this command must be placed early in the
            &dactyl.name;rc file if &dactyl.name;rc uses commands or options
            which are defined by plugins. Additionally, this command allows
            newly installed plugins to be easily loaded without restarting
            &dactyl.appname;.
        </p>
    </description>
</item>


<item>
    <tags>:ru :runtime</tags>
    <spec>:runt<oa>ime</oa><oa>!</oa> <a>file</a> …</spec>
    <description>
        <p>
            Source the specified file from the first directory in
            <o>runtimepath</o> in which it exists. When <oa>!</oa> is given,
            source the specified from all directories in <o>runtimepath</o> in
            which it exists.
        </p>
        <example><ex>:runtime plugins/foobar.js</ex></example>
    </description>
</item>


<item>
    <tags>:scrip :scriptnames</tags>
    <spec>:scrip<oa>tnames</oa></spec>
    <description>
        <p>List all sourced script names, in the order they were first sourced.</p>
    </description>
</item>


<item>
    <tags>:fini :finish</tags>
    <strut/>
    <spec>:fini<oa>sh</oa></spec>
    <description>
        <p>
            Stop sourcing a script file. This can only be called from within a
            &dactyl.appname; script file.
        </p>
    </description>
</item>


<h2 tag="profile profiling">Profiling</h2>

<item>
    <tags>:time</tags>
    <spec>:<oa>count</oa>time<oa>!</oa> <a>code|:command</a></spec>
    <description>
        <p>
            Profile a piece of JavaScript code or an Ex command. Run
            <a>code</a> <oa>count</oa> times and print the elapsed time.
            If <a>code</a> begins with a <ex>:</ex>, 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
            <oa>count</oa> times.
        </p>

        <p>
            When <oa>!</oa> is given, <a>code</a> is executed <oa>count</oa>
            times, but no statistics are printed.
        </p>
    </description>
</item>

</document>
<!-- vim:se sts=4 sw=4 et: -->