chapters/11.markdown @ 8d3cdc4c9c2a

Buffer-Local Options and Mappings
=================================

Now we're going to take a few minutes to revisit three things we've already
talked about: mappings, abbreviations, and options, but with a twist.  We're
going to set each of them in a single buffer at a time.

The true power of this idea will become apparent in the next chapter, but we
need to lay the groundwork for it now.

For this chapter you'll need to open two files in Vim, each in its own split.
I'll call them `foo` and `bar`, but you can name them whatever you like.  Put
some text into each of them.

Mappings
--------

Switch to file `foo` and run the following commands:

    :::vim
    :nnoremap          <leader>d dd
    :nnoremap <buffer> <leader>x dd

Now stay in file `foo`, make sure you're in normal mode, and type `<leader>d`.
Vim will delete a line.  This is nothing new.

Still in file `foo`, type `<leader>x`.  Vim will delete a line again.  This
makes sense because we mapped `<leader>x` to `dd` as well.

Now move over to file `bar`.  While in normal mode, type `<leader>d`.  Again,
Vim deletes the current line.  Nothing surprising here either.

Now for the twist: while still in file `bar`, type `<leader>x`.

Instead of deleting the entire line, Vim just deleted a single character!
What happened?

The `<buffer>` in the second `nnoremap` command told Vim to only consider that
mapping when we're in the buffer where we defined it.

When you typed `<leader>x` in file `bar` Vim couldn't find a mapping that
matched it, so it treated it as two commands: `<leader>` (which does nothing on
its own) and `x` (the normal command to delete a single character).

Local Leader
------------

In our example we used `<leader>x` for our buffer-local mapping, but this is bad
form.  In general, when you create a mapping that only applies to specific
buffers you should use `<localleader>` instead of `<leader>`.

Using two separate leader keys provides a sort of "namespacing" that will help
you keep all your various mappings straight in your head.

It's even more important when you're writing a plugin for other people to use.
The convention of using `<localleader>` for local mappings will prevent your
plugin from overwriting someone else's `<leader>` mapping that they've
painstakingly burned into their fingers over time.

Settings
--------

In one of the earliest chapters of the book we talked about settings options
with `set`.  Some options always apply to all of Vim, but others can be set on
a per-buffer basis.

Switch to file `foo` and run the following command:

    :::vim
    :setlocal wrap

Now switch to file `bar` and run this command:

    :::vim
    :setlocal nowrap

Make your Vim window smaller and you'll see that the lines in `foo` wrap, but
the lines in `bar` don't.

Let's try another option.  Switch to `foo` and run this command:

    :::vim
    :setlocal number

Now switch over to `bar` and run this command:

    :::vim
    :setlocal nonumber

You now have line numbers in `foo` but not in `bar`.

Not all options can be used with `setlocal`.  To see if you can set a particular
option locally, read its `:help`.

I've glossed over a bit of detail about how local options *actually* work for
now.  In the exercises you'll learn more about the gory details.

Shadowing
---------

Before we move on, let's look at a particularly interesting property of local
mappings.  Switch over to `foo` and run the following commands:

    :::vim
    :nnoremap <buffer> Q x
    :nnoremap          Q dd

Now type `Q`.  What happens?

When you press `Q`, Vim will run the first mapping, not the second, because the
first mapping is *more specific* than the second.

Switch to file `bar` and type `Q` to see that Vim uses the second mapping,
because it's not shadowed by the first in this buffer.

Exercises
---------

Read `:help local-options`.

Read `:help setlocal`.

Read `:help map-local`.