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

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

<document
    name="autocommands"
    title="&dactyl.appName; Autocommands"
    xmlns="&xmlns.dactyl;"
    xmlns:html="&xmlns.html;">

<h1 tag="autocommands">Automatic commands</h1>
<toc start="2"/>

<p>
    Autocommands are a way to automatically execute code when
    certain events happen.
</p>

<item>
    <tags>:au :autocmd</tags>
    <spec>:au<oa>tocmd</oa><oa>!</oa> <oa>events</oa> <oa>filter</oa> <oa>cmd</oa></spec>
    <description>
        <p>Execute commands automatically on events.</p>

        <p>
            When <oa>cmd</oa> is not given, list all commands
            defined for the given <oa>events</oa> and <oa>filter</oa>.
            When <oa>!</oa> is given, delete the matching commands
            rather than listing them.
        </p>

        <p>
            When <oa>cmd</oa> is given, add it to the list of commands to be
            executed when <oa>events</oa> occur for pages matching the
            comma-separated list of <t>site-filters</t>, <oa>filter</oa>. If the
            <em>-javascript</em> (short name <em>-js</em>) option is given,
            <oa>cmd</oa> is interpreted as JavaScript code. Otherwise, it is
            interpreted as an Ex command.
        </p>

        <p>
            If the <em>-group</em>=<a>group</a> flag is given, add this
            autocommand to the named <t>group</t>. Any filters for <a>group</a>
            apply in addition to <oa>filter</oa>. When listing commands this
            limits the output to the specified group.
        </p>

        <p>Available <oa>events</oa>:</p>

        <dl tag="autocommand-list"/>

        <p>
            For Ex <oa>cmd</oa>s, the following keywords are
            replaced with the appropriate value before the commands
            are executed. For JavaScript commands, they may be
            accessed as ordinary variables, sans angle brackets.
        </p>

        <dl tag="autocommand-args"/>
    </description>
</item>

<item>
</item>

<item>
    <tags>:doautoa :doautoall</tags>
    <spec>:doautoa<oa>ll</oa> <a>event</a> <oa>url</oa></spec>
    <description>
        <p>
            Apply all <a>event</a> autocommands matching the
            specified <oa>url</oa> to all buffers. If no
            <oa>url</oa> is specified use the current URL.
        </p>
    </description>
</item>

<item>
    <tags>:do :doautocmd</tags>
    <spec>:do<oa>autocmd</oa> <a>event</a> <oa>url</oa></spec>
    <description>
        <p>
            Apply all autocommands matching the specified
            <oa>url</oa> to the current buffer. If no <oa>url</oa>
            is specified use the current URL.
        </p>
    </description>
</item>
<h2 tag="autocmd-examples">Examples</h2>

<p>Enable <em>Pass Through</em> mode on all Google sites:</p>

<code><ex>:autocmd LocationChange</ex> <str delim="">google.com</str> <ex>:normal!</ex> <k name="C-z"/></code>

<p>Enable <em>Pass Through</em> mode on <em>some</em> Google sites:</p>

<code><ex>:autocmd LocationChange</ex> <str delim="">www.google.com</str>,<str delim="">mail.google.com</str> <ex>:normal!</ex> <k name="C-z"/></code>

<p>or</p>

<code><ex>:autocmd LocationChange</ex> <str delim="'">^https?://(www|mail)\.google\.com/</str> <ex>:normal!</ex> <k name="C-z"/></code>

<p>Set the filetype to mail when editing email at Gmail:</p>

<code><ex>:autocmd LocationChange</ex> !<str delim="">mail.google.com</str>,<str delim="">*</str> <se opt="editor" op="&amp;"/>
<ex>:autocmd LocationChange</ex> <str delim="'">mail.google.com</str> <se opt="editor"><str>gvim -f -c 'set ft=mail' +&lt;line></str></se></code>

</document>

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